env-contract-mcp 1.0.0

package/README.md

@@ -0,0 +1,43 @@
+# env-contract-mcp
+
+Env Contract is a local MCP tool for finding configuration drift before a project fails at runtime. It compares variable names declared in `.env.example` and dotenv files with likely environment references in source and config files.
+
+## Tool
+
+- `inspect_contract`: report declared names, referenced names, missing names, unused names, and the files where they occur.
+
+## Safety
+
+- Reads local project files only; it never fetches URLs.
+- Never reads or emits environment values. Only names and bounded file paths are returned.
+- Ignores `node_modules`, build output, coverage, and Git internals.
+- Caps file count, file size, recursion depth, and output.
+- Matching is heuristic and is not a replacement for a build, deployment check, or secret scanner.
+
+Set `ENV_CONTRACT_ROOT` to bound analysis to a workspace root. It defaults to the parent of the MCP package when launched normally.
+
+## 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
+
+- `inspect_contract`: Inspect a local project for declared and referenced environment variable names without reading values.
+
+## 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 `inspect_contract`.

package/dist/contract.d.ts

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

package/dist/contract.js

@@ -0,0 +1,94 @@
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+const MAX_FILE_BYTES = 512 * 1024;
+const MAX_FILES = 100;
+const MAX_NAMES = 500;
+const MAX_OUTPUT = 14000;
+const ALLOWED_FILES = /(^|\/)(\.env(?:\.[\w.-]+)?|docker-compose(?:\.[\w.-]+)?\.ya?ml|compose(?:\.[\w.-]+)?\.ya?ml|package\.json|.*\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|yml|yaml))$/i;
+const NAME = /\b[A-Z][A-Z0-9_]{1,127}\b/g;
+const RESERVED = new Set(["JSON", "HTTP", "HTTPS", "TRUE", "FALSE", "NULL", "NODE", "PATH", "HOME", "USER", "PORT"]);
+export class ContractError extends Error {
+}
+async function safeRoot(input) {
+    const configured = process.env.ENV_CONTRACT_ROOT ?? path.join(process.cwd(), "..");
+    const root = await realpath(path.resolve(configured)).catch(() => path.resolve(configured));
+    const target = await realpath(path.resolve(input || ".")).catch(() => path.resolve(input || "."));
+    const relative = path.relative(root, target);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new ContractError(`Project path must stay inside ${root}`);
+    return target;
+}
+function kind(file) { if (/\.env(?:\.|$)/i.test(file))
+    return /\.env\.example$/i.test(file) ? "env-example" : "dotenv"; return /\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb)$/i.test(file) ? "source" : "config"; }
+function names(text) { return [...new Set((text.match(NAME) ?? []).filter((value) => !RESERVED.has(value) && !/^\d+$/.test(value)))].slice(0, MAX_NAMES); }
+function declared(text) { return [...new Set(text.split(/\r?\n/).map((line) => line.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]{1,127})\s*(?:=|:|$)/)?.[1]).filter((value) => Boolean(value)))].slice(0, MAX_NAMES); }
+async function files(root) {
+    const result = [];
+    async function walk(directory, depth) {
+        if (depth > 5 || result.length >= MAX_FILES)
+            return;
+        let entries;
+        try {
+            entries = await (await import("node:fs/promises")).readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") && !entry.name.startsWith(".env"))
+                continue;
+            if (["node_modules", "dist", ".git", "coverage", "build"].includes(entry.name))
+                continue;
+            const full = path.join(directory, entry.name);
+            const resolved = await realpath(full).catch(() => "");
+            if (!resolved)
+                continue;
+            const relativeResolved = path.relative(root, resolved);
+            if (relativeResolved.startsWith("..") || path.isAbsolute(relativeResolved))
+                continue;
+            if (entry.isDirectory())
+                await walk(resolved, depth + 1);
+            else if (ALLOWED_FILES.test(relativeResolved))
+                result.push(resolved);
+            if (result.length >= MAX_FILES)
+                return;
+        }
+    }
+    await walk(root, 0);
+    return result;
+}
+export async function analyze(project) {
+    const root = await safeRoot(project);
+    const all = await files(root);
+    const declarations = new Map();
+    const references = new Map();
+    const fileKinds = {};
+    let read = 0;
+    for (const file of all) {
+        const relative = path.relative(root, file);
+        fileKinds[relative] = kind(relative);
+        let text;
+        try {
+            const buffer = await readFile(file);
+            if (buffer.byteLength > MAX_FILE_BYTES)
+                continue;
+            text = buffer.toString("utf8");
+        }
+        catch {
+            continue;
+        }
+        read += 1;
+        const found = names(text);
+        const type = fileKinds[relative];
+        if (type === "env-example" || type === "dotenv")
+            declarations.set(relative, declared(text));
+        if (type === "source" || type === "config")
+            references.set(relative, found.filter((value) => /ENV|KEY|TOKEN|SECRET|URL|HOST|PORT|MODE|REGION|DATABASE|REDIS|AWS|GITHUB|NPM|API/i.test(value)));
+    }
+    const declaredNames = [...new Set([...declarations.values()].flat())].sort();
+    const referencedNames = [...new Set([...references.values()].flat())].sort();
+    const missing = referencedNames.filter((value) => !declaredNames.includes(value)).slice(0, MAX_NAMES);
+    const unused = declaredNames.filter((value) => !referencedNames.includes(value)).slice(0, MAX_NAMES);
+    return { root, filesScanned: read, declarations: Object.fromEntries(declarations), references: Object.fromEntries(references), declaredNames, referencedNames, missing, unused, valueFree: true, warning: "Only variable names and file paths are reported. Environment values are never read or emitted; matches are heuristic and not a complete build validation." };
+}
+export function format(value) { return JSON.stringify(value, null, 2).slice(0, MAX_OUTPUT); }

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,22 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { analyze, format } from "./contract.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: "env-contract-mcp", version: "1.0.0" });
+    server.registerTool("inspect_contract", {
+        title: "Inspect contract",
+        description: "Inspect a local project for declared and referenced environment variable names without reading values.",
+        inputSchema: z.object({ project: z.string().min(1).max(1000).describe("Local project directory; no network URLs") }),
+        annotations: READ_ONLY,
+    }, async ({ project }) => { try {
+        return text(format(await analyze(project)));
+    }
+    catch (error) {
+        return errorText(error);
+    } });
+    return server;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "env-contract-mcp",
+  "version": "1.0.0",
+  "description": "Local value-free environment contract and configuration drift inspection. Tools include inspect contract",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/env-contract-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/env-contract-mcp.git"
+  },
+  "bin": {
+    "env-contract-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",
+    "environment",
+    "configuration",
+    "dotenv",
+    "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/env-contract-mcp",
+  "description": "Local value-free environment contract and configuration drift inspection. Tools include inspect...",
+  "repository": {
+    "url": "https://github.com/mrfentmen/env-contract-mcp",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "env-contract-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}