@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/azdo/src/mcp-server.ts

@@ -0,0 +1,209 @@
+#!/usr/bin/env bun
+/**
+ * The Azure DevOps MCP server (stdio) and its direct CLI mode.
+ *
+ * P4 (docs/architecture/cli-design.md §7 row P4, §12 Items row 15) folds the
+ * standalone `azure-devops-mcp` binary into `adl`: `adl mcp serve` calls
+ * `runMcpServer()` below, `adl mcp cli <args...>` calls `runCli()` from
+ * `./cli.ts` (see apps/cli/src/commands/mcp.ts). Both are exported functions
+ * that do nothing at import time — no `Server` instance is constructed and
+ * no handler is registered until `createServer()`/`runMcpServer()` is
+ * actually called — so importing this module from the `adl` binary's static
+ * import graph (required: `bun build --compile` only bundles static
+ * imports) never starts a server as a side effect of loading `adl` for an
+ * unrelated command.
+ *
+ * This file remains runnable standalone too (`bun src/mcp-server.ts[
+ * cli ...]`), unchanged, for anything not yet moved onto `adl mcp` (see
+ * `import.meta.main` below).
+ */
+import { runCli } from './cli.ts';
+import { dispatchTool } from './tool-dispatch.ts';
+export { pullRequestWriteArgs, pullRequestReviewArgs } from './tool-dispatch.ts';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import pkg from '../package.json' with { type: 'json' };
+
+/**
+ * Builds a fresh, unconnected `Server` with the 7 public tools registered.
+ * Called by `runMcpServer()` below; also usable directly by tests that want
+ * to drive the server without stdio (e.g. via an in-memory transport).
+ */
+export function createServer(): Server {
+  const server = new Server(
+    {
+      name: 'azure-devops-tools',
+      version: '1.0.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: 'pr_list_or_get',
+        description: 'List or get Azure DevOps pull requests. Provide id to get specific PR, omit to list.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'number', description: 'Pull request ID (optional)' },
+            status: { type: 'string', enum: ['active', 'completed', 'abandoned', 'all'], description: 'Filter by status (default: active)' },
+            repository: { type: 'string', description: 'Repository name; defaults to AZURE_DEVOPS_REPO' },
+          },
+        },
+      },
+      {
+        name: 'pr_create_or_update',
+        description: 'Create a pull request from the current branch into integration, or update a pull request.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            title: { type: 'string', description: 'Conventional lowercase title: <type>(<scope>): <subject>' },
+            description: { type: 'string', description: 'Must contain non-empty ## Summary, ## Why, and ## Changes sections' },
+            action: { type: 'string', enum: ['create', 'update'] },
+            pullRequestId: { type: 'number' },
+            autoComplete: { type: 'boolean' },
+            mergeStrategy: { type: 'string', enum: ['Squash'] },
+            deleteSourceBranch: { type: 'boolean' },
+            repository: { type: 'string', description: 'Repository name; defaults to AZURE_DEVOPS_REPO' },
+          },
+          required: ['action'],
+        },
+      },
+      {
+        name: 'pr_review',
+        description:
+          'Comment on and/or vote on an Azure DevOps pull request (docs/operations/agent-permissions.md rows 6-8). A builder (agent-tarun/agent-vivek) or agent-reviewer may comment on any pull request. Only agent-reviewer may vote, and only on a pull request whose real target is `main` — targetBranch must name that real target; a vote is refused when targetBranch is omitted or names `integration` (no vote gate there).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            pullRequestId: { type: 'number', description: 'Pull request ID' },
+            comment: { type: 'string', description: 'Posts a new top-level comment thread on the pull request' },
+            vote: {
+              type: 'string',
+              enum: ['approve', 'approve-with-suggestions', 'reset', 'wait-for-author', 'reject'],
+              description: 'agent-reviewer only, and only when targetBranch is main',
+            },
+            targetBranch: {
+              type: 'string',
+              description:
+                "Required with vote: the pull request's real target branch, as the caller believes it. Re-verified against Azure DevOps; refused on mismatch or when omitted.",
+            },
+            repository: { type: 'string', description: 'Repository name; defaults to AZURE_DEVOPS_REPO' },
+          },
+          required: ['pullRequestId'],
+        },
+      },
+      {
+        name: 'build_list_or_get',
+        description: 'List repository build definitions, branch builds, or one build with live stage progress and optional failed-task log tails.',
+        inputSchema: {
+          type: 'object',
+          properties: { buildId: { type: 'number' }, branch: { type: 'string' }, top: { type: 'number' }, tail: { type: 'number' } },
+        },
+      },
+      {
+        name: 'build_run',
+        description: 'Queue a build definition returned by build_list_or_get.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'number' },
+            branch: { type: 'string' },
+          },
+          required: ['id'],
+        },
+      },
+      {
+        name: 'workitem_list_or_get',
+        description: 'Get one or many tracked work items, or query the scoped backlog.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'number' }, ids: { type: 'array', items: { type: 'number' } }, type: { type: 'string', enum: ['Feature', 'Product Backlog Item', 'Bug'] }, state: { type: 'string' }, assignedTo: { type: 'string' }, limit: { type: 'number' }, raw: { type: 'boolean' },
+          },
+        },
+      },
+      {
+        name: 'workitem_create_or_update',
+        description: 'Create a tracked work item under its required parent, or update an existing item.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'number' }, type: { type: 'string', enum: ['Feature', 'Product Backlog Item', 'Bug'] },
+            title: { type: 'string' },
+            description: { type: 'string' }, parentId: { type: 'number' }, predecessors: { type: 'array', items: { type: 'number' } }, related: { type: 'array', items: { type: 'number' } }, fields: { type: 'object' }, state: { type: 'string' }, comment: { type: 'string' }, assignedTo: { type: 'string' }, acceptanceCriteria: { type: 'string' }, priority: { type: 'number' }, startDate: { type: 'string' }, targetDate: { type: 'string' },
+          },
+        },
+      },
+    ],
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+      const output = await dispatchTool(name, args ?? {});
+
+      return {
+        content: [{ type: 'text', text: output }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `Error: ${err}` }],
+        isError: true,
+      };
+    }
+  });
+
+  return server;
+}
+
+/**
+ * Runs the Azure DevOps MCP server over stdio until the transport closes.
+ * The server must start and answer initialize/tools/list without a session
+ * agent identity configured; see lib/agent-identity.ts's
+ * resolveAgentIdentity() for the lazy, per-tool-call check (P2).
+ */
+export async function runMcpServer(): Promise<void> {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+/** Direct CLI mode: `runCli` (./cli.ts) does the real work; this only maps a thrown error to stderr + exit code, exactly as the standalone binary's `cli` mode did. */
+export async function runCliMode(argv: readonly string[]): Promise<void> {
+  try {
+    await runCli(argv);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+}
+
+async function main(): Promise<void> {
+  if (process.argv[2] === 'cli') {
+    await runCliMode(process.argv.slice(3));
+    return;
+  }
+  await runMcpServer();
+}
+
+if (import.meta.main) {
+  // Supports global-tools' bun-compile idempotency check (`$executable
+  // --version`), which never spawns the server itself. Handled before
+  // main() connects the stdio transport, not as an MCP request.
+  if (process.argv.includes('--version')) {
+    console.log(pkg.version);
+    process.exit(0);
+  }
+  main().catch(console.error);
+}

package/packages/azdo/src/tool-dispatch.ts

@@ -0,0 +1,204 @@
+import { resolveAgentIdentity } from './lib/agent-identity.ts';
+import {
+  validatePullRequestDescription,
+  validatePullRequestMetadata,
+  validatePullRequestTitle,
+} from './lib/validate-pr-metadata.ts';
+import { prCreateOrUpdate, prListOrGet, type PrCreateOrUpdateArgs } from './azdo-pr.ts';
+import { prReview, VOTE_NAMES, type PrReviewArgs, type VoteName } from './azdo-pr-review.ts';
+import { buildListOrGet, buildRun } from './azdo-pl.ts';
+import { workitemCreateOrUpdate, workitemListOrGet } from './azdo-wit.ts';
+
+type PullRequestWriteArguments = {
+  action?: unknown;
+  pullRequestId?: unknown;
+  title?: unknown;
+  description?: unknown;
+  autoComplete?: unknown;
+  mergeStrategy?: unknown;
+  deleteSourceBranch?: unknown;
+  repository?: unknown;
+  sourceBranch?: unknown;
+  targetBranch?: unknown;
+};
+
+export function pullRequestWriteArgs(args: PullRequestWriteArguments): PrCreateOrUpdateArgs {
+  const action = args.action;
+  const errors: string[] = [];
+
+  if (action !== 'create' && action !== 'update') errors.push('action must be create or update');
+  if (args.sourceBranch !== undefined) errors.push('sourceBranch is not supported; PRs always use the current branch');
+  if (args.targetBranch !== undefined) errors.push('targetBranch is not supported; PRs always target integration');
+  if (action === 'create') {
+    errors.push(
+      ...validatePullRequestMetadata(
+        typeof args.title === 'string' ? args.title : '',
+        typeof args.description === 'string' ? args.description : '',
+      ),
+    );
+  }
+  if (action === 'update') {
+    if (!Number.isInteger(args.pullRequestId)) errors.push('pullRequestId is required for update');
+    if (typeof args.title === 'string') errors.push(...validatePullRequestTitle(args.title));
+    if (typeof args.description === 'string') errors.push(...validatePullRequestDescription(args.description));
+    if (
+      args.title === undefined &&
+      args.description === undefined &&
+      args.autoComplete !== true &&
+      args.mergeStrategy === undefined &&
+      args.deleteSourceBranch !== true
+    ) {
+      errors.push('update requires metadata or completion options');
+    }
+  }
+  if (args.mergeStrategy !== undefined && args.mergeStrategy !== 'Squash') {
+    errors.push('mergeStrategy must be Squash');
+  }
+  if (errors.length > 0) throw new Error(`Invalid pull request write:\n- ${errors.join('\n- ')}`);
+
+  return {
+    ...(action === 'update' ? { id: String(args.pullRequestId) } : {}),
+    ...(typeof args.title === 'string' ? { title: args.title } : {}),
+    ...(typeof args.description === 'string' ? { description: args.description } : {}),
+    ...(args.autoComplete === true || (action === 'create' && args.autoComplete !== false)
+      ? { autoComplete: true }
+      : {}),
+    ...(args.mergeStrategy === 'Squash' ? { mergeStrategy: args.mergeStrategy } : {}),
+    ...(args.deleteSourceBranch === true ? { deleteSourceBranch: true } : {}),
+    ...(typeof args.repository === 'string' ? { repository: args.repository } : {}),
+  };
+}
+
+type PullRequestReviewArguments = {
+  pullRequestId?: unknown;
+  comment?: unknown;
+  vote?: unknown;
+  targetBranch?: unknown;
+  repository?: unknown;
+};
+
+/** Same combined-error idiom as pullRequestWriteArgs() above — one thrown message listing every problem, not the first one found. */
+export function pullRequestReviewArgs(args: PullRequestReviewArguments): PrReviewArgs {
+  const errors: string[] = [];
+
+  const hasPullRequestId =
+    (typeof args.pullRequestId === 'string' && args.pullRequestId.trim() !== '') ||
+    (typeof args.pullRequestId === 'number' && Number.isInteger(args.pullRequestId));
+  if (!hasPullRequestId) errors.push('pullRequestId is required');
+
+  if (args.comment !== undefined && typeof args.comment !== 'string') errors.push('comment must be a string');
+  if (args.comment === undefined && args.vote === undefined) errors.push('supply comment, vote, or both');
+
+  if (args.vote !== undefined) {
+    if (typeof args.vote !== 'string' || !VOTE_NAMES.includes(args.vote as VoteName)) {
+      errors.push(`vote must be one of ${VOTE_NAMES.join(', ')}`);
+    }
+  }
+  if (args.targetBranch !== undefined && typeof args.targetBranch !== 'string') {
+    errors.push('targetBranch must be a string');
+  }
+  if (args.repository !== undefined && typeof args.repository !== 'string') errors.push('repository must be a string');
+
+  if (errors.length > 0) throw new Error(`Invalid pull request review:\n- ${errors.join('\n- ')}`);
+
+  return {
+    pullRequestId: String(args.pullRequestId),
+    ...(typeof args.comment === 'string' ? { comment: args.comment } : {}),
+    ...(typeof args.vote === 'string' ? { vote: args.vote as VoteName } : {}),
+    ...(typeof args.targetBranch === 'string' ? { targetBranch: args.targetBranch } : {}),
+    ...(typeof args.repository === 'string' ? { repository: args.repository } : {}),
+  };
+}
+
+export type ToolArguments = Record<string, unknown>;
+
+function assertString(args: ToolArguments, key: string, allowNumber = false): void {
+  const value = args[key];
+  if (value !== undefined && typeof value !== 'string' && !(allowNumber && typeof value === 'number')) {
+    throw new Error(`${key} must be a ${allowNumber ? 'string or number' : 'string'}`);
+  }
+}
+function assertInteger(args: ToolArguments, key: string): void {
+  if (args[key] !== undefined && !Number.isInteger(args[key])) throw new Error(`${key} must be an integer`);
+}
+function assertIntegerArray(args: ToolArguments, key: string): void {
+  if (args[key] !== undefined && (!Array.isArray(args[key]) || (args[key] as unknown[]).some((value) => !Number.isInteger(value)))) throw new Error(`${key} must be an array of integers`);
+}
+function assertBoolean(args: ToolArguments, key: string): void {
+  if (args[key] !== undefined && typeof args[key] !== 'boolean') throw new Error(`${key} must be a boolean`);
+}
+function validateToolArguments(name: string, args: ToolArguments): void {
+  switch (name) {
+    case 'build_list_or_get': ['buildId', 'top', 'tail'].forEach((key) => assertString(args, key, true)); assertString(args, 'branch'); return;
+    case 'build_run': assertString(args, 'id', true); assertString(args, 'branch'); return;
+    case 'workitem_list_or_get':
+      ['id', 'limit'].forEach((key) => assertInteger(args, key)); assertIntegerArray(args, 'ids');
+      ['type', 'state', 'assignedTo'].forEach((key) => assertString(args, key)); assertBoolean(args, 'raw'); return;
+    case 'workitem_create_or_update':
+      ['id', 'parentId', 'priority'].forEach((key) => assertInteger(args, key)); ['predecessors', 'related'].forEach((key) => assertIntegerArray(args, key));
+      ['type', 'title', 'description', 'state', 'comment', 'assignedTo', 'acceptanceCriteria', 'startDate', 'targetDate'].forEach((key) => assertString(args, key));
+      if (args.fields !== undefined && (typeof args.fields !== 'object' || args.fields === null || Array.isArray(args.fields))) throw new Error('fields must be an object');
+      return;
+    default: return;
+  }
+}
+
+/** Execute one public MCP operation. Both MCP and direct CLI modes use this path. */
+export async function dispatchTool(name: string, args: ToolArguments = {}): Promise<string> {
+  // MCP discovery remains identity-free; actual Azure DevOps work does not --
+  // reads and writes alike require the session's own agent identity (P2).
+  validateToolArguments(name, args);
+  resolveAgentIdentity();
+
+  switch (name) {
+    case 'pr_list_or_get': {
+      const repository = typeof args.repository === 'string' ? { repository: args.repository } : {};
+      if (args.id) return prListOrGet({ id: String(args.id), ...repository });
+      return prListOrGet({ status: (args.status as string | undefined) ?? 'active', ...repository });
+    }
+    case 'pr_create_or_update':
+      return prCreateOrUpdate(pullRequestWriteArgs(args));
+    case 'pr_review':
+      return prReview(pullRequestReviewArgs(args));
+    case 'build_list_or_get':
+      return buildListOrGet({
+        ...(args.buildId === undefined ? {} : { buildId: String(args.buildId) }),
+        ...(typeof args.branch === 'string' ? { branch: args.branch } : {}),
+        ...(args.top === undefined ? {} : { top: String(args.top) }),
+        ...(args.tail === undefined ? {} : { tail: String(args.tail) }),
+      });
+    case 'build_run':
+      if (args.id === undefined) throw new Error('id is required (a definition id, from build_list_or_get)');
+      return buildRun({ id: String(args.id), ...(typeof args.branch === 'string' ? { branch: args.branch } : {}) });
+    case 'workitem_list_or_get':
+      return workitemListOrGet({
+        ...(Number.isInteger(args.id) ? { id: args.id as number } : {}),
+        ...(Array.isArray(args.ids) ? { ids: args.ids as number[] } : {}),
+        ...(typeof args.type === 'string' ? { type: args.type } : {}),
+        ...(typeof args.state === 'string' ? { state: args.state } : {}),
+        ...(typeof args.assignedTo === 'string' ? { assignedTo: args.assignedTo } : {}),
+        ...(Number.isInteger(args.limit) ? { limit: args.limit as number } : {}),
+        ...(typeof args.raw === 'boolean' ? { raw: args.raw } : {}),
+      });
+    case 'workitem_create_or_update':
+      return workitemCreateOrUpdate({
+        ...(Number.isInteger(args.id) ? { id: args.id as number } : {}),
+        ...(typeof args.type === 'string' ? { type: args.type } : {}),
+        ...(typeof args.title === 'string' ? { title: args.title } : {}),
+        ...(typeof args.description === 'string' ? { description: args.description } : {}),
+        ...(Number.isInteger(args.parentId) ? { parentId: args.parentId as number } : {}),
+        ...(Array.isArray(args.predecessors) ? { predecessors: args.predecessors as number[] } : {}),
+        ...(Array.isArray(args.related) ? { related: args.related as number[] } : {}),
+        ...(args.fields && typeof args.fields === 'object' && !Array.isArray(args.fields) ? { fields: args.fields as Record<string, unknown> } : {}),
+        ...(typeof args.state === 'string' ? { state: args.state } : {}),
+        ...(typeof args.comment === 'string' ? { comment: args.comment } : {}),
+        ...(typeof args.assignedTo === 'string' ? { assignedTo: args.assignedTo } : {}),
+        ...(typeof args.acceptanceCriteria === 'string' ? { acceptanceCriteria: args.acceptanceCriteria } : {}),
+        ...(Number.isInteger(args.priority) ? { priority: args.priority as number } : {}),
+        ...(typeof args.startDate === 'string' ? { startDate: args.startDate } : {}),
+        ...(typeof args.targetDate === 'string' ? { targetDate: args.targetDate } : {}),
+      });
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}

package/packages/azdo/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "types": ["bun"],
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "../../scripts/azdo/**/*.ts"]
+}