@martinloop/mcp 0.1.2 → 0.1.3

package/README.md

@@ -1,81 +1,110 @@
 # @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` exposes three stdio tools:
 
 - `martin_run`
 - `martin_inspect`
 - `martin_status`
 
-## What's new in 0.1.2
+## What This Server Is For
 
-- `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
+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 Claude Code:
 
 ```sh
 # macOS/Linux
-claude mcp add --scope user martin-loop -- npx @martinloop/mcp
+claude mcp add --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 --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_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.
+
+- `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
 
-Example request body:
+### `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 +114,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 +150,36 @@ Status for a specific persisted loop:
 
 ```json
 {
-  "loopId": "loop-123",
-  "runsDir": "C:/Users/you/.martin/runs"
+  "loopId": "loop-123"
+}
+```
+
+Status from inline JSON:
+
+```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}}"
 }
 ```
 
-## Official MCP Registry
+## Registry Metadata
+
+The registry manifest artifact for this package is `server.json`. In this repository, that manifest is authored at `packages/mcp/server.json`.
 
-This package is prepared for the official MCP Registry metadata flow:
+Current metadata:
 
 - npm package: `@martinloop/mcp`
 - registry server name: `io.github.keesan12/martin-loop`
-- manifest file: `packages/mcp/server.json`
+- 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:
 
@@ -153,5 +191,9 @@ pnpm --filter @martinloop/mcp smoke:pack
 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` 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/`.

package/dist/server.js

@@ -17,6 +17,7 @@
  * 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";
@@ -24,7 +25,9 @@ import { getStatusTool } from "./tools/get-status.js";
 import { inspectLoopTool } from "./tools/inspect-loop.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
 // ---------------------------------------------------------------------------
@@ -35,6 +38,7 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
             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 +46,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 +59,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 +80,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 +104,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 +122,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 +130,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 +138,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"] }
+                ]
             }
         }
     ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martinloop/mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "mcpName": "io.github.keesan12/martin-loop",
   "private": false,
   "type": "module",
@@ -24,22 +24,18 @@
     "claude",
     "codex"
   ],
-  "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 +48,7 @@
     "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",
     "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, policy checks, and audit trails.",
+  "repository": {
+    "url": "https://github.com/Keesan12/martin-loop",
+    "source": "github"
+  },
+  "version": "0.1.3",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@martinloop/mcp",
+      "version": "0.1.3",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}