ado-mcp

Architecture

cmd/ado                entrypoint: a urfave/cli command tree (mcp, test, note)
internal/config        environment configuration + validation
internal/client        generic JSON REST client (auth, api-version, paging, error mapping)
internal/server        MCP server wrapper, typed tool registration, read-only policy
internal/ado           Azure DevOps connection (one REST client per service host)
internal/ado/<area>    one package per service area: <area>.go (operations) + tools.go (tools)
internal/sevenpace     7pace Timetracker integration
internal/notes         local notes store (SQLite): notes + key/value config, optional 7pace sync

The CLI (full reference) exposes three commands: mcp (load config, register the enabled toolsets, and serve over stdio), test (verify credentials against Azure DevOps), and note (manage the local notes store).

Each service area follows the same shape: a service wrapping the shared REST clients exposes typed operations, and a Register function registers thin MCP tool handlers for them. Adding a new area is a matter of dropping in a package and listing it in cmd/ado.

Request flow

  1. cmd/ado’s mcp command loads configuration (internal/config) and assembles the server (internal/app), which registers every enabled toolset’s tools against internal/server.
  2. Each toolset’s tools.go derives a JSON Schema from its Go input/output structs, validates incoming arguments against it, and dispatches to the area’s service methods.
  3. service methods call out through internal/client, a generic JSON REST client that adds auth, resolves the right api-version (with automatic renegotiation on a 400), pages through continuationToken/$top/$skip, and maps non-2xx responses to a structured APIError.
  4. internal/ado owns one client.Client per Azure DevOps service host (dev.azure.com, vssps, vsrm, feeds, auditservice, almsearch, vsaex, extmgmt, advsec), so each area’s service only has to pick the right host, not rebuild routing.

The notes and sevenpace toolsets sit outside this Azure DevOps host graph: internal/notes talks to a local SQLite database, and internal/sevenpace talks to 7pace’s own API, joined to the rest of the server only through the optional notes_push_sevenpace/notes_pull_sevenpace sync tools.

Next: contribute

See Development for the build, test, lint, and protocol smoke-testing workflow.

This site is open source. Improve this page.