@morphism-systems/agentic-math 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @morphism-systems/agentic-math
+
+Category theory MCP server for AI agents. Provides morphism composition, functor mapping, natural transformations, entropy computation, and convergence checking.
+
+## Install
+
+```bash
+npx @morphism-systems/agentic-math
+```
+
+## MCP Config
+
+Add to your `.claude/mcp.json` or Cursor MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "morphism-math": {
+      "command": "npx",
+      "args": ["@morphism-systems/agentic-math"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `morphism_compose` | Compose two morphisms f . g |
+| `functor_map_object` | Apply a functor to an object |
+| `functor_map_morphism` | Apply a functor to a morphism |
+| `natural_transform_check` | Check naturality condition |
+| `natural_transform_compose` | Vertical composition of natural transformations |
+| `entropy_compute` | Shannon entropy H(s) = -sum(p_i ln(p_i)) |
+| `convergence_check` | Check if governance converges (kappa < 1) |
+| `drift_check` | Compute drift delta between states |
+| `analyze_scores` | Full governance score analysis |
+
+## Why Morphism
+
+Morphism provides mathematically-grounded governance for AI agent fleets. Instead of heuristics, it uses category theory and the Banach contraction principle to guarantee convergence. [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,480 @@
+#!/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/compose.ts
+import { z as z2 } from "zod";
+
+// src/engine/morphism.ts
+import { z } from "zod";
+var MorphismSchema = z.object({
+  name: z.string(),
+  source: z.string(),
+  target: z.string(),
+  metadata: z.record(z.unknown()).default({})
+});
+function compose(f, g) {
+  if (f.source !== g.target) {
+    throw new TypeError(
+      `Cannot compose: ${f.name}.source (${f.source}) != ${g.name}.target (${g.target})`
+    );
+  }
+  return {
+    name: `${f.name} . ${g.name}`,
+    source: g.source,
+    target: f.target,
+    metadata: { composed_from: [f.name, g.name] }
+  };
+}
+
+// src/tools/compose.ts
+var ComposeInput = z2.object({
+  f: MorphismSchema.describe("First morphism (applied second)"),
+  g: MorphismSchema.describe("Second morphism (applied first)")
+});
+function morphismCompose(input) {
+  return compose(input.f, input.g);
+}
+
+// src/tools/functor-map.ts
+import { z as z4 } from "zod";
+
+// src/engine/functor.ts
+import { z as z3 } from "zod";
+var FunctorSchema = z3.object({
+  name: z3.string(),
+  source_category: z3.string(),
+  target_category: z3.string(),
+  object_map: z3.record(z3.string()).default({}),
+  metadata: z3.record(z3.unknown()).default({})
+});
+function mapObject(functor, obj) {
+  const mapped = functor.object_map[obj];
+  if (mapped === void 0) {
+    throw new Error(`Object '${obj}' not in functor ${functor.name}'s object map`);
+  }
+  return mapped;
+}
+function mapMorphism(functor, morphism) {
+  return {
+    name: `${functor.name}(${morphism.name})`,
+    source: mapObject(functor, morphism.source),
+    target: mapObject(functor, morphism.target),
+    metadata: { functor: functor.name, original: morphism.name }
+  };
+}
+
+// src/tools/functor-map.ts
+var FunctorMapObjectInput = z4.object({
+  functor: FunctorSchema,
+  object: z4.string().describe("Object name to map")
+});
+var FunctorMapMorphismInput = z4.object({
+  functor: FunctorSchema,
+  morphism: MorphismSchema
+});
+function functorMapObject(input) {
+  return { mapped: mapObject(input.functor, input.object) };
+}
+function functorMapMorphism(input) {
+  return mapMorphism(input.functor, input.morphism);
+}
+
+// src/tools/nat-transform.ts
+import { z as z6 } from "zod";
+
+// src/engine/natural-transformation.ts
+import { z as z5 } from "zod";
+var NaturalTransformationSchema = z5.object({
+  name: z5.string(),
+  source_functor: FunctorSchema,
+  target_functor: FunctorSchema,
+  components: z5.record(MorphismSchema).default({}),
+  metadata: z5.record(z5.unknown()).default({})
+});
+function componentAt(nt, obj) {
+  const component = nt.components[obj];
+  if (!component) {
+    throw new Error(`No component defined at object '${obj}' for ${nt.name}`);
+  }
+  return component;
+}
+function checkNaturality(nt, morphism) {
+  const x = morphism.source;
+  const y = morphism.target;
+  const alphaX = componentAt(nt, x);
+  const gF = mapMorphism(nt.target_functor, morphism);
+  const left = compose(gF, alphaX);
+  const alphaY = componentAt(nt, y);
+  const fF = mapMorphism(nt.source_functor, morphism);
+  const right = compose(alphaY, fF);
+  return left.source === right.source && left.target === right.target;
+}
+function composeVertical(beta, alpha) {
+  if (beta.source_functor.name !== alpha.target_functor.name) {
+    throw new TypeError(
+      `Cannot compose: ${beta.name}.source_functor (${beta.source_functor.name}) != ${alpha.name}.target_functor (${alpha.target_functor.name})`
+    );
+  }
+  const allObjects = Object.keys(beta.components).filter(
+    (obj) => obj in alpha.components
+  );
+  const composed = {};
+  for (const obj of allObjects) {
+    composed[obj] = compose(componentAt(beta, obj), componentAt(alpha, obj));
+  }
+  return {
+    name: `${beta.name} . ${alpha.name}`,
+    source_functor: alpha.source_functor,
+    target_functor: beta.target_functor,
+    components: composed,
+    metadata: { composed_from: [beta.name, alpha.name] }
+  };
+}
+
+// src/tools/nat-transform.ts
+var CheckNaturalityInput = z6.object({
+  transformation: NaturalTransformationSchema,
+  morphism: MorphismSchema.describe("Morphism f: X -> Y to check naturality against")
+});
+var ComposeVerticalInput = z6.object({
+  beta: NaturalTransformationSchema.describe("Top transformation (applied second)"),
+  alpha: NaturalTransformationSchema.describe("Bottom transformation (applied first)")
+});
+function natCheckNaturality(input) {
+  return { commutes: checkNaturality(input.transformation, input.morphism) };
+}
+function natComposeVertical(input) {
+  return composeVertical(input.beta, input.alpha);
+}
+
+// src/tools/entropy.ts
+import { z as z7 } from "zod";
+
+// src/engine/convergence.ts
+function convergenceConstant(scoreSequence, tolerance = 1e-6) {
+  if (scoreSequence.length < 3) return 0;
+  const deltas = [];
+  for (let i = 1; i < scoreSequence.length; i++) {
+    deltas.push(Math.abs(scoreSequence[i] - scoreSequence[i - 1]));
+  }
+  if (deltas.length === 0 || 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]);
+    }
+  }
+  if (ratios.length === 0) return 0;
+  return ratios.reduce((a, b) => a + b, 0) / ratios.length;
+}
+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 entropy(probabilities) {
+  if (probabilities.length === 0) return 0;
+  let h = 0;
+  for (const p of probabilities) {
+    if (p > 0) {
+      h -= p * Math.log(p);
+    }
+  }
+  return h;
+}
+function analyzeFromScores(scores) {
+  const kappa = convergenceConstant(scores);
+  const current = scores.length > 0 ? scores[scores.length - 1] : 0;
+  const baseline = scores.length > 0 ? scores[0] : 0;
+  const delta = robustnessDelta(baseline, current);
+  return { kappa, delta, current, baseline };
+}
+
+// src/tools/entropy.ts
+var EntropyInput = z7.object({
+  probabilities: z7.array(z7.number()).describe("Probability distribution (should sum to ~1)")
+});
+function entropyCompute(input) {
+  const h = entropy(input.probabilities);
+  return { entropy: h };
+}
+
+// src/tools/convergence.ts
+import { z as z8 } from "zod";
+var ConvergenceCheckInput = z8.object({
+  scores: z8.array(z8.number()).describe("Sequence of governance scores over time"),
+  tolerance: z8.number().optional().default(1e-6)
+});
+var DriftCheckInput = z8.object({
+  baseline: z8.union([z8.number(), z8.array(z8.number())]).describe("Baseline state"),
+  current: z8.union([z8.number(), z8.array(z8.number())]).describe("Current state")
+});
+function convergenceCheck(input) {
+  const kappa = convergenceConstant(input.scores, input.tolerance);
+  return {
+    kappa,
+    converges: kappa < 1,
+    interpretation: kappa === 0 ? "Already converged or insufficient data" : kappa < 1 ? `Converging (\u03BA=${kappa.toFixed(4)})` : `Diverging (\u03BA=${kappa.toFixed(4)}) \u2014 governance not contracting`
+  };
+}
+function driftCheck(input) {
+  const delta = robustnessDelta(input.baseline, input.current);
+  return {
+    delta,
+    drifted: delta > 0
+  };
+}
+function analyzeScores(input) {
+  return analyzeFromScores(input.scores);
+}
+
+// src/tools/governance-validate.ts
+import { z as z9 } from "zod";
+import { execSync } from "child_process";
+var GovernanceValidateInput = z9.object({
+  project_path: z9.string().describe("Absolute path to the project root"),
+  write_proof: z9.boolean().optional().default(true).describe(
+    "Write proof artifact to .morphism/proofs/"
+  ),
+  include_sheaf: z9.boolean().optional().default(true).describe(
+    "Run sheaf-theoretic drift analysis (H\xB9 cohomology)"
+  )
+});
+function governanceCategoricalValidate(input) {
+  const { project_path, write_proof, include_sheaf } = input;
+  const script = [
+    `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, compute_governance_vector, compute_vector_kappa`,
+    `root = Path('${project_path}')`,
+    `result = full_categorical_validation(root)`,
+    // Proof artifact generation
+    ...write_proof ? [
+      `from morphism.proof.artifact import generate_proof_artifact, write_proof_artifact`,
+      `gov_vec = result['governance_vector']`,
+      `kappa = result['kappa']`,
+      `proof = generate_proof_artifact(`,
+      `    root=root,`,
+      `    naturality_result=result['naturality'],`,
+      `    chain_morphisms=[v['morphism'] for v in result['naturality'].get('verdicts', [])],`,
+      `    chain_source='Policy', chain_target='Runbook',`,
+      `    convergence_data={'kappa': kappa, 'governance_vector': gov_vec, 'vector_labels': result['vector_labels'], 'l_inf_distance': kappa, 'kappa_history': [kappa]},`,
+      `    sheaf_radius=result['sheaf']['consistency_radius'],`,
+      `    drift_types=result['sheaf']['drift_types'],`,
+      `    governance_score=sum(gov_vec)/len(gov_vec) if gov_vec else 0.0,`,
+      `)`,
+      `p = write_proof_artifact(proof, root)`,
+      `result['proof_artifact_path'] = str(p)`,
+      `result['proof_sha256'] = proof.sha256`
+    ] : [],
+    `print(json.dumps(result, default=str))`
+  ].join("\n");
+  try {
+    const out = execSync(
+      `python3 -c "${script.replace(/\n/g, "\n").replace(/"/g, '\\"')}"`,
+      { cwd: project_path, encoding: "utf-8", timeout: 6e4 }
+    );
+    const parsed = JSON.parse(out.trim());
+    return {
+      success: true,
+      all_valid: parsed.all_valid,
+      kappa: parsed.kappa,
+      governance_vector: parsed.governance_vector,
+      vector_labels: parsed.vector_labels,
+      naturality: {
+        all_natural: parsed.naturality?.all_natural,
+        summary: parsed.naturality?.summary,
+        violations: (parsed.naturality?.verdicts ?? []).filter((v) => !v.natural).map((v) => v.violation).filter(Boolean)
+      },
+      sheaf: parsed.sheaf,
+      categorical_errors: parsed.categorical_errors,
+      proof_artifact_path: parsed.proof_artifact_path,
+      proof_sha256: parsed.proof_sha256
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err.stderr || err.message || "Unknown error",
+      stdout: err.stdout || ""
+    };
+  }
+}
+var NaturalityCheckInput = z9.object({
+  project_path: z9.string().describe("Path to project root"),
+  morphism_name: z9.string().optional().describe(
+    'Check naturality for a specific morphism only (e.g. "enforce_hook")'
+  )
+});
+function checkGovernanceNaturality(input) {
+  const script = [
+    `import json, sys`,
+    `sys.path.insert(0, '${input.project_path}/src')`,
+    `from pathlib import Path`,
+    `from morphism.governance_category import compute_runtime_evidence`,
+    `from morphism.governance_category import GOVERNANCE_OBJECTS`,
+    `from morphism.engine.naturality_bridge import check_governance_naturality`,
+    `ev, _ = compute_runtime_evidence(Path('${input.project_path}'))`,
+    `result = check_governance_naturality(ev, GOVERNANCE_OBJECTS)`,
+    ...input.morphism_name ? [
+      `result['verdicts'] = [v for v in result['verdicts'] if v['morphism'] == '${input.morphism_name}']`
+    ] : [],
+    `print(json.dumps(result))`
+  ].join("\n");
+  try {
+    const out = execSync(
+      `python3 -c "${script.replace(/\n/g, "\n").replace(/"/g, '\\"')}"`,
+      { cwd: input.project_path, encoding: "utf-8", timeout: 3e4 }
+    );
+    return { success: true, ...JSON.parse(out.trim()) };
+  } catch (err) {
+    return { success: false, error: err.stderr || err.message };
+  }
+}
+var SheafDriftInput = z9.object({
+  project_path: z9.string().describe("Path to project root")
+});
+function checkSheafDrift(input) {
+  const script = [
+    `import json, sys`,
+    `sys.path.insert(0, '${input.project_path}/src')`,
+    `from pathlib import Path`,
+    `from morphism.governance_category import compute_runtime_evidence`,
+    `from morphism.sheaf.cech_complex import build_governance_sheaf, analyze_governance_drift`,
+    `ev, dim_scores = compute_runtime_evidence(Path('${input.project_path}'))`,
+    `sheaf = build_governance_sheaf(ev, dim_scores)`,
+    `report = analyze_governance_drift(sheaf)`,
+    `print(json.dumps({'consistency_radius': report.consistency_radius, 'h1_non_trivial': report.h1_non_trivial, 'obstructions': report.obstructions, 'drift_types': report.drift_types, 'severity': report.severity, 'recommendation': report.recommendation}))`
+  ].join("\n");
+  try {
+    const out = execSync(
+      `python3 -c "${script.replace(/\n/g, "\n").replace(/"/g, '\\"')}"`,
+      { cwd: input.project_path, encoding: "utf-8", timeout: 3e4 }
+    );
+    return { success: true, ...JSON.parse(out.trim()) };
+  } catch (err) {
+    return { success: false, error: err.stderr || err.message };
+  }
+}
+
+// src/server.ts
+function createServer() {
+  const server2 = new McpServer({
+    name: "morphism-agentic-math",
+    version: "0.1.0"
+  });
+  server2.tool(
+    "morphism_compose",
+    "Compose two morphisms f . g (category theory). Requires f.source == g.target.",
+    ComposeInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(morphismCompose(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "functor_map_object",
+    "Apply a functor to an object, mapping it between categories.",
+    FunctorMapObjectInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(functorMapObject(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "functor_map_morphism",
+    "Apply a functor to a morphism, preserving structure between categories.",
+    FunctorMapMorphismInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(functorMapMorphism(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "natural_transform_check",
+    "Check if a natural transformation satisfies the naturality condition for a morphism.",
+    CheckNaturalityInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(natCheckNaturality(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "natural_transform_compose",
+    "Vertical composition of natural transformations: beta . alpha.",
+    ComposeVerticalInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(natComposeVertical(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "entropy_compute",
+    "Compute Shannon entropy H(s) = -sum(p_i * ln(p_i)) for a probability distribution.",
+    EntropyInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(entropyCompute(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "convergence_check",
+    "Check if governance iteration converges (kappa < 1, Banach contraction).",
+    ConvergenceCheckInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(convergenceCheck(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "drift_check",
+    "Compute drift delta between baseline and current governance state.",
+    DriftCheckInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(driftCheck(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "analyze_scores",
+    "Full analysis of governance score sequence: kappa, delta, current, baseline.",
+    ConvergenceCheckInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(analyzeScores(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "governance_categorical_validate",
+    "Full categorical governance validation: naturality check, sheaf drift (H\uFFFD cohomology), vector kappa, and proof artifact generation.",
+    GovernanceValidateInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(governanceCategoricalValidate(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "governance_naturality_check",
+    "Check that governance policy enforcement satisfies the naturality condition (commuting diagrams). Violations indicate input-order-dependent enforcement.",
+    NaturalityCheckInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(checkGovernanceNaturality(input), null, 2) }]
+    })
+  );
+  server2.tool(
+    "governance_sheaf_drift",
+    "Sheaf-theoretic drift detection: compute H\uFFFD cohomology obstructions. Non-trivial H\uFFFD means globally inconsistent governance that local auditing cannot detect.",
+    SheafDriftInput.shape,
+    async (input) => ({
+      content: [{ type: "text", text: JSON.stringify(checkSheafDrift(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,38 @@
+{
+  "name": "@morphism-systems/agentic-math",
+  "version": "0.1.0",
+  "description": "Category theory MCP server — morphisms, functors, natural transformations, convergence",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "agentic-math": "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",
+    "category-theory",
+    "morphism",
+    "functor",
+    "natural-transformation",
+    "ai-governance"
+  ],
+  "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"
+  }
+}