@martinloop/mcp 0.1.2 → 0.1.4

package/README.md

@@ -1,81 +1,127 @@
 # @martinloop/mcp
 
-Governed MCP server for AI coding agents with hard budgets, verifier gates, policy checks, and inspectable run records.
+Governed MCP server for AI coding agents that need hard spend limits, verifier gates, scoped file edits, and inspectable run records.
 
-Martin Loop helps MCP hosts run AI coding work inside a bounded runtime instead of an open-ended retry loop. The standalone MCP package exposes three focused tools over stdio:
+`@martinloop/mcp@0.1.4` exposes five stdio tools:
 
+- `martin_doctor`
+- `martin_preflight`
 - `martin_run`
 - `martin_inspect`
 - `martin_status`
 
-## What's new in 0.1.2
+Recommended flow:
 
-- `martin_inspect` now reads both canonical `loop-record.json` runs and legacy `.jsonl` run-store files
-- `martin_status` now supports `file`, `loopId`, `runsDir`, and `latest` selectors in addition to inline `loopJson`
-- `martin_run` now persists loop records by default in the MCP path and preserves `allowedPaths`, `deniedPaths`, and resolved `repoRoot`
-- the packaged tarball now rebuilds vendored workspace dependencies before packing, so `npm` installs match current source instead of stale `dist/` output
-- the packaged artifact now rebuilds and vendors the Martin runtime dependencies needed by the standalone MCP server
-- release validation now includes both a packed-tarball smoke and a published-artifact smoke
+1. `martin_doctor`
+2. `martin_preflight`
+3. `martin_run`
+4. `martin_inspect` or `martin_status`
+
+## What This Server Is For
+
+Use this MCP when a host already knows how to delegate coding work, but you want Martin Loop to bound that work with:
+
+- a hard budget ceiling (`maxUsd`)
+- an attempt ceiling (`maxIterations`)
+- a total token ceiling (`maxTokens`)
+- verifier commands (`verificationPlan`)
+- allowed and denied file globs
+- persisted run records you can inspect afterward
+
+It is a good fit for Claude Code, Codex-oriented hosts, and other MCP clients that want governed code-change execution instead of open-ended retry behavior.
+
+For host-facing integration guidance, see [MCP for AI Agents](https://github.com/Keesan12/martin-loop/blob/main/docs/oss/MCP-FOR-AI-AGENTS.md).
 
 ## Quickstart
 
 Run the packaged server directly:
 
 ```sh
-npx @martinloop/mcp
+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 @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 @martinloop/mcp"
+claude mcp add --transport stdio --scope user martin-loop -- cmd /c npx -y @martinloop/mcp
 ```
 
-Generic stdio configuration for non-Claude clients:
+Generic stdio configuration:
 
 ```json
 {
   "type": "stdio",
   "command": "npx",
-  "args": ["@martinloop/mcp"]
+  "args": ["-y", "@martinloop/mcp"]
 }
 ```
 
-## What the tools do
+Codex host configuration in `~/.codex/config.toml`:
 
-- `martin_run`: runs a governed coding loop with budget caps, verifier commands, engine selection, path scoping, and persisted loop records
-- `martin_inspect`: reads Martin Loop run-store data from a canonical `loop-record.json`, a legacy `.jsonl` file, or a full runs directory
-- `martin_status`: evaluates remaining budget pressure and stop conditions from inline JSON, a saved loop record, a loop id, or the latest persisted run
+```toml
+[mcp_servers.martin-loop]
+command = "npx"
+args = ["-y", "@martinloop/mcp"]
+```
 
 ## Requirements
 
 - Node 20+
-- For live runs, either the `claude` CLI or the `codex` CLI must be on `PATH`
-- For dry-run and smoke-test flows, set `MARTIN_LIVE=false`
+- For live `martin_run` usage, either the `claude` CLI or the `codex` CLI must be available on `PATH`
+- For stub or smoke flows, set `MARTIN_LIVE=false`
 
-Live `martin_run` delegates to the configured CLI adapter. If no supported CLI is installed, use the stub path for testing:
+Example stub launch:
 
 ```sh
-MARTIN_LIVE=false npx @martinloop/mcp
+MARTIN_LIVE=false npx -y @martinloop/mcp
 ```
 
-## Tool examples
+## Tool Contract
 
-### `martin_run`
+| 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. |
+
+## Safe-Root Path Model
+
+This MCP does not let tool callers point at arbitrary filesystem locations. The server resolves tool paths against safe roots chosen when the server starts.
 
-Example request body:
+- `workingDirectory`
+  Defaults to `MARTIN_MCP_WORKSPACE_ROOT` or the server process current directory. If you pass a value, it must still resolve inside that workspace root. `.` and repo-relative subpaths are the safest choices.
+- `file`
+  For `martin_inspect` and `martin_status`, `file` resolves under the runs root, not the whole machine. Direct file targets must end in `.json` or `.jsonl`; run directories are also accepted where the tool supports them.
+- `runsDir`
+  Defaults to `MARTIN_RUNS_DIR` or `~/.martin/runs`. Passing `runsDir` only re-states or narrows that safe runs root; it does not grant access outside it.
+- `allowedPaths` and `deniedPaths`
+  These are relative glob patterns only. Absolute paths, drive-qualified paths, and patterns containing `..` are rejected.
+
+Absolute paths can work only when they still resolve inside the corresponding safe root. Escapes above the workspace or runs root are rejected.
+
+## Tool Examples
+
+### `martin_run`
 
 ```json
 {
   "objective": "Fix the auth regression and prove it with tests",
   "engine": "codex",
-  "budgetUsd": 3,
-  "softLimitUsd": 2.25,
+  "maxUsd": 3,
   "maxIterations": 3,
+  "maxTokens": 20000,
   "verificationPlan": ["pnpm test --filter auth"],
   "workingDirectory": ".",
   "allowedPaths": ["src/**", "tests/**"],
@@ -85,25 +131,25 @@ Example request body:
 
 ### `martin_inspect`
 
-Inspect the default run store:
+Inspect the default runs root:
 
 ```json
 {}
 ```
 
-Inspect a legacy JSONL file directly:
+Inspect a specific saved loop record under the runs root:
 
 ```json
 {
-  "file": "C:/Users/you/.martin/runs/workspace.jsonl"
+  "file": "loop-123/loop-record.json"
 }
 ```
 
-Inspect a canonical runs directory:
+Inspect a subdirectory under the configured runs root:
 
 ```json
 {
-  "runsDir": "C:/Users/you/.martin/runs"
+  "runsDir": "team-a"
 }
 ```
 
@@ -121,27 +167,36 @@ Status for a specific persisted loop:
 
 ```json
 {
-  "loopId": "loop-123",
-  "runsDir": "C:/Users/you/.martin/runs"
+  "loopId": "loop-123"
 }
 ```
 
-## Official MCP Registry
+Status from inline JSON:
 
-This package is prepared for the official MCP Registry metadata flow:
+```json
+{
+  "loopJson": "{\"loopId\":\"loop-123\",\"status\":\"completed\",\"lifecycleState\":\"completed\",\"attempts\":[],\"budget\":{\"maxUsd\":5,\"softLimitUsd\":3,\"maxIterations\":2,\"maxTokens\":1000},\"cost\":{\"actualUsd\":1.25,\"avoidedUsd\":0,\"tokensIn\":20,\"tokensOut\":10}}"
+}
+```
+
+## Registry Metadata
+
+The registry manifest artifact for this package is `server.json`. In this repository, that manifest is authored at `packages/mcp/server.json`.
+
+Current metadata:
 
 - npm package: `@martinloop/mcp`
-- registry server name: `io.github.keesan12/martin-loop`
-- manifest file: `packages/mcp/server.json`
+- registry server name: `io.github.Keesan12/martin-loop`
+- manifest artifact name: `server.json`
 
-The official registry publish flow is separate from npm publication. After publishing the package to npm, run the publisher from `packages/mcp`:
+Official MCP Registry publication 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
+## Verification
 
 From the repository root:
 
@@ -150,8 +205,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` validates the local packed tarball before publish
-- `smoke:published` validates the npm-published artifact through `npm exec`
+- `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 and `server.json`.

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";
 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,6 +2,10 @@ 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":
@@ -18,6 +22,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;

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 five tools over the Model Context Protocol (stdio transport):
+ *   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

package/dist/server.js

@@ -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 five tools over the Model Context Protocol (stdio transport):
+ *   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
@@ -17,24 +19,119 @@
  * Manual start:
  *   node dist/server.js
  */
+import { createRequire } from "node:module";
 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 { martinDoctorTool } from "./tools/doctor.js";
 import { getStatusTool } from "./tools/get-status.js";
 import { inspectLoopTool } from "./tools/inspect-loop.js";
+import { martinPreflightTool } from "./tools/preflight.js";
 import { runLoopTool } from "./tools/run-loop.js";
 import { sanitizeToolErrorMessage, validateToolInput } from "./server-validation.js";
-const server = new Server({ name: "martin-loop", version: "0.1.2" }, { capabilities: { tools: {} } });
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+const server = new Server({ name: "martin-loop", version: packageJson.version }, { capabilities: { tools: {} } });
 // ---------------------------------------------------------------------------
 // Tool manifest
 // ---------------------------------------------------------------------------
 server.setRequestHandler(ListToolsRequestSchema, () => ({
     tools: [
+        {
+            name: "martin_doctor",
+            description: "Inspect Martin MCP readiness without changing code. Reports workspace roots, run-store visibility, execution mode, and whether claude or codex is available on PATH.",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    workingDirectory: {
+                        type: "string",
+                        description: "Optional repo-root override resolved under the MCP workspace root (or current working directory). Must stay within that safe root."
+                    },
+                    runsDir: {
+                        type: "string",
+                        description: "Optional runs-root override resolved under the default Martin runs root. Defaults to MARTIN_RUNS_DIR or ~/.martin/runs."
+                    },
+                    engine: {
+                        type: "string",
+                        enum: ["claude", "codex"],
+                        description: "Optional engine to emphasize in the readiness report."
+                    }
+                }
+            }
+        },
+        {
+            name: "martin_preflight",
+            description: "Validate and normalize a proposed martin_run contract before execution. Reports the effective budget, path scope, engine readiness, and expected run-store layout.",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    objective: {
+                        type: "string",
+                        description: "The coding task to complete. Be specific about what needs to change."
+                    },
+                    workingDirectory: {
+                        type: "string",
+                        description: "Optional repo-root override resolved under the MCP workspace root (or current working directory). Must stay within that safe root."
+                    },
+                    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",
+                        exclusiveMinimum: 0,
+                        description: "Hard budget ceiling in USD. Defaults to 25."
+                    },
+                    maxIterations: {
+                        type: "integer",
+                        exclusiveMinimum: 0,
+                        description: "Maximum number of loop attempts. Defaults to 8."
+                    },
+                    maxTokens: {
+                        type: "integer",
+                        exclusiveMinimum: 0,
+                        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'])."
+                    },
+                    allowedPaths: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Repo-relative path globs Martin may modify, such as ['src/**', 'tests/**']. Absolute paths and '..' traversal are rejected."
+                    },
+                    deniedPaths: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Repo-relative path globs Martin must never modify, such as ['.env', 'docs/security/**']. Absolute paths and '..' traversal are rejected."
+                    },
+                    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_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",
+                additionalProperties: false,
                 properties: {
                     objective: {
                         type: "string",
@@ -42,7 +139,7 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
                     },
                     workingDirectory: {
                         type: "string",
-                        description: "Absolute path to the project root. Defaults to the current working directory."
+                        description: "Optional repo-root override resolved under the MCP workspace root (or current working directory). Must stay within that safe root."
                     },
                     engine: {
                         type: "string",
@@ -55,14 +152,17 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
                     },
                     maxUsd: {
                         type: "number",
+                        exclusiveMinimum: 0,
                         description: "Hard budget ceiling in USD. Defaults to 25."
                     },
                     maxIterations: {
-                        type: "number",
+                        type: "integer",
+                        exclusiveMinimum: 0,
                         description: "Maximum number of loop attempts. Defaults to 8."
                     },
                     maxTokens: {
-                        type: "number",
+                        type: "integer",
+                        exclusiveMinimum: 0,
                         description: "Maximum total tokens across all attempts. Defaults to 80000."
                     },
                     verificationPlan: {
@@ -73,12 +173,12 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
                     allowedPaths: {
                         type: "array",
                         items: { type: "string" },
-                        description: "Relative path globs Martin may modify, such as ['src/**', 'tests/**']."
+                        description: "Repo-relative path globs Martin may modify, such as ['src/**', 'tests/**']. Absolute paths and '..' traversal are rejected."
                     },
                     deniedPaths: {
                         type: "array",
                         items: { type: "string" },
-                        description: "Relative path globs Martin must never modify, such as ['.env', 'docs/security/**']."
+                        description: "Repo-relative path globs Martin must never modify, such as ['.env', 'docs/security/**']. Absolute paths and '..' traversal are rejected."
                     },
                     workspaceId: {
                         type: "string",
@@ -97,14 +197,15 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
             description: "Summarise Martin Loop run records from a saved loop file or run-store directory. Supports canonical loop-record.json files, legacy JSONL files, and full runs directories.",
             inputSchema: {
                 type: "object",
+                additionalProperties: false,
                 properties: {
                     file: {
                         type: "string",
-                        description: "Optional path under the Martin runs root to a loop-record.json file, a legacy .jsonl file, or a run-store directory."
+                        description: "Optional path resolved under the Martin runs root to a loop-record.json file, a legacy .jsonl file, or a run-store directory."
                     },
                     runsDir: {
                         type: "string",
-                        description: "Optional Martin runs directory. Defaults to MARTIN_RUNS_DIR or ~/.martin/runs."
+                        description: "Optional runs-root override resolved under the default Martin runs root. Defaults to MARTIN_RUNS_DIR or ~/.martin/runs."
                     }
                 }
             }
@@ -114,6 +215,7 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
             description: "Return the current budget and cost state of a Martin loop record. Accepts inline JSON, a saved loop file, a loopId under the run store, or the latest run in the store.",
             inputSchema: {
                 type: "object",
+                additionalProperties: false,
                 properties: {
                     loopJson: {
                         type: "string",
@@ -121,7 +223,7 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
                     },
                     file: {
                         type: "string",
-                        description: "Optional path under the Martin runs root to a loop-record.json file, a legacy .jsonl file, or a run-store directory."
+                        description: "Optional path resolved under the Martin runs root to a loop-record.json file, a legacy .jsonl file, or a run-store directory."
                     },
                     loopId: {
                         type: "string",
@@ -129,13 +231,19 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
                     },
                     runsDir: {
                         type: "string",
-                        description: "Optional Martin runs directory. Defaults to MARTIN_RUNS_DIR or ~/.martin/runs."
+                        description: "Optional runs-root override resolved under the default Martin runs root. Defaults to MARTIN_RUNS_DIR or ~/.martin/runs."
                     },
                     latest: {
-                        type: "boolean",
+                        const: true,
                         description: "When true, loads the most recently updated loop record in the runs directory."
                     }
-                }
+                },
+                oneOf: [
+                    { required: ["loopJson"] },
+                    { required: ["file"] },
+                    { required: ["loopId"] },
+                    { required: ["latest"] }
+                ]
             }
         }
     ]
@@ -146,6 +254,16 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
+        if (name === "martin_doctor") {
+            const input = validateToolInput("martin_doctor", args);
+            const output = await martinDoctorTool(input);
+            return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+        }
+        if (name === "martin_preflight") {
+            const input = validateToolInput("martin_preflight", args);
+            const output = await martinPreflightTool(input);
+            return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+        }
         if (name === "martin_run") {
             const input = validateToolInput("martin_run", args);
             const output = await runLoopTool(input);

package/dist/tools/doctor.d.ts

@@ -0,0 +1,35 @@
+import { type LoopPreview, type MartinEngine } from "./tool-support.js";
+export interface MartinDoctorInput {
+    workingDirectory?: string;
+    runsDir?: string;
+    engine?: MartinEngine;
+}
+export interface MartinDoctorOutput {
+    status: "ok" | "degraded";
+    summary: string;
+    server: {
+        name: "martin-loop";
+        nodeVersion: string;
+        platform: NodeJS.Platform;
+    };
+    environment: {
+        workspaceRoot: string;
+        workingDirectory: string;
+        runsRoot: string;
+        mode: "live" | "stub";
+        liveMode: boolean;
+    };
+    engines: Record<MartinEngine, {
+        available: boolean;
+        detail: string;
+        resolvedPath?: string;
+    }>;
+    requestedEngine?: MartinEngine;
+    runStore: {
+        exists: boolean;
+        loopCount: number;
+        latestRun?: LoopPreview;
+    };
+    warnings: string[];
+}
+export declare function martinDoctorTool(input: MartinDoctorInput): Promise<MartinDoctorOutput>;

package/dist/tools/doctor.js

@@ -0,0 +1,56 @@
+import { resolveRunsRoot } from "../vendor/core/index.js";
+import { resolveSafeRepoRoot, resolveSafeRunsRootPath } from "../server-validation.js";
+import { getEngineAvailability, inspectRunsRoot, resolveExecutionMode } from "./tool-support.js";
+export async function martinDoctorTool(input) {
+    const workingDirectory = resolveSafeRepoRoot(input.workingDirectory);
+    const runsRoot = resolveSafeRunsRootPath(input.runsDir, resolveRunsRoot(process.env));
+    const executionMode = resolveExecutionMode();
+    const claude = getEngineAvailability("claude");
+    const codex = getEngineAvailability("codex");
+    const runStore = await inspectRunsRoot(runsRoot);
+    const warnings = [];
+    if (!runStore.exists) {
+        warnings.push("Configured Martin runs root does not exist yet.");
+    }
+    if (executionMode.liveMode && !claude.available && !codex.available) {
+        warnings.push("Neither claude nor codex is currently available on PATH for live runs.");
+    }
+    if (input.engine && executionMode.liveMode) {
+        const selected = input.engine === "claude" ? claude : codex;
+        if (!selected.available) {
+            warnings.push(`Requested engine '${input.engine}' is not available on PATH.`);
+        }
+    }
+    warnings.push(...runStore.warnings);
+    const status = warnings.length === 0 ? "ok" : "degraded";
+    return {
+        status,
+        summary: status === "ok"
+            ? `Doctor passed: ${runStore.loopCount} run(s) visible in ${runsRoot}.`
+            : `Doctor found ${warnings.length} issue(s); review warnings before live execution.`,
+        server: {
+            name: "martin-loop",
+            nodeVersion: process.version,
+            platform: process.platform
+        },
+        environment: {
+            workspaceRoot: resolveSafeRepoRoot(),
+            workingDirectory,
+            runsRoot,
+            mode: executionMode.mode,
+            liveMode: executionMode.liveMode
+        },
+        engines: {
+            claude,
+            codex
+        },
+        ...(input.engine ? { requestedEngine: input.engine } : {}),
+        runStore: {
+            exists: runStore.exists,
+            loopCount: runStore.loopCount,
+            ...(runStore.latestRun ? { latestRun: runStore.latestRun } : {})
+        },
+        warnings
+    };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/tools/preflight.d.ts

@@ -0,0 +1,62 @@
+import { type MartinEngine } from "./tool-support.js";
+export interface MartinPreflightInput {
+    objective: string;
+    workingDirectory?: string;
+    engine?: MartinEngine;
+    model?: string;
+    maxUsd?: number;
+    maxIterations?: number;
+    maxTokens?: number;
+    verificationPlan?: string[];
+    allowedPaths?: string[];
+    deniedPaths?: string[];
+    workspaceId?: string;
+    projectId?: string;
+}
+export interface MartinPreflightOutput {
+    ok: boolean;
+    summary: string;
+    warnings: string[];
+    readiness: {
+        mode: "live" | "stub";
+        liveMode: boolean;
+        engineReady: boolean;
+    };
+    normalized: {
+        objective: string;
+        workingDirectory: string;
+        engine: MartinEngine;
+        model?: string;
+        budget: {
+            maxUsd: number;
+            softLimitUsd: number;
+            maxIterations: number;
+            maxTokens: number;
+        };
+        verificationPlan: string[];
+        allowedPaths?: string[];
+        deniedPaths?: string[];
+        workspaceId: string;
+        projectId: string;
+    };
+    execution: {
+        requestedEngine: MartinEngine;
+        engineAvailability: {
+            available: boolean;
+            detail: string;
+            resolvedPath?: string;
+        };
+        runsRoot: string;
+        pathScope: {
+            repoRoot: string;
+            allowedPathsCount: number;
+            deniedPathsCount: number;
+            hasScopeConflicts: boolean;
+        };
+        expectedRunLayout: {
+            runDirectoryPattern: string;
+            loopRecordPathPattern: string;
+        };
+    };
+}
+export declare function martinPreflightTool(input: MartinPreflightInput): Promise<MartinPreflightOutput>;

package/dist/tools/preflight.js

@@ -0,0 +1,76 @@
+import { DEFAULT_BUDGET } from "../vendor/contracts/index.js";
+import { resolveRunsRoot } from "../vendor/core/index.js";
+import { resolveSafeRepoRoot } from "../server-validation.js";
+import { formatUsd, getEngineAvailability, resolveExecutionMode } from "./tool-support.js";
+export async function martinPreflightTool(input) {
+    const executionMode = resolveExecutionMode();
+    const workingDirectory = resolveSafeRepoRoot(input.workingDirectory);
+    const engine = input.engine ?? "claude";
+    const engineAvailability = getEngineAvailability(engine);
+    const warnings = [];
+    const allowedPaths = input.allowedPaths ?? [];
+    const deniedPaths = input.deniedPaths ?? [];
+    const overlappingScopes = allowedPaths.filter((candidate) => deniedPaths.includes(candidate));
+    const budget = {
+        ...DEFAULT_BUDGET,
+        ...(input.maxUsd !== undefined ? { maxUsd: input.maxUsd } : {}),
+        ...(input.maxIterations !== undefined ? { maxIterations: input.maxIterations } : {}),
+        ...(input.maxTokens !== undefined ? { maxTokens: input.maxTokens } : {})
+    };
+    if (!executionMode.liveMode) {
+        warnings.push("Stub mode is active; preflight only proves configuration shape, not live CLI readiness.");
+    }
+    else if (!engineAvailability.available) {
+        warnings.push(`Requested engine '${engine}' is not available on PATH.`);
+    }
+    if ((input.verificationPlan?.length ?? 0) === 0) {
+        warnings.push("No verificationPlan was provided; Martin can run, but completion confidence will be lower.");
+    }
+    if ((input.allowedPaths?.length ?? 0) === 0) {
+        warnings.push("No allowedPaths were provided; Martin will rely on the broader repo root scope.");
+    }
+    if (overlappingScopes.length > 0) {
+        warnings.push(`Some path patterns appear in both allowedPaths and deniedPaths: ${overlappingScopes.join(", ")}.`);
+    }
+    const ok = !executionMode.liveMode || engineAvailability.available;
+    return {
+        ok,
+        summary: ok
+            ? `Preflight ready for ${engine} in ${workingDirectory} with a ${formatUsd(budget.maxUsd)} budget cap.`
+            : `Preflight blocked: ${engine} is not available for live execution.`,
+        warnings,
+        readiness: {
+            mode: executionMode.mode,
+            liveMode: executionMode.liveMode,
+            engineReady: !executionMode.liveMode || engineAvailability.available
+        },
+        normalized: {
+            objective: input.objective,
+            workingDirectory,
+            engine,
+            ...(input.model ? { model: input.model } : {}),
+            budget,
+            verificationPlan: input.verificationPlan ?? [],
+            ...(input.allowedPaths ? { allowedPaths: input.allowedPaths } : {}),
+            ...(input.deniedPaths ? { deniedPaths: input.deniedPaths } : {}),
+            workspaceId: input.workspaceId ?? "ws_mcp",
+            projectId: input.projectId ?? "proj_mcp"
+        },
+        execution: {
+            requestedEngine: engine,
+            engineAvailability,
+            runsRoot: resolveRunsRoot(process.env),
+            pathScope: {
+                repoRoot: workingDirectory,
+                allowedPathsCount: allowedPaths.length,
+                deniedPathsCount: deniedPaths.length,
+                hasScopeConflicts: overlappingScopes.length > 0
+            },
+            expectedRunLayout: {
+                runDirectoryPattern: "<runsRoot>/<loopId>/",
+                loopRecordPathPattern: "<runsRoot>/<loopId>/loop-record.json"
+            }
+        }
+    };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/tools/tool-support.d.ts

@@ -0,0 +1,37 @@
+export type MartinEngine = "claude" | "codex";
+export interface LoopPreview {
+    loopId: string;
+    title: string;
+    objective: string;
+    status: string;
+    lifecycleState: string;
+    createdAt?: string;
+    updatedAt?: string;
+    attempts: number;
+    costUsd: number;
+    avoidedUsd: number;
+    pressure: string;
+    shouldStop: boolean;
+    remainingBudgetUsd: number;
+    remainingIterations: number;
+    remainingTokens: number;
+}
+export interface CliAvailability {
+    available: boolean;
+    detail: string;
+    resolvedPath?: string;
+}
+export interface ExecutionMode {
+    liveMode: boolean;
+    mode: "live" | "stub";
+}
+export interface RunStoreInspection {
+    exists: boolean;
+    loopCount: number;
+    latestRun?: LoopPreview;
+    warnings: string[];
+}
+export declare function resolveExecutionMode(): ExecutionMode;
+export declare function getEngineAvailability(engine: MartinEngine): CliAvailability;
+export declare function formatUsd(value: number): string;
+export declare function inspectRunsRoot(runsRoot?: string): Promise<RunStoreInspection>;

package/dist/tools/tool-support.js

@@ -0,0 +1,110 @@
+import { spawnSync } from "node:child_process";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { evaluateCostGovernor, readLatestLoopRecordFromFile, resolveRunsRoot } from "../vendor/core/index.js";
+export function resolveExecutionMode() {
+    const liveMode = process.env.MARTIN_LIVE !== "false";
+    return {
+        liveMode,
+        mode: liveMode ? "live" : "stub"
+    };
+}
+export function getEngineAvailability(engine) {
+    const locator = process.platform === "win32" ? "where.exe" : "which";
+    const result = spawnSync(locator, [engine], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+    const resolvedPath = result.status === 0
+        ? (result.stdout ?? "")
+            .split(/\r?\n/u)
+            .map((line) => line.trim())
+            .find(Boolean)
+        : undefined;
+    return result.status === 0
+        ? {
+            available: true,
+            detail: `${engine} is available on PATH.`,
+            ...(resolvedPath ? { resolvedPath } : {})
+        }
+        : {
+            available: false,
+            detail: `${engine} is not available on PATH.`
+        };
+}
+export function formatUsd(value) {
+    return `$${value.toFixed(2)}`;
+}
+export async function inspectRunsRoot(runsRoot = resolveRunsRoot(process.env)) {
+    let exists = false;
+    try {
+        exists = (await stat(runsRoot)).isDirectory();
+    }
+    catch {
+        exists = false;
+    }
+    if (!exists) {
+        return {
+            exists: false,
+            loopCount: 0,
+            warnings: []
+        };
+    }
+    const warnings = [];
+    const loops = [];
+    const entries = await readdir(runsRoot, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const loopRecordPath = join(runsRoot, entry.name, "loop-record.json");
+        try {
+            const loop = await readLatestLoopRecordFromFile(loopRecordPath);
+            if (!loop) {
+                continue;
+            }
+            const costState = evaluateCostGovernor({
+                budget: loop.budget,
+                cost: {
+                    actualUsd: loop.cost.actualUsd,
+                    avoidedUsd: loop.cost.avoidedUsd ?? 0,
+                    tokensIn: loop.cost.tokensIn,
+                    tokensOut: loop.cost.tokensOut
+                },
+                attemptsUsed: loop.attempts.length
+            });
+            loops.push({
+                loopId: loop.loopId,
+                title: loop.task?.title ?? loop.loopId,
+                objective: loop.task?.objective ?? "Loop record summary",
+                status: loop.status,
+                lifecycleState: loop.lifecycleState,
+                ...(loop.createdAt ? { createdAt: loop.createdAt } : {}),
+                ...(loop.updatedAt ? { updatedAt: loop.updatedAt } : {}),
+                attempts: loop.attempts.length,
+                costUsd: loop.cost.actualUsd,
+                avoidedUsd: loop.cost.avoidedUsd ?? 0,
+                pressure: costState.pressure,
+                shouldStop: costState.shouldStop,
+                remainingBudgetUsd: costState.remainingBudgetUsd,
+                remainingIterations: costState.remainingIterations,
+                remainingTokens: costState.remainingTokens
+            });
+        }
+        catch {
+            warnings.push(`Skipped unreadable loop record for '${entry.name}'.`);
+        }
+    }
+    loops.sort((left, right) => {
+        const leftTime = Date.parse(left.updatedAt ?? left.createdAt ?? "");
+        const rightTime = Date.parse(right.updatedAt ?? right.createdAt ?? "");
+        return (Number.isFinite(rightTime) ? rightTime : 0) - (Number.isFinite(leftTime) ? leftTime : 0);
+    });
+    return {
+        exists: true,
+        loopCount: loops.length,
+        ...(loops[0] ? { latestRun: loops[0] } : {}),
+        warnings
+    };
+}
+//# sourceMappingURL=tool-support.js.map

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@martinloop/mcp",
-  "version": "0.1.2",
-  "mcpName": "io.github.keesan12/martin-loop",
+  "version": "0.1.4",
+  "mcpName": "io.github.Keesan12/martin-loop",
   "private": false,
   "type": "module",
-  "description": "Governed MCP server for AI coding agents with budgets, verifier gates, policy checks, and audit trails.",
-  "license": "MIT",
+  "description": "Governed MCP server for AI coding agents with budgets, verifier gates, and inspectable runs.",
+  "license": "Apache-2.0",
   "author": "Vakeesan Mahalingam and Gobi Shanthan",
   "homepage": "https://martinloop.com/",
   "repository": {
@@ -22,24 +22,22 @@
     "martin-loop",
     "ai-agent",
     "claude",
-    "codex"
+    "codex",
+    "martin_doctor",
+    "martin_preflight"
   ],
-  "main": "./dist/server.js",
-  "types": "./dist/server.d.ts",
   "bin": {
     "mcp": "./dist/server.js",
     "martin-loop-mcp": "./dist/server.js"
   },
   "exports": {
-    ".": {
-      "types": "./dist/server.d.ts",
-      "default": "./dist/server.js"
-    },
+    "./server.json": "./server.json",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "server.json"
   ],
   "engines": {
     "node": ">=20.0.0"
@@ -52,6 +50,8 @@
     "prepack": "pnpm build",
     "smoke:pack": "node ./scripts/smoke-package.mjs",
     "smoke:published": "node ./scripts/smoke-published-package.mjs",
+    "smoke:published:pack": "node ./scripts/smoke-published-package.mjs --package-spec=pack",
+    "verify:release": "node --test ../../scripts/tests/publish-mcp-workflow.test.mjs ../../scripts/tests/mcp-publish-reliability.test.mjs ../../scripts/tests/mcp-release-docs.test.mjs",
     "test": "vitest run",
     "lint": "tsc -p tsconfig.json --noEmit",
     "start": "node dist/server.js"

package/server.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.Keesan12/martin-loop",
+  "title": "Martin Loop",
+  "description": "Governed MCP server for AI coding agents with budgets, verifier gates, and inspectable runs.",
+  "repository": {
+    "url": "https://github.com/Keesan12/martin-loop",
+    "source": "github"
+  },
+  "version": "0.1.4",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@martinloop/mcp",
+      "version": "0.1.4",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}