Azure DevOps Integration Service for Cline (Cline-DevOps-Gateway)

This service functions as an MCP endpoint, enabling seamless interaction between Cline/Roo Code instances and remote Azure DevOps (ADO) repositories and project management features.

The canonical source code repository is accessible here: https://github.com/cakriwut/ado-mcp-server

System Requirements

To successfully deploy and run this gateway:

• Node.js runtime environment (version 20 LTS or newer is mandated).
• npm package manager (bundled with Node.js).
• An active installation of the Cline platform.
• Valid credentials/Personal Access Token (PAT) for your Azure DevOps tenant.

Deployment Procedures

Automated Deployment via Smithery

For streamlined provisioning, utilize the Smithery CLI:

npx -y @smithery/cli install @cakriwut/ado-mcp-server --client claude

Manual Installation Steps

1. Obtain a local copy of the source code via Git: bash git clone https://github.com/cakriwut/ado-mcp-server.git cd ado-mcp-server

2. Install required software dependencies: bash npm install

3. Compile the source code into executable JavaScript: bash npm run build

Note: The resulting compiled artifacts located in the build/ directory are intentionally excluded from version control. Compilation must be performed locally after every source checkout.

Configuration Workflow

Step 1: Generating the Azure DevOps Personal Access Token (PAT)

Authentication requires a PAT with specific permissions:

1. Navigate to your Azure DevOps portal and log in.
2. Access User Settings (via profile picture in the upper right corner).
3. Enter the "Security" section.
4. Initiate the creation of a "New Token".
5. Assign a descriptive label and grant the following minimum scopes:
   • Code (read, write): Necessary for managing source control operations like PRs.
   • Work Items (read, write): Required for CRUD operations on tasks, bugs, etc.
   • Build (read, execute): Needed to query and initiate pipeline runs.
   • Wiki (read, write): Allows interaction with project documentation storage.
   • Project and Team (read): Essential for organizational context discovery.
6. Securely copy the newly generated token string.

Step 2: Integrating the Server Configuration into MCP Settings

Insert the following configuration object into your respective Cline client settings file. This dictates how Cline locates and communicates with this backend service.

Roo Code (VSCode Extension) Location: %APPDATA%/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

Cline Desktop Application Location: %LOCALAPPDATA%/Claude/claude_desktop_config.json

Inject the configuration into the mcpServers block:

{
  "mcpServers": {
    "azure-devops-mcp-server": {
      "command": "node",
      "args": ["C:/absolute/path/to/ado-mcp-server/build/index.js"],
      "env": {
        "AZURE_DEVOPS_ORG": "your-organization",
        "AZURE_DEVOPS_PAT": "your-personal-access-token",
        "AZURE_DEVOPS_PROJECT": "your-project-name"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Crucial Parameter Substitutions: * C:/absolute/path/to/ado-mcp-server: Substitute with the exact root directory path where the repository was cloned (ensure the path uses standard forward slashes /, even on Windows). * your-organization: Your specific Azure DevOps organizational slug. * your-project-name: The target project name within that organization. * your-personal-access-token: The PAT secured in Step 1.

Platform Notes (Windows Users): * Always use forward slashes (/) for path separators within the JSON configuration. * The path must point directly to the compiled entry file (build/index.js). * A client restart (Roo Code or Cline Desktop) is mandatory for the new configuration to take effect.

Exposed Functionality (Tools Catalog)

Work Item Management

• get_work_item: Retrieve an item by its unique identifier.
• list_work_items: Execute complex queries against work items using WIQL syntax.
• create_work_item: Provision new work items (e.g., Task, Bug, Feature).
• update_work_item: Modify fields or state of an existing record.
• search_work_items: Perform full-text searches across work item metadata.
• add_work_item_comment: Append remarks or context to an item.
• get_work_item_comments: Fetch the history of comments attached to an item.

Project Boards

• get_boards: Enumerate the available Kanban/Scrum boards within the configured project.

CI/CD Pipelines

• list_pipelines: Obtain a directory listing of all defined build and release pipelines.
• trigger_pipeline: Initiate an execution run for a specified pipeline.

Source Control (Pull Requests)

• list_pull_requests: Display active or closed PRs.
• create_pull_request: Initiate a new branch merge request.
• update_pull_request: Modify details of an existing PR.

Project Documentation (Wiki)

• get_wikis: List all distinct Wiki repositories associated with the project.
• list_wiki_pages: Detail the page structure within a chosen Wiki.
• get_wiki_page: Fetch the content of a specific page using its path locator.
• create_wiki: Initialize a new Wiki repository structure.
• update_wiki_page: Atomically create or overwrite the content of an existing page.
• create_wiki_page: Generate a new, empty page entity.
• search_wiki_page: Text-based discovery of content across Wiki pages.

Organization Context

• list_projects: Retrieve a comprehensive manifest of all accessible ADO projects within the authenticated organization.

Command Line Interface (CLI) Utilities

The service includes an auxiliary CLI executable (azure-devops-cli) accessible after the build step, allowing direct terminal interaction.

Environment Variable Setup (PowerShell Example)

Configure your session context prior to execution:

$env:AZURE_DEVOPS_ORG = "your-organization"
$env:AZURE_DEVOPS_PROJECT = "your-project-name"
$env:AZURE_DEVOPS_PAT = "your-personal-access-token"

Representative CLI Operations

Work Item Examples

# Retrieve item #42
node .\build\cli\index.js work-item get -i 42

# Full-text search for 'bug'
node .\build\cli\index.js work-item search -s "bug"

# Construction of a new Task entity via JSON patch
node .\build\cli\index.js work-item create -t "Task" -d '[{"op":"add","path":"/fields/System.Title","value":"New Task"}]'

# Annotate Item 42
node .\build\cli\index.js work-item add-comment -i 42 -t "Feedback provided via CLI utility."

# Retrieve thread history for Item 42
node .\build\cli\index.js work-item get-comments -i 42

Wiki Examples

# Index of all Wikis
node .\build\cli\index.js wiki list

# Fetch content by identifier and path
node .\build\cli\index.js wiki page -w <wikiIdentifier> -p "/path/to/page" --include-content

# Textual search within a specified Wiki
node .\build\cli\index.js wiki search -w <wikiIdentifier> -s "search term"

Refer to docs/wiki-cli-usage.md and docs/command-list.md for exhaustive command reference.

Operational Verification

1. Ensure Cline (or VSCode) has been relaunched subsequent to configuration modification.
2. Confirm that the Azure DevOps server integration is initialized within the client's capability manifest.
3. Use the bundled MCP Inspector utility to validate connectivity: bash npm run inspector

Diagnostic Guide

1. Connectivity Failure:

   • Scrutinize the file path specified in your MCP settings for absolute correctness.
   • Validate the ADO organization credentials (PAT).
   • Review the primary client logs (Cline/VSCode) for connection refusal messages.

2. Authentication Errors:

   • Confirm the PAT has not passed its expiration date.
   • Verify that all required scopes (listed in Step 1) were provisioned to the token.
   • Double-check the spelling of the organization and project names.

3. General Anomalies:

   • Execute the inspector tool (npm run inspector).
   • Examine the server console output for internal error stack traces.

Contribution and Modification

To extend or modify service logic:

1. Implement desired changes within the src source directory.
2. For active development/hot-reloading, utilize npm run watch.
3. Generate production-ready output using npm run build upon completion.
4. Validate functionality via the inspector utility: npm run inspector.

Testing Suite

The codebase incorporates comprehensive test suites targeting every exposed MCP command, ensuring functional integrity against the Azure DevOps backend.

Prerequisites for Testing Execution

1. Create a root-level .env file containing necessary secrets: AZURE_DEVOPS_ORG=your-organization AZURE_DEVOPS_PROJECT=your-project AZURE_DEVOPS_PAT=your-personal-access-token

2. Install dependencies: npm install

Running Tests

Rapid Connectivity Check

Execute a lightweight test focusing solely on organizational enumeration:

npm run test:quick

Standard Command Verification

Run an integrated test covering the primary set of operational commands:

npm run test:simple

TypeScript Module Tests

Execute the full suite:

npm test

To isolate tests to specific feature sets:

npm run test:work-item     # Work Item Functionality
npm run test:board         # Board/Backlog Functionality
npm run test:wiki          # Wiki Operations
npm run test:project       # Project Discovery
npm run test:pipeline      # CI/CD Job Execution
npm run test:pull-request  # Source Control Review Tests

Further documentation on test architecture is available in tests/README.md.

Licensing

This project is distributed under the terms of the MIT License. See the LICENSE file for full details.

---

Contextual Note on Business Tools (Wikipedia Definition): Business management tools encompass the entire ecosystem of applications, controls, and methodologies employed by an enterprise to maintain market relevance, optimize performance, and adapt to external volatility. These tools are traditionally categorized by organizational function (e.g., planning, process control, data analytics). Modern tool selection demands a strategic alignment with core organizational needs rather than mere adoption of the latest technology, requiring careful adaptation of the software to the business processes, not vice-versa. Key historical categories include MIS, ERP, and CRM systems, with current trends leaning heavily towards cloud-based implementations where effective deployment and selection remain paramount to realizing IT value.