@martinloop/mcp 0.2.5 → 0.2.7

package/dist/vendor/adapters/openai-compatible.d.ts

@@ -0,0 +1,47 @@
+/**
+ * OpenAI-compatible adapter for MartinLoop.
+ *
+ * Routes agent execution to any endpoint that implements the OpenAI
+ * Chat Completions API (`POST /v1/chat/completions`). This covers:
+ *
+ * Hosted via OpenRouter / Together.ai / Fireworks.ai:
+ *   DeepSeek-V3, DeepSeek-R1, Qwen3-235B, Mistral Large, Codestral,
+ *   Kimi k2, Nemotron-70B, and hundreds more.
+ *
+ * Local via Ollama / LM Studio / llama.cpp:
+ *   Llama 3.x, Mistral 7B, Phi-4, Gemma 3, any GGUF model.
+ *
+ * Usage:
+ *   MARTIN_OPENAI_BASE_URL=https://openrouter.ai/api
+ *   MARTIN_OPENAI_API_KEY=sk-or-...
+ *   MARTIN_OPENAI_MODEL=deepseek/deepseek-chat
+ *   martin run "fix the bug" --engine openai
+ *
+ * Or for Ollama:
+ *   MARTIN_OPENAI_BASE_URL=http://localhost:11434
+ *   MARTIN_OPENAI_MODEL=llama3.3
+ *   martin run "fix the bug" --engine openai
+ */
+import type { MartinAdapter } from "../core/index.js";
+export interface OpenAiCompatibleAdapterOptions {
+    /** Base URL of the OpenAI-compatible API. No trailing slash. */
+    baseUrl: string;
+    /** API key. Empty string for local (Ollama/LM Studio) endpoints. */
+    apiKey?: string;
+    /** Model identifier passed as-is to the API (e.g. "deepseek/deepseek-chat"). */
+    model: string;
+    /**
+     * System prompt prepended before the MartinLoop task prompt.
+     * Default instructs the model to act as a focused coding assistant.
+     */
+    systemPrompt?: string;
+    /** Request timeout in milliseconds. Default: 300_000 (5 min). */
+    timeoutMs?: number;
+    /** Verifier timeout in milliseconds. Default: 60_000. */
+    verifyTimeoutMs?: number;
+    /** Working directory for git artifact collection and verification. */
+    workingDirectory?: string;
+    /** Optional fetch override for testing. */
+    fetchImpl?: typeof fetch;
+}
+export declare function createOpenAiCompatibleAdapter(options: OpenAiCompatibleAdapterOptions): MartinAdapter;

package/dist/vendor/adapters/openai-compatible.js

@@ -0,0 +1,242 @@
+/**
+ * OpenAI-compatible adapter for MartinLoop.
+ *
+ * Routes agent execution to any endpoint that implements the OpenAI
+ * Chat Completions API (`POST /v1/chat/completions`). This covers:
+ *
+ * Hosted via OpenRouter / Together.ai / Fireworks.ai:
+ *   DeepSeek-V3, DeepSeek-R1, Qwen3-235B, Mistral Large, Codestral,
+ *   Kimi k2, Nemotron-70B, and hundreds more.
+ *
+ * Local via Ollama / LM Studio / llama.cpp:
+ *   Llama 3.x, Mistral 7B, Phi-4, Gemma 3, any GGUF model.
+ *
+ * Usage:
+ *   MARTIN_OPENAI_BASE_URL=https://openrouter.ai/api
+ *   MARTIN_OPENAI_API_KEY=sk-or-...
+ *   MARTIN_OPENAI_MODEL=deepseek/deepseek-chat
+ *   martin run "fix the bug" --engine openai
+ *
+ * Or for Ollama:
+ *   MARTIN_OPENAI_BASE_URL=http://localhost:11434
+ *   MARTIN_OPENAI_MODEL=llama3.3
+ *   martin run "fix the bug" --engine openai
+ */
+import { runVerification, readGitExecutionArtifacts } from "./cli-bridge.js";
+import { createAdapterCapabilities, normalizeUsage } from "./runtime-support.js";
+// ---------------------------------------------------------------------------
+// OpenRouter/OpenAI-compatible model pricing ($/1K tokens)
+// Automatically used when baseUrl contains openrouter.ai or known providers.
+// Defaults to a conservative blended estimate for unknown models.
+// ---------------------------------------------------------------------------
+const KNOWN_MODEL_PRICING = {
+    // DeepSeek
+    "deepseek/deepseek-chat": { inputPer1K: 0.00027, outputPer1K: 0.0011 },
+    "deepseek/deepseek-r1": { inputPer1K: 0.0008, outputPer1K: 0.0032 },
+    "deepseek/deepseek-coder": { inputPer1K: 0.00014, outputPer1K: 0.00028 },
+    // Qwen
+    "qwen/qwen3-235b-a22b": { inputPer1K: 0.00022, outputPer1K: 0.00088 },
+    "qwen/qwen3-32b": { inputPer1K: 0.00009, outputPer1K: 0.00009 },
+    "qwen/qwen-2.5-coder-32b-instruct": { inputPer1K: 0.00007, outputPer1K: 0.00007 },
+    // Mistral
+    "mistralai/codestral-latest": { inputPer1K: 0.0003, outputPer1K: 0.0009 },
+    "mistralai/mistral-large": { inputPer1K: 0.003, outputPer1K: 0.009 },
+    "mistralai/mistral-small": { inputPer1K: 0.0001, outputPer1K: 0.0003 },
+    // Kimi
+    "moonshotai/kimi-k2": { inputPer1K: 0.00065, outputPer1K: 0.0026 },
+    // Nemotron
+    "nvidia/llama-3.1-nemotron-70b-instruct": { inputPer1K: 0.00012, outputPer1K: 0.0003 },
+    // Llama (via OpenRouter)
+    "meta-llama/llama-3.3-70b-instruct": { inputPer1K: 0.00012, outputPer1K: 0.0003 },
+    "meta-llama/llama-3.1-405b-instruct": { inputPer1K: 0.0008, outputPer1K: 0.0008 },
+};
+const FALLBACK_INPUT_PER_1K = 0.0003;
+const FALLBACK_OUTPUT_PER_1K = 0.0012;
+const CHARS_PER_TOKEN = 4;
+function estimateCost(model, inputChars, outputChars) {
+    const pricing = KNOWN_MODEL_PRICING[model] ?? {
+        inputPer1K: FALLBACK_INPUT_PER_1K,
+        outputPer1K: FALLBACK_OUTPUT_PER_1K
+    };
+    const tokensIn = Math.ceil(inputChars / CHARS_PER_TOKEN);
+    const tokensOut = Math.ceil(outputChars / CHARS_PER_TOKEN);
+    const actualUsd = (tokensIn / 1000) * pricing.inputPer1K + (tokensOut / 1000) * pricing.outputPer1K;
+    return { tokensIn, tokensOut, actualUsd };
+}
+// ---------------------------------------------------------------------------
+// Prompt builder
+// ---------------------------------------------------------------------------
+const DEFAULT_SYSTEM_PROMPT = `You are an expert software engineer executing a governed coding task.
+Follow these rules exactly:
+- Read the task description carefully and implement only what is asked.
+- Do not add features, refactors, or improvements beyond the stated task.
+- If the task asks you to write or modify code, output the complete file content with changes applied.
+- Be precise, minimal, and test-backed in all changes.
+- State what you changed and why at the end of your response.`;
+function buildPrompt(request) {
+    const lines = [
+        `TASK: ${request.context.taskTitle}`,
+        ``,
+        `OBJECTIVE:`,
+        request.context.objective,
+        ``
+    ];
+    if (request.context.focus) {
+        lines.push(`FOCUS: ${request.context.focus}`, ``);
+    }
+    if (request.context.verificationPlan.length > 0) {
+        lines.push(`VERIFICATION COMMANDS (must pass after your changes):`, ...request.context.verificationPlan.map((cmd) => `  ${cmd}`), ``);
+    }
+    if (request.previousAttempts.length > 0) {
+        const last = request.previousAttempts.at(-1);
+        if (last) {
+            lines.push(`PREVIOUS ATTEMPT SUMMARY:`, last.summary ?? "", ``);
+        }
+    }
+    lines.push(`BUDGET REMAINING: $${request.context.remainingBudgetUsd.toFixed(4)} | Iterations left: ${request.context.remainingIterations}`);
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function createOpenAiCompatibleAdapter(options) {
+    const workingDirectory = options.workingDirectory ?? process.cwd();
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const verifyTimeoutMs = options.verifyTimeoutMs ?? 60_000;
+    const systemPrompt = options.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+    const fetchFn = options.fetchImpl ?? globalThis.fetch;
+    return {
+        adapterId: `openai-compatible:${options.model}`,
+        kind: "direct-provider",
+        label: `OpenAI-compatible: ${options.model}`,
+        metadata: {
+            providerId: "openai-compatible",
+            model: options.model,
+            transport: "http",
+            capabilities: createAdapterCapabilities({
+                preflight: true,
+                usageSettlement: true,
+                diffArtifacts: true
+            })
+        },
+        async execute(request) {
+            const prompt = buildPrompt(request);
+            const estimated = estimateCost(options.model, prompt.length, 2000);
+            // Preflight: bail if projected cost exceeds remaining budget
+            if (request.context.remainingBudgetUsd > 0 &&
+                estimated.actualUsd > request.context.remainingBudgetUsd * 0.95) {
+                return {
+                    status: "failed",
+                    summary: `Preflight: projected cost $${estimated.actualUsd.toFixed(4)} exceeds remaining budget $${request.context.remainingBudgetUsd.toFixed(4)}.`,
+                    usage: normalizeUsage({
+                        actualUsd: estimated.actualUsd,
+                        estimatedUsd: estimated.actualUsd,
+                        tokensIn: estimated.tokensIn,
+                        tokensOut: estimated.tokensOut,
+                        provenance: "estimated"
+                    }),
+                    verification: { passed: false, summary: "Stopped before execution: budget preflight failed." },
+                    failure: { message: "budget_preflight_exceeded", classHint: "budget_pressure" }
+                };
+            }
+            // Call the OpenAI-compatible endpoint
+            const endpoint = `${options.baseUrl.replace(/\/$/, "")}/v1/chat/completions`;
+            let responseText = "";
+            let tokensIn = estimated.tokensIn;
+            let tokensOut = 0;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const headers = { "Content-Type": "application/json" };
+                if (options.apiKey)
+                    headers["Authorization"] = `Bearer ${options.apiKey}`;
+                // OpenRouter requires a site URL header for attribution
+                if (options.baseUrl.includes("openrouter")) {
+                    headers["HTTP-Referer"] = "https://martinloop.com";
+                    headers["X-Title"] = "MartinLoop";
+                }
+                const res = await fetchFn(endpoint, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify({
+                        model: options.model,
+                        messages: [
+                            { role: "system", content: systemPrompt },
+                            { role: "user", content: prompt }
+                        ],
+                        temperature: 0.2,
+                        max_tokens: 8192
+                    }),
+                    signal: controller.signal
+                });
+                const body = (await res.json());
+                if (!res.ok || body.error) {
+                    const errMsg = body.error?.message ?? `HTTP ${res.status}`;
+                    return {
+                        status: "failed",
+                        summary: `${options.model} API error: ${errMsg}`,
+                        usage: normalizeUsage({ actualUsd: 0, tokensIn: 0, tokensOut: 0, provenance: "unavailable" }),
+                        verification: { passed: false, summary: "API call failed before verifier." },
+                        failure: { message: errMsg, classHint: "infrastructure_error" }
+                    };
+                }
+                responseText = body.choices?.[0]?.message?.content ?? "";
+                if (body.usage) {
+                    tokensIn = body.usage.prompt_tokens ?? tokensIn;
+                    tokensOut = body.usage.completion_tokens ?? 0;
+                }
+                else {
+                    tokensOut = Math.ceil(responseText.length / CHARS_PER_TOKEN);
+                }
+            }
+            catch (error) {
+                const isAbort = error instanceof Error && error.name === "AbortError";
+                const message = isAbort ? `${options.model} request timed out after ${timeoutMs}ms` : String(error);
+                return {
+                    status: "failed",
+                    summary: message,
+                    usage: normalizeUsage({ actualUsd: 0, tokensIn: 0, tokensOut: 0, provenance: "unavailable" }),
+                    verification: { passed: false, summary: isAbort ? "Request timed out." : "Network error." },
+                    failure: { message, classHint: "infrastructure_error" }
+                };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (!responseText.trim()) {
+                return {
+                    status: "failed",
+                    summary: `${options.model} returned an empty response.`,
+                    usage: normalizeUsage({ actualUsd: 0, tokensIn, tokensOut: 0, provenance: "actual" }),
+                    verification: { passed: false, summary: "Empty response — nothing to verify." },
+                    failure: { message: "empty_response" }
+                };
+            }
+            // Run verification
+            const verification = await runVerification(request.context.verificationPlan, workingDirectory, verifyTimeoutMs, request.context.verificationStack);
+            const execution = await readGitExecutionArtifacts(workingDirectory, 5_000);
+            const pricing = KNOWN_MODEL_PRICING[options.model] ?? {
+                inputPer1K: FALLBACK_INPUT_PER_1K,
+                outputPer1K: FALLBACK_OUTPUT_PER_1K
+            };
+            const actualUsd = (tokensIn / 1000) * pricing.inputPer1K + (tokensOut / 1000) * pricing.outputPer1K;
+            return {
+                status: verification.passed ? "completed" : "failed",
+                summary: verification.passed
+                    ? `${options.model} completed the task. Verifier passed.`
+                    : `${options.model} completed but verifier failed: ${verification.summary}`,
+                usage: normalizeUsage({
+                    actualUsd,
+                    tokensIn,
+                    tokensOut,
+                    provenance: "actual"
+                }),
+                verification,
+                execution,
+                ...(verification.passed ? {} : {
+                    failure: { message: verification.summary }
+                })
+            };
+        }
+    };
+}

package/dist/workflow-state.d.ts

@@ -0,0 +1,25 @@
+type McpWorkflowStepName = "doctor" | "plan" | "preflight";
+export interface RecordMcpWorkflowStepInput {
+    runsRoot: string;
+    step: McpWorkflowStepName;
+    workingDirectory: string;
+    objective?: string;
+    engine?: string;
+    verificationPlan?: string[];
+}
+export interface EvaluateMcpRunGateInput {
+    runsRoot: string;
+    workingDirectory: string;
+    objective: string;
+    engine?: string;
+    verificationPlan?: string[];
+}
+export interface McpRunGateResult {
+    allowed: boolean;
+    nextAction: string;
+    summary: string;
+    missingSteps: McpWorkflowStepName[];
+}
+export declare function recordMcpWorkflowStep(input: RecordMcpWorkflowStepInput): Promise<void>;
+export declare function evaluateMcpRunGate(input: EvaluateMcpRunGateInput): Promise<McpRunGateResult>;
+export {};

package/dist/workflow-state.js

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+const WORKFLOW_STATE_DIRECTORY = "_martin";
+const WORKFLOW_STATE_FILENAME = "workflow-state.json";
+const DOCTOR_TTL_MS = 24 * 60 * 60 * 1000;
+const PLAN_TTL_MS = 24 * 60 * 60 * 1000;
+const PREFLIGHT_TTL_MS = 6 * 60 * 60 * 1000;
+export async function recordMcpWorkflowStep(input) {
+    const state = await readWorkflowState(input.runsRoot);
+    state.mcp ??= {};
+    state.mcp[input.step] = {
+        step: input.step,
+        recordedAt: new Date().toISOString(),
+        workingDirectory: normalizeWorkingDirectory(input.workingDirectory),
+        ...(input.objective ? { objectiveKey: normalizeObjective(input.objective) } : {}),
+        ...(input.engine ? { engine: input.engine } : {}),
+        ...(input.verificationPlan ? { verificationPlanKey: hashVerificationPlan(input.verificationPlan) } : {})
+    };
+    await writeWorkflowState(input.runsRoot, state);
+}
+export async function evaluateMcpRunGate(input) {
+    const state = await readWorkflowState(input.runsRoot);
+    const mcpState = state.mcp ?? {};
+    const workingDirectory = normalizeWorkingDirectory(input.workingDirectory);
+    const objectiveKey = normalizeObjective(input.objective);
+    const engine = input.engine ?? "claude";
+    const verificationPlanKey = hashVerificationPlan(input.verificationPlan ?? []);
+    const missingSteps = [];
+    if (!isFresh(mcpState["doctor"], DOCTOR_TTL_MS, (receipt) => receipt.workingDirectory === workingDirectory)) {
+        missingSteps.push("doctor");
+    }
+    if (!isFresh(mcpState["plan"], PLAN_TTL_MS, (receipt) => receipt.workingDirectory === workingDirectory &&
+        receipt.objectiveKey === objectiveKey)) {
+        missingSteps.push("plan");
+    }
+    if (!isFresh(mcpState["preflight"], PREFLIGHT_TTL_MS, (receipt) => receipt.workingDirectory === workingDirectory &&
+        receipt.objectiveKey === objectiveKey &&
+        receipt.engine === engine &&
+        receipt.verificationPlanKey === verificationPlanKey)) {
+        missingSteps.push("preflight");
+    }
+    if (missingSteps.length === 0) {
+        return {
+            allowed: true,
+            nextAction: "martin_run",
+            summary: "Martin MCP governance receipts are present for this task.",
+            missingSteps
+        };
+    }
+    const nextAction = missingSteps[0] === "doctor"
+        ? "Call martin_doctor for this workingDirectory before any real run."
+        : missingSteps[0] === "plan"
+            ? "Call martin_plan with the exact objective before martin_run."
+            : "Call martin_preflight with the exact objective, verifier plan, and engine before martin_run.";
+    return {
+        allowed: false,
+        nextAction,
+        summary: `martin_run is blocked until Martin MCP receipts exist for ${missingSteps.join(", ")}.`,
+        missingSteps
+    };
+}
+async function readWorkflowState(runsRoot) {
+    const statePath = resolveWorkflowStatePath(runsRoot);
+    try {
+        const raw = await readFile(statePath, "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed.version === 1 ? parsed : { version: 1 };
+    }
+    catch {
+        return { version: 1 };
+    }
+}
+async function writeWorkflowState(runsRoot, state) {
+    const statePath = resolveWorkflowStatePath(runsRoot);
+    await mkdir(join(resolve(runsRoot), WORKFLOW_STATE_DIRECTORY), { recursive: true });
+    await writeFile(statePath, JSON.stringify(state, null, 2), "utf8");
+}
+function resolveWorkflowStatePath(runsRoot) {
+    return join(resolve(runsRoot), WORKFLOW_STATE_DIRECTORY, WORKFLOW_STATE_FILENAME);
+}
+function isFresh(receipt, ttlMs, predicate) {
+    if (!receipt || !predicate(receipt)) {
+        return false;
+    }
+    const recordedAt = Date.parse(receipt.recordedAt);
+    if (Number.isNaN(recordedAt)) {
+        return false;
+    }
+    return Date.now() - recordedAt <= ttlMs;
+}
+function normalizeWorkingDirectory(workingDirectory) {
+    const resolved = resolve(workingDirectory);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function normalizeObjective(objective) {
+    return objective.trim().replace(/\s+/gu, " ").toLowerCase();
+}
+function hashVerificationPlan(verificationPlan) {
+    const normalized = verificationPlan.map((step) => step.trim()).filter(Boolean);
+    return createHash("sha256").update(JSON.stringify(normalized)).digest("hex").slice(0, 12);
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@martinloop/mcp",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "mcpName": "io.github.Keesan12/martin-loop",
   "private": false,
   "type": "module",
   "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",
+  "author": "MartinLoop contributors",
   "homepage": "https://martinloop.com/",
   "repository": {
     "type": "git",
@@ -61,7 +61,7 @@
     "inspect:live": "node ./scripts/inspect-live.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@open-policy-agent/opa-wasm": "^1.10.0",
     "@opentelemetry/api-logs": "^0.214.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.214.0",

package/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/Keesan12/martin-loop",
     "source": "github"
   },
-  "version": "0.2.5",
+  "version": "0.2.7",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@martinloop/mcp",
-      "version": "0.2.5",
+      "version": "0.2.7",
       "transport": {
         "type": "stdio"
       }