evidence-diff-mcp 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# evidence-diff-mcp
+
+Evidence Diff is a local MCP tool for explaining coarse changes in a Git project’s test and build evidence. It can tell an agent that a worktree changed, that uncommitted evidence exists, or that test-like artifacts appear without build-like artifacts, without exposing source diffs.
+
+## Tool
+
+- `explain_change_evidence`: inspect local Git state and bounded top-level evidence names.
+
+## Safety
+
+- Local paths only, bounded by `EVIDENCE_DIFF_ROOT` and realpath checks.
+- Returns only counts, coarse categories, coarse branch state, and commit dates.
+- Never returns source diffs, evidence filenames, branch names, file paths from Git output, commit subjects, authors, command output, file contents, or secrets.
+- Does not execute tests, builds, or arbitrary project commands.
+- This is an evidence explanation aid, not a code review or CI oracle.
+
+## Run
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+## Quick start
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code, MCP Inspector, or another compatible MCP client.
+
+## Tools at a glance
+
+- `explain_change_evidence`: Explain coarse changes in local Git and test-build evidence without returning source diffs, file contents, or secrets.
+
+## Try it
+
+After building, connect the server through your MCP client. The repository root also contains `smoke-test.mjs` for projects covered by the shared harness. A typical tool call starts with `explain_change_evidence`.

package/dist/evidence.d.ts

@@ -0,0 +1,4 @@
+export declare class EvidenceError extends Error {
+}
+export declare function explainEvidence(input: string): Promise<Record<string, unknown>>;
+export declare function format(value: unknown): string;

package/dist/evidence.js

@@ -0,0 +1,82 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+const exec = promisify(execFile);
+const MAX_OUTPUT = 14000;
+const MAX_ENTRIES = 120;
+const MAX_LOG_BYTES = 2 * 1024 * 1024;
+const TEST_NAMES = /(?:test|spec|e2e|playwright|cypress|vitest|jest|pytest|cargo test)/i;
+const BUILD_NAMES = /(?:dist|build|coverage|artifact|report|junit|test-results)/i;
+export class EvidenceError extends Error {
+}
+async function safeRoot(input) {
+    const configured = process.env.EVIDENCE_DIFF_ROOT ?? path.join(process.cwd(), "..");
+    const allowed = await realpath(path.resolve(configured)).catch(() => path.resolve(configured));
+    const requested = path.isAbsolute(input) ? input : path.resolve(allowed, input || ".");
+    const target = await realpath(requested).catch(() => requested);
+    const relative = path.relative(allowed, target);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new EvidenceError("Project path must stay inside the configured local workspace");
+    return target;
+}
+async function git(cwd, args) {
+    try {
+        const result = await exec("git", args, { cwd, timeout: 15000, maxBuffer: MAX_LOG_BYTES });
+        return result.stdout.trim();
+    }
+    catch {
+        throw new EvidenceError("Git evidence unavailable for this local project");
+    }
+}
+async function topLevel(root) {
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        return entries.filter((entry) => entry.name !== ".git" && entry.name !== "node_modules").slice(0, MAX_ENTRIES).map((entry) => entry.name).sort();
+    }
+    catch {
+        throw new EvidenceError("Local project evidence could not be read");
+    }
+}
+function classify(name) { if (TEST_NAMES.test(name))
+    return "test-evidence"; if (BUILD_NAMES.test(name))
+    return "build-evidence"; return "other"; }
+export async function explainEvidence(input) {
+    const root = await safeRoot(input);
+    const inside = await git(root, ["rev-parse", "--is-inside-work-tree"]);
+    if (inside !== "true")
+        throw new EvidenceError("Project is not a Git work tree");
+    const status = await git(root, ["status", "--porcelain=v1"]);
+    const recent = await git(root, ["log", "-5", "--date=short", "--format=%ad%x09%s"]);
+    const changed = await git(root, ["diff", "--name-status", "HEAD"]);
+    const staged = await git(root, ["diff", "--cached", "--name-status"]);
+    const entries = await topLevel(root);
+    const evidenceKinds = entries.filter((name) => TEST_NAMES.test(name) || BUILD_NAMES.test(name)).map(classify);
+    const testEvidenceCount = evidenceKinds.filter((kind) => kind === "test-evidence").length;
+    const buildEvidenceCount = evidenceKinds.filter((kind) => kind === "build-evidence").length;
+    const concerns = [];
+    if (status)
+        concerns.push("working-tree-not-clean");
+    if (changed || staged)
+        concerns.push("uncommitted-change-evidence");
+    if (testEvidenceCount > 0 && buildEvidenceCount === 0)
+        concerns.push("test-evidence-without-build-evidence");
+    return {
+        root: "<local-project>",
+        branch: (await git(root, ["branch", "--show-current"])) ? "named-branch" : "detached",
+        workingTree: status ? "changed" : "clean",
+        recentCommitCount: recent ? recent.split("\n").length : 0,
+        changedPathCount: (changed ? changed.split("\n").length : 0) + (staged ? staged.split("\n").length : 0),
+        evidenceKinds: [...new Set(evidenceKinds)].sort(),
+        testEvidenceCount,
+        buildEvidenceCount,
+        concerns,
+        explanation: concerns.length ? "The available local evidence suggests a change or an incomplete test-build evidence trail; inspect the project directly for details." : "No coarse evidence contradiction was detected; this does not prove the build or tests are correct.",
+        valueFree: true,
+        warning: "Only counts, coarse categories, branch state, and commit dates are returned. Source diffs, paths, subjects, authors, file contents, command output, and secrets are never emitted."
+    };
+}
+export function format(value) {
+    const output = JSON.stringify(value, null, 2);
+    return output.length <= MAX_OUTPUT ? output : JSON.stringify({ error: "Result exceeded the output budget and was reduced.", valueFree: true, truncated: true });
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,11 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+    console.error("MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,24 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { explainEvidence, format } from "./evidence.js";
+const text = (value) => ({ content: [{ type: "text", text: value }] });
+const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+const errorText = (error) => text(`Error: ${error instanceof Error ? error.message : String(error)}`);
+export function createServer() {
+    const server = new McpServer({ name: "evidence-diff-mcp", version: "1.0.0" });
+    server.registerTool("explain_change_evidence", {
+        title: "Explain change evidence",
+        description: "Explain coarse changes in local Git and test-build evidence without returning source diffs, file contents, or secrets.",
+        inputSchema: z.object({ project: z.string().min(1).max(1000).describe("Local Git project directory; no URLs") }),
+        annotations: READ_ONLY,
+    }, async ({ project }) => {
+        try {
+            return text(format(await explainEvidence(project)));
+        }
+        catch (error) {
+            return errorText(error);
+        }
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "evidence-diff-mcp",
+  "version": "1.0.0",
+  "description": "Explain coarse Git and test-build evidence changes without source diff contents. Tools include explain change evidence",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/evidence-diff-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/evidence-diff-mcp.git"
+  },
+  "bin": {
+    "evidence-diff-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "server.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "npm run build && node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "git",
+    "ci",
+    "test",
+    "build",
+    "local-first"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.mrfentmen/evidence-diff-mcp",
+  "description": "Explain coarse Git and test-build evidence changes without source diff contents. Tools include...",
+  "repository": {
+    "url": "https://github.com/mrfentmen/evidence-diff-mcp",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "evidence-diff-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}