curate-ipsum
Utilizes Neo4j graph database for storing code graphs and performing spectral analysis, partitioning, and reachability queries.
Employs SQLite for persistent graph storage and run history, enabling durability and incremental updates.
Parses mutation reports from Stryker to identify undertested code and drive automated patch generation and verification.
Leverages SymPy for symbolic math and path condition encoding to reformulate boolean constraints into numerical problems.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@curate-ipsum synthesize a patch for the failing test in src/utils.py"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Curate-Ipsum
A graph-spectral MCP server for verified code synthesis through belief revision
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:latestClaude 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
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
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)
Implicit Region Detection
Spectral anomalies reveal undertested code
Cross-framework mutation resistance identifies critical regions
Historical mutability guides partition optimization
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:#000Roadmap
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
Phase 8: RAG / Semantic Search ✅
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 testsConfiguration
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-v2For the full service stack (ChromaDB + angr runner):
make docker-up-verify # starts Chroma + angr via Docker ComposeDocumentation
Planning & Design
Phase 2 Plan - Active: Graph-spectral infrastructure (9 steps)
Progress - Current status, what's done, what's next
Decisions - Architectural decisions with reasoning (D-001 through D-008)
M1 Multi-Framework Plan - Region model & parser design (done)
BRS Integration Plan - Belief revision integration
BRS v2 Refactoring Plan - Modular architecture
ROADMAP - Full milestone tracker
Architecture
Architectural Vision - Graph-spectral framework
Synthesis Framework - CEGIS/CEGAR/genetic approach
Belief Revision - AGM theory and provenance
Reference
Summary - Functionality catalog
Potential Directions - Enhancement roadmap
Synergies - Tool ecosystem integration
CONTEXT - Session context for AI assistants
DOCS_INDEX - Documentation quick 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 toolsadd_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
Scored across 41 tools
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.
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.
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.
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
Related MCP Connectors
Codebase knowledge graph — architectural awareness for AI coding agents via MCP
38 MCP tools: Rust computation, Discovery, composition, counterexample scans and signed checks.
Read-only MCP over an agentic SLR workspace with per-claim citation verification
Read-only MCP over an agentic SLR workspace with per-claim citation verification
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceAn 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
- AlicenseBqualityNot gradedmaintenanceMCP server for structured reasoning with cognitive trap detection, verification, and context compression541 npm1-
- AlicenseNot gradedqualityBmaintenanceMCP 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 npm219Apache 2.0
- AlicenseNot gradedqualityCmaintenanceA 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