# ado-search-mcp

MCP server that wraps the [ado-search](https://github.com/HurleySk/ado-search) CLI for Azure DevOps work item search and management.

## Tools

| Tool | Description |
|---|---|
| `ado_search` | Full-text search of indexed work items and wiki pages |
| `ado_grep` | Regex pattern search across work item fields |
| `ado_children` | List children/descendants of a work item |
| `ado_show` | Show full content of a work item or wiki page |
| `ado_list_links` | List links on a work item (live from ADO) |
| `ado_list_comments` | List comments on a work item, with their ids (live from ADO) |
| `ado_get_fields` | Read raw field values as JSON, HTML intact (live from ADO) |
| `ado_mentions` | List comments that @mention you, newest first (live from ADO) |
| `ado_test_plans` | List test plans with owner, area, iteration, dates (live from ADO) |
| `ado_test_suites` | List a test plan's suite tree (live from ADO) |
| `ado_test_cases` | List a suite's test cases with steps and testers (live from ADO) |
| `ado_test_points` | List a suite's test points with latest outcomes (live from ADO) |
| `ado_test_runs` | List test runs with outcome counts (live from ADO) |
| `ado_test_results` | List a test run's results with linked bugs (live from ADO) |
| `ado_wiki_show` | Read a wiki page or list page paths, any project (live from ADO) |
| `ado_wiki_update` | Replace a wiki page, ETag-guarded, with a dry-run diff |
| `ado_analytics` | Run a read-only Analytics OData query across all pages (live from ADO) |
| `ado_fetch` | Fetch specific work items by ID into local store |
| `ado_create` | Create a new work item |
| `ado_update` | Update an existing work item |
| `ado_add_comment` | Add a comment to a work item |
| `ado_edit_comment` | Replace the text of a comment |
| `ado_add_link` | Add a link between two work items |
| `ado_remove_link` | Remove a link between two work items |

`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).

## Prerequisites

- Node.js 18+
- [ado-search](https://github.com/HurleySk/ado-search) CLI installed and on PATH
- An initialized ado-search data directory (`ado-search init && ado-search sync`)

## Setup

1. Clone and build:

```bash
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`):

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

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

```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