mcp-ado-browser 1.2.1

package/dist/src/errors.js

@@ -0,0 +1,88 @@
+/**
+ * Structured error taxonomy. Every tool failure maps to one of these so the MCP
+ * layer can emit a clean, machine-readable error instead of a stack trace.
+ *
+ * Sentinel strings (ADO_AUTH_EXPIRED, ADO_HTTP_xxx) are thrown deep in the
+ * transport (inside page.evaluate) where only strings survive serialization;
+ * they are re-hydrated into these classes at the transport boundary.
+ */
+export class AdoError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "AdoError";
+        this.code = code;
+        this.details = details;
+    }
+    toJSON() {
+        return { code: this.code, message: this.message, ...(this.details ? { details: this.details } : {}) };
+    }
+}
+/** Session cookie is dead / expired. The agent must re-run `authenticate`. */
+export class AuthRequiredError extends AdoError {
+    constructor(url) {
+        super("AUTH_REQUIRED", "AUTH_REQUIRED: not signed in to Azure DevOps. Call the `authenticate` tool (it opens a browser for interactive sign-in), then retry this request.", url ? { url } : undefined);
+        this.name = "AuthRequiredError";
+    }
+}
+/** A requested id/resource does not exist. */
+export class NotFoundError extends AdoError {
+    constructor(resource, id, url) {
+        super("NOT_FOUND", `NOT_FOUND: ${resource} '${id}' does not exist`, { resource, id, ...(url ? { url } : {}) });
+        this.name = "NotFoundError";
+    }
+}
+/** Any other non-2xx HTTP response. */
+export class HttpError extends AdoError {
+    status;
+    constructor(status, url, body) {
+        super("HTTP_ERROR", `ADO_HTTP_${status}: ${url}`, { status, url, ...(body ? { body: body.slice(0, 500) } : {}) });
+        this.name = "HttpError";
+        this.status = status;
+    }
+}
+/** Output JSON did not match its declared zod schema (schema drift). */
+export class ValidationError extends AdoError {
+    constructor(message, issues) {
+        super("VALIDATION_ERROR", `VALIDATION_ERROR: ${message}`, issues ? { issues } : undefined);
+        this.name = "ValidationError";
+    }
+}
+/** A feature that was empirically proven unavailable via the browser session. */
+export class EmpiricallyBlockedError extends AdoError {
+    constructor(message, evidence) {
+        super("EMPIRICALLY_BLOCKED", `EMPIRICALLY_BLOCKED: ${message}`, evidence);
+        this.name = "EmpiricallyBlockedError";
+    }
+}
+export class ConfigError extends AdoError {
+    constructor(message) {
+        super("CONFIG_ERROR", `CONFIG_ERROR: ${message}`);
+        this.name = "ConfigError";
+    }
+}
+/** Sentinel thrown from inside page.evaluate (only strings survive there). */
+export const SENTINEL = {
+    authExpired: "ADO_AUTH_EXPIRED",
+    httpPrefix: "ADO_HTTP_", // followed by `${status}:${url}`
+};
+/** Re-hydrate a sentinel string thrown across the page.evaluate boundary. */
+export function rehydrateSentinel(err, fallbackUrl) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes(SENTINEL.authExpired))
+        return new AuthRequiredError(fallbackUrl);
+    const m = msg.match(/ADO_HTTP_(\d+):(.*)$/s);
+    if (m) {
+        const status = Number(m[1]);
+        const url = m[2] || fallbackUrl || "";
+        if (status === 404)
+            return new NotFoundError("resource", url, url);
+        if (status === 401 || status === 403)
+            return new AuthRequiredError(url);
+        return new HttpError(status, url);
+    }
+    if (err instanceof AdoError)
+        return err;
+    return new AdoError("INTERNAL", msg);
+}

package/dist/src/index.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * Single binary entry point (mission §1: one package, one npx binary).
+ *
+ *   npx mcp-ado-browser                -> start the MCP stdio server (9 tools)
+ *   npx mcp-ado-browser authenticate   -> open a VISIBLE browser for interactive
+ *                                          (re)auth on the isolated profile, persist
+ *                                          the session, then re-validate headless.
+ *
+ * The authenticate subcommand is the "authenticate tool/mechanism" of mission §3,
+ * kept out of tools/list so that list stays at exactly the 9 data tools (§7).
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createMcpServer } from "./server.js";
+import { AdoRuntime, runAuthenticate, runLogout, runStatus } from "./runtime.js";
+import { applyArgs, parseArgs } from "./cli.js";
+import { log } from "./logger.js";
+const HELP = `mcp-ado-browser — read-only Azure DevOps for MCP, via your browser session (no PAT)
+
+Usage:
+  npx mcp-ado-browser [--org <org>] [--project <project>]      start the MCP stdio server
+  npx mcp-ado-browser authenticate --org <org>                 interactive sign-in (visible browser)
+  npx mcp-ado-browser status --org <org>                       show identity + whether the session is valid
+  npx mcp-ado-browser logout                                   clear the persisted session and cache
+
+Options (also settable via env, shown in []):
+  --org <org>                 [ADO_ORG]                 organization (required)
+  --project <project>         [ADO_PROJECT]             default project scope (optional; org-wide otherwise)
+  --channel <chrome|msedge>   [ADO_BROWSER_CHANNEL]     installed browser to drive (default chrome)
+  --user-data-dir <path>      [ADO_USER_DATA_DIR]       isolated persistent profile dir
+  --cache-ttl <seconds>       [ADO_CACHE_TTL_SECONDS]   cache TTL (default 900)
+  --api-version <v>           [ADO_API_VERSION]         force an api-version (else discovery/defaults)
+  --no-app-window             [ADO_APP_WINDOW=0]        normal browser window for auth (not chromeless)
+  --headed                    [ADO_HEADLESS=0]          run work with a visible window
+`;
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    applyArgs(parsed); // CLI flags -> process.env (precedence), before loadConfig
+    const sub = parsed.command;
+    if (sub === "authenticate" || sub === "auth") {
+        process.exitCode = await runAuthenticate();
+        return;
+    }
+    if (sub === "logout") {
+        process.exitCode = await runLogout();
+        return;
+    }
+    if (sub === "status" || sub === "whoami") {
+        process.exitCode = await runStatus();
+        return;
+    }
+    if (sub === "help" || process.argv.includes("--help") || process.argv.includes("-h")) {
+        process.stdout.write(HELP);
+        return;
+    }
+    // Default: MCP stdio server. The browser session is built lazily on first use so
+    // `initialize`/`tools/list` work without a browser, and `authenticate` can open a
+    // visible window from inside the running server.
+    const cfg = loadConfig();
+    const runtime = new AdoRuntime(cfg);
+    const server = createMcpServer({
+        getClient: () => runtime.getClient(),
+        authenticate: (timeoutSeconds) => runtime.authenticate(timeoutSeconds * 1000),
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log.info("MCP stdio server ready (mcp-ado-browser).");
+}
+main().catch((e) => {
+    log.error(`fatal: ${String(e)}`);
+    process.exit(1);
+});

package/dist/src/logger.js

@@ -0,0 +1,22 @@
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+const threshold = LEVELS[process.env.ADO_LOG_LEVEL ?? "info"] ?? LEVELS.info;
+function emit(level, msg, extra) {
+    if (LEVELS[level] < threshold)
+        return;
+    const line = extra === undefined ? `[${level}] ${msg}` : `[${level}] ${msg} ${safe(extra)}`;
+    process.stderr.write(line + "\n");
+}
+function safe(v) {
+    try {
+        return typeof v === "string" ? v : JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+export const log = {
+    debug: (m, e) => emit("debug", m, e),
+    info: (m, e) => emit("info", m, e),
+    warn: (m, e) => emit("warn", m, e),
+    error: (m, e) => emit("error", m, e),
+};

package/dist/src/mock/mock-ado-server.js

@@ -0,0 +1,108 @@
+/**
+ * MockAdoServer — a deterministic replay/route server over node:http.
+ *
+ * Keys routes by the *real* ADO host (forwarded by MockTransport in
+ * `x-ado-real-host`) + method + pathname, so all 5 ADO hosts share one port.
+ *
+ * It also ENFORCES the mandatory `X-TFS-FedAuthRedirect: Suppress` header: a
+ * request missing it gets 400. That turns mission §1's "header obligatoire" into
+ * a positive, testable assertion rather than a convention.
+ *
+ * Handlers are dynamic (not just static fixtures) so freshness tests can mutate
+ * the returned `System.Rev` between calls, and auth-expiry can be toggled live.
+ */
+import * as http from "node:http";
+export class MockAdoServer {
+    server;
+    routes = [];
+    baseUrl = "";
+    /** When true, every request returns 401 (simulates a dead session). */
+    failAuth = false;
+    /** Count of requests that arrived missing the mandatory FedAuthRedirect header. */
+    missingFedAuthHeaderCount = 0;
+    /** Register a handler. `host` is the real ADO host (e.g. "dev.azure.com"); omit for any. */
+    on(method, host, match, handler) {
+        const matcher = typeof match === "string"
+            ? (p) => p === match
+            : match instanceof RegExp
+                ? (p) => match.test(p)
+                : match;
+        this.routes.push({ method: method.toUpperCase(), host, match: matcher, handler });
+        return this;
+    }
+    /** Convenience: static JSON fixture for an exact method+host+path. */
+    fixture(method, host, pathname, response) {
+        return this.on(method, host, pathname, () => response);
+    }
+    async start() {
+        this.server = http.createServer((req, res) => this.handle(req, res));
+        await new Promise((resolve) => this.server.listen(0, "127.0.0.1", resolve));
+        const addr = this.server.address();
+        this.baseUrl = `http://127.0.0.1:${addr.port}`;
+        return this.baseUrl;
+    }
+    url() {
+        return this.baseUrl;
+    }
+    async stop() {
+        if (!this.server)
+            return;
+        await new Promise((resolve) => this.server.close(() => resolve()));
+        this.server = undefined;
+    }
+    async handle(req, res) {
+        const chunks = [];
+        for await (const c of req)
+            chunks.push(c);
+        const body = Buffer.concat(chunks).toString("utf8");
+        const realHost = req.headers["x-ado-real-host"] || "dev.azure.com";
+        const u = new URL(req.url ?? "/", `http://${realHost}`);
+        const mreq = {
+            method: (req.method ?? "GET").toUpperCase(),
+            host: realHost,
+            pathname: u.pathname,
+            query: u.searchParams,
+            body,
+            headers: req.headers,
+        };
+        // Enforce the mandatory anti-redirect header.
+        const fed = req.headers["x-tfs-fedauthredirect"];
+        if (fed !== "Suppress") {
+            this.missingFedAuthHeaderCount++;
+            return send(res, 400, { message: "missing or wrong X-TFS-FedAuthRedirect header" });
+        }
+        if (this.failAuth) {
+            return send(res, 401, { message: "Azure DevOps session expired (mock failAuth)" }, { "x-vss-mock": "failAuth" });
+        }
+        const route = this.routes.find((r) => r.method === mreq.method && (r.host === undefined || r.host === realHost) && r.match(mreq.pathname, mreq));
+        if (!route) {
+            return send(res, 404, { message: `no mock route for ${mreq.method} ${realHost}${mreq.pathname}` });
+        }
+        let out;
+        try {
+            out = await route.handler(mreq);
+        }
+        catch (e) {
+            return send(res, 500, { message: String(e) });
+        }
+        const status = out.status ?? 200;
+        const headers = { "x-vss-mock": "1", activityid: "mock-activity-0000", ...(out.headers ?? {}) };
+        if (out.buffer) {
+            res.writeHead(status, { "content-type": headers["content-type"] ?? "application/octet-stream", "content-length": String(out.buffer.length), ...stripContentHeaders(headers) });
+            res.end(out.buffer);
+            return;
+        }
+        return send(res, status, out.json ?? {}, headers);
+    }
+}
+function stripContentHeaders(h) {
+    const o = { ...h };
+    delete o["content-type"];
+    delete o["content-length"];
+    return o;
+}
+function send(res, status, json, headers = {}) {
+    const body = Buffer.from(JSON.stringify(json));
+    res.writeHead(status, { "content-type": "application/json", "content-length": String(body.length), ...headers });
+    res.end(body);
+}

package/dist/src/runtime.js

@@ -0,0 +1,155 @@
+/**
+ * Runtime wiring: builds the live AdoClient (browser session + cache + versions)
+ * and runs the interactive authenticate flow. Shared by the MCP server and the CLI.
+ */
+import { loadConfig, requireConnection } from "./config.js";
+import { BrowserSession } from "./browser/session.js";
+import { SqliteCache } from "./cache/sqlite-cache.js";
+import { AdoClient } from "./ado/client.js";
+import { VersionRegistry } from "./ado/versions.js";
+import { AuthRequiredError } from "./errors.js";
+import { log } from "./logger.js";
+/**
+ * Owns a SINGLE browser profile across the server's lifetime and arbitrates between
+ * the HEADLESS work session (data tools) and the HEADFUL interactive sign-in — so the
+ * profile lock is never held by two Chrome instances at once. This is what lets the
+ * `authenticate` MCP tool open the login window from inside the running server.
+ */
+export class AdoRuntime {
+    cfg;
+    versions;
+    cache = null;
+    session = null;
+    client = null;
+    // NOTE: org is validated lazily (getClient/authenticate), NOT in the constructor —
+    // so `initialize`/`tools/list` work over stdio even before any org is configured.
+    constructor(cfg = loadConfig()) {
+        this.cfg = cfg;
+        this.versions = new VersionRegistry(cfg.apiVersionOverride);
+    }
+    newSession() {
+        requireConnection(this.cfg); // throws CONFIG_ERROR if ADO_ORG is missing
+        return new BrowserSession({ userDataDir: this.cfg.userDataDir, channel: this.cfg.browserChannel, org: this.cfg.org, versions: this.versions });
+    }
+    getCache() {
+        if (!this.cache)
+            this.cache = new SqliteCache({ dbPath: this.cfg.cacheDbPath, defaultTtlSeconds: this.cfg.cacheTtlSeconds, ttlOverrides: this.cfg.cacheTtlOverrides });
+        return this.cache;
+    }
+    /** Lazily (re)build the HEADLESS work client, reusing the persisted session cookies. */
+    async getClient() {
+        if (this.client && this.session)
+            return this.client;
+        this.session = this.newSession();
+        await this.session.ensureLaunched(true);
+        this.client = new AdoClient({ transport: this.session.transport, hosts: this.session.hosts, versions: this.versions, project: this.cfg.project, cache: this.getCache() });
+        return this.client;
+    }
+    async disposeSession() {
+        if (this.session)
+            await this.session.close();
+        this.session = null;
+        this.client = null;
+    }
+    /**
+     * Interactive sign-in usable as an MCP tool. If the session is already valid it
+     * returns immediately (no window). Otherwise it releases the headless session,
+     * opens a VISIBLE window, polls until sign-in (bounded), persists, and closes the
+     * window so the next data call relaunches headless and reuses the cookies.
+     */
+    async authenticate(timeoutMs) {
+        try {
+            await this.getClient();
+            if (await this.session.validate()) {
+                return { authenticated: true, identity: null, message: "Already signed in — the persisted session is still valid." };
+            }
+        }
+        catch {
+            /* fall through to interactive sign-in */
+        }
+        await this.disposeSession(); // free the profile lock for the headful window
+        const auth = this.newSession();
+        try {
+            const id = await auth.authenticate(timeoutMs);
+            return { authenticated: true, identity: id.displayName, message: `Signed in as ${id.displayName}. Session persisted; tools are ready.` };
+        }
+        catch (e) {
+            if (e instanceof AuthRequiredError) {
+                return { authenticated: false, identity: null, message: "Timed out waiting for sign-in. A browser window was opened — complete the login, then call `authenticate` again." };
+            }
+            throw e;
+        }
+        finally {
+            await auth.close();
+        }
+    }
+    async close() {
+        await this.disposeSession();
+        this.cache?.close();
+        this.cache = null;
+    }
+}
+export async function buildLiveRuntime(cfg = loadConfig(), opts) {
+    requireConnection(cfg);
+    const versions = new VersionRegistry(cfg.apiVersionOverride);
+    const session = new BrowserSession({ userDataDir: cfg.userDataDir, channel: cfg.browserChannel, org: cfg.org, versions });
+    await session.ensureLaunched(opts?.headless ?? cfg.headless);
+    const cache = new SqliteCache({ dbPath: cfg.cacheDbPath, defaultTtlSeconds: cfg.cacheTtlSeconds, ttlOverrides: cfg.cacheTtlOverrides });
+    const client = new AdoClient({ transport: session.transport, hosts: session.hosts, versions, project: cfg.project, cache });
+    return { client, session, cache, versions, cfg };
+}
+/** Clear the persisted session (and cached data) — a local "sign out". No org needed. */
+export async function runLogout(cfg = loadConfig()) {
+    const fs = await import("node:fs");
+    let cleared = 0;
+    for (const target of [cfg.userDataDir, cfg.cacheDbPath]) {
+        if (fs.existsSync(target)) {
+            fs.rmSync(target, { recursive: true, force: true });
+            cleared++;
+        }
+    }
+    log.info(cleared > 0 ? `Logged out — browser session and cache cleared (${cfg.userDataDir}).` : "Nothing to clear — no persisted session found.");
+    return 0;
+}
+/** Report the configured org/profile and whether the persisted session is signed in. */
+export async function runStatus(cfg = loadConfig()) {
+    log.info(`Profile dir : ${cfg.userDataDir}`);
+    log.info(`Cache DB    : ${cfg.cacheDbPath}`);
+    if (!cfg.org) {
+        log.info("Org         : (not set — pass --org or set ADO_ORG)");
+        log.info("Signed in   : unknown (no org to check against)");
+        return 0;
+    }
+    log.info(`Org         : ${cfg.org}${cfg.project ? `   Project: ${cfg.project}` : ""}`);
+    const session = new BrowserSession({ userDataDir: cfg.userDataDir, channel: cfg.browserChannel, org: cfg.org, versions: new VersionRegistry(cfg.apiVersionOverride) });
+    try {
+        const id = await session.whoami();
+        log.info(id ? `Signed in   : yes — ${id.displayName}` : "Signed in   : no — run `authenticate` to sign in");
+        return id ? 0 : 1;
+    }
+    finally {
+        await session.close();
+    }
+}
+/** Interactive (re)authentication: opens a VISIBLE browser, waits for sign-in, persists session. */
+export async function runAuthenticate(cfg = loadConfig()) {
+    requireConnection(cfg);
+    const session = new BrowserSession({ userDataDir: cfg.userDataDir, channel: cfg.browserChannel, org: cfg.org, versions: new VersionRegistry(cfg.apiVersionOverride) });
+    const timeoutMs = (Number(process.env.ADO_AUTH_TIMEOUT_SECONDS) || 600) * 1000;
+    try {
+        const id = await session.authenticate(timeoutMs);
+        log.info(`Authentication OK — session persisted at ${cfg.userDataDir}. Identity: ${id.displayName}`);
+        // Prove the persisted session is reusable headless.
+        await session.close();
+        const ok = await session.validate();
+        log.info(ok ? "Headless re-validation OK (session reused without re-login)." : "WARNING: headless re-validation failed.");
+        return ok ? 0 : 1;
+    }
+    catch (e) {
+        log.error(`Authentication failed: ${String(e)}`);
+        return 1;
+    }
+    finally {
+        await session.close();
+    }
+}

package/dist/src/scrub.js

@@ -0,0 +1,38 @@
+/**
+ * Deterministic scrubbing of personal identifiers before anything is written to
+ * disk (fixtures, live-acceptance-report.json). Same input -> same pseudonym, so
+ * checksums stay stable across runs while emails/names/UPNs never leak.
+ */
+import * as crypto from "node:crypto";
+const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+/** Keys whose string values are treated as personal and pseudonymized wholesale. */
+const PERSONAL_KEYS = new Set(["displayname", "uniquename", "mail", "principalname", "emailaddress", "directoryalias", "authenticateduser"]);
+function pseudo(prefix, value) {
+    const h = crypto.createHash("sha256").update(value).digest("hex").slice(0, 8);
+    return `${prefix}-${h}`;
+}
+function scrubString(s) {
+    return s.replace(EMAIL_RE, (m) => `user-${crypto.createHash("sha256").update(m).digest("hex").slice(0, 8)}@example.invalid`);
+}
+export function scrub(value) {
+    return walk(value);
+}
+function walk(value) {
+    if (typeof value === "string")
+        return scrubString(value);
+    if (Array.isArray(value))
+        return value.map(walk);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (typeof v === "string" && PERSONAL_KEYS.has(k.toLowerCase())) {
+                out[k] = pseudo("person", v);
+            }
+            else {
+                out[k] = walk(v);
+            }
+        }
+        return out;
+    }
+    return value;
+}

package/dist/src/server.js

@@ -0,0 +1,51 @@
+/**
+ * MCP server wiring. Registers exactly the 9 data tools (tools/list contract,
+ * mission §7). `authenticate` is a subcommand of the same binary (see index.ts),
+ * not a 10th tool — keeping tools/list at exactly 9 while staying one package.
+ *
+ * Every tool result is a well-formed content block. Failures map to a structured
+ * AdoError JSON with isError:true — never a stack trace, never a partial success.
+ */
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { TOOL_DEFS } from "./tools/defs.js";
+import { toAdoError } from "./tools/errors.js";
+import { log } from "./logger.js";
+const AUTH_TOOL_DESCRIPTION = "Sign in to Azure DevOps by opening a VISIBLE browser window for interactive login (MFA included). Run this once (or whenever a tool returns AUTH_REQUIRED). The session is persisted on an isolated profile and reused headless afterward — no PAT or token is ever stored.";
+export function createMcpServer(deps) {
+    const server = new McpServer({ name: deps.name ?? "mcp-ado-browser", version: deps.version ?? "0.0.0" });
+    for (const t of TOOL_DEFS) {
+        server.registerTool(t.name, { description: t.description, inputSchema: t.inputShape }, async (args) => {
+            try {
+                const client = await deps.getClient();
+                const out = await t.run(client, args);
+                return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
+            }
+            catch (e) {
+                const err = toAdoError(e);
+                log.warn(`tool ${t.name} failed: ${err.code} ${err.message}`);
+                return { isError: true, content: [{ type: "text", text: JSON.stringify(err.toJSON()) }] };
+            }
+        });
+    }
+    // The `authenticate` tool — folds the interactive sign-in into the MCP itself so
+    // setup is a single client-config step (no separate terminal command).
+    server.registerTool("authenticate", {
+        description: AUTH_TOOL_DESCRIPTION,
+        inputSchema: { timeoutSeconds: z.number().int().positive().max(600).optional().describe("How long to wait for sign-in (default 240s).") },
+    }, async (args) => {
+        if (!deps.authenticate) {
+            return { isError: true, content: [{ type: "text", text: JSON.stringify({ code: "CONFIG_ERROR", message: "Interactive authenticate is unavailable here. Run: npx mcp-ado-browser authenticate --org <org>" }) }] };
+        }
+        try {
+            const result = await deps.authenticate(args.timeoutSeconds ?? 240);
+            return { isError: !result.authenticated, content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (e) {
+            const err = toAdoError(e);
+            log.warn(`authenticate failed: ${err.code} ${err.message}`);
+            return { isError: true, content: [{ type: "text", text: JSON.stringify(err.toJSON()) }] };
+        }
+    });
+    return server;
+}

package/dist/src/tools/defs.js

@@ -0,0 +1,128 @@
+/**
+ * The 9 read tools (mission §5). Each declares a zod INPUT shape (for tools/list
+ * + input validation) and a zod OUTPUT schema (drift detection). Handlers map
+ * arguments onto AdoClient calls and validate the result before returning.
+ *
+ * The same defs power both the live MCP server and the offline verify harness,
+ * so what the harness asserts is exactly what ships.
+ */
+import { z } from "zod";
+import { CommentDetailsSchema, DownloadedArtifactSchema, FeedsBrowseSchema, ProjectsListSchema, PullRequestCommentsSchema, PullRequestSchema, PullRequestSearchResultSchema, RepositoriesListSchema, WorkItemCommentsSchema, WorkItemSchema, WorkItemSearchResultSchema, validateOutput, } from "../ado/schemas.js";
+function def(d) {
+    return d;
+}
+export const TOOL_DEFS = [
+    def({
+        name: "list_projects",
+        description: "List ALL Azure DevOps projects the user can access in the organization (GET _apis/projects). Use this to discover projects to browse.",
+        inputShape: {},
+        outputSchema: ProjectsListSchema,
+        run: (c) => c.listProjects().then((r) => validateOutput(ProjectsListSchema, r, "list_projects")),
+    }),
+    def({
+        name: "list_repositories",
+        description: "List ALL Git repositories the user can access across the organization (GET _apis/git/repositories), or within one project. Returns id, name and owning project for each repo.",
+        inputShape: {
+            project: z.string().optional().describe("Restrict to a single project (optional; omit for org-wide)."),
+        },
+        outputSchema: RepositoriesListSchema,
+        run: (c, a) => c.listRepositories(a).then((r) => validateOutput(RepositoriesListSchema, r, "list_repositories")),
+    }),
+    def({
+        name: "search_work_items",
+        description: "Search/browse work items ORG-WIDE (cross-project) by default. Backend is WIQL (POST _apis/wit/wiql); pass `text` for full-text Search (almsearch), or `project` to scope to one project. Returns id + summary fields.",
+        inputShape: {
+            wiql: z.string().optional().describe("Raw WIQL query. If omitted, a bounded recent-items query (@Me) is used."),
+            text: z.string().optional().describe("Full-text search string (uses almsearch; falls back to WIQL)."),
+            project: z.string().optional().describe("Restrict to a single project (optional; omit for org-wide)."),
+            top: z.number().int().positive().max(200).optional().describe("Max results (default 50)."),
+        },
+        outputSchema: WorkItemSearchResultSchema,
+        run: (c, a) => c.searchWorkItems(a).then((r) => validateOutput(WorkItemSearchResultSchema, r, "search_work_items")),
+    }),
+    def({
+        name: "get_work_item",
+        description: "Get a single work item with $expand=all, including `relations` (hierarchy, Related, and ArtifactLink PR references resolved).",
+        inputShape: {
+            id: z.number().int().positive().describe("Work item id."),
+            bypassCache: z.boolean().optional().describe("Force a fresh fetch, ignoring the cache."),
+        },
+        outputSchema: WorkItemSchema,
+        run: (c, a) => c.getWorkItem(a.id, { bypassCache: a.bypassCache }).then((r) => validateOutput(WorkItemSchema, r, "get_work_item")),
+    }),
+    def({
+        name: "get_work_item_comments",
+        description: "Get the full discussion for a work item (GET _apis/wit/workItems/{id}/comments — a SEPARATE endpoint, not part of $expand).",
+        inputShape: { id: z.number().int().positive().describe("Work item id.") },
+        outputSchema: WorkItemCommentsSchema,
+        run: (c, a) => c.getWorkItemComments(a.id).then((r) => validateOutput(WorkItemCommentsSchema, r, "get_work_item_comments")),
+    }),
+    def({
+        name: "get_comment_details",
+        description: "Resolve a work item (and optionally a specific comment) AND download all related attachments (work-item AttachedFile relations + attachments referenced in the comment body). Returns metadata + downloaded content stats (size, sha256).",
+        inputShape: {
+            workItemId: z.number().int().positive().describe("Work item id."),
+            commentId: z.number().int().positive().optional().describe("Specific comment id to resolve (optional)."),
+            saveDir: z.string().optional().describe("Directory to write downloaded attachment files to (optional)."),
+        },
+        outputSchema: CommentDetailsSchema,
+        run: (c, a) => c.getCommentDetails(a).then((r) => validateOutput(CommentDetailsSchema, r, "get_comment_details")),
+    }),
+    def({
+        name: "search_pull_requests",
+        description: "Search pull requests ORG-WIDE by default, or within a repo (repoId) or a project. Filters: status, creatorId, targetRef. (GET _apis/git/pullrequests)",
+        inputShape: {
+            repoId: z.string().optional().describe("Repository id (GUID) or name (omit for org-wide / project-wide search)."),
+            project: z.string().optional().describe("Restrict to a single project (optional)."),
+            status: z.string().optional().describe("active | completed | abandoned | all."),
+            creatorId: z.string().optional().describe("Creator identity id."),
+            targetRef: z.string().optional().describe("Target branch ref name, e.g. refs/heads/main."),
+            top: z.number().int().positive().max(200).optional(),
+        },
+        outputSchema: PullRequestSearchResultSchema,
+        run: (c, a) => c.searchPullRequests(a).then((r) => validateOutput(PullRequestSearchResultSchema, r, "search_pull_requests")),
+    }),
+    def({
+        name: "get_pull_request",
+        description: "Get a pull request with metadata, branches, reviewers and linked work items. Resolved org-wide — repoId may be a GUID or a repository name.",
+        inputShape: {
+            repoId: z.string().describe("Repository id (GUID) or name."),
+            prId: z.number().int().positive().describe("Pull request id."),
+        },
+        outputSchema: PullRequestSchema,
+        run: (c, a) => c.getPullRequest(a).then((r) => validateOutput(PullRequestSchema, r, "get_pull_request")),
+    }),
+    def({
+        name: "get_pull_request_comments",
+        description: "Get PR threads (system vs human). Resolved org-wide — repoId may be a GUID or a repository name.",
+        inputShape: {
+            repoId: z.string().describe("Repository id (GUID) or name."),
+            prId: z.number().int().positive().describe("Pull request id."),
+        },
+        outputSchema: PullRequestCommentsSchema,
+        run: (c, a) => c.getPullRequestComments(a).then((r) => validateOutput(PullRequestCommentsSchema, r, "get_pull_request_comments")),
+    }),
+    def({
+        name: "search_feeds",
+        description: "Browse Azure Artifacts feeds (GET feeds.dev.azure.com/_apis/packaging/feeds). Pass feedId to also list packages + versions.",
+        inputShape: { feedId: z.string().optional().describe("Feed id to browse for packages (optional).") },
+        outputSchema: FeedsBrowseSchema,
+        run: (c, a) => c.searchFeeds(a).then((r) => validateOutput(FeedsBrowseSchema, r, "search_feeds")),
+    }),
+    def({
+        name: "download_artifact",
+        description: "Download a package artifact (.nupkg / .tgz) from a feed via the browser session (pkgs.dev.azure.com). Validates archive integrity (size, sha256, valid zip/tgz) for re-hosting.",
+        inputShape: {
+            feedId: z.string().describe("Feed id (or name)."),
+            packageName: z.string().describe("Package name."),
+            version: z.string().describe("Exact version to download."),
+            protocol: z.enum(["nuget", "npm"]).describe("Package protocol."),
+            saveDir: z.string().describe("Directory to write the downloaded artifact to."),
+        },
+        outputSchema: DownloadedArtifactSchema,
+        run: (c, a) => c.downloadArtifact(a).then((r) => validateOutput(DownloadedArtifactSchema, r, "download_artifact")),
+    }),
+];
+export function toolByName(name) {
+    return TOOL_DEFS.find((t) => t.name === name);
+}