@morphism-systems/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# @morphism-systems/mcp-server
+
+Governance MCP server for AI agents. Validate governance policies, compute maturity scores, track convergence and drift metrics.
+
+## Install
+
+```bash
+npx @morphism-systems/mcp-server
+```
+
+## MCP Config
+
+```json
+{
+  "mcpServers": {
+    "morphism-governance": {
+      "command": "npx",
+      "args": ["@morphism-systems/mcp-server"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `governance_validate` | Run full governance validation pipeline |
+| `governance_score` | Compute maturity score (0-105) |
+| `compute_kappa` | Convergence metric (kappa < 1 = converging) |
+| `compute_delta` | Drift metric between governance states |
+| `ssot_verify` | Verify SSOT integrity |
+
+## Why Morphism
+
+Governance-as-code with mathematical guarantees. [Learn more](https://morphism.systems).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools/validate.ts
+import { z } from "zod";
+import { execSync } from "child_process";
+var ValidateInput = z.object({
+  project_path: z.string().describe("Path to the project root to validate"),
+  mode: z.enum(["categorical", "pipeline", "full"]).optional().default("full").describe(
+    "categorical: naturality + sheaf + kappa only; pipeline: legacy file checks; full: both"
+  )
+});
+function runPython(cmd, cwd) {
+  try {
+    const stdout = execSync(cmd, { cwd, encoding: "utf-8", timeout: 6e4 });
+    return { stdout, stderr: "", ok: true };
+  } catch (err) {
+    return { stdout: err.stdout || "", stderr: err.stderr || "", ok: false };
+  }
+}
+async function governanceValidate(input) {
+  const { project_path, mode } = input;
+  const catScript = `
+import json, sys
+sys.path.insert(0, '${project_path}/src')
+from pathlib import Path
+from morphism.governance_category import full_categorical_validation
+result = full_categorical_validation(Path('${project_path}'))
+print(json.dumps(result))
+`;
+  const catResult = runPython(
+    `python3 -c "${catScript.replace(/\n/g, "; ").replace(/"/g, '\\"')}"`,
+    project_path
+  );
+  let categorical = null;
+  if (catResult.ok && catResult.stdout.trim()) {
+    try {
+      categorical = JSON.parse(catResult.stdout.trim());
+    } catch (_) {
+    }
+  }
+  let pipelineOutput = "";
+  let pipelineOk = true;
+  if (mode === "pipeline" || mode === "full") {
+    const pipe = runPython("python3 scripts/verify_pipeline.py", project_path);
+    pipelineOutput = pipe.stdout + pipe.stderr;
+    pipelineOk = pipe.ok;
+  }
+  if (categorical) {
+    const proofScript = `
+import json, sys
+sys.path.insert(0, '${project_path}/src')
+from pathlib import Path
+from morphism.governance_category import full_categorical_validation, compute_runtime_evidence
+from morphism.proof.artifact import generate_proof_artifact, write_proof_artifact
+root = Path('${project_path}')
+cat = full_categorical_validation(root)
+gov_vec = cat['governance_vector']
+kappa = cat['kappa']
+proof = generate_proof_artifact(
+    root=root,
+    naturality_result=cat['naturality'],
+    chain_morphisms=[v['morphism'] for v in cat['naturality'].get('verdicts', [])],
+    chain_source='Policy',
+    chain_target='Runbook',
+    convergence_data={'kappa': kappa, 'governance_vector': gov_vec, 'vector_labels': cat['vector_labels'], 'l_inf_distance': kappa},
+    sheaf_radius=cat['sheaf']['consistency_radius'],
+    drift_types=cat['sheaf']['drift_types'],
+    governance_score=sum(gov_vec) / len(gov_vec) if gov_vec else 0.0,
+)
+p = write_proof_artifact(proof, root)
+print(str(p))
+`;
+    const proofResult = runPython(
+      `python3 -c "${proofScript.replace(/\n/g, "; ").replace(/"/g, '\\"')}"`,
+      project_path
+    );
+    const proofPath = proofResult.ok ? proofResult.stdout.trim() : void 0;
+    const nat = categorical.naturality || {};
+    return {
+      valid: categorical.all_valid && pipelineOk,
+      kappa: categorical.kappa,
+      governance_vector: categorical.governance_vector,
+      vector_labels: categorical.vector_labels,
+      naturality: {
+        all_natural: nat.all_natural ?? false,
+        summary: nat.summary ?? "",
+        total: nat.total ?? 0
+      },
+      sheaf: {
+        consistency_radius: categorical.sheaf?.consistency_radius ?? 0,
+        severity: categorical.sheaf?.severity ?? "unknown",
+        drift_types: categorical.sheaf?.drift_types ?? []
+      },
+      categorical_errors: categorical.categorical_errors ?? [],
+      proof_artifact_path: proofPath,
+      output: pipelineOutput || void 0
+    };
+  }
+  const legacy = runPython("python3 scripts/verify_pipeline.py", project_path);
+  return {
+    valid: legacy.ok,
+    output: legacy.stdout,
+    error: legacy.stderr || catResult.stderr || void 0
+  };
+}
+
+// src/tools/score.ts
+import { z as z2 } from "zod";
+var ScoreInput = z2.object({
+  project_path: z2.string().describe("Path to the project root")
+});
+async function governanceScore(input) {
+  const { execSync: execSync3 } = await import("child_process");
+  try {
+    const result = execSync3(
+      `python3 scripts/maturity_score.py --ci --threshold 0`,
+      { cwd: input.project_path, encoding: "utf-8", timeout: 3e4 }
+    );
+    const match = result.match(/(\d+)\s*\/\s*(\d+)/);
+    if (match) {
+      return { score: parseInt(match[1]), total: parseInt(match[2]), output: result };
+    }
+    return { output: result };
+  } catch (err) {
+    const error = err;
+    return { error: error.stderr || error.stdout || "Unknown error" };
+  }
+}
+
+// src/tools/kappa.ts
+import { z as z3 } from "zod";
+import { execSync as execSync2 } from "child_process";
+var KappaInput = z3.object({
+  scores: z3.array(z3.number()).optional().describe("Legacy scalar score sequence (backward compat)"),
+  governance_vector: z3.array(z3.number()).optional().describe(
+    "7-dimensional governance state vector [Policy, GitHook, CIWorkflow, SSOTAtom, Document, SecurityGate, Runbook]"
+  ),
+  kappa_history: z3.array(z3.number()).optional().describe(
+    "Historical kappa values for convergence trajectory check"
+  ),
+  project_path: z3.string().optional().describe(
+    "If provided, compute vector from live project state (ignores governance_vector)"
+  ),
+  tolerance: z3.number().optional().default(1e-6)
+});
+var GOVERNANCE_OBJECTS = [
+  "Policy",
+  "GitHook",
+  "CIWorkflow",
+  "SSOTAtom",
+  "Document",
+  "SecurityGate",
+  "Runbook"
+];
+var WEIGHTS = {
+  Policy: 1.5,
+  GitHook: 1.2,
+  CIWorkflow: 1.2,
+  SSOTAtom: 1,
+  Document: 0.8,
+  SecurityGate: 1.5,
+  Runbook: 0.9
+};
+function vectorKappa(v, ideal = []) {
+  const n = GOVERNANCE_OBJECTS.length;
+  if (v.length !== n) return NaN;
+  const target = ideal.length === n ? ideal : new Array(n).fill(1);
+  return Math.max(...GOVERNANCE_OBJECTS.map(
+    (obj, i) => (WEIGHTS[obj] ?? 1) * Math.abs(target[i] - v[i])
+  ));
+}
+function legacyKappa(scores, tolerance) {
+  if (scores.length < 3) return 0;
+  const deltas = scores.slice(1).map((s, i) => Math.abs(s - scores[i]));
+  if (deltas[deltas.length - 1] <= tolerance) return 0;
+  const ratios = [];
+  for (let i = 1; i < deltas.length; i++) {
+    if (deltas[i - 1] > tolerance) ratios.push(deltas[i] / deltas[i - 1]);
+  }
+  return ratios.length > 0 ? ratios.reduce((a, b) => a + b, 0) / ratios.length : 0;
+}
+function isConverging(history, tolerance = 1e-4) {
+  for (let i = 0; i < history.length - 1; i++) {
+    if (history[i + 1] > history[i] + tolerance) return false;
+  }
+  return true;
+}
+function computeKappa(input) {
+  const tolerance = input.tolerance ?? 1e-6;
+  if (input.project_path) {
+    try {
+      const out = execSync2(
+        `python3 -c "
+import json, sys
+sys.path.insert(0, '${input.project_path}/src')
+from pathlib import Path
+from morphism.governance_category import compute_runtime_evidence, compute_governance_vector, compute_vector_kappa
+ev, _ = compute_runtime_evidence(Path('${input.project_path}'))
+vec = compute_governance_vector(ev)
+k = compute_vector_kappa(vec)
+print(json.dumps({'vector': vec, 'kappa': k}))
+"`,
+        { cwd: input.project_path, encoding: "utf-8", timeout: 3e4 }
+      );
+      const parsed = JSON.parse(out.trim());
+      const kappa = parsed.kappa;
+      const history = input.kappa_history ? [...input.kappa_history, kappa] : [kappa];
+      return {
+        kappa,
+        governance_vector: parsed.vector,
+        vector_labels: GOVERNANCE_OBJECTS,
+        converging: isConverging(history),
+        kappa_history: history,
+        method: "vector_linf_formal",
+        interpretation: interpretKappa(kappa)
+      };
+    } catch (_) {
+    }
+  }
+  if (input.governance_vector && input.governance_vector.length === GOVERNANCE_OBJECTS.length) {
+    const kappa = vectorKappa(input.governance_vector);
+    const history = input.kappa_history ? [...input.kappa_history, kappa] : [kappa];
+    return {
+      kappa,
+      governance_vector: input.governance_vector,
+      vector_labels: GOVERNANCE_OBJECTS,
+      converging: isConverging(history),
+      kappa_history: history,
+      method: "vector_linf_formal",
+      interpretation: interpretKappa(kappa)
+    };
+  }
+  if (input.scores && input.scores.length >= 2) {
+    const kappa = legacyKappa(input.scores, tolerance);
+    return {
+      kappa,
+      converges: kappa < 1,
+      method: "legacy_scalar_ratio",
+      interpretation: kappa === 0 ? "Converged or insufficient data" : kappa < 1 ? `Converging (\u03BA=${kappa.toFixed(4)}) \u2014 NOTE: scalar heuristic, use governance_vector for formal \u03BA` : `Diverging (\u03BA=${kappa.toFixed(4)})`
+    };
+  }
+  return { error: "Provide governance_vector (preferred), scores, or project_path" };
+}
+function interpretKappa(k) {
+  if (k === 0) return "Fixed point: governance is fully compliant";
+  if (k < 0.1) return `\u03BA=${k.toFixed(3)}: Excellent \u2014 near fixed point`;
+  if (k < 0.3) return `\u03BA=${k.toFixed(3)}: Good \u2014 governance converging`;
+  if (k < 0.6) return `\u03BA=${k.toFixed(3)}: WARNING \u2014 significant compliance gaps`;
+  return `\u03BA=${k.toFixed(3)}: CRITICAL \u2014 governance far from fixed point`;
+}
+
+// src/tools/delta.ts
+import { z as z4 } from "zod";
+var DeltaInput = z4.object({
+  baseline: z4.union([z4.number(), z4.array(z4.number())]).describe("Baseline state"),
+  current: z4.union([z4.number(), z4.array(z4.number())]).describe("Current state")
+});
+function robustnessDelta(baseline, current) {
+  if (typeof baseline === "number" && typeof current === "number") {
+    return Math.abs(current - baseline);
+  }
+  if (Array.isArray(baseline) && Array.isArray(current)) {
+    if (baseline.length !== current.length) return Infinity;
+    if (baseline.length === 0) return 0;
+    const sum = baseline.reduce((acc, b, i) => acc + Math.abs(current[i] - b), 0);
+    return sum / baseline.length;
+  }
+  return 0;
+}
+function computeDelta(input) {
+  const delta = robustnessDelta(input.baseline, input.current);
+  return {
+    delta,
+    drifted: delta > 0,
+    severity: delta === 0 ? "none" : delta < 5 ? "low" : delta < 15 ? "medium" : "high"
+  };
+}
+
+// src/tools/ssot.ts
+import { z as z5 } from "zod";
+var SsotInput = z5.object({
+  project_path: z5.string().describe("Path to the project root")
+});
+async function ssotVerify(input) {
+  const { execSync: execSync3 } = await import("child_process");
+  try {
+    const result = execSync3(
+      `python3 scripts/ssot_verify.py`,
+      { cwd: input.project_path, encoding: "utf-8", timeout: 3e4 }
+    );
+    return { valid: true, output: result };
+  } catch (err) {
+    const error = err;
+    return { valid: false, output: error.stdout || "", error: error.stderr || "" };
+  }
+}
+
+// src/server.ts
+function createServer() {
+  const server2 = new McpServer({
+    name: "morphism-governance",
+    version: "0.1.0"
+  });
+  server2.tool(
+    "governance_validate",
+    "Run the full governance validation pipeline on a project.",
+    ValidateInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(await governanceValidate(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "governance_score",
+    "Compute the governance maturity score (0-105) for a project.",
+    ScoreInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(await governanceScore(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "compute_kappa",
+    "Compute convergence metric \u03BA from governance scores. \u03BA < 1 means converging.",
+    KappaInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(computeKappa(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "compute_delta",
+    "Compute drift metric \u03B4 between baseline and current governance state.",
+    DeltaInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(computeDelta(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "ssot_verify",
+    "Verify SSOT integrity \u2014 check for drift between source of truth atoms.",
+    SsotInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(await ssotVerify(input), null, 2) }]
+    })
+  );
+  return server2;
+}
+
+// src/index.ts
+var server = createServer();
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@morphism-systems/mcp-server",
+  "version": "0.1.0",
+  "description": "Governance MCP server — validation, maturity scoring, convergence and drift metrics",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "morphism-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "echo 'no lint configured'"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-governance",
+    "morphism",
+    "governance-as-code"
+  ],
+  "license": "BUSL-1.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.0.0"
+  }
+}