Skip to content
Back to search

code-graph-mcp

MCP Server for code intelligence

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/eas4ai--code-graph-mcp/badge.svg)](/listings/eas4ai--code-graph-mcp)

HTML

<a href="/listings/eas4ai--code-graph-mcp"><img src="/api/listings/eas4ai--code-graph-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Quick Start (PyPI)

pip install code-graph-mcp ast-grep-py rustworkx

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 502 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Code Graph MCP Server
  2. Model Context Protocol server providing comprehensive code analysis, navigation, and quality assessment capabilities **across 25+ programming languages**.
  3. ## Features
  4. 🎯 **Enhanced Tool Guidance & AI Optimization** ⭐ *NEW in v1.2.0*
  5. - **Comprehensive Usage Guide** - Built-in `get_usage_guide` tool with workflows, best practices, and examples
  6. - **Rich Tool Descriptions** - Visual hierarchy with 🎯 PURPOSE, 🔧 USAGE, ⚡ PERFORMANCE, 🔄 WORKFLOW, 💡 TIP sections
  7. - **Performance-Aware Design** - Clear expectations for Fast (<3s), Moderate (3-15s), and Expensive (10-60s) operations
  8. - **Workflow Orchestration** - Optimal tool sequences for Code Exploration, Refactoring Analysis, and Architecture Analysis
  9. - **AI Model Optimization** - Reduces trial-and-error, improves tool orchestration, enables strategic usage patterns
  10. 🌍 **Multi-Language Support**
  11. - **25+ Programming Languages**: JavaScript, TypeScript, Python, Java, C#, C++, C, Rust, Go, Kotlin, Scala, Swift, Dart, Ruby, PHP, Elixir, Elm, Lua, HTML, CSS, SQL, YAML, JSON, XML, Markdown, Haskell, OCaml, F#
  12. - **Intelligent Language Detection**: Extension-based, MIME type, shebang, and content signature analysis
  13. - **Framework Recognition**: React, Angular, Vue, Django, Flask, Spring, and 15+ more
  14. - **Universal AST Abstraction**: Language-agnostic code analysis and graph structures
  15. 🔍 **Advanced Code Analysis**
  16. - Complete codebase structure analysis with metrics across all languages
  17. - Universal AST parsing with ast-grep backend and intelligent caching
  18. - Cyclomatic complexity calculation with language-specific patterns
  19. - Project health scoring and maintainability indexing
  20. - Code smell detection: long functions, complex logic, duplicate patterns
  21. - Cross-language similarity analysis and pattern matching
  22. 🧭 **Navigation & Search**
  23. - Symbol definition lookup across mixed-language codebases
  24. - Reference tracking across files and languages
  25. - Function caller/callee analysis with cross-language calls
  26. - Dependency mapping and circular dependency detection
  27. - Call graph generation across entire project
  28. ⚡ **Performance Optimized**
  29. - **Debounced File Watcher** - Automatic re-analysis when files change with 2-second intelligent debouncing
  30. - **Real-time Updates** - Code graph automatically updates during active development
  31. - Aggressive LRU caching with 50-90% speed improvements on repeated operations
  32. - Cache sizes optimized for 500+ file codebases (up to 300K entries)
  33. - Sub-microsecond response times on cache hits
  34. - Memory-efficient universal graph building
  35. 🏢 **Enterprise Ready**
  36. - Production-quality error handling across all languages
  37. - Comprehensive logging and monitoring with language context
  38. - UV package management with ast-grep integration
  39. ## Installation
  40. ### Quick Start (PyPI)
  41. ```bash
  42. pip install code-graph-mcp ast-grep-py rustworkx
  43. ```
  44. ## MCP Host Integration
  45. ### Claude Desktop
  46. #### Method 1: Using Claude CLI (Recommended)
  47. **For PyPI installation:**
  48. ```bash
  49. # Project-specific installation
  50. claude mcp add --scope project code-graph-mcp code-graph-mcp
  51. # User-wide installation
  52. claude mcp add --scope user code-graph-mcp code-graph-mcp
  53. ```
  54. **For development installation:**
  55. ```bash
  56. # Project-specific installation
  57. claude mcp add --scope project code-graph-mcp uv run code-graph-mcp
  58. # User-wide installation
  59. claude mcp add --scope user code-graph-mcp uv run code-graph-mcp
  60. ```
  61. **Verify installation:**
  62. ```bash
  63. claude mcp list
  64. ```
  65. #### Method 2: Manual Configuration
  66. Add to your Claude Desktop configuration file:
  67. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  68. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  69. ```json
  70. {
  71. "mcpServers": {
  72. "code-graph-mcp": {
  73. "command": "code-graph-mcp"
  74. }
  75. }
  76. }
  77. ```
  78. ### Cline (VS Code Extension)
  79. Add to your Cline MCP settings in VS Code:
  80. 1. Open VS Code Settings (Ctrl/Cmd + ,)
  81. 2. Search for "Cline MCP"
  82. 3. Add server configuration:
  83. ```json
  84. {
  85. "cline.mcp.servers": {
  86. "code-graph-mcp": {
  87. "command": "code-graph-mcp"
  88. }
  89. }
  90. }
  91. ```
  92. ### Continue (VS Code Extension)
  93. Add to your `~/.continue/config.json`:
  94. ```json
  95. {
  96. "mcpServers": [
  97. {
  98. "name": "code-graph-mcp",
  99. "command": "code-graph-mcp",
  100. "env": {}
  101. }
  102. ]
  103. }
  104. ```
  105. ### Cursor
  106. Add to Cursor's MCP configuration:
  107. 1. Open Cursor Settings
  108. 2. Navigate to Extensions → MCP
  109. 3. Add server:
  110. ```json
  111. {
  112. "name": "code-graph-mcp",
  113. "command": "code-graph-mcp"
  114. }
  115. ```
  116. ### Zed Editor
  117. Add to your Zed `settings.json`:
  118. ```json
  119. {
  120. "assistant": {
  121. "mcp_servers": {
  122. "code-graph-mcp": {
  123. "command": "code-graph-mcp"
  124. }
  125. }
  126. }
  127. }
  128. ```
  129. ### Zencoder ⭐
  130. **The best AI coding tool!** Add to your Zencoder MCP configuration:
  131. ```json
  132. {
  133. "mcpServers": {
  134. "code-graph-mcp": {
  135. "command": "code-graph-mcp",
  136. "env": {},
  137. "description": "Multi-language code analysis with 25+ language support"
  138. }
  139. }
  140. }
  141. ```
  142. **Pro Tip**: Zencoder's advanced AI capabilities work exceptionally well with Code Graph MCP's comprehensive multi-language analysis. Perfect combination for professional development! 🚀
  143. ### Windsurf
  144. Add to Windsurf's MCP configuration:
  145. ```json
  146. {
  147. "mcpServers": {
  148. "code-graph-mcp": {
  149. "command": "code-graph-mcp"
  150. }
  151. }
  152. }
  153. ```
  154. ### Aider
  155. Use with Aider AI coding assistant:
  156. ```bash
  157. aider --mcp-server code-graph-mcp
  158. ```
  159. ### Open WebUI
  160. For Open WebUI integration, add to your MCP configuration:
  161. ```json
  162. {
  163. "mcp_servers": {
  164. "code-graph-mcp": {
  165. "command": "code-graph-mcp",
  166. "env": {}
  167. }
  168. }
  169. }
  170. ```
  171. ### Generic MCP Client
  172. For any MCP-compatible client, use these connection details:
  173. ```json
  174. {
  175. "name": "code-graph-mcp",
  176. "command": "code-graph-mcp",
  177. "env": {}
  178. }
  179. ```
  180. ### Docker Integration
  181. Run as a containerized MCP server:
  182. ```dockerfile
  183. FROM python:3.12-slim
  184. RUN pip install code-graph-mcp ast-grep-py rustworkx
  185. WORKDIR /workspace
  186. CMD ["code-graph-mcp"]
  187. ```
  188. ```bash
  189. docker run -v $(pwd):/workspace code-graph-mcp
  190. ```
  191. ### Development Installation
  192. For contributing or custom builds:
  193. ```bash
  194. git clone <repository-url>
  195. cd code-graph-mcp
  196. uv sync --dev
  197. uv build
  198. ```
  199. **Add to Claude Code (development):**
  200. ```bash
  201. # Project-specific
  202. claude mcp add --scope project code-graph-mcp uv run code-graph-mcp
  203. # User-wide
  204. claude mcp add --scope user code-graph-mcp uv run code-graph-mcp
  205. ```
  206. **For other MCP clients, use:**
  207. ```json
  208. {
  209. "command": "uv",
  210. "args": ["run", "code-graph-mcp"]
  211. }
  212. ```
  213. ## Configuration Options
  214. ### Command Line Arguments
  215. ```bash
  216. code-graph-mcp --help
  217. ```
  218. Available options:
  219. - `--project-root PATH`: Root directory of your project (optional, defaults to current directory)
  220. - `--verbose`: Enable detailed logging
  221. - `--no-file-watcher`: Disable automatic file change detection
  222. ### Environment Variables
  223. ```bash
  224. export CODE_GRAPH_MCP_LOG_LEVEL=DEBUG
  225. export CODE_GRAPH_MCP_CACHE_SIZE=500000
  226. export CODE_GRAPH_MCP_MAX_FILES=10000
  227. export CODE_GRAPH_MCP_FILE_WATCHER=true
  228. export CODE_GRAPH_MCP_DEBOUNCE_DELAY=2.0
  229. ```
  230. ### File Watcher (v1.1.0+)
  231. The server includes an intelligent file watcher that automatically updates the code graph when files change:
  232. - **Automatic Detection**: Monitors all supported file types in your project
  233. - **Smart Debouncing**: 2-second delay prevents excessive re-analysis during rapid changes
  234. - **Efficient Filtering**: Respects `.gitignore` patterns and only watches relevant files
  235. - **Thread-Safe**: Runs in background without blocking analysis operations
  236. - **Zero Configuration**: Starts automatically after first analysis
  237. **File Watcher Features:**
  238. - Real-time graph updates during development
  239. - Batch processing of multiple rapid changes
  240. - Duplicate change prevention
  241. - Graceful error recovery
  242. - Resource cleanup on shutdown
  243. ### Troubleshooting
  244. #### Common Issues
  245. 1. **"Command not found"**: Ensure `code-graph-mcp` is in your PATH
  246. ```bash
  247. pip install --upgrade code-graph-mcp
  248. which code-graph-mcp
  249. ```
  250. 2. **"ast-grep not found"**: Install the required dependency
  251. ```bash
  252. pip install ast-grep-py
  253. ```
  254. 3. **Permission errors**: Use virtual environment
  255. ```bash
  256. python -m venv venv
  257. source venv/bin/activate # Linux/Mac
  258. # or
  259. venv\Scripts\activate # Windows
  260. pip install code-graph-mcp ast-grep-py rustworkx
  261. ```
  262. 4. **Large project performance**: Use verbose mode for debugging
  263. ```bash
  264. code-graph-mcp --verbose
  265. ```
  266. #### Debug Mode
  267. Enable verbose logging for troubleshooting:
  268. ```bash
  269. code-graph-mcp --verbose
  270. ```
  271. #### Supported File Types
  272. The server automatically detects and analyzes these file extensions:
  273. - **Web**: `.js`, `.ts`, `.jsx`, `.tsx`, `.html`, `.css`
  274. - **Backend**: `.py`, `.java`, `.cs`, `.cpp`, `.c`, `.rs`, `.go`
  275. - **Mobile**: `.swift`, `.dart`, `.kt`
  276. - **Scripting**: `.rb`, `.php`, `.lua`, `.pl`
  277. - **Config**: `.json`, `.yaml`, `.yml`, `.toml`, `.xml`
  278. - **Docs**: `.md`, `.rst`, `.txt`
  279. ## Available Tools
  280. The MCP server provides **9 comprehensive analysis tools** with enhanced guidance that work across all 25+ supported languages:
  281. ### 🎯 **Enhanced Tool Experience** ⭐ *NEW in v1.2.0*
  282. Each tool now includes **rich guidance** with visual hierarchy:
  283. - **🎯 PURPOSE** - Clear explanation of what the tool does
  284. - **🔧 USAGE** - When and how to use the tool effectively
  285. - **⚡ PERFORMANCE** - Speed expectations and caching information
  286. - **🔄 WORKFLOW** - Optimal tool sequencing recommendations
  287. - **💡 TIP** - Pro tips for maximum effectiveness
  288. ### 📚 **Usage Guide Tool**
  289. | Tool | Description | Key Features |
  290. |------|-------------|--------------|
  291. | `get_usage_guide` | **NEW** - Comprehensive guidance with workflows, best practices, and examples | Complete documentation, workflow patterns, performance guidelines |
  292. ### 🛠️ **Analysis Tools**
  293. | Tool | Description | Multi-Language Features | Performance |
  294. |------|-------------|------------------------|-------------|
  295. | `analyze_codebase` | Complete project analysis with structure metrics and complexity assessment | Language detection, framework identification, cross-language dependency mapping | ⚡ Expensive (10-60s) |
  296. | `find_definition` | Locate symbol definitions with detailed metadata and documentation | Universal AST traversal, language-agnostic symbol resolution | ⚡ Fast (<3s) |
  297. | `find_references` | Find all references to symbols throughout the codebase | Cross-file and cross-language reference tracking | ⚡ Fast (<3s) |
  298. | `find_callers` | Identify all functions that call a specified function | Multi-language call graph analysis | ⚡ Fast (<3s) |
  299. | `find_callees` | List all functions called by a specified function | Universal function call detection across languages | ⚡ Fast (<3s) |
  300. | `complexity_analysis` | Analyze code complexity with refactoring recommendations | Language-specific complexity patterns, universal metrics | ⚡ Moderate (5-15s) |
  301. | `dependency_analysis` | Generate module dependency graphs and import relationships | Cross-language dependency detection, circular dependency analysis | ⚡ Moderate (3-10s) |
  302. | `project_statistics` | Comprehensive project health metrics and statistics | Multi-language project profiling, maintainability indexing | ⚡ Fast (<3s) |
  303. ## Usage Examples
  304. ### 🎯 **Getting Started with Enhanced Guidance** ⭐ *NEW in v1.2.0*
  305. ```
  306. First, get comprehensive guidance on using the tools effectively:
  307. get_usage_guide
  308. ```
  309. ### 🔍 **Multi-Language Analysis Workflows**
  310. **Code Exploration Workflow:**
  311. ```
  312. 1. analyze_codebase (build the foundation)
  313. 2. project_statistics (get overview)
  314. 3. find_definition("MyClass") (locate specific symbols)
  315. 4. find_references("MyClass") (understand usage patterns)
  316. ```
  317. **Refactoring Analysis Workflow:**
  318. ```
  319. 1. analyze_codebase
  320. 2. complexity_analysis (threshold=15 for critical issues)
  321. 3. find_callers("complex_function") (impact analysis)
  322. 4. find_callees("complex_function") (dependency analysis)
  323. ```
  324. **Architecture Analysis Workflow:**
  325. ```
  326. 1. analyze_codebase
  327. 2. dependency_analysis (identify circular dependencies)
  328. 3. project_statistics (health metrics)
  329. 4. complexity_analysis (quality assessment)
  330. ```
  331. ### 💬 **Natural Language Examples**
  332. ```
  333. Analyze this React/TypeScript frontend with Python backend - show me the overall structure and complexity metrics
  334. ```
  335. ```
  336. Find all references to the function "authenticate" across both the Java services and JavaScript frontend
  337. ```
  338. ```
  339. Show me functions with complexity higher than 15 across all languages that need refactoring
  340. ```
  341. ```
  342. Generate a dependency graph showing how the Python API connects to the React components
  343. ```
  344. ```
  345. Detect code smells and duplicate patterns across the entire multi-language codebase
  346. ```
  347. ## Development
  348. ### Requirements
  349. - Python 3.12+
  350. - UV package manager
  351. - MCP SDK
  352. - ast-grep-py (for multi-language support)
  353. - rustworkx (for high-performance graph operations)
  354. ### Running locally
  355. ```bash
  356. # Install dependencies
  357. uv sync
  358. # Run the server directly (auto-detects current directory)
  359. uv run code-graph-mcp --verbose
  360. # Test with help
  361. uv run code-graph-mcp --help
  362. ```
  363. ### Performance Features
  364. - **LRU Caching**: 50-90% speed improvements with cache sizes up to 300K entries for large codebases
  365. - **High-Performance Analytics**: PageRank at 4.9M nodes/second, Betweenness Centrality at 104K nodes/second
  366. - **Sub-microsecond Response**: Cache hits deliver sub-microsecond response times for repeated operations
  367. - **Memory Optimized**: Cache configurations optimized for 500+ file codebases with 500MB memory allocation
  368. - **Comprehensive Benchmarks**: Performance monitoring with detailed cache effectiveness metrics
  369. ## Supported Languages
  370. | Category | Languages | Count |
  371. |----------|-----------|-------|
  372. | **Web & Frontend** | JavaScript, TypeScript, HTML, CSS | 4 |
  373. | **Backend & Systems** | Python, Java, C#, C++, C, Rust, Go | 7 |
  374. | **JVM Languages** | Java, Kotlin, Scala | 3 |
  375. | **Functional** | Elixir, Elm | 2 |
  376. | **Mobile** | Swift, Dart | 2 |
  377. | **Scripting** | Ruby, PHP, Lua | 3 |
  378. | **Data & Config** | SQL, YAML, JSON, TOML | 4 |
  379. | **Markup & Docs** | XML, Markdown | 2 |
  380. | **Additional** | Haskell, OCaml, F# | 3 |
  381. | **Total** | | **25+** |
  382. ## Status
  383. ✅ **Multi-Language Support** - 25+ programming languages with ast-grep backend
  384. ✅ **MCP SDK integrated** - Full protocol compliance across all languages
  385. ✅ **Universal Architecture** - Language-agnostic graph structures and analysis
  386. ✅ **Server architecture complete** - Enterprise-grade multi-language structure
  387. ✅ **Core tools implemented** - 8 comprehensive analysis tools working across all languages
  388. ✅ **Performance optimized** - Multi-language AST caching with intelligent routing
  389. ✅ **Production ready** - comprehensive error handling, defensive security

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.