🦠 Cordyceps Search

Cordyceps Search is a high-performance codebase semantic search, dependency tracking, and AST-aware refactoring engine. It is packaged as an MCP (Model Context Protocol) server designed to empower developer agents with the structural understanding and refactoring capabilities of a mature IDE.

By combining the blazing speed of a Rust-native CSR (Compressed Sparse Row) graph engine with the precision of tree-sitter AST parsers, Cordyceps Search enables instant semantic discovery, caller/callee blast radius auditing, and cross-file refactoring.

🚀 Key Features

• Zero-Copy CSR Graph Engine: Backed by a high-performance Rust core (engramdb) for microsecond-level graph traversals and memory efficiency.

• Multi-Language AST Parsing: Full structural extraction (classes, methods, functions, calls, returns, docstrings) for Python, JavaScript, JSX, TypeScript, and TSX using tree-sitter.

• Cross-Boundary API Tracking: Traces connections between frontend HTTP requests (fetch, axios) and backend endpoints (Django, Flask, FastAPI).

• AST-Aware Safe Refactoring: Supports syntax-validated node edits, structured node creation, and AST-aware renaming with cross-file reference propagation.

• Watchdog-Driven Real-Time Sync: Automatically detects file additions, modifications, and deletions in the workspace, debouncing events, and keeping the code graph dynamically updated.

• Thread-Safe RW Concurrency: Protected by a read-write lock mechanism to ensure safe multi-threaded reads while keeping the unsendable Rust engine execution serial.

Related MCP server: OmniWeave

Supported Languages

Indexed via tree-sitter. Adding a language = drop a YAML config in src/database/parser/languages/ — no code changes required. Other files are ingested as body-only File nodes (searchable, no AST).

Body-only file nodes (no AST, searchable as files): .json, .md, .html, .css, .yml, .yaml, .toml, .txt, .sql.

Excluded from indexing: node_modules, venv, .venv, __pycache__, target, dist, build, migrations, .git, .idea, .vscode, coverage, .next, .nuxt, fixtures, test_fixtures, test_data and any dotfile dirs. Extend via CORDYCEPS_EXCLUDE env var (comma-separated).

🏗️ Architecture

• main.py: The stdio transport server entrypoint using FastMCP.

• src/database/: Core client interface wrapping the Rust engine, managing Django ORM/URL resolutions, and enforcing read-write thread safety.

• src/database/parser/: Language-specific grammar configurations and the UniversalCodeParser that walks tree-sitter ASTs.

• src/watcher/: File system events monitor built on watchdog to coordinate incremental rebuilds.

• src/services/: Logical business operations supporting graph queries, fuzzy searches, and AST modification edits.

Getting Started

Prerequisites

• Python >= 3.11

• uv (Fast Python Package Installer)

• Rust toolchain (only for local engramedb development)

Installation

git clone https://github.com/ghassenTn/cordyceps_mcp.git
cd cordyceps_mcp
uv sync --python 3.11

This installs engramedb from PyPI as declared in pyproject.toml. No local engine checkout required for normal use.

Local Development (engine + MCP)

For editable installs where MCP uses a sibling engramedb checkout:

git clone https://github.com/ghassenTn/cordyceps_mcp.git
git clone https://github.com/ghassenTn/engramedb.git
# layout: cordyceps_mcp/  ../engramedb/
cd cordyceps_mcp
uv sync --python 3.11  # uses [tool.uv.sources] path = "../engramedb"

Engine development:

cd ../engramedb
maturin develop --release

📂 Command Guide

Run the following commands using the uv toolchain:

MCP Tools Provided

The server exposes a single unified tool. Legacy standalone tools (search_nodes, analyse_impact, trace_business_flow, etc.) were removed — all capabilities are now via the query DSL.

query_dsl — Unified Code Graph Query

Executes a Cordyceps Query DSL string against the live CSR graph. All outputs are YAML.

Parameters

• raw (str, required): DSL query string

• expand_body (bool, default false): when true returns full body, otherwise body_preview (150 chars)

query_dsl_help returns the full DSL grammar.

DSL quick reference

All legacy search / impact / flow / full-stack capabilities are available through query_dsl with the appropriate verb — see query_dsl_help for the complete command reference.

IDE Integration (example kiro ide)

{
  "mcpServers": {
    "cordyceps": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/cordyceps_mcp",
        "run",
        "--python",
        "3.11",
        "python",
        "/path/to/cordyceps_mcp/main.py",
        "/path/to/your workspace"
      ],
      "autoApprove": [
        "query_dsl"
      ]
    }

  }
}

🧪 Testing

The test coverage covers parsing, synchronization safety, and graph queries. To run tests, use:

uv run python -m pytest

All tests use pytest fixtures defined in conftest.py with custom thread-safety and environment isolated markers.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.