symkit-mcp

# SymKit > **Mathematica-style symbolic computation, powered by LLMs.** [](LICENSE) [](https://www.python.org/) [](https://modelcontextprotocol.io/) []() []() 🌐 **English** | [简体中文](README.zh-CN.md) ## What if you had Mathematica's symbolic engine, driven by natural language? Mathematica gave us precise symbolic math. LLMs gave us natural-language reasoning. **SymKit combines both.** It is an MCP server that lets AI agents perform step-by-step symbolic derivations: calculate, transform, verify, and store formulas with full provenance — all through conversation. ```text ┌────────────────────────────────────────────────────────────────────┐ │ │ │ You describe the math in plain English │ │ ↓ │ │ SymKit executes, verifies, and records every step │ │ ↓ │ │ You get an exact, reusable formula with an audit trail │ │ │ └────────────────────────────────────────────────────────────────────┘ ``` ## Why SymKit? | Traditional LLM | SymKit | |---|---| | ❌ "The answer is approximately..." | ✅ "The exact expression is..." | | ❌ "Let me calculate that again" | ✅ Every step is recorded and verifiable | | ❌ "I think these units work out" | ✅ Dimensional analysis checks every result | | ❌ "Where did this formula come from?" | ✅ Full provenance: base formulas + derivation steps | | ❌ Calculation is lost in chat history | ✅ Stored as reusable Markdown + YAML | ## What it does SymKit is **not a formula database**. It is a **symbolic derivation engine** that creates new formulas from existing ones. ```text Known formulas New formula ┌─────────────────┐ ┌────────────────────────────┐ │ F = -kx │ │ │ │ F = ma │ ──compose──▶ │ ω = √(k/m) │ │ d²x/dt² = a │ │ (simple harmonic oscillator) │ └─────────────────┘ └────────────────────────────┘ ``` Use it for physics, engineering, chemistry, biology, economics — any domain where you need to combine and transform mathematical relationships. ## ⚡ Four superpowers | Capability | What it means | Tools | |---|---|---| | **Derive** | Combine base formulas into new ones | `derive`, `intent_execute`, `math` | | **Control** | Review, annotate, and rollback every step | `session_*`, `*_step` | | **Verify** | Check correctness symbolically and dimensionally | `session_verify_*`, `assume*` | | **Ship** | Turn results into Python, LaTeX, Markdown, or SymPy | `generate_*` | ## 🚀 See it in action **Derive a physical law from first principles:** ```text User: Derive the angular frequency of a simple harmonic oscillator. SymKit: 1. Load F = -kx and F = m·d²x/dt² 2. Substitute → m·d²x/dt² = -kx 3. Solve ODE → x(t) = A·cos(ωt + φ), ω = √(k/m) 4. Verify by substitution: d²x/dt² = -ω²x ✓ 5. Store result with full derivation history ``` **Build a custom engineering model:** ```text User: Find the cutoff frequency of an RC high-pass filter. SymKit: 1. Load Q = CV and V = IR 2. Derive capacitive reactance X_c = 1/(2πfC) 3. Set X_c = R at cutoff 4. Solve for f → f_c = 1 / (2πRC) ✓ ``` **Verify a calculus result:** ```text User: Calculate and verify ∫(x² + 3x) dx. → Result: x³/3 + 3x²/2 + C → Verify: d/dx(x³/3 + 3x²/2) = x² + 3x ✓ ``` ## 🛠️ 41 MCP tools, one coherent workflow SymKit exposes **41 MCP tools** across 8 categories. Everything routes through a few high-level tools while power users can drop down to individual steps. | Category | Tools | Count | |---|---|---| | **Unified Math** | `math` | 1 | | **Session Management** | `session_start`, `session_show`, `session_rollback`, `session_complete`, ... | 17 | | **Assumptions** | `assume`, `show_assumptions`, `assume_for_step`, `list_assumptions`, `check_assumption_conflicts`, `clear_step_assumptions` | 6 | | **Formula Search** | `formula_search`, `formula_get`, `formula_add`, `formula_categories` | 4 | | **Symbol Registry** | `register_symbol`, `lookup_symbol`, `list_domain_symbols`, `check_symbol_conflicts` | 4 | | **Code Generation** | `generate_python_function`, `generate_latex_derivation`, `generate_derivation_report`, `generate_sympy_script` | 4 | | **Derivation & Orchestration** | `derive`, `intent_execute`, `list_patterns` | 3 | | **Tool Discovery** | `tool_categories`, `tool_recommend` | 2 | The `math()` tool alone covers ~25 symbolic operations — calculus, ODEs, matrices, vector analysis, integral transforms — and can write its result directly into a derivation session. ## 🔍 Formula search workflow SymKit can pull authoritative formulas from Wikidata and physical constants from SciPy, normalize LLM queries automatically, and load the chosen formula straight into a derivation session. **Recommended workflow:** ```text 1. Search formula_search("Navier-Stokes equations", domain="fluid_dynamics") 2. Get and load formula_get("Q201321", source="wikidata", load_into_session=True) 3. Derive math("simplify", "...", session=True) 4. Complete session_complete(description="Incompressible NS momentum equation") ``` **Query normalization:** you can write queries naturally — `fluid_dynamics`, `fluid mechanics`, and `cfd` all resolve to the same domain; `Navier–Stokes` (en dash) and `Navier-Stokes` (hyphen) match the same Wikidata item. **MathML handling:** Wikidata sometimes returns rendered MathML for search previews. Call `formula_get` on the result ID to retrieve the original LaTeX and a SymPy-ready string. ## 🎛️ You own every step A derivation in SymKit is a chain of immutable, verifiable steps. You can: - **Create** — `session_record_step` - **Read** — `session_get_steps`, `session_show` - **Annotate** — `session_add_note` - **Rollback** — `session_rollback` - **Verify** — `session_verify_step`, `session_verify_session` Expressions are never edited in place. If something goes wrong, roll back to the last good state and continue. This keeps the entire derivation reproducible. ## 🌍 Works with the MCP ecosystem SymKit is designed to extend, not replace, your scientific computing stack. It handles derivation, verification, and provenance; raw symbolic computation and base formulas are delegated to SymPy-MCP. **When to use SymKit:** - ✅ Deriving new formulas from existing ones - ✅ Building temperature/pressure/parameter-corrected models - ✅ Creating custom models for any quantitative domain - ✅ Producing verified, citable derivation results **When to use something else:** - ❌ Looking up basic physics formulas → use `sympy-mcp` - ❌ Fetching physical constants → use `sympy-mcp` or `SciPy` - ❌ Clinical scoring → use `medical-calc-mcp` - ❌ Reading textbook formulas → use the reference directly ## 📦 Get started in 60 seconds ### Requirements - **Python 3.10+** - **uv** (recommended) ```bash # Install uv add symkit-mcp # Or use pip pip install symkit-mcp ``` ### Where data lives After install, SymKit stores runtime data in a per-user directory (resolved via `platformdirs`): derived formulas and session JSONs persist under `~/.local/share/symkit/` (Linux), `%LOCALAPPDATA%\symkit` (Windows), or `~/Library/Application Support/symkit` (macOS). Set the `SYMKIT_DATA_DIR` environment variable to override this location. Seed formulas (Reynolds number, Navier-Stokes, …) ship read-only inside the package; user-added formulas via `formula_add` are written to the writable overlay and override seeds by id. ### Connect to Claude Desktop / Cherry Studio The same JSON works in any MCP-compatible client (Claude Desktop, Cherry Studio, etc.). **If you installed from PyPI:** ```json { "mcpServers": { "symkit": { "command": "uvx", "args": ["symkit-mcp"] } } } ``` **If you are running from the local source directory (no install needed):** ```json { "mcpServers": { "symkit": { "command": "uv", "args": [ "run", "--no-sync", "--directory", "<your-local-symkit-mcp-path>", "python", "-m", "symkit_mcp.server" ] } } } ``` Replace `--directory` with the absolute path to your local `symkit-mcp` clone. `--no-sync` skips dependency resolution on every launch; run `uv sync` manually when dependencies change. ### From source ```bash git clone https://github.com/LBurny/symkit-mcp.git cd symkit-mcp uv sync --all-extras uv run symkit-mcp ``` ## 🏗️ Clean architecture, built to extend ```text symkit-mcp/ ├── src/ │ ├── symkit/ # Pure domain logic (no MCP dependency) │ │ ├── domain/ # Entities, value objects, derivation engine │ │ ├── application/ # Use cases │ │ └── infrastructure/ # SymPy engine, adapters, persistence │ └── symkit_mcp/ # MCP server layer │ ├── server.py │ └── tools/ # 41 MCP tools ├── formulas/ # Seed formula library (source tree) ├── tests/ # 295 tests └── pyproject.toml ``` - **Domain-driven design** — core logic is independent of MCP and SymPy. - **Pluggable engines** — swap the symbolic engine or verifier via protocols. - **File-based persistence** — formulas and sessions live in readable Markdown/YAML/JSON. ## 🧪 Development ```bash # Run the full test suite uv run pytest # Lint and type check uv run ruff check src/ tests/ uv run mypy src/ # Start the dev server uv run symkit-mcp ``` ## 📖 Learn more - [Architecture](ARCHITECTURE.md) — DDD layering and responsibilities - [SymKit Design](docs/symkit-design.md) — In-depth technical design (English) - [SymKit Design (中文)](docs/symkit-design.zh-CN.md) — 中文设计文档 - [SymKit vs SymPy-MCP](docs/symkit-vs-sympy-mcp.md) — Capability comparison - [Roadmap](ROADMAP.md) — What's coming next ## 🙏 Acknowledgments SymKit is built on the foundation of [nsforge-mcp](https://github.com/u9401066/nsforge-mcp), which pioneered the neurosymbolic formula-derivation approach. The original Chinese README of nsforge-mcp can be found [here](https://github.com/u9401066/nsforge-mcp/blob/master/README.zh-TW.md). SymKit works alongside [sympy-mcp](https://github.com/sdiehl/sympy-mcp), which provides the underlying SymPy-based symbolic computation and base formula lookup that SymKit builds upon. ## 📄 License Apache 2.0 — see [LICENSE](LICENSE). --- <p align="center"> <strong>Stop answering math questions. Start deriving new knowledge.</strong> </p>