@martinloop/mcp 0.1.1

package/README.md

@@ -0,0 +1,59 @@
+# @martinloop/mcp
+
+Martin Loop's installable Model Context Protocol server.
+
+It exposes three MCP tools over stdio:
+
+- `martin_run`
+- `martin_inspect`
+- `martin_status`
+
+## Quickstart
+
+Run the packaged server directly:
+
+```sh
+npx @martinloop/mcp
+```
+
+Add it to Claude Code:
+
+```sh
+# macOS/Linux
+claude mcp add --scope user martin-loop -- npx @martinloop/mcp
+
+# Windows PowerShell/cmd
+claude mcp add --scope user martin-loop cmd /c "npx @martinloop/mcp"
+```
+
+For clients that want explicit command/args:
+
+- Command: `npx`
+- Args: `@martinloop/mcp`
+
+## Official MCP Registry
+
+This package is prepared for the official MCP Registry metadata flow:
+
+- npm package: `@martinloop/mcp`
+- registry server name: `io.github.keesan12/martin-loop`
+- manifest file: `packages/mcp/server.json`
+
+The official registry publish flow is separate from npm publication. After publishing the package to npm, run the publisher from `packages/mcp`:
+
+```sh
+mcp-publisher login github
+mcp-publisher publish
+```
+
+## Local Verification
+
+From the repository root:
+
+```sh
+pnpm --filter @martinloop/mcp build
+pnpm --filter @martinloop/mcp test
+pnpm --filter @martinloop/mcp smoke:pack
+```
+
+`smoke:pack` packs the tarball, launches it through `npx`, performs the MCP handshake, lists tools, and verifies a `martin_status` call.

package/dist/server.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Martin Loop MCP Server
+ *
+ * Exposes three tools over the Model Context Protocol (stdio transport):
+ *   martin_run      — execute a full Martin loop on a coding task
+ *   martin_inspect  — summarise a saved loop record file
+ *   martin_status   — return cost and pressure state from a loop record
+ *
+ * Setup (Claude Code):
+ *   macOS/Linux: claude mcp add --scope user martin-loop -- npx @martinloop/mcp
+ *   Windows:     claude mcp add --scope user martin-loop cmd /c "npx @martinloop/mcp"
+ *
+ * Packaged smoke test:
+ *   pnpm --filter @martinloop/mcp smoke:pack
+ *
+ * Manual start:
+ *   node dist/server.js
+ */
+export {};

package/dist/server.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * Martin Loop MCP Server
+ *
+ * Exposes three tools over the Model Context Protocol (stdio transport):
+ *   martin_run      — execute a full Martin loop on a coding task
+ *   martin_inspect  — summarise a saved loop record file
+ *   martin_status   — return cost and pressure state from a loop record
+ *
+ * Setup (Claude Code):
+ *   macOS/Linux: claude mcp add --scope user martin-loop -- npx @martinloop/mcp
+ *   Windows:     claude mcp add --scope user martin-loop cmd /c "npx @martinloop/mcp"
+ *
+ * Packaged smoke test:
+ *   pnpm --filter @martinloop/mcp smoke:pack
+ *
+ * Manual start:
+ *   node dist/server.js
+ */
+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 { getStatusTool } from "./tools/get-status.js";
+import { inspectLoopTool } from "./tools/inspect-loop.js";
+import { runLoopTool } from "./tools/run-loop.js";
+const server = new Server({ name: "martin-loop", version: "0.1.1" }, { capabilities: { tools: {} } });
+// ---------------------------------------------------------------------------
+// Tool manifest
+// ---------------------------------------------------------------------------
+server.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: [
+        {
+            name: "martin_run",
+            description: "Execute a full Martin Loop on a coding task. Martin spawns the selected agent CLI (claude or codex), runs the task, classifies failures, and retries within the specified budget. Returns the loop outcome including lifecycle state, attempt count, and spend.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    objective: {
+                        type: "string",
+                        description: "The coding task to complete. Be specific about what needs to change."
+                    },
+                    workingDirectory: {
+                        type: "string",
+                        description: "Absolute path to the project root. Defaults to the current working directory."
+                    },
+                    engine: {
+                        type: "string",
+                        enum: ["claude", "codex"],
+                        description: "Which agent CLI to use. Defaults to 'claude'."
+                    },
+                    model: {
+                        type: "string",
+                        description: "Model override passed to the CLI (e.g. 'claude-opus-4-6', 'o3')."
+                    },
+                    maxUsd: {
+                        type: "number",
+                        description: "Hard budget ceiling in USD. Defaults to 25."
+                    },
+                    maxIterations: {
+                        type: "number",
+                        description: "Maximum number of loop attempts. Defaults to 8."
+                    },
+                    maxTokens: {
+                        type: "number",
+                        description: "Maximum total tokens across all attempts. Defaults to 80000."
+                    },
+                    verificationPlan: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Shell commands that must all exit 0 for the task to be considered complete (e.g. ['pnpm test', 'pnpm build'])."
+                    },
+                    workspaceId: {
+                        type: "string",
+                        description: "Workspace identifier for telemetry. Defaults to 'ws_mcp'."
+                    },
+                    projectId: {
+                        type: "string",
+                        description: "Project identifier for telemetry. Defaults to 'proj_mcp'."
+                    }
+                },
+                required: ["objective"]
+            }
+        },
+        {
+            name: "martin_inspect",
+            description: "Summarise a saved Martin loop record file. Reads a JSON file containing one or more LoopRecords and returns portfolio-level statistics: total spend, avoided spend, token counts, and loop counts.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    file: {
+                        type: "string",
+                        description: "Absolute or relative path to a LoopRecord JSON file."
+                    }
+                },
+                required: ["file"]
+            }
+        },
+        {
+            name: "martin_status",
+            description: "Return the current budget and cost state of a Martin loop record. Useful for monitoring in-progress or completed loops.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    loopJson: {
+                        type: "string",
+                        description: "JSON-serialized LoopRecord."
+                    }
+                },
+                required: ["loopJson"]
+            }
+        }
+    ]
+}));
+// ---------------------------------------------------------------------------
+// Tool dispatch
+// ---------------------------------------------------------------------------
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        if (name === "martin_run") {
+            const input = args;
+            const output = await runLoopTool(input);
+            return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+        }
+        if (name === "martin_inspect") {
+            const input = args;
+            const output = await inspectLoopTool(input);
+            return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+        }
+        if (name === "martin_status") {
+            const input = args;
+            const output = getStatusTool(input);
+            return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+        }
+        return {
+            content: [{ type: "text", text: `Unknown tool: ${name}` }],
+            isError: true
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Tool error: ${message}` }],
+            isError: true
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=server.js.map

package/dist/tools/get-status.d.ts

@@ -0,0 +1,18 @@
+export interface GetStatusInput {
+    /** JSON-serialized LoopRecord. */
+    loopJson: string;
+}
+export interface GetStatusOutput {
+    loopId: string;
+    status: string;
+    lifecycleState: string;
+    attempts: number;
+    costUsd: number;
+    avoidedUsd: number;
+    pressure: string;
+    shouldStop: boolean;
+    remainingBudgetUsd: number;
+    remainingIterations: number;
+    remainingTokens: number;
+}
+export declare function getStatusTool(input: GetStatusInput): GetStatusOutput;

package/dist/tools/get-status.js

@@ -0,0 +1,23 @@
+import { evaluateCostGovernor } from "../vendor/core/index.js";
+export function getStatusTool(input) {
+    const loop = JSON.parse(input.loopJson);
+    const costState = evaluateCostGovernor({
+        budget: loop.budget,
+        cost: loop.cost,
+        attemptsUsed: loop.attempts.length
+    });
+    return {
+        loopId: loop.loopId,
+        status: loop.status,
+        lifecycleState: loop.lifecycleState,
+        attempts: loop.attempts.length,
+        costUsd: loop.cost.actualUsd,
+        avoidedUsd: loop.cost.avoidedUsd,
+        pressure: costState.pressure,
+        shouldStop: costState.shouldStop,
+        remainingBudgetUsd: costState.remainingBudgetUsd,
+        remainingIterations: costState.remainingIterations,
+        remainingTokens: costState.remainingTokens
+    };
+}
+//# sourceMappingURL=get-status.js.map

package/dist/tools/inspect-loop.d.ts

@@ -0,0 +1,11 @@
+import { type PortfolioSnapshot } from "../vendor/contracts/index.js";
+export interface InspectLoopInput {
+    /** Absolute or relative path to a JSON file containing a LoopRecord or LoopRecord[]. */
+    file: string;
+}
+export interface InspectLoopOutput {
+    source: string;
+    loopCount: number;
+    portfolio: PortfolioSnapshot;
+}
+export declare function inspectLoopTool(input: InspectLoopInput): Promise<InspectLoopOutput>;

package/dist/tools/inspect-loop.js

@@ -0,0 +1,15 @@
+import { readFile } from "node:fs/promises";
+import { buildPortfolioSnapshot } from "../vendor/contracts/index.js";
+export async function inspectLoopTool(input) {
+    const raw = await readFile(input.file, "utf8");
+    const parsed = JSON.parse(raw);
+    const loops = Array.isArray(parsed)
+        ? parsed
+        : [parsed];
+    return {
+        source: input.file,
+        loopCount: loops.length,
+        portfolio: buildPortfolioSnapshot(loops)
+    };
+}
+//# sourceMappingURL=inspect-loop.js.map

package/dist/tools/run-loop.d.ts

@@ -0,0 +1,22 @@
+export interface RunLoopInput {
+    objective: string;
+    workingDirectory?: string;
+    engine?: "claude" | "codex";
+    model?: string;
+    maxUsd?: number;
+    maxIterations?: number;
+    maxTokens?: number;
+    verificationPlan?: string[];
+    workspaceId?: string;
+    projectId?: string;
+}
+export interface RunLoopOutput {
+    status: string;
+    lifecycleState: string;
+    reason: string;
+    attempts: number;
+    costUsd: number;
+    verificationPassed: boolean;
+    loopId: string;
+}
+export declare function runLoopTool(input: RunLoopInput): Promise<RunLoopOutput>;

package/dist/tools/run-loop.js

@@ -0,0 +1,50 @@
+import { createClaudeCliAdapter, createCodexCliAdapter, createStubDirectProviderAdapter } from "../vendor/adapters/index.js";
+import { runMartin } from "../vendor/core/index.js";
+import { DEFAULT_BUDGET } from "../vendor/contracts/index.js";
+export async function runLoopTool(input) {
+    const workingDirectory = input.workingDirectory ?? process.cwd();
+    const engine = input.engine ?? "claude";
+    const model = input.model;
+    const adapter = process.env.MARTIN_LIVE === "false"
+        ? createStubDirectProviderAdapter({ label: "Stub adapter (MARTIN_LIVE=false)", providerId: "stub", model: "stub" })
+        : engine === "codex"
+            ? createCodexCliAdapter({ workingDirectory, ...(model ? { model } : {}) })
+            : createClaudeCliAdapter({ workingDirectory, ...(model ? { model } : {}) });
+    const partialBudget = {};
+    if (input.maxUsd !== undefined) {
+        partialBudget.maxUsd = input.maxUsd;
+    }
+    if (input.maxIterations !== undefined) {
+        partialBudget.maxIterations = input.maxIterations;
+    }
+    if (input.maxTokens !== undefined) {
+        partialBudget.maxTokens = input.maxTokens;
+    }
+    const budget = {
+        ...DEFAULT_BUDGET,
+        ...partialBudget
+    };
+    const result = await runMartin({
+        workspaceId: input.workspaceId ?? "ws_mcp",
+        projectId: input.projectId ?? "proj_mcp",
+        task: {
+            title: input.objective.slice(0, 100),
+            objective: input.objective,
+            verificationPlan: input.verificationPlan ?? []
+        },
+        budget,
+        adapter
+    });
+    const lastAttempt = result.loop.attempts.at(-1);
+    const verificationPassed = lastAttempt !== undefined && result.decision.lifecycleState === "completed";
+    return {
+        status: result.loop.status,
+        lifecycleState: result.decision.lifecycleState,
+        reason: result.decision.reason,
+        attempts: result.loop.attempts.length,
+        costUsd: result.loop.cost.actualUsd,
+        verificationPassed,
+        loopId: result.loop.loopId
+    };
+}
+//# sourceMappingURL=run-loop.js.map

package/dist/vendor/adapters/claude-cli.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Real agent-CLI adapters.
+ *
+ * Exports a generic factory (`createAgentCliAdapter`) and two pre-configured
+ * factories (`createClaudeCliAdapter`, `createCodexCliAdapter`) that spawn
+ * the respective AI coding CLI as a child subprocess.
+ *
+ * Usage in CLI:
+ *   createClaudeCliAdapter({ workingDirectory: process.cwd() })
+ *   createCodexCliAdapter({ workingDirectory: process.cwd() })
+ *
+ * MCP tools and integration tests use the same factories.
+ */
+import type { MartinAdapter } from "../core/index.js";
+import { type SpawnLike } from "./cli-bridge.js";
+/**
+ * Given a prompt string, returns the full argv array to pass to spawn().
+ * Example for Claude:  (p) => ["--print", p, "--dangerously-skip-permissions"]
+ * Example for Codex:   (p) => ["--full-auto", p]
+ */
+export type CliArgsBuilder = (prompt: string) => string[];
+export interface AgentCliAdapterOptions {
+    /** The executable to spawn (e.g. "claude", "codex"). */
+    command: string;
+    /** Converts a prompt string into the argv array passed to spawn(). */
+    argsBuilder: CliArgsBuilder;
+    /** Adapter ID suffix. Defaults to command. */
+    adapterIdSuffix?: string;
+    /** Working directory for all subprocesses. Defaults to process.cwd(). */
+    workingDirectory?: string;
+    /** Timeout for the agent subprocess in ms. Defaults to 300_000 (5 min). */
+    timeoutMs?: number;
+    /** Timeout per verification command in ms. Defaults to 60_000 (1 min). */
+    verifyTimeoutMs?: number;
+    /** Human-readable label shown in loop records. */
+    label?: string;
+    /** Model name surfaced in adapter metadata (also used for cost estimation). */
+    model?: string;
+    /**
+     * Whether the CLI outputs JSON when --output-format json is passed.
+     * Set to false for CLIs that don't support this flag (e.g. Codex).
+     * Defaults to true for Claude.
+     */
+    supportsJsonOutput?: boolean;
+    /** Test-only override for subprocess spawning. */
+    spawnImpl?: SpawnLike;
+}
+export interface ClaudeCliAdapterOptions {
+    workingDirectory?: string;
+    timeoutMs?: number;
+    verifyTimeoutMs?: number;
+    label?: string;
+    /** Override the model passed via --model flag. */
+    model?: string;
+    /** Extra args appended after core args (before prompt). */
+    extraArgs?: string[];
+    spawnImpl?: SpawnLike;
+}
+export interface CodexCliAdapterOptions {
+    workingDirectory?: string;
+    timeoutMs?: number;
+    verifyTimeoutMs?: number;
+    label?: string;
+    /** Override the model passed via --model flag. */
+    model?: string;
+    /** Run in full-auto mode (--full-auto). Defaults to true. */
+    fullAuto?: boolean;
+    /** Extra args appended after core args (before prompt). */
+    extraArgs?: string[];
+    spawnImpl?: SpawnLike;
+}
+export declare function createAgentCliAdapter(options: AgentCliAdapterOptions): MartinAdapter;
+/**
+ * Spawns `claude --output-format json --print "<prompt>" --dangerously-skip-permissions [extraArgs]`.
+ *
+ * The --output-format json flag causes Claude CLI to return structured JSON
+ * including real token usage counts, enabling accurate cost tracking.
+ *
+ * Requires the Claude Code CLI to be installed and authenticated:
+ *   https://docs.anthropic.com/claude-code
+ */
+export declare function createClaudeCliAdapter(options?: ClaudeCliAdapterOptions): MartinAdapter;
+/**
+ * Spawns `codex [--full-auto] [--model <model>] "<prompt>" [extraArgs]`.
+ *
+ * Requires the Codex CLI to be installed and authenticated:
+ *   npm install -g @openai/codex
+ */
+export declare function createCodexCliAdapter(options?: CodexCliAdapterOptions): MartinAdapter;