ado-search-mcp

MCP server that wraps the ado-search CLI for Azure DevOps work item search and management.

Tools

ado_search and ado_grep accept an optional project filter for data dirs that sync several projects (ado-search >= 1.14).

ado_add_comment turns @Display Name and @email tags into ADO mentions and refuses to post when a tag is unknown or names several people (ado-search >= 1.15). A tag may start the comment. Write @ for a literal @, or pass resolve_mentions: false to post the text as-is. ado_edit_comment takes a comment_id from ado_list_comments and handles text and mentions the same way (ado-search >= 1.16). HTML values (comment text, description, acceptance criteria) reach the CLI through a temp file, so text starting with @ or - is safe.

ado_get_fields returns {field: value} JSON for an optional fields list of reference names (default: type, title, state, assignee, tags, story points, description, acceptance criteria). Description and acceptance criteria keep their HTML, which ado_show strips, so read them here before editing with ado_update. Identity fields return the email; empty fields return null (ado-search >= 1.17).

ado_mentions lists the comments that @mention the authenticated user over the last 30 days (WIQL @RecentMentions), newest first: work item id, title, state, type and assignee, then comment id, author, created date (UTC) and plain text with mentions as @Name. since (ISO datetime, UTC) keeps comments created or modified after it, limit defaults to 50, and your own comments are dropped unless include_own is true (ado-search >= 1.18).

The ado_test_* tools read Azure Test Plans live and return JSON; each takes an optional project (ado-search >= 1.19). ado_test_suites lists suites depth-first with type, linked requirement and query; ado_test_cases returns steps as {action, expected} with shared steps as {shared_steps: id}, plus parameters and tester/configuration assignments; ado_test_results includes linked bug ids.

ado_wiki_show reads one page's markdown (or lists page paths) from any project's wiki. ado_wiki_update replaces a page with content: it reads the live page first and sends its ETag with If-Match, so a page changed in between is refused. dry_run returns the unified diff and writes nothing; create allows a new page; comment is stored with the revision (ado-search >= 1.19).

ado_analytics runs a read-only Analytics OData query (analytics.dev.azure.com/{org}[/{project}]/_odata/v4.0-preview/{entity}) and follows @odata.nextLink to the last page or max_rows. query is the raw OData query string, e.g. $select=WorkItemId,Title&$filter=WorkItemType eq 'Bug' or $apply=.../groupby(...); path literals take single backslashes. Without project the query is organization-level. Rows come back inline, capped at 200 with a truncated note; with out_file the CLI writes {"value": [...]} there and the tool returns the row count and the first 3 rows. An invalid query returns Analytics' HTTP status and message (ado-search >= 1.20).

Related MCP server: Azure DevOps MCP Server

Prerequisites

• Node.js 18+

• ado-search CLI installed and on PATH

• An initialized ado-search data directory (ado-search init && ado-search sync)

Setup

1. Clone and build:

git clone https://github.com/HurleySk/ado-search-mcp.git
cd ado-search-mcp
npm install
npm run build

2. Create a config file (ado-search-mcp.json):

{
  "dataDir": "/path/to/your/ado-search/data-dir",
  "adoSearchPath": "ado-search"
}

3. Add to your project's .mcp.json:

{
  "mcpServers": {
    "ado-search": {
      "command": "node",
      "args": ["/path/to/ado-search-mcp/dist/server.js"],
      "env": {
        "ADO_SEARCH_CONFIG": "/path/to/ado-search-mcp.json"
      }
    }
  }
}

Configuration

The server looks for config in this order:

1. ADO_SEARCH_CONFIG environment variable (path to JSON config file)

2. ado-search-mcp.json sidecar file next to dist/server.js

3. ADO_DATA_DIR environment variable (data directory path only)

License

MIT