@martinloop/mcp 0.1.4 → 0.2.5

package/dist/server-validation.js

@@ -1,105 +1,78 @@
-import { extname, isAbsolute, relative, resolve } from "node:path";
+import { existsSync, lstatSync, realpathSync } from "node:fs";
+import { dirname, extname, isAbsolute, relative, resolve } from "node:path";
 import { resolveRunsRoot } from "./vendor/core/index.js";
+import { invalidArgumentsError, invalidPathError, invalidSelectorError } from "./tools/tool-errors.js";
+export { sanitizeToolErrorMessage } from "./tools/tool-errors.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_doctor":
+            return validateDoctorInput(args);
+        case "martin_preflight":
+            return validatePreflightInput(args);
+        case "martin_list_runs":
+            return validateListRunsInput(args);
+        case "martin_triage_runs":
+            return validateTriageRunsInput(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}`);
+            throw invalidArgumentsError(`Unknown tool: ${name}`, "Refresh the Martin tool manifest and retry.");
     }
 }
-export function sanitizeToolErrorMessage(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return /([A-Za-z]:\\|\/|policy\.rego|policy\.wasm|\.pem|\.env)/u.test(message)
-        ? "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;
-    assertPathWithinRoot(candidate, baseRoot, "workingDirectory");
+    assertPathWithinRoot(candidate, baseRoot, "workingDirectory", {
+        requireExistingCandidate: true,
+        requireExistingRoot: true
+    });
     return candidate;
 }
 export function resolveSafeRunsJsonPath(file, runsRoot = resolveRunsRoot(process.env)) {
     const baseRoot = resolve(runsRoot);
     const candidate = resolve(baseRoot, file);
-    assertPathWithinRoot(candidate, baseRoot, "file");
+    assertPathWithinRoot(candidate, baseRoot, "file", {
+        requireExistingCandidate: true,
+        requireExistingRoot: true
+    });
     const extension = extname(candidate).toLowerCase();
     if (extension !== ".json" && extension !== ".jsonl") {
-        throw new Error("Invalid file.");
+        throw invalidPathError("Invalid file.", "Point file at a loop-record.json, a legacy .jsonl file, or a run directory under the runs root.");
     }
     return candidate;
 }
 export function resolveSafeRunsPath(file, runsRoot = resolveRunsRoot(process.env)) {
     const baseRoot = resolve(runsRoot);
     const candidate = resolve(baseRoot, file);
-    assertPathWithinRoot(candidate, baseRoot, "file");
+    assertPathWithinRoot(candidate, baseRoot, "file", {
+        requireExistingCandidate: true,
+        requireExistingRoot: true
+    });
     const extension = extname(candidate).toLowerCase();
     if (extension && extension !== ".json" && extension !== ".jsonl") {
-        throw new Error("Invalid file.");
+        throw invalidPathError("Invalid file.", "Point file at a loop-record.json, a legacy .jsonl file, or a run directory under the runs root.");
     }
     return candidate;
 }
 export function resolveSafeRunsRootPath(runsRoot, fallbackRunsRoot = resolveRunsRoot(process.env)) {
     const baseRoot = resolve(fallbackRunsRoot);
     const candidate = runsRoot ? resolve(baseRoot, runsRoot) : baseRoot;
-    assertPathWithinRoot(candidate, baseRoot, "runsDir");
+    assertPathWithinRoot(candidate, baseRoot, "runsDir", {
+        requireExistingCandidate: false,
+        requireExistingRoot: false
+    });
     return candidate;
 }
 export function resolveSafeLoopRecordPath(loopId, runsRoot = resolveRunsRoot(process.env)) {
@@ -117,7 +90,7 @@ export function normalizeSafePathPatterns(value, name) {
             normalized.startsWith("/") ||
             /^[A-Za-z]:\//u.test(normalized) ||
             normalized.split("/").includes("..")) {
-            throw new Error(`Invalid ${name}.`);
+            throw invalidPathError(`Invalid ${name}.`);
         }
         return normalized;
     });
@@ -159,18 +132,24 @@ function validateRunInput(args) {
 function validateInspectInput(args) {
     const record = requireObject(args);
     assertAllowedKeys(record, ["file", "runsDir"]);
+    const resolvedRunsDir = record.runsDir !== undefined
+        ? resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir"))
+        : undefined;
     return {
         ...(record.file !== undefined
-            ? { file: resolveSafeRunsPath(requireString(record.file, "file")) }
+            ? {
+                file: resolveSafeRunsPath(requireString(record.file, "file"), resolvedRunsDir ?? resolveRunsRoot(process.env))
+            }
             : {}),
-        ...(record.runsDir !== undefined
-            ? { runsDir: resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir")) }
-            : {})
+        ...(resolvedRunsDir ? { runsDir: resolvedRunsDir } : {})
     };
 }
 function validateStatusInput(args) {
     const record = requireObject(args);
     assertAllowedKeys(record, ["loopJson", "file", "loopId", "runsDir", "latest"]);
+    const resolvedRunsDir = record.runsDir !== undefined
+        ? resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir"))
+        : undefined;
     const selectors = [
         record.loopJson !== undefined ? "loopJson" : null,
         record.file !== undefined ? "file" : null,
@@ -178,58 +157,266 @@ function validateStatusInput(args) {
         record.latest !== undefined ? "latest" : null
     ].filter((value) => value !== null);
     if (selectors.length !== 1) {
-        throw new Error("Provide exactly one of loopJson, file, loopId, or latest.");
+        throw invalidSelectorError("Provide exactly one of loopJson, file, loopId, or latest.", "Choose exactly one status selector per call.");
     }
     if (record.latest !== undefined && record.latest !== true) {
-        throw new Error("Invalid latest.");
+        throw invalidArgumentsError("Invalid latest.", "latest must be the literal boolean value true.");
     }
     return {
         ...(record.loopJson !== undefined
             ? { loopJson: requireString(record.loopJson, "loopJson") }
             : {}),
         ...(record.file !== undefined
-            ? { file: resolveSafeRunsPath(requireString(record.file, "file")) }
+            ? {
+                file: resolveSafeRunsPath(requireString(record.file, "file"), resolvedRunsDir ?? resolveRunsRoot(process.env))
+            }
             : {}),
         ...(record.loopId !== undefined
-            ? { loopId: requireLoopId(record.loopId, "loopId") }
+            ? {
+                loopId: requireLoopId(record.loopId, "loopId")
+            }
+            : {}),
+        ...(resolvedRunsDir ? { runsDir: resolvedRunsDir } : {}),
+        ...(record.latest === true ? { latest: true } : {})
+    };
+}
+function validateDoctorInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, ["workingDirectory", "runsDir", "engine"]);
+    return {
+        ...(record.workingDirectory !== undefined
+            ? { workingDirectory: resolveSafeRepoRoot(requireString(record.workingDirectory, "workingDirectory")) }
             : {}),
         ...(record.runsDir !== undefined
             ? { runsDir: resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir")) }
             : {}),
+        ...optionalEnumAsObject(record.engine, "engine", ["claude", "codex"])
+    };
+}
+function validatePreflightInput(args) {
+    return validateRunInput(args);
+}
+function validateListRunsInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, [
+        "runsDir",
+        "limit",
+        "status",
+        "lifecycleState",
+        "adapterId",
+        "model",
+        "updatedAfter"
+    ]);
+    return {
+        ...(record.runsDir !== undefined
+            ? { runsDir: resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir")) }
+            : {}),
+        ...optionalPositiveInteger(record.limit, "limit"),
+        ...optionalString(record.status, "status"),
+        ...optionalString(record.lifecycleState, "lifecycleState"),
+        ...optionalString(record.adapterId, "adapterId"),
+        ...optionalString(record.model, "model"),
+        ...optionalString(record.updatedAfter, "updatedAfter")
+    };
+}
+function validateGetRunInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, ["file", "loopId", "runsDir", "latest"]);
+    const resolvedRunsDir = record.runsDir !== undefined
+        ? resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir"))
+        : undefined;
+    const selectors = [
+        record.file !== undefined ? "file" : null,
+        record.loopId !== undefined ? "loopId" : null,
+        record.latest !== undefined ? "latest" : null
+    ].filter((value) => value !== null);
+    if (selectors.length !== 1) {
+        throw invalidSelectorError("Provide exactly one of file, loopId, or latest.", "Choose exactly one run selector per call.");
+    }
+    if (record.latest !== undefined && record.latest !== true) {
+        throw invalidArgumentsError("Invalid latest.", "latest must be the literal boolean value true.");
+    }
+    return {
+        ...(record.file !== undefined
+            ? {
+                file: resolveSafeRunsPath(requireString(record.file, "file"), resolvedRunsDir ?? resolveRunsRoot(process.env))
+            }
+            : {}),
+        ...(record.loopId !== undefined
+            ? { loopId: requireLoopId(record.loopId, "loopId") }
+            : {}),
+        ...(resolvedRunsDir ? { runsDir: resolvedRunsDir } : {}),
         ...(record.latest === true ? { latest: true } : {})
     };
 }
+function validateTriageRunsInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, [
+        "runsDir",
+        "limit",
+        "status",
+        "lifecycleState",
+        "adapterId",
+        "model",
+        "updatedAfter",
+        "includeHealthy"
+    ]);
+    return {
+        ...(record.runsDir !== undefined
+            ? { runsDir: resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir")) }
+            : {}),
+        ...optionalPositiveInteger(record.limit, "limit"),
+        ...optionalString(record.status, "status"),
+        ...optionalString(record.lifecycleState, "lifecycleState"),
+        ...optionalString(record.adapterId, "adapterId"),
+        ...optionalString(record.model, "model"),
+        ...optionalString(record.updatedAfter, "updatedAfter"),
+        ...optionalBoolean(record.includeHealthy, "includeHealthy")
+    };
+}
+function validateGetAttemptInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, ["file", "loopId", "runsDir", "attemptIndex"]);
+    const resolvedRunsDir = record.runsDir !== undefined
+        ? resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir"))
+        : undefined;
+    const selectors = [
+        record.file !== undefined ? "file" : null,
+        record.loopId !== undefined ? "loopId" : null
+    ].filter((value) => value !== null);
+    if (selectors.length !== 1) {
+        throw invalidSelectorError("Provide exactly one of file or loopId.", "Choose exactly one run selector per call.");
+    }
+    return {
+        ...(record.file !== undefined
+            ? {
+                file: resolveSafeRunsPath(requireString(record.file, "file"), resolvedRunsDir ?? resolveRunsRoot(process.env))
+            }
+            : {}),
+        ...(record.loopId !== undefined
+            ? { loopId: requireLoopId(record.loopId, "loopId") }
+            : {}),
+        ...(resolvedRunsDir ? { runsDir: resolvedRunsDir } : {}),
+        ...optionalPositiveInteger(record.attemptIndex, "attemptIndex")
+    };
+}
+function validateGetVerificationResultsInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, ["file", "loopId", "runsDir"]);
+    const resolvedRunsDir = record.runsDir !== undefined
+        ? resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir"))
+        : undefined;
+    const selectors = [
+        record.file !== undefined ? "file" : null,
+        record.loopId !== undefined ? "loopId" : null
+    ].filter((value) => value !== null);
+    if (selectors.length !== 1) {
+        throw invalidSelectorError("Provide exactly one of file or loopId.", "Choose exactly one run selector per call.");
+    }
+    return {
+        ...(record.file !== undefined
+            ? {
+                file: resolveSafeRunsPath(requireString(record.file, "file"), resolvedRunsDir ?? resolveRunsRoot(process.env))
+            }
+            : {}),
+        ...(record.loopId !== undefined
+            ? { loopId: requireLoopId(record.loopId, "loopId") }
+            : {}),
+        ...(resolvedRunsDir ? { runsDir: resolvedRunsDir } : {})
+    };
+}
+function validateRunDossierInput(args) {
+    return validateGetRunInput(args);
+}
 function requireObject(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new Error("Tool arguments must be an object.");
+        throw invalidArgumentsError("Tool arguments must be an object.");
     }
     return value;
 }
 function assertAllowedKeys(record, allowed) {
     const unknownKeys = Object.keys(record).filter((key) => !allowed.includes(key));
     if (unknownKeys.length > 0) {
-        throw new Error(`Unknown arguments: ${unknownKeys.join(", ")}`);
+        throw invalidArgumentsError(`Unknown arguments: ${unknownKeys.join(", ")}`);
     }
 }
-function assertPathWithinRoot(candidatePath, rootPath, name) {
-    const relativePath = relative(rootPath, candidatePath);
+function assertPathWithinRoot(candidatePath, rootPath, name, options = {}) {
+    assertNoSymbolicLinkSegments(candidatePath, name, rootPath);
+    const canonicalRoot = canonicalizePath(rootPath, name, options.requireExistingRoot ?? false);
+    const canonicalCandidate = canonicalizePath(candidatePath, name, options.requireExistingCandidate ?? false);
+    const relativePath = relative(canonicalRoot, canonicalCandidate);
     if (relativePath === "" || relativePath === ".") {
         return;
     }
     if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
-        throw new Error(`Invalid ${name}.`);
+        throw invalidPathError(`Invalid ${name}.`);
+    }
+}
+function assertNoSymbolicLinkSegments(pathValue, name, stopAtPath) {
+    const stopAt = stopAtPath ? resolve(stopAtPath) : undefined;
+    let current = resolve(pathValue);
+    while (true) {
+        if (existsSync(current)) {
+            try {
+                const stats = lstatSync(current);
+                if (stats.isSymbolicLink()) {
+                    throw invalidPathError(`Invalid ${name}.`);
+                }
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    throw error;
+                }
+                throw invalidPathError(`Invalid ${name}.`);
+            }
+        }
+        if (stopAt && relative(stopAt, current) === "") {
+            break;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+}
+function canonicalizePath(pathValue, name, requireExisting) {
+    const resolvedPath = resolve(pathValue);
+    if (!existsSync(resolvedPath)) {
+        if (requireExisting) {
+            throw invalidPathError(`Invalid ${name}.`);
+        }
+        return resolvedPath;
+    }
+    try {
+        const stats = lstatSync(resolvedPath);
+        if (stats.isSymbolicLink()) {
+            throw invalidPathError(`Invalid ${name}.`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw error;
+        }
+        throw invalidPathError(`Invalid ${name}.`);
+    }
+    try {
+        return realpathSync.native(resolvedPath);
+    }
+    catch {
+        throw invalidPathError(`Invalid ${name}.`);
     }
 }
 function requireString(value, name) {
     if (typeof value !== "string" || value.trim().length === 0) {
-        throw new Error(`Invalid ${name}.`);
+        throw invalidArgumentsError(`Invalid ${name}.`);
     }
     return value.trim();
 }
 function requireLoopId(value, name) {
     const loopId = requireString(value, name);
     if (!/^[A-Za-z0-9._-]+$/u.test(loopId)) {
-        throw new Error(`Invalid ${name}.`);
+        throw invalidPathError(`Invalid ${name}.`, "loopId may only include letters, numbers, dots, underscores, and hyphens.");
     }
     return loopId;
 }
@@ -244,7 +431,7 @@ function optionalPositiveNumber(value, name) {
         return {};
     }
     if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
-        throw new Error(`Invalid ${name}.`);
+        throw invalidArgumentsError(`Invalid ${name}.`);
     }
     return { [name]: value };
 }
@@ -253,7 +440,25 @@ function optionalPositiveInteger(value, name) {
         return {};
     }
     if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
-        throw new Error(`Invalid ${name}.`);
+        throw invalidArgumentsError(`Invalid ${name}.`);
+    }
+    return { [name]: value };
+}
+function optionalNonNegativeInteger(value, name) {
+    if (value === undefined) {
+        return {};
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw invalidArgumentsError(`Invalid ${name}.`);
+    }
+    return { [name]: value };
+}
+function optionalBoolean(value, name) {
+    if (value === undefined) {
+        return {};
+    }
+    if (typeof value !== "boolean") {
+        throw invalidArgumentsError(`Invalid ${name}.`);
     }
     return { [name]: value };
 }
@@ -262,7 +467,7 @@ function optionalStringArray(value, name) {
         return undefined;
     }
     if (!Array.isArray(value)) {
-        throw new Error(`Invalid ${name}.`);
+        throw invalidArgumentsError(`Invalid ${name}.`);
     }
     return value.map((item) => requireString(item, name));
 }
@@ -279,8 +484,11 @@ function optionalEnum(value, name, allowed) {
         return undefined;
     }
     if (typeof value !== "string" || !allowed.includes(value)) {
-        throw new Error(`Invalid ${name}.`);
+        throw invalidArgumentsError(`Invalid ${name}.`);
     }
     return value;
 }
-//# sourceMappingURL=server-validation.js.map
+function optionalEnumAsObject(value, name, allowed) {
+    const enumValue = optionalEnum(value, name, allowed);
+    return enumValue ? { [name]: enumValue } : {};
+}

package/dist/server.d.ts

@@ -2,12 +2,9 @@
 /**
  * Martin Loop MCP Server
  *
- * 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
+ * Martin Loop MCP is a governed execution cockpit for AI coding agents.
+ * It exposes execution, diagnostics, run inspection, resources, and prompts
+ * over the Model Context Protocol (stdio transport).
  *
  * Setup (Claude Code):
  *   macOS/Linux: claude mcp add --scope user martin-loop -- npx @martinloop/mcp
@@ -19,4 +16,76 @@
  * Manual start:
  *   node dist/server.js
  */
-export {};
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function createMartinMcpServer(serverInfo?: {
+    name?: string;
+    version?: string;
+}): Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>;
+export declare function connectMartinMcpStdioServer(): Promise<Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>>;
+export declare function isDirectExecutionEntry(entryPath: string | undefined, moduleUrl?: string): boolean;