agentloopkit 0.25.0 → 0.26.0

package/README.md

@@ -60,8 +60,8 @@ npx agentloopkit init --local-only
 Pin the current version when you need repeatable CI or team setup:
 
 ```bash
-npx --yes agentloopkit@0.25.0 version
-npx --yes agentloopkit@0.25.0 init
+npx --yes agentloopkit@0.26.0 version
+npx --yes agentloopkit@0.26.0 init
 ```
 
 Run the CLI after install:
@@ -84,6 +84,7 @@ npx agentloopkit badge
 npx agentloopkit ci-summary
 npx agentloopkit release-notes
 npx agentloopkit npm-status
+npx agentloopkit mcp-server
 npx agentloopkit policy list
 npx agentloopkit policy show security
 npx agentloopkit policy status
@@ -146,6 +147,7 @@ pnpm build
 | `agentloop ci-summary`                  | Summarize CI context and local AgentLoop evidence                              |
 | `agentloop release-notes`               | Draft local release notes from changelog, git, task, and verification evidence |
 | `agentloop npm-status`                  | Check npm registry status without publishing                                   |
+| `agentloop mcp-server`                  | Start a read-only MCP stdio server for local AgentLoopKit state                |
 | `agentloop policy list`                 | List local safety policy files                                                 |
 | `agentloop policy show <policy>`        | Print a local safety policy without mutating files                             |
 | `agentloop policy status`               | Compare local policy files with bundled templates                              |
@@ -393,7 +395,7 @@ See `docs/ci-summary.md`.
 ```bash
 agentloop release-notes
 agentloop release-notes --from v0.19.0 --to HEAD
-agentloop release-notes --release-version 0.25.0
+agentloop release-notes --release-version 0.26.0
 agentloop release-notes --json
 agentloop release-notes --write
 ```
@@ -417,6 +419,18 @@ Use it after a publish attempt before saying npm has caught up. It runs `npm vie
 
 See `docs/npm-status.md`.
 
+## MCP Server
+
+AgentLoopKit can expose existing repo evidence to MCP clients through a read-only stdio server:
+
+```bash
+npx --yes agentloopkit@0.26.0 mcp-server
+```
+
+The server provides tools for status, next action, task contracts, active task, policies, latest verification report, and handoff summaries. It does not run verification commands, edit files, call external APIs, read `.env` contents, or upload data.
+
+See `docs/mcp.md` for client configuration, tool names, and registry notes.
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/docs/assets/readme/agentloopkit-verification.png" alt="AgentLoopKit verification report screenshot showing task context, passing command results, and reviewer handoff sections" width="100%">
 </p>
@@ -459,7 +473,19 @@ Use `agentloop check-gates --strict` as a review-evidence gate in pull request C
 
 CI-generated verification reports include GitHub Actions provenance when available, so reviewers can trace an artifact back to the workflow run that created it.
 
-See `docs/github-actions.md`, `examples/github-actions/`, `examples/gitlab-ci/`, and `examples/buildkite/` for copy-pasteable workflows. Pin `agentloopkit@0.25.0` or a newer vetted release when reproducibility matters.
+See `docs/github-actions.md`, `examples/github-actions/`, `examples/gitlab-ci/`, and `examples/buildkite/` for copy-pasteable workflows. Pin `agentloopkit@0.26.0` or a newer vetted release when reproducibility matters.
+
+## Other Install Channels
+
+npm and npx remain the primary install path. AgentLoopKit also ships release assets and maintainer artifacts for:
+
+- GitHub Releases: versioned tarballs for provenance and rollback.
+- GitHub Action: a thin wrapper for `agentloop` commands in CI.
+- Docker/GHCR: a minimal image that runs `agentloop`.
+- Homebrew: a formula under `packaging/homebrew/` for the tap release flow.
+- MCP Registry: read-only server metadata for MCP clients once the matching npm package is published.
+
+See `docs/distribution-channels.md` for current commands and maintainer release steps.
 
 ## PR Summaries
 

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { Command as Command20 } from "commander";
+import { Command as Command21 } from "commander";
 
 // src/cli/commands/init.ts
 import { Command } from "commander";
@@ -2210,6 +2210,7 @@ var topLevelCommands = [
   ["ci-summary", "Summarize CI context and AgentLoop evidence"],
   ["release-notes", "Generate deterministic release notes"],
   ["npm-status", "Check npm registry catch-up status"],
+  ["mcp-server", "Start the read-only MCP stdio server"],
   ["policy", "List or inspect local AgentLoopKit policies"],
   ["task", "List, inspect, update, or archive task contracts"],
   ["install-agent", "Install agent-specific instructions"],
@@ -3902,8 +3903,261 @@ function npmStatusCommand() {
   );
 }
 
+// src/cli/commands/mcp-server.ts
+import { Command as Command20 } from "commander";
+
+// src/mcp/server.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";
+
+// src/core/mcp-tools.ts
+import path23 from "path";
+import { readdir as readdir9, readFile as readFile18, stat as stat9 } from "fs/promises";
+var emptyInputSchema = {
+  type: "object",
+  properties: {},
+  additionalProperties: false
+};
+var tools = [
+  {
+    name: "agentloop_status",
+    description: "Read AgentLoopKit status, active task, latest verification, git state, and next action.",
+    inputSchema: emptyInputSchema
+  },
+  {
+    name: "agentloop_next",
+    description: "Read only the next recommended AgentLoopKit action and reason.",
+    inputSchema: emptyInputSchema
+  },
+  {
+    name: "agentloop_list_tasks",
+    description: "List local task contracts under the configured AgentLoopKit task directory.",
+    inputSchema: emptyInputSchema
+  },
+  {
+    name: "agentloop_show_active_task",
+    description: "Read the active task contract content when one is pinned.",
+    inputSchema: emptyInputSchema
+  },
+  {
+    name: "agentloop_list_policies",
+    description: "List local AgentLoopKit safety policy files.",
+    inputSchema: emptyInputSchema
+  },
+  {
+    name: "agentloop_read_policy",
+    description: "Read one local AgentLoopKit policy by policy name.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        policyName: {
+          type: "string",
+          description: 'Policy name, for example "security" or "security-policy.md".'
+        }
+      },
+      required: ["policyName"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "agentloop_latest_verification_report",
+    description: "Read the latest local verification report metadata and Markdown content.",
+    inputSchema: emptyInputSchema
+  },
+  {
+    name: "agentloop_list_handoffs",
+    description: "List recent local reviewer handoff summaries.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "number",
+          minimum: 1,
+          maximum: 50,
+          description: "Maximum handoff summaries to return. Defaults to 20."
+        }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "agentloop_latest_handoff",
+    description: "Read the latest local reviewer handoff summary Markdown content.",
+    inputSchema: emptyInputSchema
+  }
+];
+function listMcpTools() {
+  return [...tools];
+}
+function textResult(payload) {
+  return {
+    payload,
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2)
+      }
+    ]
+  };
+}
+function extractHeading7(markdown, fallback) {
+  return markdown.match(/^#\s+(.+)$/m)?.[1]?.trim() || fallback;
+}
+function toStoredPath3(cwd, absolutePath) {
+  return path23.relative(cwd, absolutePath).split(path23.sep).join("/");
+}
+async function readMarkdownArtifact(cwd, filePath, key) {
+  if (!filePath) return { [key]: null };
+  const content = await readFile18(filePath, "utf8");
+  const fileStat = await stat9(filePath);
+  return {
+    [key]: {
+      path: toStoredPath3(cwd, filePath),
+      title: extractHeading7(content, path23.basename(filePath, ".md")),
+      modifiedAt: fileStat.mtime.toISOString(),
+      content
+    }
+  };
+}
+async function listHandoffs(cwd, handoffsDir, limit) {
+  if (!await pathExists(handoffsDir)) return [];
+  const entries = await readdir9(handoffsDir, { withFileTypes: true });
+  const handoffs = await Promise.all(
+    entries.filter((entry) => entry.isFile() && prSummaryPattern.test(entry.name)).map(async (entry) => {
+      const filePath = path23.join(handoffsDir, entry.name);
+      const [content, fileStat] = await Promise.all([readFile18(filePath, "utf8"), stat9(filePath)]);
+      return {
+        path: toStoredPath3(cwd, filePath),
+        title: extractHeading7(content, path23.basename(filePath, ".md")),
+        modifiedAt: fileStat.mtime.toISOString(),
+        modifiedMs: fileStat.mtimeMs
+      };
+    })
+  );
+  return handoffs.sort((left, right) => {
+    if (left.modifiedMs !== right.modifiedMs) return right.modifiedMs - left.modifiedMs;
+    return left.path.localeCompare(right.path);
+  }).slice(0, limit).map((handoff) => ({
+    path: handoff.path,
+    title: handoff.title,
+    modifiedAt: handoff.modifiedAt
+  }));
+}
+function readStringArgument(args, key) {
+  const value = args?.[key];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new AgentLoopError(`MCP tool argument "${key}" must be a non-empty string.`);
+  }
+  return value;
+}
+function readLimitArgument(args) {
+  const value = args?.limit;
+  if (value === void 0) return 20;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 50) {
+    throw new AgentLoopError('MCP tool argument "limit" must be an integer from 1 to 50.');
+  }
+  return value;
+}
+async function callMcpTool(options) {
+  const config = await loadAgentLoopConfig(options.cwd);
+  switch (options.name) {
+    case "agentloop_status": {
+      const status = await getAgentLoopStatus({ cwd: options.cwd, config });
+      return textResult(status);
+    }
+    case "agentloop_next": {
+      const status = await getAgentLoopStatus({ cwd: options.cwd, config });
+      return textResult(status.nextAction);
+    }
+    case "agentloop_list_tasks": {
+      return textResult({ tasks: await listTasks({ cwd: options.cwd, config }) });
+    }
+    case "agentloop_show_active_task": {
+      const activeTask = await getActiveTask({ cwd: options.cwd, config });
+      if (!activeTask) return textResult({ task: null });
+      const task = await readTaskContract({ cwd: options.cwd, config, taskPath: activeTask.path });
+      return textResult({ task });
+    }
+    case "agentloop_list_policies": {
+      return textResult({ policies: await listPolicies({ cwd: options.cwd, config }) });
+    }
+    case "agentloop_read_policy": {
+      const policyName = readStringArgument(options.arguments, "policyName");
+      return textResult({
+        policy: await readPolicy({ cwd: options.cwd, config, policyName })
+      });
+    }
+    case "agentloop_latest_verification_report": {
+      const reportPath = await latestMarkdownFile(
+        path23.join(options.cwd, config.paths.reportsDir),
+        {
+          pattern: verificationReportPattern
+        }
+      );
+      return textResult(await readMarkdownArtifact(options.cwd, reportPath, "report"));
+    }
+    case "agentloop_list_handoffs": {
+      const limit = readLimitArgument(options.arguments);
+      return textResult({
+        handoffs: await listHandoffs(
+          options.cwd,
+          path23.join(options.cwd, config.paths.handoffsDir),
+          limit
+        )
+      });
+    }
+    case "agentloop_latest_handoff": {
+      const handoffPath = await latestMarkdownFile(
+        path23.join(options.cwd, config.paths.handoffsDir),
+        {
+          pattern: prSummaryPattern
+        }
+      );
+      return textResult(await readMarkdownArtifact(options.cwd, handoffPath, "handoff"));
+    }
+    default:
+      throw new AgentLoopError(`Unknown MCP tool: ${options.name}`);
+  }
+}
+
+// src/mcp/server.ts
+async function startAgentLoopMcpServer(options) {
+  const server = new Server(
+    {
+      name: "agentloopkit",
+      version: getPackageVersion()
+    },
+    {
+      capabilities: {
+        tools: {}
+      },
+      instructions: "Read-only AgentLoopKit server. Exposes local task contracts, policies, verification reports, handoffs, status, and next action. It does not run verification commands, read env file contents, call external APIs, upload files, or mutate repository files."
+    }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: listMcpTools()
+  }));
+  server.setRequestHandler(
+    CallToolRequestSchema,
+    async (request) => callMcpTool({
+      cwd: options.cwd,
+      name: request.params.name,
+      arguments: request.params.arguments
+    })
+  );
+  await server.connect(new StdioServerTransport());
+}
+
+// src/cli/commands/mcp-server.ts
+function mcpServerCommand() {
+  return new Command20("mcp-server").description("Start the read-only AgentLoopKit MCP stdio server").action(async () => {
+    await startAgentLoopMcpServer({ cwd: process.cwd() });
+  });
+}
+
 // src/cli/index.ts
-var program = new Command20();
+var program = new Command21();
 program.name("agentloop").description("A drop-in engineering loop for coding agents.").version(getPackageVersion(), "-V, --version", "print CLI version");
 program.addCommand(initCommand());
 program.addCommand(doctorCommand());
@@ -3919,6 +4173,7 @@ program.addCommand(badgeCommand());
 program.addCommand(ciSummaryCommand());
 program.addCommand(releaseNotesCommand());
 program.addCommand(npmStatusCommand());
+program.addCommand(mcpServerCommand());
 program.addCommand(policyCommand());
 program.addCommand(taskCommand());
 program.addCommand(installAgentCommand());