Mycelium

Knowledge graph engine for understanding TypeScript/JavaScript codebases. Built on the TypeScript Compiler API — Mycelium parses your project once into a shared graph (files, imports, symbols, dependencies) and every command below queries that graph rather than guessing from raw text.

Install

npx @mycelium-core/cli analyze .

or install globally:

npm install -g @mycelium-core/cli
mycelium analyze .

Commands

mycelium analyze [path]

File/function/class/interface counts, circular dependencies, unused files, dead exports.

mycelium analyze . --json

mycelium memory [path]

Architecture summary, naming conventions, and task-scoped relevant context — a compact "memory pack" any LLM call can use instead of the whole repo.

mycelium memory . --query "where is auth handled?"

mycelium explain [path]

Explains an error deterministically: classifies common JS/TS error shapes, locates the exact file/line in your project graph, and shows the surrounding source and related files.

mycelium explain . --message "Cannot read properties of undefined (reading 'map')"

mycelium doctor [path]

Detects your package manager (npm, pnpm, or yarn) and reports dependency conflicts with suggested fixes, using each manager's own conflict data rather than reimplementing semver resolution. Note: on yarn projects this runs a real install and may modify node_modules/yarn.lock.

mycelium doctor .

mycelium migrate [path] --package <name>

Finds every import and call site of a package across your codebase — useful before a version bump or a swap to a different library.

mycelium migrate . --package react-dom --removed render

mycelium inspect [path]

Cyclomatic complexity per function and structural duplicate-code detection.

mycelium inspect . --threshold 10

mycelium refactor [path]

Ranked refactor suggestions built directly from inspect's complexity/duplicate signals — no invented pattern names, only what was actually measured.

mycelium refactor .

Every command supports --json for structured output.

MCP server

Mycelium can run as an MCP server, exposing all 7 commands above as tools an AI agent (Claude, Cursor, etc.) can call directly instead of you running the CLI and pasting output back.

mycelium mcp --root ./my-project

The server is scoped to one project root for its lifetime, communicating over stdio — the standard way MCP clients spawn and talk to local servers.

To use it with Claude Desktop, add it to claude_desktop_config.json:

{
  "mcpServers": {
    "mycelium": {
      "command": "npx",
      "args": ["-y", "@mycelium-core/cli", "mcp", "--root", "/absolute/path/to/your/project"]
    }
  }
}

Available tools: mycelium_analyze, mycelium_memory, mycelium_explain, mycelium_doctor, mycelium_migrate, mycelium_inspect, mycelium_refactor — each mirrors its CLI command's parameters and returns the same JSON shape as --json output.

Known limitations

Mycelium is early (v0.1) and has been tested against its own codebase and one real external monorepo (zod). Known gaps:

• Dead-export and migration detection are heuristic, not full symbol resolution — they can miss renamed imports (import { foo as bar }).
• doctor's yarn path is not a true dry-run. Unlike npm/pnpm, yarn's peer-conflict warnings only surface during a real yarn install, so this path may modify node_modules/yarn.lock — the CLI and MCP tool description both flag this explicitly.
• Entry-point detection resolves main/bin/types from package.json (including npm/yarn workspaces and pnpm-workspace.yaml sub-packages), but doesn't yet resolve packages that only define entry points via the exports map with no main/dist field.
• Circular dependency detection reports each strongly-connected component of mutually importing files as one group — accurate, but large clusters (e.g. a tightly-coupled core module) are reported as a single group rather than broken into individual cycles.

Issues and PRs welcome at the GitHub repo.

License

MIT