lorenzo-cambiaghi/LynxMCP

**LynxMCP is a 100% local MCP server for the code questions grep can't answer: what calls this, what breaks if I change it, where is the code that does X, how does the library version I actually use behave. AST-aware chunking, hybrid BM25 + dense retrieval, an optional code knowledge graph, and your library docs and PDFs indexed next to your code. Works with any MCP client (Claude Code, Cursor, Windsurf, Antigravity, ...).**
Grep is the right tool when you know the identifier, and your agent already has it. Lynx is for the questions grep cannot answer. Behaviour: "where do we clamp the camera zoom?" matches nothing literal. Structure: who calls this, what inherits from it, what breaks if it changes; polymorphic dispatch leaves no textual trace. Knowledge past the model's training cutoff: the docs of the framework version you run, indexed as a source. Nothing leaves your machine.
What grep can't answer
Each row is measured; the numbers come from the benchmarks below.
| Question | Agentic grep | Lynx |
|---|---|---|
| "What inherits from Field?" (Django, 100 classes over 4 levels) | 101 grep rounds, one per discovered class | 4 graph_query calls, file:line on every edge |
| "What breaks if I change ApplyDamage?" | the textual mentions of the name | impact: every transitive caller with its hop distance, plus the tests to re-run |
| "Where do we validate session tokens?" on C# (Json.NET) | hit@1 33% | hit@1 47% |
| "How does this API behave in the version we ship?" | the model's memory | the docs you indexed, cited with the page they came from |
Where grep is better, this page says so. On Guava, whose class names document themselves (BloomFilter, RateLimiter), grep ranks higher: hit@1 73% against 60%. On a repository that fits in the agent's context, the built-in tools are fine. Lynx pays off on large codebases, on framework docs your model has gone stale on, and on repeated sessions where re-exploring from scratch is waste.
Quickstart
lynx manager init also offers to open the web UI, where the same source can be added through a guided form with a folder picker. Everything below works either way.
Every tool your AI gets is also a command, with the same name and the same output: lynx find-definition ApplyDamage, lynx impact ApplyDamage, lynx graph query --op callers --symbol ApplyDamage. Add --json to any of them for scripts.
Then register Lynx in your MCP client. Claude Code is shown; the full guide covers Cursor, Antigravity, and generic stdio clients, or let lynx manager ui generate the snippet for you:
The server answers the MCP handshake in about a second and opens the indexes in the background; a call that arrives earlier gets the loading state back and is retried. If you would rather skip the terminal, there are double-click installers for macOS and Windows.
The tools your AI gets
The tool set is fixed: it does not grow with the number of sources. It is also layered, because every tool definition rides in your client's context on every turn. Three profiles: core (5 tools, about 1,300 tokens of definitions), standard (10 tools, about 2,800 tokens, the default) and full (17 tools, about 4,150 tokens). Set tools.profile in config.json or pass lynx serve --profile full; tools.include adds a single tool to a profile. Tools take a source argument where relevant.
| Tool | Profile | What it answers |
|------|---------|-----------------|
| search(query, source?, outline?) | core | Primary hybrid search. Omit source to search every source at once (RRF-fused). outline=true returns signatures only, for cheap triage. |
| deep_search(queries, source?) | standard | Escalation: tries multiple query phrasings until one passes a quality threshold. |
| graph_query(operation, symbol?) | standard | callers, callees, subclasses, superclasses, imports, neighbors, shortest_path, overview, surprising_connections, status. |
| find_definition(symbol) | standard | Where is X defined? (AST-precise when the graph is on, BM25 fallback otherwise.) |