mcp-code-context
Advanced tools
Powerful MCP server with Tree-sitter WASM parsers for 100% AST accuracy. Zero native dependencies. Production-ready with persistent caching, structured logging, file watching, fuzzy search, rate limiting, file locking, and ReDoS protection. Supports TypeS
MCP server with Tree-sitter WASM parsers for 100% AST accuracy. Zero native dependencies. Production-ready with persistent caching, structured logging, fuzzy search, and multi-process safety.
npm install -g mcp-code-contextclaude_desktop_config.json:{
"mcpServers": {
"code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"]
}
}
}
@code-context to map repos or edit code surgically.No build tools required - Works on Windows/Mac/Linux without Visual Studio, Python, or node-gyp.
Works with Claude Desktop, Cursor, Windsurf, GitHub Copilot, Amazon Q, and any Model Context Protocol compatible client.
📖 For AI Agents: See INSTRUCTIONS.md for essential usage patterns and best practices.
This tool was born out of necessity in Caracas, Venezuela 🇻🇪, where economic limitations made every API token count. When you're choosing between groceries and Claude API credits, you learn to optimize fast.
What started as a personal script to compress context windows became a full MCP server when I realized others faced the same problem: LLM APIs are expensive, and most tools waste tokens on boilerplate.
If this tool saves you money or time, consider supporting its development. Every contribution helps keep this project maintained and free for everyone.
LLMs working with code face two bottlenecks:
mcp-code-context provides 13 tools — 6 for reading, 2 for cleanup, and 5 for writing — that operate at the symbol level (functions, classes, methods). Furthermore, tools support a className scope which correctly isolates identical symbol names in the same file (e.g. Flutter build() methods) to avoid reading or changing the wrong logic. Read tools extract structural skeletons. Write tools splice changes into the exact AST location.
| File | Original | Compressed | Reduction |
|---|---|---|---|
| PHP class (426 lines) | 426 | 60 | 85.9% |
| Dart repository (230 lines) | 230 | 30 | 87.0% |
| PHP config (68 lines) | 68 | 15 | 77.9% |
Built to be robust and precise. Both read and write engines are tested against real-world, complex codebases (including nested generic types in Dart, complex interfaces in PHP, and multi-file rename operations) with a 100% test pass rate across all languages and operations.
| Feature | Description |
|---|---|
| ⚡ Persistent Cache | WASM SQLite cache — <100ms hits, 10× faster on repeated reads |
| 📝 Structured Logging | pino JSON logging to stderr (MCP-safe, never pollutes stdio) |
| 👁️ File Watcher | chokidar auto-invalidates cache on file changes |
| 🔍 Fuzzy Search | fuse.js finds authUser when you search authenticateUser |
| 📄 Pagination | Search defaults to 10 results with startIndex for navigation |
| 🔒 Multi-process Safe | Filesystem locks via proper-lockfile (was in-memory) |
| 💾 OS Temp Backups | Backups in os.tmpdir() — no more hot-reload loops |
| 🧪 74 Tests | Unit + integration + performance + stress tests |
| 🎯 Token Savings | 50-80% reduction: compact diffs, no Phase 2 repeat, auto-optimize output |
className to scope disambiguation (e.g., getting multiple build() methods in Dart).require(), Python imports, PHP use/require_once/include, and Dart imports..gitignore and .repomixignore rules. Automatically excludes node_modules, dist, vendor, .git, etc.className parameter.confirmationToken by default. Changes are only applied after explicit confirmation..mcp-backups/ directory.rollback_file tool._ and __ prefixed symbols in Dart and Python.| Language | Read (Compress + Extract) | Write (Replace + Insert + Rename + Remove) | Import Analysis |
|---|---|---|---|
| TypeScript / JavaScript | ✅ AST (Tree-sitter WASM) | ✅ AST (Tree-sitter WASM) | ✅ |
| PHP | ✅ AST (Tree-sitter WASM) | ✅ AST + line-splice | ✅ |
| Dart | ✅ AST (Tree-sitter WASM) | ✅ AST + line-splice | ✅ |
| Python | ✅ AST (Tree-sitter WASM) | ✅ Indentation-aware | ✅ |
| Others (JSON, YAML, CSS, etc.) | Passthrough / truncation | — | — |
rename_symbol ToolDart and Python: Cross-file rename is NOT supported for .dart, .py, and .pyi files.
write_file_surgical to rename within a single fileTypeScript, JavaScript, PHP: Fully supported with AST-aware renaming ✅
Note: While the definition file uses pure AST replacement, dependent files (imports) are updated using regex word-boundaries. Review the generated diffs carefully to ensure strings or comments sharing the same name aren't unintentionally modified.
get_semantic_repo_map Tool@folder syntax to target specific directoriesrollback_file if something goes wrong.# Global installation (recommended)
npm install -g mcp-code-context
# Or use directly with npx (no installation)
npx -y mcp-code-context
Note: Unlike v2.x, this version uses web-tree-sitter (WASM) instead of native bindings. No Visual Studio, Python, or node-gyp required!
Add to your claude_desktop_config.json:
{
"mcpServers": {
"mcp-code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"]
}
}
}
Add to your Cursor MCP settings (.cursor/mcp.json):
{
"mcpServers": {
"mcp-code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"]
}
}
}
Add to your Windsurf MCP config:
{
"mcpServers": {
"mcp-code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"]
}
}
}
Any MCP-compatible client can use this server. The transport is stdio (JSON-RPC over stdin/stdout). Point your client to npx -y mcp-code-context.
get_semantic_repo_mapGenerate a compressed architectural overview of an entire repository.
directoryPath (required) — Path to the repo rootformat (optional) — "xml" (default) or "markdown"read_file_surgicalRead a file, or extract only a specific named symbol. Returns structured suggestions if the symbol is missing.
filePath (required) — Path to the source filesymbolName (optional) — Name of a function, class, method, or typeclassName (optional) — Scope the symbol to a specific class (to avoid duplicates)analyze_impactFind all files that depend on a given file.
filePath (required) — Path to the file being modifiedrootDir (optional) — Repository root (auto-detected)read_file_linesRead specific line ranges from a file without loading the entire content. More efficient than read_file_surgical for small fragments.
filePath (required) — Path to the source filestartLine (optional) — Starting line number (1-indexed)endLine (optional) — Ending line number (1-indexed)aroundPattern (optional) — Search pattern to find and return surrounding linescontextLines (optional) — Number of lines before/after pattern (default: 5)search_code_patternSearch for code patterns across multiple files with context. Respects .gitignore rules.
rootDir (required) — Repository root directorypattern (required) — Regular expression pattern to searchfileExtensions (optional) — Array of extensions to search (e.g., [".ts", ".dart"])excludeDirs (optional) — Directories to exclude (default: ["node_modules", "dist", "build"])maxResults (optional) — Maximum matches per page (default: 10)startIndex (optional) — Pagination offset (default: 0)fuzzyMatch (optional) — Enable fuzzy/typo-tolerant matching (default: false)fuzzyThreshold (optional) — Fuzzy sensitivity 0.0–1.0 (default: 0.4)rollback_fileSurgically restore a file to a previous state from the automated backup system.
filePath (required) — Path to the file to restoresteps (optional) — Number of versions to go back (1-5, default: 1)clean_backupsRemove all backup files for a project to keep the working directory clean.
projectRoot (required) — Absolute path to the project rootNote: Backups are stored centrally at [project-root]/.mcp-backups/ to keep your project organized.
All write tools follow a Two-Phase Workflow:
diff and a confirmationToken.confirm: true and provide the token to apply the changes.write_file_surgicalReplace the full source code of a named symbol in a file.
filePath (required) — Path to the filesymbolName (required) — Symbol to replacenewContent (required) — Replacement code (signature + body)confirmationToken (optional) — Token from Phase 1 to apply changesconfirm (optional) — Set to true to applyclassName (optional) — Scope the symbol to a specific classinsert_symbolInsert new code at a precise location relative to an existing symbol.
filePath (required) — Path to the filecode (required) — Code to insertanchorSymbol (optional) — Symbol to position relative toposition (optional) — "before", "after", "inside_start", "inside_end"className (optional) — Scope the anchor to a specific classconfirmationToken, confirm (optional)rename_symbolRename a symbol across the entire repository (definition + all usages).
filePath (required) — File where the symbol is definedoldName (required) — Current namenewName (required) — New namerootDir (optional) — Repository rootconfirmationToken, confirm (optional)remove_symbolSafely remove a symbol from a file with dependency checking.
filePath (required) — Path to the filesymbolName (required) — Symbol to removeclassName (optional) — Scope the symbol to a specific classforce (optional) — Skip dependency checkconfirmationToken, confirm (optional)get_semantic_repo_map to see the architectureread_file_surgical with symbol name for specific implementationsanalyze_impact before modifying shared filesdiff and confirmationTokenconfirm: true to applyrollback_file if something goes wrong after confirmationThis tool was born in Caracas, Venezuela 🇻🇪, where economic limitations mean every API token counts. What started as a personal script to save money on Claude API became a full MCP server when I realized others faced the same problem.
Current Reality:
If this tool saves you time or money, consider supporting its development.
Ko-fi (PayPal + Cards, 0% fees)
ko-fi.com/achatainga
PayPal (Direct)
paypal.me/achatainga
Binance (USDT) (Crypto, lowest fees)
0xa68d53f7853ce0175eb96aaad4a30c068ca96444367669339Recommended: TRC20 for lower gas fees
Ko-fi Membership
ko-fi.com/achatainga/tiers
Monthly tiers:
Need custom MCP tools or AI integrations?
📧 Contact: a.chataing.a@gmail.com
📄 Details: HIRE_ME.md
I believe in radical transparency:
Current Status:
(Updated monthly)
Thank you to these amazing supporters:
(No sponsors yet - be the first!)
See full list: SPONSORS.md
Can't donate? No problem! You can still help:
Every contribution matters, financial or not.
# Build
npm run build
# Run tests
npm test
# Development (build + start)
npm run dev
ignore npm package (full .gitignore spec support)See CONTRIBUTING.md for guidelines.
See SECURITY.md for security policies and reporting vulnerabilities.
See TROUBLESHOOTING.md for common issues and solutions.
Because MCP uses stdout for protocol communication, all logs are safely routed to stderr. You can view them in your client's log files:
~/Library/Logs/Claude/mcp-server-mcp-code-context.log%APPDATA%\Claude\logs\mcp-server-mcp-code-context.logOutput panel → Select mcp-code-context from the dropdownEnvironment Variables (optional):
{
"mcpServers": {
"mcp-code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"],
"env": {
"NODE_ENV": "development",
"LOG_LEVEL": "debug"
}
}
}
}
Supported LOG_LEVEL values: fatal, error, warn, info, debug, trace (default: info).
See CHANGELOG.md for version history.
Built with ❤️ from Caracas, Venezuela 🇻🇪
FAQs
Powerful MCP server with Tree-sitter WASM parsers for 100% AST accuracy. Zero native dependencies. Production-ready with persistent caching, structured logging, file watching, fuzzy search, rate limiting, file locking, and ReDoS protection. Supports TypeS
The npm package mcp-code-context receives a total of 33 weekly downloads. As such, mcp-code-context popularity was classified as not popular.
We found that mcp-code-context demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A mini Shai-Hulud campaign compromised Red Hat Cloud Services npm packages to steal developer and CI/CD secrets during installation.
Research
/Security News
The North Korean malware loader hides in a Packagist-listed package and its GitHub branch to fetch and execute remote code in a likely Contagious Interview-style lure.
Security News
The Rust project is moving toward formal rules on LLM use in contributions after months of internal debate over maintainer burden, code quality, and contributor experience.