{
  "markdown": "# Grafyx\n\n<!-- mcp-name: io.github.bilal07karadeniz/grafyx -->\n\n[![PyPI](https://img.shields.io/pypi/v/grafyx-mcp.svg)](https://pypi.org/project/grafyx-mcp/)\n[![Downloads](https://img.shields.io/pypi/dm/grafyx-mcp.svg)](https://pypistats.org/packages/grafyx-mcp)\n[![CI](https://github.com/bilal07karadeniz/Grafyx/actions/workflows/ci.yml/badge.svg)](https://github.com/bilal07karadeniz/Grafyx/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/protocol-MCP-green.svg)](https://modelcontextprotocol.io)\n[![Grafyx MCP server](https://glama.ai/mcp/servers/bilal07karadeniz/Grafyx/badges/score.svg)](https://glama.ai/mcp/servers/bilal07karadeniz/Grafyx)\n\n**Real-time codebase understanding for AI coding assistants.**\n\n---\n\n## What is Grafyx?\n\nAI coding tools read raw files with zero architectural understanding -- they don't know what calls what, which classes inherit from where, or how your modules connect. Grafyx fixes this by parsing your entire codebase into a full relationship graph using [Graph-sitter](https://github.com/getsentry/graph-sitter) (built on tree-sitter), then exposing that graph to any AI assistant through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). Your assistant can trace call chains, map dependencies, find related code by description, detect conventions, and understand your project's architecture -- all in real time, with a file watcher that keeps the graph current as you edit.\n\n---\n\n## Quick Start\n\n### Claude Code\n\n```bash\n# Zero-install (recommended)\nclaude mcp add --scope user grafyx -- uvx --from grafyx-mcp grafyx\n\n# Or install with pip first\npip install grafyx-mcp\nclaude mcp add --scope user grafyx -- grafyx\n```\n\n### Cursor / Windsurf / Cline\n\nAdd to your MCP config file:\n\n- **Cursor**: `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)\n- **Windsurf**: `~/.codeium/windsurf/mcp_config.json`\n- **Cline**: Cline MCP settings in VS Code\n\n```json\n{\n  \"mcpServers\": {\n    \"grafyx\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"grafyx-mcp\", \"grafyx\"]\n    }\n  }\n}\n```\n\n### VS Code (GitHub Copilot)\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"grafyx\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"grafyx-mcp\", \"grafyx\"]\n    }\n  }\n}\n```\n\n> **Using pip instead of uvx?** Replace the command with: `\"command\": \"grafyx\"` (no args needed).\n\n---\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_project_skeleton` | Full project structure with stats per module |\n| `get_function_context` | Everything about a function: callers, callees, deps |\n| `get_file_context` | File contents, imports, dependencies |\n| `get_class_context` | Class methods, inheritance, usages |\n| `find_related_code` | Natural language search across the codebase |\n| `find_related_files` | Find files relevant to a feature by matching symbols |\n| `get_dependency_graph` | Impact analysis: what depends on what |\n| `get_conventions` | Detected coding patterns and conventions |\n| `get_call_graph` | Call chain tracing upstream and downstream |\n| `refresh_graph` | Force re-parse of the codebase |\n| `get_module_context` | Symbols in a directory/package (intermediate zoom) |\n| `get_subclasses` | Inheritance tree for a base class |\n| `get_unused_symbols` | Dead code detection |\n| `set_project` | Switch the served project at runtime |\n\n---\n\n## How It Works\n\n```\nYour AI Assistant\n       |\n       | MCP Protocol (stdio)\n       v\n  +-----------+\n  |  Grafyx   |  FastMCP server with 14 tools\n  |  Server   |\n  +-----------+\n       |\n  +-----------+     +-----------+     +-------------+\n  |  Graph    |---->|  Search   |     | Convention  |\n  |  Engine   |---->|  Engine   |     | Detector    |\n  +-----------+     +-----------+     +-------------+\n       |\n       v\n  +-----------+\n  |  Graph-   |  Tree-sitter based parsing\n  |  sitter   |\n  +-----------+\n       |\n  +-----------+\n  |  Watchdog |  File watcher for live updates\n  +-----------+\n```\n\n1. **Startup** -- Grafyx detects languages in your project and parses all source files into a semantic graph via Graph-sitter.\n2. **Serving** -- The FastMCP server exposes 14 tools over stdio. Your AI assistant calls them as needed.\n3. **Live updates** -- Watchdog monitors file changes. When you save, the graph is automatically re-parsed after a short debounce.\n\n### ML-augmented search\n\nGrafyx's `find_related_code` uses a pretrained code embedding model (default:\n`jinaai/jina-embeddings-v2-base-code`, Apache-2.0, 161M params) running on CPU\nvia ONNX through [`fastembed`](https://github.com/qdrant/fastembed). The model\nis downloaded on first use and cached locally — no GPU, no daemon, no cloud\ncalls.\n\nSince 0.2.1, `fastembed` is a hard dependency, so the default install\nalready includes the encoder — no extra needed.\n\n**Benchmark (0.2.0, 278 docstring→function queries across FastAPI + Django):**\n\n| Encoder | nDCG@10 | MRR@10 | p50 latency |\n|---|---:|---:|---:|\n| jina-v2 (default) | **0.787** | **0.741** | ~1.5 s |\n| coderankembed | 0.663 | 0.623 | ~1.3 s |\n| tokens-only (no fastembed) | 0.335 | 0.297 | ~0.9 s |\n\nThe default encoder more than doubles retrieval quality over plain\nsource-token search (+135% nDCG@10).\n\nFull breakdown + per-query JSONL: [`docs/benchmarks/0.2.0/`](docs/benchmarks/0.2.0/).\n\nSwitch encoders via the `GRAFYX_ENCODER` env var:\n\n- `jina-v2` (default) — Apache-2.0, fastembed-native, ~150 MB. Wins on\n  accuracy; recommended unless you have a specific reason to switch.\n- `coderankembed` — MIT, 137M, ONNX-int8, ~140 MB. Lower latency but\n  ~12 nDCG@10 points behind jina-v2 in our eval. Hosted at\n  [`Bilal7Dev/grafyx-coderankembed-onnx`](https://huggingface.co/Bilal7Dev/grafyx-coderankembed-onnx).\n\nSupporting numpy-only MLPs (~5 MB total weights, bundled in the wheel):\n\n- **M1 Relevance ranker** — 33-feature MLP that re-ranks the encoder's top\n  candidates using structural signals (caller count, name overlap, exports).\n- **M3 Source token filter** — suppresses noise tokens (imports, strings,\n  magic methods) from full-text search.\n- **M4 Symbol importance** — weights symbols by caller count, exports, and\n  structural signals.\n- **Gibberish detector** — character-bigram MLP that blocks nonsense queries\n  before they hit the index.\n\nReproducible benchmarks against FastAPI, Django, and Home Assistant ship in\n[`benchmarks/`](benchmarks/) (`python -m scripts.run_all`).\n\n---\n\n## Supported Languages\n\n| Language | Extensions |\n|----------|------------|\n| Python | `.py`, `.pyi` |\n| TypeScript | `.ts`, `.tsx` |\n| JavaScript | `.js`, `.jsx` |\n\nLanguages are auto-detected. To specify manually:\n\n```bash\ngrafyx --languages python,typescript\n```\n\n---\n\n## Options\n\n```\ngrafyx [OPTIONS]\n\n  --project PATH       Project to analyze (default: current directory)\n  --languages LANGS    Comma-separated languages (default: auto-detect)\n  --ignore PATTERNS    Additional directories to ignore\n  --no-watch           Disable file watching\n  --verbose, -v        Debug logging\n  --version            Show version\n```\n\nDefault ignored: `node_modules`, `.git`, `__pycache__`, `.venv`, `venv`, `.env`, `dist`, `build`, `.tox`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`, `egg-info`, `.eggs`, `.next`, `.nuxt`, `coverage`, `.coverage`, `.nyc_output`\n\n---\n\n## Multi-Agent Support\n\nGrafyx works with agent teams. A single Grafyx instance serves all agents connected to the same project. When one agent modifies code, the file watcher updates the graph automatically, so other agents immediately see the changes.\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/bilal07karadeniz/Grafyx.git\ncd Grafyx\npip install -e \".[dev]\"\npytest\n```\n\n---\n\n## Troubleshooting\n\n**Windows**: Graph-sitter requires Linux. Use WSL and configure your MCP client to launch via `wsl`:\n\n```json\n{\n  \"mcpServers\": {\n    \"grafyx\": {\n      \"command\": \"wsl\",\n      \"args\": [\"-e\", \"bash\", \"-c\", \"source ~/your-venv/bin/activate && grafyx\"]\n    }\n  }\n}\n```\n\n---\n\n## License\n\nMIT -- see [LICENSE](LICENSE) for details.\n",
  "bytes": 8200,
  "sha": "66da42fa4fb9cca75b7a4c659e525dc35aca9309b7e224f41aaa924ed52b3257",
  "repo_slug": "bilal07karadeniz/grafyx",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bilal07karadeniz_grafyx_9fd6dbce/readme"
}