@martinloop/mcp 0.1.3 → 0.2.0

package/README.md

@@ -2,11 +2,25 @@
 
 Governed MCP server for AI coding agents that need hard spend limits, verifier gates, scoped file edits, and inspectable run records.
 
-`@martinloop/mcp` exposes three stdio tools:
+`@martinloop/mcp@0.2.0` exposes ten stdio tools plus read-only MCP resources, resource templates, and prompts:
 
+- `martin_doctor`
+- `martin_preflight`
 - `martin_run`
 - `martin_inspect`
 - `martin_status`
+- `martin_list_runs`
+- `martin_get_run`
+- `martin_get_attempt`
+- `martin_get_verification_results`
+- `martin_run_dossier`
+
+Recommended flow:
+
+1. `martin_doctor`
+2. `martin_preflight`
+3. `martin_run`
+4. `martin_list_runs`, `martin_run_dossier`, `martin_inspect`, or `martin_status`
 
 ## What This Server Is For
 
@@ -31,14 +45,20 @@ Run the packaged server directly:
 npx -y @martinloop/mcp
 ```
 
+Add it to Codex:
+
+```sh
+codex mcp add martin-loop -- npx -y @martinloop/mcp
+```
+
 Add it to Claude Code:
 
 ```sh
 # macOS/Linux
-claude mcp add --scope user martin-loop -- npx -y @martinloop/mcp
+claude mcp add --transport stdio --scope user martin-loop -- npx -y @martinloop/mcp
 
 # Windows PowerShell/cmd
-claude mcp add --scope user martin-loop cmd /c "npx -y @martinloop/mcp"
+claude mcp add --transport stdio --scope user martin-loop -- cmd /c npx -y @martinloop/mcp
 ```
 
 Generic stdio configuration:
@@ -75,9 +95,36 @@ MARTIN_LIVE=false npx -y @martinloop/mcp
 
 | Tool | Purpose | Required input | Important optional input | Notes |
 | --- | --- | --- | --- | --- |
+| `martin_doctor` | Inspect local readiness and run-store health | none | `workingDirectory`, `runsDir`, `engine` | Read-only setup lane before execution. |
+| `martin_preflight` | Normalize and validate a proposed run contract | `objective` | `workingDirectory`, `engine`, `model`, `maxUsd`, `maxIterations`, `maxTokens`, `verificationPlan`, `allowedPaths`, `deniedPaths`, `workspaceId`, `projectId` | Read-only contract check; does not execute work. |
 | `martin_run` | Run a governed coding loop | `objective` | `workingDirectory`, `engine`, `model`, `maxUsd`, `maxIterations`, `maxTokens`, `verificationPlan`, `allowedPaths`, `deniedPaths`, `workspaceId`, `projectId` | Unknown arguments are rejected. |
 | `martin_inspect` | Read a saved run record or run folder | none | `file`, `runsDir` | `file` may point to a `loop-record.json`, legacy `.jsonl`, or a run directory under the runs root. |
 | `martin_status` | Report budget pressure and stop conditions | exactly one of `loopJson`, `file`, `loopId`, or `latest` | `runsDir` | `latest` must be `true` when used. |
+| `martin_list_runs` | List recent run summaries | none | `runsDir`, `limit` | Read-only cockpit view over local run records. |
+| `martin_get_run` | Load a run dossier | exactly one of `loopId` or `latest` | `runsDir` | Read-only task, budget, cost, and attempt details. |
+| `martin_get_attempt` | Load one attempt | `loopId`, `attemptIndex` | `runsDir` | Read-only attempt evidence. |
+| `martin_get_verification_results` | Extract verifier events | exactly one of `loopId` or `latest` | `runsDir` | Read-only verifier completion summaries. |
+| `martin_run_dossier` | Build a compact review dossier | exactly one of `loopId` or `latest` | `runsDir` | Summary, budget, attempts, and verification evidence. |
+
+## Discovery Surface
+
+`0.2.0` adds read-only cockpit discovery for MCP hosts that support resources and prompts.
+
+Resources:
+
+- `martin://runs/summary`
+- `martin://runs/latest`
+
+Resource templates:
+
+- `martin://runs/{loopId}`
+- `martin://runs/{loopId}/attempts/{attemptIndex}`
+- `martin://runs/{loopId}/verification`
+
+Prompts:
+
+- `martin_review_run`
+- `martin_triage_failures`
 
 ## Safe-Root Path Model
 
@@ -169,7 +216,7 @@ The registry manifest artifact for this package is `server.json`. In this reposi
 Current metadata:
 
 - npm package: `@martinloop/mcp`
-- registry server name: `io.github.keesan12/martin-loop`
+- registry server name: `io.github.Keesan12/martin-loop`
 - manifest artifact name: `server.json`
 
 Official MCP Registry publication is separate from npm publication. After publishing the package to npm, run the publisher from `packages/mcp`:
@@ -188,12 +235,16 @@ pnpm --filter @martinloop/mcp lint
 pnpm --filter @martinloop/mcp test
 pnpm --filter @martinloop/mcp build
 pnpm --filter @martinloop/mcp smoke:pack
+pnpm --filter @martinloop/mcp smoke:published:pack
+pnpm --filter @martinloop/mcp verify:release
 pnpm --filter @martinloop/mcp smoke:published
 ```
 
 - `smoke:pack` verifies the packed tarball shape and a stdio MCP launch
+- `smoke:published:pack` verifies install-and-run behavior from a freshly packed local tarball before npm publish
+- `verify:release` checks metadata parity, release-note presence, and public MCP doc accuracy for the current package version
 - `smoke:published` verifies the npm-installed artifact through `npm install` plus live MCP tool calls
 
 ## Version Notes
 
-The root `CHANGELOG.md` is repo-wide and includes non-MCP changes. For the `@martinloop/mcp` surface, prefer this README, `server.json`, and the MCP release notes under `docs/release/`.
+The root `CHANGELOG.md` is repo-wide and includes non-MCP changes. For the `@martinloop/mcp` surface, prefer this README and `server.json`.

package/dist/prompts.d.ts

@@ -0,0 +1,3 @@
+import type { GetPromptResult, ListPromptsResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function listMartinPrompts(): ListPromptsResult["prompts"];
+export declare function getMartinPrompt(name: string, args?: Record<string, unknown>): GetPromptResult;

package/dist/prompts.js

@@ -0,0 +1,84 @@
+export function listMartinPrompts() {
+    return [
+        {
+            name: "martin_review_run",
+            description: "Review a Martin Loop run for governance, verification, and release-readiness evidence.",
+            arguments: [
+                {
+                    name: "loopId",
+                    description: "Run loopId to review.",
+                    required: true
+                },
+                {
+                    name: "objective",
+                    description: "Review objective or release question.",
+                    required: false
+                }
+            ]
+        },
+        {
+            name: "martin_triage_failures",
+            description: "Triage failed Martin runs and propose the next safest bounded action.",
+            arguments: [
+                {
+                    name: "loopId",
+                    description: "Optional run loopId to triage. If omitted, use latest run resources.",
+                    required: false
+                }
+            ]
+        }
+    ];
+}
+export function getMartinPrompt(name, args = {}) {
+    if (name === "martin_review_run") {
+        const loopId = requireOptionalText(args.loopId, "loopId") ?? "latest";
+        const objective = requireOptionalText(args.objective, "objective") ?? "Assess whether the run is safe to ship.";
+        return {
+            description: "Review Martin Loop run evidence.",
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Review Martin Loop run ${loopId}.`,
+                            `Objective: ${objective}`,
+                            "Use martin://runs/{loopId}, martin://runs/{loopId}/verification, and the read-only tools before making a shipping recommendation.",
+                            "Call out missing verifier proof, budget pressure, safety-leash violations, and whether human review is required."
+                        ].join("\n")
+                    }
+                }
+            ]
+        };
+    }
+    if (name === "martin_triage_failures") {
+        const loopId = requireOptionalText(args.loopId, "loopId") ?? "latest";
+        return {
+            description: "Triage failed Martin Loop evidence.",
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Triage Martin Loop run ${loopId}.`,
+                            "Use the run dossier, attempt evidence, and verification results.",
+                            "Return the smallest safe next action and do not suggest re-running until the failure class and verifier evidence are clear."
+                        ].join("\n")
+                    }
+                }
+            ]
+        };
+    }
+    throw new Error("Unknown prompt.");
+}
+function requireOptionalText(value, name) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Invalid ${name}.`);
+    }
+    return value.trim();
+}
+//# sourceMappingURL=prompts.js.map

package/dist/resources.d.ts

@@ -0,0 +1,7 @@
+import type { ListResourceTemplatesResult, ListResourcesResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+export interface ResourceReadOptions {
+    runsDir?: string;
+}
+export declare function listMartinResources(): ListResourcesResult["resources"];
+export declare function listMartinResourceTemplates(): ListResourceTemplatesResult["resourceTemplates"];
+export declare function readMartinResource(uri: string, options?: ResourceReadOptions): Promise<ReadResourceResult>;

package/dist/resources.js

@@ -0,0 +1,89 @@
+import { buildRunDossier, getAttempt, listRunSummaries, loadSelectedRun } from "./tools/cockpit-support.js";
+import { getVerificationResultsTool } from "./tools/get-verification-results.js";
+export function listMartinResources() {
+    return [
+        {
+            uri: "martin://runs/summary",
+            name: "Martin run summary",
+            description: "Read-only summary of recent governed Martin Loop runs.",
+            mimeType: "application/json"
+        },
+        {
+            uri: "martin://runs/latest",
+            name: "Latest Martin run",
+            description: "Read-only dossier for the newest run in the local run store.",
+            mimeType: "application/json"
+        }
+    ];
+}
+export function listMartinResourceTemplates() {
+    return [
+        {
+            uriTemplate: "martin://runs/{loopId}",
+            name: "Martin run dossier",
+            description: "Read-only run dossier by loopId.",
+            mimeType: "application/json"
+        },
+        {
+            uriTemplate: "martin://runs/{loopId}/attempts/{attemptIndex}",
+            name: "Martin run attempt",
+            description: "Read-only attempt evidence for a run.",
+            mimeType: "application/json"
+        },
+        {
+            uriTemplate: "martin://runs/{loopId}/verification",
+            name: "Martin verification results",
+            description: "Verifier results extracted from a run ledger.",
+            mimeType: "application/json"
+        }
+    ];
+}
+export async function readMartinResource(uri, options = {}) {
+    const parsed = new URL(uri);
+    if (parsed.protocol !== "martin:") {
+        throw new Error("Unsupported resource URI.");
+    }
+    const segments = parsed.pathname.split("/").filter(Boolean);
+    if (parsed.hostname === "runs" && segments.length === 1 && segments[0] === "summary") {
+        return asJsonResource(uri, await listRunSummaries({ runsDir: options.runsDir }));
+    }
+    if (parsed.hostname === "runs" && segments.length === 1 && segments[0] === "latest") {
+        const loop = await loadSelectedRun({ latest: true, runsDir: options.runsDir });
+        return asJsonResource(uri, buildRunDossier(loop));
+    }
+    if (parsed.hostname !== "runs" || segments.length < 1) {
+        throw new Error("Unknown resource URI.");
+    }
+    const [loopId, child, attemptIndex] = segments;
+    if (!loopId || !/^[A-Za-z0-9._-]+$/u.test(loopId)) {
+        throw new Error("Invalid loopId.");
+    }
+    if (!child) {
+        const loop = await loadSelectedRun({ loopId, runsDir: options.runsDir });
+        return asJsonResource(uri, buildRunDossier(loop));
+    }
+    if (child === "attempts") {
+        const parsedAttempt = Number(attemptIndex);
+        if (!Number.isInteger(parsedAttempt) || parsedAttempt <= 0) {
+            throw new Error("Invalid attemptIndex.");
+        }
+        const loop = await loadSelectedRun({ loopId, runsDir: options.runsDir });
+        return asJsonResource(uri, getAttempt(loop, parsedAttempt));
+    }
+    if (child === "verification") {
+        return asJsonResource(uri, await getVerificationResultsTool({ loopId, runsDir: options.runsDir }));
+    }
+    throw new Error("Unknown resource URI.");
+}
+function asJsonResource(uri, value) {
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(value, null, 2)
+            }
+        ]
+    };
+}
+//# sourceMappingURL=resources.js.map

package/dist/server-validation.d.ts

@@ -1,4 +1,4 @@
-type ToolName = "martin_run" | "martin_inspect" | "martin_status";
+type ToolName = "martin_doctor" | "martin_preflight" | "martin_run" | "martin_inspect" | "martin_status" | "martin_list_runs" | "martin_get_run" | "martin_get_attempt" | "martin_get_verification_results" | "martin_run_dossier";
 export declare function validateToolInput(name: ToolName, args: unknown): unknown;
 export declare function sanitizeToolErrorMessage(error: unknown): string;
 export declare function resolveSafeRepoRoot(repoRoot?: string, workspaceRoot?: string): string;

package/dist/server-validation.js

@@ -2,12 +2,26 @@ import { extname, isAbsolute, relative, resolve } from "node:path";
 import { resolveRunsRoot } from "./vendor/core/index.js";
 export function validateToolInput(name, args) {
     switch (name) {
+        case "martin_doctor":
+            return validateDoctorInput(args);
+        case "martin_preflight":
+            return validatePreflightInput(args);
         case "martin_run":
             return validateRunInput(args);
         case "martin_inspect":
             return validateInspectInput(args);
         case "martin_status":
             return validateStatusInput(args);
+        case "martin_list_runs":
+            return validateListRunsInput(args);
+        case "martin_get_run":
+            return validateGetRunInput(args);
+        case "martin_get_attempt":
+            return validateGetAttemptInput(args);
+        case "martin_get_verification_results":
+            return validateGetVerificationResultsInput(args);
+        case "martin_run_dossier":
+            return validateRunDossierInput(args);
         default:
             throw new Error(`Unknown tool: ${name}`);
     }
@@ -18,6 +32,54 @@ export function sanitizeToolErrorMessage(error) {
         ? "Tool execution failed."
         : message;
 }
+function validateDoctorInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, ["workingDirectory", "runsDir", "engine"]);
+    const engine = optionalEnum(record.engine, "engine", ["claude", "codex"]);
+    return {
+        ...(record.workingDirectory !== undefined
+            ? { workingDirectory: resolveSafeRepoRoot(requireString(record.workingDirectory, "workingDirectory")) }
+            : {}),
+        ...(record.runsDir !== undefined
+            ? { runsDir: resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir")) }
+            : {}),
+        ...(engine ? { engine } : {})
+    };
+}
+function validatePreflightInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, [
+        "objective",
+        "workingDirectory",
+        "engine",
+        "model",
+        "maxUsd",
+        "maxIterations",
+        "maxTokens",
+        "verificationPlan",
+        "allowedPaths",
+        "deniedPaths",
+        "workspaceId",
+        "projectId"
+    ]);
+    const engine = optionalEnum(record.engine, "engine", ["claude", "codex"]);
+    return {
+        objective: requireString(record.objective, "objective"),
+        ...(record.workingDirectory !== undefined
+            ? { workingDirectory: resolveSafeRepoRoot(requireString(record.workingDirectory, "workingDirectory")) }
+            : {}),
+        ...(engine ? { engine } : {}),
+        ...optionalString(record.model, "model"),
+        ...optionalPositiveNumber(record.maxUsd, "maxUsd"),
+        ...optionalPositiveInteger(record.maxIterations, "maxIterations"),
+        ...optionalPositiveInteger(record.maxTokens, "maxTokens"),
+        ...optionalStringArrayAsObject(record.verificationPlan, "verificationPlan"),
+        ...optionalPathPatternArrayAsObject(record.allowedPaths, "allowedPaths"),
+        ...optionalPathPatternArrayAsObject(record.deniedPaths, "deniedPaths"),
+        ...optionalString(record.workspaceId, "workspaceId"),
+        ...optionalString(record.projectId, "projectId")
+    };
+}
 export function resolveSafeRepoRoot(repoRoot, workspaceRoot = process.env.MARTIN_MCP_WORKSPACE_ROOT ?? process.cwd()) {
     const baseRoot = resolve(workspaceRoot);
     const candidate = repoRoot ? resolve(baseRoot, repoRoot) : baseRoot;
@@ -147,6 +209,61 @@ function validateStatusInput(args) {
         ...(record.latest === true ? { latest: true } : {})
     };
 }
+function validateListRunsInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, ["runsDir", "limit"]);
+    return {
+        ...(record.runsDir !== undefined
+            ? { runsDir: resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir")) }
+            : {}),
+        ...(record.limit !== undefined ? { limit: requirePositiveInteger(record.limit, "limit") } : {})
+    };
+}
+function validateGetRunInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, ["loopId", "runsDir", "latest"]);
+    return validateRunSelector(record);
+}
+function validateGetVerificationResultsInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, ["loopId", "runsDir", "latest"]);
+    return validateRunSelector(record);
+}
+function validateRunDossierInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, ["loopId", "runsDir", "latest"]);
+    return validateRunSelector(record);
+}
+function validateGetAttemptInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, ["loopId", "attemptIndex", "runsDir"]);
+    return {
+        loopId: requireLoopId(record.loopId, "loopId"),
+        attemptIndex: requirePositiveInteger(record.attemptIndex, "attemptIndex"),
+        ...(record.runsDir !== undefined
+            ? { runsDir: resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir")) }
+            : {})
+    };
+}
+function validateRunSelector(record) {
+    const selectors = [
+        record.loopId !== undefined ? "loopId" : null,
+        record.latest !== undefined ? "latest" : null
+    ].filter((value) => value !== null);
+    if (selectors.length !== 1) {
+        throw new Error("Provide exactly one of loopId or latest.");
+    }
+    if (record.latest !== undefined && record.latest !== true) {
+        throw new Error("Invalid latest.");
+    }
+    return {
+        ...(record.loopId !== undefined ? { loopId: requireLoopId(record.loopId, "loopId") } : {}),
+        ...(record.latest === true ? { latest: true } : {}),
+        ...(record.runsDir !== undefined
+            ? { runsDir: resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir")) }
+            : {})
+    };
+}
 function requireObject(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new Error("Tool arguments must be an object.");
@@ -200,10 +317,13 @@ function optionalPositiveInteger(value, name) {
     if (value === undefined) {
         return {};
     }
+    return { [name]: requirePositiveInteger(value, name) };
+}
+function requirePositiveInteger(value, name) {
     if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
         throw new Error(`Invalid ${name}.`);
     }
-    return { [name]: value };
+    return value;
 }
 function optionalStringArray(value, name) {
     if (value === undefined) {

package/dist/server.d.ts

@@ -2,10 +2,12 @@
 /**
  * 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
+ * Exposes a governed local MCP cockpit over stdio:
+ *   martin_doctor     — inspect local readiness and run-store health
+ *   martin_preflight  — normalize a proposed run contract before execution
+ *   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