Skip to main content
Glama

Curate-Ipsum

A graph-spectral MCP server for verified code synthesis through belief revision

PyPI MCP Registry Claude Desktop License: MIT Python

Top Language Code Size Last Commit Repo Size

Curate-Ipsum bridges the gap between LLM-generated code (fast, plausible, unverified) and formally verified patches (slow, correct, trustworthy). It treats mutation testing as one component of a larger system for maintaining robust, self-healing codebase metadata that supports reachability analysis, symbolic execution, and automated test generation.

Install

# PyPI
pip install curate-ipsum

# or with uv
uv pip install curate-ipsum

# Docker (includes baked-in embedding model)
docker pull ghcr.io/egoughnour/curate-ipsum:latest

Claude Desktop / MCP Client

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "curate-ipsum": {
      "command": "uvx",
      "args": ["curate-ipsum"]
    }
  }
}

Or with Docker (embedding model pre-loaded, no Python needed):

{
  "mcpServers": {
    "curate-ipsum": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/egoughnour/curate-ipsum:latest"]
    }
  }
}

Related MCP server: verifiable-thinking-mcp

MCP Tools

Curate-Ipsum exposes 30 tools over the MCP stdio transport, organised into six groups:

Testing — run_unit_tests, run_integration_tests, run_mutation_tests, get_run_history, get_region_metrics, detect_frameworks, parse_region, check_region_relationship, create_region

Belief Revision — add_assertion, contract_assertion, revise_theory, get_entrenchment, list_assertions, get_theory_snapshot, store_evidence, get_provenance, why_believe, belief_stability

Rollback & Failure — rollback_to, undo_last_operations, analyze_failure, list_world_history

Graph-Spectral — extract_call_graph, compute_partitioning, query_reachability, get_hierarchy, find_function_partition, incremental_update, persistent_graph_stats, graph_query

Verification — verify_property (Z3/angr), verify_with_orchestrator (CEGAR budget escalation), list_verification_backends

Synthesis & RAG — synthesize_patch (CEGIS + genetic + LLM), synthesis_status, cancel_synthesis, list_synthesis_runs, rag_index_nodes, rag_search, rag_stats

Current Status

Last Updated: 2026-02-08

Component

Status

Multi-framework parsing (5 frameworks)

Complete

Graph Infrastructure (Spectral/Kameda)

Complete

Belief Revision Engine (AGM/Provenance)

Complete

Synthesis Loop (CEGIS/Genetic)

Complete

Verification Backends (Z3/angr)

Complete

Graph Persistence (SQLite/Kuzu)

Complete

RAG / Semantic Search (Chroma)

Complete

The Problem

LLMs produce code that is:

  • ✅ Syntactically valid (usually)

  • ✅ Statistically plausible

  • ❌ Semantically correct (sometimes)

  • ❌ Type-safe (by accident)

  • ❌ Formally verified (never)

Current approaches either trust LLM output blindly or reject it entirely. Neither is optimal.

The Solution

Use LLMs for cheap candidate generation, then invest computational resources to achieve formal guarantees:

LLM Candidates (k samples)
        ↓
   Seed Population
        ↓
┌───────────────────────────┐
│  CEGIS + CEGAR + Genetic  │  ← Verification loop
│  + Belief Revision        │
└───────────────────────────┘
        ↓
  Strongly Typed Patch
  (with proof certificate)

Key Differentiators from State of the Art

vs. Traditional Mutation Testing (Stryker, mutmut, cosmic-ray)

Traditional

Curate-Ipsum

Single tool, single language

Multi-framework orchestration

Flat file-level analysis

Hierarchical graph-spectral decomposition

Mutation score as output

Mutation testing as input to synthesis

No formal verification

CEGIS/CEGAR verification loop

Manual test writing

Automated patch generation

vs. LLM Code Generation (Copilot, Claude, GPT)

LLM-only

Curate-Ipsum

Trust model output

Verify model output

Single sample or best-of-k

Population-based refinement

No formal guarantees

Proof certificates

Stateless generation

Belief revision with provenance

Plausible code

Provably correct code

vs. Program Synthesis (Sketch, Rosette, SyGuS)

Traditional Synthesis

Curate-Ipsum

Hand-written sketches

LLM-generated candidates

Cold-start search

Warm-start from LLM population

No learning across runs

Totalizing theory accumulates knowledge

Single specification

Multi-framework implicit regions

vs. Symbolic Execution (KLEE, S2E)

Symbolic Execution

Curate-Ipsum

Path exploration only

Integrated with synthesis

Boolean constraint solving

Mathematical reformulation (SymPy)

Single-tool analysis

Graph DB + SMT + mutation orchestration

No code generation

Generates verified patches

Novel Contributions

  1. Graph-Spectral Code Decomposition

    • Fiedler vector partitioning for optimal reachability

    • Hierarchical SCC condensation

    • Planar subgraph identification → O(1) Kameda queries

    • Kuratowski subgraphs as atomic non-planar units

  2. Belief Revision for Synthesis

    • AGM-compliant theory revision

    • Entrenchment ordering for minimal contraction

    • Provenance DAG for failure mode analysis

    • Rollback sharpens validity (failures refine the universal model)

  3. Implicit Region Detection

    • Spectral anomalies reveal undertested code

    • Cross-framework mutation resistance identifies critical regions

    • Historical mutability guides partition optimization

  4. Mathematical Constraint Reformulation

    • Boolean-intractable → differential/root-finding

    • SymPy path condition encoding

    • Hybrid SMT + numerical solving

Architecture

flowchart TB
    subgraph MCP["MCP Interface"]
        direction TB

        subgraph Sources["Analysis Sources"]
            direction LR
            MUT["🧬 Mutation<br/>Orchestrator<br/><small>Stryker<br/>mutmut<br/>cosmic-ray</small>"]
            SYM["🔬 Symbolic<br/>Execution<br/><small>KLEE · Z3<br/>SymPy</small>"]
            GRAPH["📊 Graph<br/>Analysis<br/><small>Joern<br/>Neo4j<br/>Fiedler</small>"]
        end

        MUT --> BRE
        SYM --> BRE
        GRAPH --> BRE

        BRE["🧠 Belief Revision Engine<br/><small>AGM Theory · Entrenchment · Provenance DAG</small>"]

        BRE --> SYNTH

        SYNTH["⚙️ Synthesis Loop<br/><small>CEGIS · CEGAR · Genetic Algorithm</small>"]

        SYNTH --> |"counterexample"| BRE

        SYNTH --> OUTPUT

        OUTPUT["✅ Strongly Typed Patch<br/><small>Proof Certificate ·Type Signature<br/>Pre/Post Conditions</small>"]
    end

    LLM["🤖 LLM Candidates<br/><small>top-k samples</small>"] --> SYNTH

    style MCP fill:#1a1a2e,stroke:#16213e,color:#eee
    style Sources fill:#16213e,stroke:#0f3460,color:#eee
    style MUT fill:#0f3460,stroke:#e94560,color:#eee
    style SYM fill:#0f3460,stroke:#e94560,color:#eee
    style GRAPH fill:#0f3460,stroke:#e94560,color:#eee
    style BRE fill:#533483,stroke:#e94560,color:#eee
    style SYNTH fill:#e94560,stroke:#ff6b6b,color:#fff
    style OUTPUT fill:#06d6a0,stroke:#118ab2,color:#000
    style LLM fill:#ffd166,stroke:#ef476f,color:#000

Roadmap

Phase 1: Foundation ✅

  • MCP server infrastructure

  • Stryker report parsing

  • Run history and PID metrics

  • Flexible region model (hierarchical: file → class → function → lines)

  • mutmut parser integration

  • Framework auto-detection

  • Unified parser interface

Phase 2: Graph Infrastructure ✅

  • Graph models (CodeGraph, Node, Edge)

  • Call graph extraction (AST-based)

  • ASR extractor (import/class analysis)

  • Dependency graph extraction (module-level imports)

  • Laplacian construction from call/dependency graphs

  • Fiedler vector computation (scipy.sparse.linalg)

  • Recursive Fiedler partitioning with virtual sink/source

  • SCC detection and hierarchical condensation

  • Planar subgraph identification (Boyer-Myrvold)

  • Kameda preprocessing for O(1) reachability

  • MCP tools (extract, partition, reachability, hierarchy, find)

Phase 3: Multi-Framework Orchestration ✅

  • Unified mutation framework interface

  • cosmic-ray parser

  • poodle parser

  • universalmutator parser

Phase 4: Belief Revision Engine ✅

  • py-brs library integration (AGM core)

  • Evidence adapter (mutation results → beliefs)

  • Theory manager for curate-ipsum

  • AGM contraction (py-brs v2.0.0 released)

  • Entrenchment calculation (py-brs v2.0.0)

  • Provenance DAG storage and queries

  • Failure mode analyzer

  • Rollback mechanism

Phase 5: Synthesis Loop ✅

  • CEGIS implementation with LLM seeding

  • Genetic algorithm with AST-aware crossover

  • Entropy monitoring and diversity injection

  • Counterexample-directed mutation

  • CEGAR budget escalation (10s → 30s → 120s)

Phase 6: Verification Backends ✅

  • Z3 integration for SMT solving (default backend)

  • angr Docker symbolic execution (expensive tier)

  • CEGAR orchestrator with budget escalation

  • Verification harness builder (C source generation)

  • Mock backend for testing

  • Alternative solvers (CVC5, Boolector)

  • SymPy path condition encoding

Phase 7: Graph Persistence ✅

  • Abstract GraphStore ABC

  • SQLite graph store (primary)

  • Kuzu graph store (optional)

  • Synthesis result persistence

  • Kameda & Fiedler persistence

  • Incremental update engine

  • ChromaDB vector store integration

  • sentence-transformers embedding provider (all-MiniLM-L6-v2)

  • Graph-expanded RAG pipeline (vector top-k → neighbor expansion → rerank)

  • Decay scoring for temporal relevance

  • CEGIS integration for context-aware synthesis

Phase 9: Production Hardening ✅

  • CI/CD (GitHub Actions — lint, test matrix, integration, lockfile)

  • Release pipeline (tag push → PyPI + GHCR + MCP registry)

  • uv lockfile (149 packages)

  • pre-commit hooks (ruff format + lint + lock check)

  • MCP bundle packaging (server.json, smithery.yaml, manifest.json)

  • HTML/SARIF reporting

  • IDE extensions (VSCode)

  • Regression detection and alerting

Future Work

Advanced Orchestration (Deferred)

  • Implicit region detection (spectral anomalies)

  • Non-contradictory framework assignment

  • Cross-framework survival analysis

Semantic Search & RAG

  • Code Graph RAG for semantic search

  • Semantic search index (ChromaDB)

  • RAG retrieval pipeline with graph expansion

  • Text-to-Cypher queries

Quick Start

# Clone and install (dev)
git clone https://github.com/egoughnour/curate-ipsum.git
cd curate-ipsum
uv sync --extra dev --extra verify --extra rag --extra graph --extra synthesis

# Run the MCP server
uv run curate-ipsum

# Or run tests
make test                     # fast suite (no Docker/model needed)
make test-all                 # including integration tests

Configuration

All configuration is via environment variables (see .env.example):

CURATE_IPSUM_GRAPH_BACKEND=sqlite   # or kuzu
MUTATION_TOOL_DATA_DIR=.mutation_tool_data
MUTATION_TOOL_LOG_LEVEL=INFO
CHROMA_HOST=                         # empty = in-process, or localhost:8000
EMBEDDING_MODEL=all-MiniLM-L6-v2

For the full service stack (ChromaDB + angr runner):

make docker-up-verify         # starts Chroma + angr via Docker Compose

Documentation

Planning & Design

Architecture

Reference

Key References

  • Alchourrón, Gärdenfors, Makinson (1985). On the Logic of Theory Change

  • Fiedler (1973). Algebraic Connectivity of Graphs

  • Kameda (1975). On the Vector Representation of Reachability in Planar Directed Graphs

  • Solar-Lezama (2008). Program Synthesis by Sketching (CEGIS)

  • Clarke et al. (2000). Counterexample-Guided Abstraction Refinement (CEGAR)

License

MIT License - see LICENSE


Available Tools

41 tools
add_assertion_toolB

Add an assertion to the synthesis theory with evidence grounding. Assertions are typed beliefs about code (type, behavior, invariant, contract). Each assertion must be grounded by evidence (test results, mutation results, etc.).

Inputs: content (required), projectId (required), evidenceId (required), assertionType (required), +2 more.

analyze_failure_toolA

Analyze why a synthesis attempt failed. Classifies the failure mode (type mismatch, overfitting, underfitting, etc.) and suggests which assertions to contract to fix the issue.

Inputs: projectId (required), regionId, errorMessage, testPassRate, +1 more.

belief_stability_toolB

Measure the stability of an assertion. Returns a score from 0.0 (constantly revised) to 1.0 (never touched). Unstable assertions may need stronger evidence or reformulation.

Inputs: projectId (required), assertionId (required).

cancel_synthesis_toolA

Cancel a running synthesis. Sets a cancellation flag that the CEGIS engine checks between iterations.

Inputs: synthesisId (required).

check_region_relationship_toolA

Check if one region contains or overlaps another. Useful for aggregating metrics across related regions. A file region contains all functions within it; a function region contains its line ranges.

Inputs: regionA (required), regionB (required).

compute_partitioningB

Compute Fiedler spectral partitioning of a project's call graph. Recursively bipartitions the graph using the Fiedler vector (2nd eigenvector of the graph Laplacian). Returns a partition tree with node assignments and algebraic connectivity (λ₂) values.

Inputs: workingDirectory (required), max_depth, min_partition_size.

contract_assertion_toolA

Contract (remove) an assertion from the theory using AGM contraction. Strategies: 'entrenchment' (removes target and less-entrenched dependents), 'minimal' (target and edges only), 'full_cascade' (target and all descendants).

Inputs: nodeId (required), projectId (required), strategy.

create_region_toolB

Create a region identifier for a specific code location. Use level='file' for whole file, 'function' for a function, 'class' for a class, or 'lines' for a line range.

Inputs: filePath (required), level, lineEnd, funcName, +2 more.

detect_frameworks_toolB

Detect available mutation testing frameworks and project language. Returns detected frameworks with confidence scores and a recommendation for which framework to use.

Inputs: workingDirectory (required).

extract_call_graphA

Extract and analyze the call graph of a Python project. Returns summary statistics: node count, edge count, SCC count, connected components, and top-level function list.

Inputs: workingDirectory (required), backend.

find_function_partitionA

Find which partition a function belongs to in the Fiedler partition tree. Returns the partition ID, sibling functions in the same partition, and the entry/exit points of that partition.

Inputs: function_name (required), workingDirectory (required).

get_entrenchment_toolB

Get the entrenchment score for an assertion. Entrenchment measures belief resilience (0.0-1.0, higher = more entrenched). Highly entrenched beliefs are harder to remove via contraction.

Inputs: nodeId (required), projectId (required).

get_hierarchyB

Get the hierarchical decomposition of a project's call graph. Alternates between SCC condensation and Fiedler spectral partitioning to produce a tree representing the project's modular structure.

Inputs: workingDirectory (required).

get_provenance_toolA

Get the provenance DAG summary for a project's synthesis theory. Shows the history of belief revision operations: expansions, contractions, revisions, and evidence storage events.

Inputs: projectId (required).

get_region_metrics_toolC

Compute PID-like metrics and mutation score for a specific region within a project.

Inputs: regionId (required), commitSha (required), projectId (required).

get_run_history_toolB

Return recent unit, integration, and mutation runs for a project and optional region.

Inputs: projectId (required), limit, regionId.

get_theory_snapshot_toolA

Get a snapshot of the current synthesis theory. Returns the world bundle with all nodes, edges, and evidence.

Inputs: projectId (required).

graph_query_toolB

Execute a structured graph query against the persistent store. Supports query types: 'neighbors' (get adjacent nodes), 'reachability' (check if source reaches target via Kameda O(1) index), and 'node' (get node details). Uses stored graph data without re-extraction.

Inputs: projectId (required), queryType (required), workingDirectory (required), nodeId, +3 more.

incremental_update_toolA

Detect file changes and update the persisted call graph incrementally. Compares file hashes to find added/modified/removed files, then updates only the affected graph nodes. Much faster than full re-extraction.

Inputs: projectId (required), workingDirectory (required), pattern.

list_assertions_toolA

List all assertions in the synthesis theory. Optionally filter by assertion type (type, behavior, invariant, contract) or by region ID.

Inputs: projectId (required), regionId, assertionType.

list_synthesis_runs_toolB

List all synthesis runs for a project. Returns a summary of past runs with outcomes, iterations, and fitness.

Inputs: projectId (required).

list_verification_backends_toolA

List available verification backends and their capabilities. Shows which find/avoid predicates and constraint types each backend supports.

Inputs: no named parameters.

list_world_history_toolA

List all historical world states for a project's synthesis theory. Returns world hashes with timestamps and reasons, useful for understanding theory evolution and choosing rollback targets.

Inputs: projectId (required).

parse_region_toolA

Parse a region identifier string into its components. Regions use a hierarchical format: file:::class:::func:::lines:-. Useful for understanding region hierarchy.

Inputs: regionId (required).

persistent_graph_stats_toolB

Get statistics from the persistent graph store for a project. Returns node count, edge count, whether Kameda index and partitions are stored, backend type, and last update timestamp.

Inputs: projectId (required), workingDirectory (required).

query_reachabilityA

Query reachability between two functions in a project's call graph. Uses Kameda O(1) index for planar subgraphs with BFS fallback for non-planar edges. Returns whether the source can reach the target, the method used, and the path if reachable via BFS.

Inputs: source_function (required), target_function (required), workingDirectory (required).

rag_index_nodes_toolB

Index code nodes into the RAG vector store for semantic search. Each node should have an ID, text content, and optional metadata.

Inputs: nodes (required), projectId (required), collection, persistDirectory.

rag_search_toolB

Search the RAG vector store for code relevant to a query. Optionally expands results using the project's call graph.

Inputs: query (required), topK, projectId, collection, +2 more.

rag_stats_toolC

Get statistics about the RAG vector store.

Inputs: collection.

revise_theory_toolA

Revise the theory by incorporating a new assertion. If the new assertion contradicts existing beliefs, those are first contracted (via AGM revision / Levi identity) before adding the new belief.

Inputs: content (required), projectId (required), evidenceId (required), assertionType (required), +2 more.

rollback_to_toolA

Revert the synthesis theory to a prior world state. Uses content-addressable storage — no data is lost, only the current world pointer changes.

Inputs: projectId (required), worldHash (required).

run_integration_tests_toolC

Run integration tests for a project and return a summarized result.

Inputs: command (required), commitSha (required), projectId (required), workingDirectory (required), +2 more.

run_mutation_tests_toolA

Run mutation tests and return summarized mutation statistics. Supports multiple frameworks: stryker (JS/TS), mutmut (Python). If tool is not specified, auto-detects based on project structure.

Inputs: command (required), commitSha (required), projectId (required), workingDirectory (required), +3 more.

run_unit_tests_toolC

Run unit tests for a project and return a summarized result.

Inputs: command (required), commitSha (required), projectId (required), workingDirectory (required), +2 more.

store_evidence_toolA

Store a piece of evidence (test result, mutation result, etc.) in the synthesis theory. Evidence is required to ground assertions.

Inputs: citation (required), projectId (required), evidenceId (required), kind, +1 more.

synthesis_status_toolA

Check the status of a completed synthesis run. Returns iteration count, fitness history, counterexamples resolved, and outcome.

Inputs: synthesisId (required).

synthesize_patch_toolA

Start CEGIS synthesis to generate a patch that kills a surviving mutant. The engine uses LLM candidates + genetic algorithm evolution + counterexample feedback to produce a verified patch. Returns a SynthesisResult dict.

Inputs: projectId (required), testCommand (required), workingDirectory (required), regionId, +7 more.

undo_last_operations_toolA

Undo the last N belief revision operations. Walks backward through the provenance DAG to find the prior world state, then rolls back to it.

Inputs: projectId (required), count.

verify_property_toolB

Run formal verification on a binary or constraint set. Supports Z3 (constraint solving), angr (Docker symbolic execution), and mock backends. Returns verification status and any counterexample found.

Inputs: entry, backend, findKind, avoidKind, +6 more.

verify_with_orchestrator_toolA

Run the CEGAR verification orchestrator with budget escalation. Chains verification attempts with progressively larger budgets (10s → 30s → 120s). Returns aggregated result with iteration history.

Inputs: entry, backend, findKind, findValue, +3 more.

why_believe_toolB

Trace the evidence chain for an assertion. Returns the list of evidence IDs that ground (support) a given assertion, answering 'why do we believe this?'.

Inputs: projectId (required), assertionId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 41 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, and the descriptions are detailed enough to differentiate them. However, a few pairs could cause confusion, such as query_reachability and graph_query_tool (which also supports reachability queries), and the various history-related tools (get_run_history_tool, list_synthesis_runs_tool, list_world_history_tool). Overall, an agent can usually tell them apart with careful reading.

    Naming Consistency3/5

    The vast majority of tools follow a verb_noun pattern and many end with '_tool', but five tools (extract_call_graph, compute_partitioning, query_reachability, get_hierarchy, find_function_partition) break the pattern by omitting the '_tool' suffix. This inconsistency, while minor, makes the set feel less uniform and could lead to an agent treating those tools as a separate category.

    Tool Count2/5

    With 41 tools, this server is extremely comprehensive, spanning testing, theory revision, call graph analysis, synthesis, verification, and RAG. While each tool may have a purpose, the sheer number is overwhelming and likely exceeds what an agent can effectively manage in a single server. The scope is too broad for a coherent toolset; it feels like multiple servers merged into one.

    Completeness4/5

    The tool surface is remarkably complete for the domains it covers: testing, mutation analysis, belief revision, call graph operations, CEGIS synthesis, formal verification, and RAG. There are some minor gaps, such as no explicit deletion of evidence or regions, but these are workable through other tools (e.g., contract_assertion_tool serves as deletion for assertions). Overall, no critical dead ends are apparent.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      An MCP server that enables Large Language Models to interactively create, edit, and solve constraint models using backends like MiniZinc, Z3, PySAT, and Clingo. It bridges natural language with symbolic reasoning for solving complex logical, SAT, SMT, and optimization problems.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server that gives LLMs access to formal verification via Z3 and SWI-Prolog, plus tree-sitter-based source code analysis. Translates natural language problems into formal logic using a template-based pipeline, verifies results with mathematical certainty, and analyzes call graphs for reachability, dead code, and impact analysis.
      205 npm
      219
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      A cognitive optimization engine exposed as an MCP server that amplifies LLM reasoning through self-consistency sampling, MCTS, Dung argumentation, symbolic verification, and measured confidence.
      MIT