fittok MCP server

fittok

Retrieve only the relevant source code for a question — instead of the model reading whole files — so an LLM answers codebase questions on a small, focused slice of context. Less input = fewer tokens, lower cost, faster answers.

Works three ways from one install: an MCP server, a CLI, and a Python library — plus a Claude Code plugin that injects context automatically.

📖 Full command reference → docs/HANDBOOK.md

<!-- MCP Registry: PyPI ownership verification — do not remove this line --> mcp-name: io.github.likhithreddy/fittok

How it works

codebase ──▶ graphify ──▶ slurp ──▶ readable slice ──▶ LLM answers
             (parse)      (select)   (trim to budget)

functions / classes / methods (Python, JS, JSX, TS, TSX, Java, Go, Rust). Supports multi-language call/import/reference edges.

1. graphify — parses the repo with tree-sitter into a knowledge graph of

1. slurp — scores every node against the question using a 4-signal hybrid:

• Semantic embeddings (all-MiniLM-L6-v2) — meaning-based matching
• Content-BM25 (with camelCase/snake_case splitting) — keyword matching
• Summary-BM25 (node name + file + callers + callees) — structural matching
• PageRank — graph centrality / hub detection

Signals are fused via Reciprocal Rank Fusion (RRF) — rank-based, no score calibration issues. Nodes are selected via round-robin directory interleaving (guarantees facet coverage on multi-aspect queries — one node from each code area before any gets a second) with a per-node token cap (25% of budget, so large components don't crowd out smaller functions). A relevance cliff (semantic OR BM25 OR summary-BM25 threshold) excludes noise.

plus a codebase map (table of contents with docstrings, inspired by Karpathy's LLM Wiki / Google's OKF) so the model can route follow-up calls precisely. The model answers directly from it — no file reads needed.

1. readable output — returns the actual source code of selected nodes,

As you edit, a file watcher (auto-started on first query) updates the graph incrementally — only changed files are re-parsed and merged, and only changed functions re-embed. Graphs and embeddings are cached on disk (~/.cache/fittok). Set FITTOK_AUTOWATCH=false to disable the watcher, in which case an edit triggers a full re-parse on the next query.

Getting the best results (and known limitations)

Ask focused questions

fittok ranks code against your question using a 4-signal hybrid (semantic + BM25 + structural + PageRank, fused via RRF) with round-robin directory diversity — so multi-facet questions surface code from multiple areas (UI, server, database) instead of clustering in one dominant area. It's most accurate with focused, specific questions — ideally one concern each, and naming the function/component/route when you can. Multi-facet questions are supported via decomposition (the tool description tells the model to call once per aspect) and the codebase map (a table of contents prepended to every response).

• ✅ "How does runSandboxQuery execute and isolate a SQL query?" → surfaces the exact function + its isolation code.
• ✅ "How does the querydle client submit a query and render results?" → surfaces the UI component.
• ✅ "Trace the full lifecycle: UI submission, sandbox execution, data isolation" → decomposition + round-robin diversity covers multiple facets; the codebase map routes the model to any missed files.

Rule of thumb: one concern per question (or 2–3 facets max). For "explain the whole feature," split it into a few focused questions instead of one mega-query.

Known limitations

Shortened. The full README is on GitHub.