Devin Workflow MCP Server

A complete Model Context Protocol (MCP) server implementation for Devin AI workflow automation. This server provides tools to parse markdown workflows, execute multi-step processes with polling, and manage step dependencies.

Features

• Markdown Workflow Parsing: Parse structured workflows with Playbook, Prompt, Handoff, and RelyPreviousStep parameters
• Multi-Step Execution: Execute complete workflows with automatic step dependencies
• Polling Mechanism: Automatically poll sessions every 10 seconds to detect completion
• Handoff Management: Handle step-to-step communication and result passing
• API Integration: Direct integration with Devin AI API using exact patterns from specifications

Installation

npm install

Project Structure

devin-workflow-mcp/
├── package.json
├── src/
│   ├── index.js           # Main MCP server entry point
│   ├── server.js          # Core MCP server implementation
│   ├── workflow-parser.js # Markdown workflow parser
│   ├── devin-client.js    # Devin API client
│   └── handoff-manager.js # Workflow execution orchestrator
├── examples/
│   └── sample-workflows.md # Example workflows and usage
└── README.md

Usage

Starting the Server

npm start

MCP Tools Available

parse_workflow

Parse markdown workflow into structured steps.

{
  "markdown": "## Step 1 ##\n- Prompt: Review code\n- Handoff: Provide review"
}

execute_workflow

Execute complete multi-step workflow with polling.

{
  "workflow": "markdown workflow content",
  "api_key": "your-devin-api-key",
  "polling_interval": 10
}

create_devin_session

Create a new Devin AI session.

{
  "api_key": "your-devin-api-key",
  "prompt": "What should I do?",
  "playbook_id": "code-review",
  "title": "My Session"
}

chat_devin_session

Send message to existing session.

{
  "api_key": "your-devin-api-key",
  "session_id": "session-id",
  "message": "Follow up instruction"
}

get_session_status

Check session completion status.

{
  "api_key": "your-devin-api-key",
  "session_id": "session-id"
}

configure_polling

Configure polling intervals.

{
  "interval": 15,
  "timeout": 600
}

Workflow Format

Workflows are written in markdown with specific step format:

## Step 1 ##
- Playbook: playbook-id (optional, auto-prefix "playbook-" if missing)
- Prompt: user prompt text (mandatory)
- Handoff: instruction for what Devin should prepare/deliver (optional)

## Step 2 ##
- Playbook: playbook-id (optional)
- RelyPreviousStep: yes/no (default: yes)
- Prompt: user prompt text (mandatory)
- Handoff: instruction for handoff (optional)

Parameter Details

• Playbook: Optional playbook ID, automatically prefixed with "playbook-" if not present
• Prompt: Mandatory instruction for Devin
• Handoff: Optional instruction for what Devin should deliver
• RelyPreviousStep: Whether to append previous step's result to current prompt (default: yes)

API Integration

The server implements the exact API patterns specified in the original README.MD:

CREATE_SESSION

• Endpoint: POST https://api.devin.ai/v1/sessions
• Authentication: Bearer token via DEVIN_API_KEY
• Parameters: prompt (mandatory), playbook_id (optional), title (optional)

CHAT_SESSION

• Endpoint: POST https://api.devin.ai/v1/sessions/{session_id}/messages
• Parameters: session_id (mandatory), message payload (mandatory)

GET_SESSION

• Endpoint: GET https://api.devin.ai/v1/session/{session_id}
• Response Processing: Extracts message from last devin_message type in response.messages array

Polling Mechanism

The server automatically polls GET_SESSION every 10 seconds (configurable) to detect completion using:

• status field values
• status_enum field values

Completion is detected when status indicates: completed, finished, done, success, failed, error, cancelled, etc.

Step Dependencies

When RelyPreviousStep=yes (default):

1. Execute step normally
2. Wait for completion via polling
3. If step has handoff instruction, send it and wait for completion again
4. Append handoff result to next step's prompt

Example Workflow Execution

## Step 1 ##
- Playbook: code-review
- Prompt: Review pull request #123 for security issues
- Handoff: Provide security assessment report

## Step 2 ##
- Playbook: documentation
- RelyPreviousStep: yes
- Prompt: Create fix documentation based on security findings
- Handoff: Generate remediation guide

This workflow will:

1. Create session with code review prompt
2. Poll until completion
3. Send handoff instruction for security report
4. Poll until handoff completion
5. Create second session with documentation prompt + previous step's result
6. Poll until completion
7. Send handoff instruction for remediation guide
8. Poll until final completion

Error Handling

• API errors are caught and returned with structured error responses
• Timeout handling for long-running sessions
• Validation of required parameters and workflow structure
• Graceful handling of incomplete or failed steps

Configuration

Default settings:

• Polling interval: 10 seconds
• Session timeout: 5 minutes
• Auto-retry on temporary failures

Configure via configure_polling tool or environment variables.

Development

# Install dependencies
npm install

# Start in development mode
npm run dev

# Run server
npm start

Requirements

• Node.js >= 18.0.0
• Valid Devin API key
• MCP-compatible client (Claude Desktop, etc.)

License

MIT License

Programmatic Usage: executeWorkflow

You can execute workflows directly from your own Node.js scripts using the exported executeWorkflow function.

1. Set Up Your API Key

Create a file named env.local in the project root and add your Devin API key:

DEVIN_API_KEY=your-devin-api-key-here

Or, set the environment variable in your shell:

export DEVIN_API_KEY=your-devin-api-key-here

2. Example Usage

import { executeWorkflow } from './src/workflow-executor.js';

const markdownWorkflow = `
## Step 1 ##
- Prompt: Review the following code
- Playbook: code-review

## Step 2 ##
- Prompt: Summarize the review
- RelyPreviousStep: yes
`;

(async () => {
  const result = await executeWorkflow(markdownWorkflow, {
    // Optional overrides:
    // apiKey: 'your-devin-api-key',
    // pollingInterval: 10, // seconds
    // timeout: 300, // seconds
    // verbose: true
  });
  console.log(result);
})();

3. Options

• apiKey: (string) Devin API key. Defaults to process.env.DEVIN_API_KEY.
• pollingInterval: (number) Polling interval in seconds (default: 10).
• timeout: (number) Timeout in seconds (default: 300).
• verbose: (boolean) Show detailed logs (default: true).
• useMockMode: (boolean) Use mock API for testing (default: true if no API key).

4. Output

The function returns a summary object with execution status, step results, and session IDs.

CLI Usage: Run Workflows from the Command Line

You can execute a workflow markdown file directly from the command line using the CLI script:

node index.js --file <absolute path to workflow markdown file> [--pollingInterval N] [--timeout N] [--verbose true|false] [--mock true|false] [--apiKey KEY]

Options

• --file <path>: (required) Absolute path to your workflow markdown file
• --pollingInterval <number>: Polling interval in seconds (default: 10)
• --timeout <number>: Timeout in seconds (default: 300)
• --verbose true|false: Enable or disable verbose output (default: true)
• --mock true|false: Use mock API for testing (default: true if no API key)
• --apiKey <key>: Provide a Devin API key (overrides env)

Example:

node index.js --file /absolute/path/to/workflow.md --pollingInterval 5 --timeout 120 --verbose false --mock false --apiKey your-key

All options are passed to executeWorkflow as described in the programmatic usage section below.