Builds a local repository graph for JavaScript and TypeScript to provide specific source code and symbol lookups for coding agents.
Also known as mohanagy/madar, @lubab/madar
- Stars
- 21
- Tools
- 1
- Downloads, 30 days
- 1,217
- Latest version
- 0.40.0-beta.1
- Last commit
- Nov 15, 2026
- License
- MIT
What is Madar MCP?
Madar builds a local repository graph for JavaScript and TypeScript to provide specific source code and symbol lookups for coding agents. It exposes 1 tool, such as retrieve.
Summary generated from the project's README
About Madar MCP server
Madar builds a local repository graph specifically for JavaScript and TypeScript projects to assist coding agents with precise source code and symbol lookups. It functions as a local-first tool that indexes declarations, imports, and calls without requiring cloud services or API keys. Developers can integrate it into various environments including Claude Code, Cursor, GitHub Copilot, and Gemini CLI using specific installation commands and profiles like strict or core.
The server provides tools such as context_pack and context_expand to manage how much source code is sent to an AI client. When an agent knows a specific file and symbol, it can request exact function bodies with a defined token budget. For broader inquiries, the tool offers experimental discovery features to navigate dependencies and static graph relationships. It is designed to complement existing IDE indexing by providing structured evidence and continuation handles for large source files.
What you can do with it
- 1Handle large source filesAgents can retrieve remaining lines of a function that was too large for a single response.
Written from the project's README. Every use case is checked against a quote from it.
How to install Madar MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Madar MCP in Claude Code
$ claude mcp add madar -- npx -y @lubab/madar mcpInstall Madar MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"madar": {
"command": "npx",
"args": [
"-y",
"@lubab/madar",
"mcp"
]
}
}
}Install Madar MCP in VS Code
.vscode/mcp.json
{
"servers": {
"madar": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@lubab/madar",
"mcp"
]
}
}
}Install Madar MCP in VS Code CLI
$ code --add-mcp '{"name":"madar","type":"stdio","command":"npx","args":["-y","@lubab/madar","mcp"]}'Install Madar MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"madar": {
"command": "npx",
"args": [
"-y",
"@lubab/madar",
"mcp"
]
}
}
}Install Madar MCP in Codex
$ codex mcp add madar -- npx -y @lubab/madar mcpInstall Madar MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.madar] command = "npx" args = ["-y", "@lubab/madar", "mcp"]
Install Madar MCP in Gemini CLI
$ gemini mcp add -s user madar npx -- -y @lubab/madar mcpInstall Madar MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"madar": {
"command": "npx",
"args": [
"-y",
"@lubab/madar",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @lubab/madar 0.40.0-beta.1 in an isolated container with no network and no keys. It answered and listed 1 tool.
Madar MCP tools 1
Read from the server with tools/listretrieveReturn the smallest deterministic evidence path for a TypeScript or JavaScript codebase question.
| retrieve | Return the smallest deterministic evidence path for a TypeScript or JavaScript codebase question. |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubMadar
Retrieve specific source code for your coding agent.
Madar builds a local repository graph for JavaScript and TypeScript function lookup by file and symbol. Agents can inspect returned source and request omitted lines.
Broad context discovery and workflow packs are experimental: they can omit necessary evidence and increase total tokens once follow-up reads are counted. Consistent whole-task accuracy and token savings have not been established. Use direct source reads when they are sufficient.
Try It in 60 Seconds
Install Madar with Node.js 20 or newer. For an experimental discovery preview, run it inside your repository:
npm install -g @lubab/madar
cd your-repository
madar try "how does authentication work?"
madar try builds or reuses the local graph, prints an experimental source preview, and shows an optional agent-install command. It does not modify your source code.
For a concrete example, Madar's included password-reset workspace contains this path:
account-routes.ts
-> PasswordResetService.requestPasswordReset()
-> userRepository.saveResetToken()
-> enqueueResetEmailJob()
-> sendPasswordResetEmail()
This is an example of a partial starting path. The agent must verify the conditions, dependencies, and failure paths needed for its answer.
Connect Your Agent
Choose the agent you use. For Claude Code:
madar claude install --profile strict
madar doctor
madar status
The compact strict profile exposes context_pack and context_expand; full also includes them, while core exposes graph-navigation tools. After installing, run madar doctor and madar status.
When the file and function are known, use this MCP request:
{
"prompt": "Read these functions",
"task": "explain",
"targets": [{"file": "lib/util.js", "symbol": "join"}],
"budget": 1500
}
Replace the example file and symbol with those in your repository. Targets select function source, not a complete workflow; inspect omissions and returned continuation handles. A direct source read remains appropriate.
Without exact targets, questions such as these use experimental discovery:
How does authentication work?
Why does this endpoint return 403?
Where is the report generated?
What breaks if I change this service?
Add telemetry to this flow.
For MCP source lookup and recovery, use strict. Codex and OpenCode install it automatically; Aider installs prompt guidance without an MCP server.
| Agent | Install command |
|---|---|
| Claude Code | madar claude install --profile strict |
| Codex CLI | madar codex install |
| Cursor | madar cursor install --profile strict |
| GitHub Copilot | madar copilot install --profile strict |
| Gemini CLI | madar gemini install --profile strict |
| Aider | madar aider install |
| OpenCode | madar opencode install |
Installer details are in the CLI and MCP reference. Step-by-step setup and smoke tests are in the agent quickstarts.
After upgrading Madar, rerun your agent's install command to refresh its managed profile. Older profiles may lack automatic refresh or Codex's longer startup window.
During automatic reconciliation, graph-backed calls return a retryable response. If continuing with Madar, retry after its suggested delay. Native source investigation remains available.
What Changes for the Agent
context_pack returns source locations, excerpts, omissions, freshness, and advisory coverage. Its compact source_evidence_v2 response has a serialized token budget, including metadata. A small packet does not establish a cheaper or more accurate investigation.
For exact lookup, use up to eight JavaScript or TypeScript targets, each with a workspace-relative file and case-sensitive symbol. Only explain mode is supported. Missing, ambiguous, excluded, or stale owners are refused. Targets select functions, not complete workflows; they do not infer calls.
To inspect a known call instead, add "callee":"scan" to its caller target. Madar checks the full current caller and returns a uniquely bound local implementation. Identifier and static dotted calls are supported; nested-closure calls and dynamic expressions are excluded. Unverified bindings are refused.
One oversized exact function request returns a budgeted first page; continuations retrieve remaining lines without repetition.
For omitted evidence:
- Follow a node's
source_expand_handlewithcontext_expandin the same MCP session. Continue with each returned handle until the remaining whole source lines are delivered. Changed or newly excluded source invalidates the handle. - Use an
expandablehandle for related evidence. An optional exactsymbolselects a verified function inside that handle's scope. Do not pass a symbol with a source-continuation handle. - If a page reports
budget_insufficient, retry with a larger budget or request fewer targets. Minimum budget: 128 tokens; expansion defaults to 1500.
A snippet_ref points to shared source text; use the referring node's snippet_line_range for its excerpt. When line_number is omitted, use that range's start. Response paths may be workspace-relative.
Experimental discovery can include source-resolved dependencies and static graph relationships. source_dependencies reports verified calls and unresolved locations; selection_omitted reports exact matches omitted by the lookup limit. Unresolved details may use either a flat list or grouped calls, including repeated line_numbers. Counts can exceed the bounded examples shown. None of these establishes runtime execution or whole-task completeness.
Regenerate older graphs to include newly supported source forms. Root/workspace package.json objects up to 128 KiB and JavaScript/TypeScript files under lib/ are eligible under source policy. Exclude generated output with .madarignore. Other JSON configuration files are not source evidence.
How It Works
- Madar indexes source files, declarations, imports, calls, framework metadata, and selected documentation locally.
- Exact targets or experimental query matching select source evidence.
- Responses expose omissions and recovery handles. Installed MCP profiles refresh the graph after workspace changes.
The MCP response shape describes the response contract.
Use Madar Without MCP
The CLI can generate and inspect context without installing an agent integration:
madar generate .
madar summary
madar pack "how does auth work?" --task explain --format text
By default, madar generate . combines SPI metadata with proven legacy semantics for JavaScript/TypeScript, and uses legacy fallback for other supported languages. Strict modes are in the CLI reference.
Legacy updates rebuild the current corpus when files change or disappear, refreshing incoming calls and imports from unchanged files. Parser caches can still be reused; unchanged graphs are reused after any required extractor-version upgrade.
Create a provider-ready prompt:
madar prompt "how does auth work?" --provider claude
Create a share-safe handoff for another coding tool:
madar handoff "add auth telemetry" --task implement --consumer copilot
See the getting-started tutorial for a sample workspace.
Where Madar Fits
Consider precise source lookup when you know the JavaScript or TypeScript file and function and need selected bodies with explicit omissions and continuations.
It helps less when the repository is small, one direct read is sufficient, source is stale, or the question depends on dynamic or live runtime behavior. Architecture, review, and impact discovery remain experimental.
Madar complements agents and IDE indexing. It is not a hosted knowledge base, runtime tracer, PR reviewer, or vulnerability scanner.
Local by Design
- Privacy: Madar graph generation runs locally and does not require an API key. Your coding agent may still send prompts or selected file context to its own model provider, depending on that agent's configuration.
- Sensitive files: ordinary security source code remains indexable, while private keys,
.env*, credential stores, and known non-source secret material are excluded. This is a path policy, not a content-level secret scanner. - Freshness: installed MCP profiles use automatic refresh. Manual CLI users can regenerate with
madar generate .; strict workflows can require--require-fresh-contextor--require-fresh-graph. - Worktrees: run Madar and the agent from the same linked Git worktree. Each worktree receives isolated graph artifacts outside the checkout; reconnect the MCP server after switching worktrees.
- Telemetry: Telemetry is disabled unless you explicitly enable it. Controls and the exact source-safe event schema are documented in telemetry.
Treat every local MCP install, hook, or agent profile as part of your local trust boundary. Read the MCP threat model.
Evidence and Limits
Madar publishes the prompts, answers, traces, and share-safe reports behind its benchmark statements. Two public experiment types answer different questions and should not be compared as if they were the same test.
Controlled v0.30 evidence
Six June TypeScript runtime-flow trials used a source checkout with task-specific proof profiles. In those controlled runs, Madar was invoked once per row and the recorded results showed:
3.5xto18.5xfewer tool calls2.2xto15.6xless provider-reported input1.65xto7.09xlower latency
Those receipts are real measurements of profile-assisted Madar. They demonstrate what the workflow can achieve when the correct task evidence is available. They are not evidence that an untuned npm installation will reproduce the same result for arbitrary questions, because the old prompts and checkout retrieval contained benchmark-specific obligations unavailable to normal package users.
v0.31 production-artifact validation
The July reruns removed that assistance and used the same isolated, unpacked @lubab/madar@0.31.0 package artifact. Four of six repositories recorded an agent-adoption failure: no attributable Madar MCP call occurred. The other two invoked Madar but failed strict prompt or answer gates. The correct result is zero valid performance comparisons, not six product losses. These reruns expose adoption and answer-completeness work; they neither confirm nor refute the earlier controlled efficiency measurements.
Read the benchmark suite and all dated receipts or the shorter claims and evidence map.
Current Release
Current version: 0.33.0.
See the 0.33.0 changelog.
Documentation
| Need | Start here |
|---|---|
| First run | Getting started |
| Agent setup | Agent quickstarts |
| CLI and MCP tools | CLI and MCP reference |
| Context packs | Context-pack concepts |
| Freshness and automatic refresh | Auto-refresh policy |
| Indexing coverage | Indexing completeness |
| Privacy and MCP trust | Threat model |
| Evidence and benchmarks | Claims and evidence |
| Roadmap | Public roadmap |
| Release history | Changelog |
Contributing
The most useful contributions right now are tests on real TypeScript and Node.js repositories, missed-context reports, Windows/WSL/MCP reliability improvements, framework detection, and clearer setup examples.
Open issues or pull requests against the maintained default branch. Before opening a PR, run:
npm test
npm run build
npm run release:verify
See the full contributor graph on GitHub contributors.
Contributors
Thanks to everyone shaping Madar. The list below is regenerated automatically on every push to main.
Special thanks to @jamemackson for #54, the first community-contributed feature in Madar.
License
MIT. Use it, fork it, ship it.
Madar MCP questions
How do I add Madar MCP to Claude Code?
Run claude mcp add madar -- npx -y @lubab/madar mcp in your terminal. Add --scope user to make it available in every project.
How do I add Madar MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Madar MCP provide?
It exposes 1 tool, including retrieve.
Does Madar require an API key?
No, Madar graph generation runs locally and does not require an API key.
What languages does Madar support for function lookup?
Madar builds a local repository graph specifically for JavaScript and TypeScript function lookup by file and symbol.
Can Madar modify my source code?
No, the Madar command does not change your existing source code.