Предоставляет AI-агентам для кодинга постоянный граф знаний о коде с возможностью выполнения запросов, что снижает расход токенов и ускоряет исследование кодовой базы.
Также известен как pyalwin/codemesh, @pyalwin/codemesh
- Звёзды
- 0
- Инструменты
- 10
- Загрузки, 30 дней
- —
- Последняя версия
- 0.1.2
- Последний коммит
- 2 нояб. 2026 г.
- Лицензия
- MIT
Что такое Codemesh MCP?
Codemesh — это MCP server. Предоставляет AI-агентам для кодинга постоянный граф знаний о коде с возможностью выполнения запросов, что снижает расход токенов и ускоряет исследование кодовой базы. Он предоставляет 10 инструментов, например codemesh_map, codemesh_source, codemesh_inspect.
Сводка сгенерирована из README проекта
О Codemesh MCP server
Codemesh предоставляет AI-агентам для кодинга постоянный граф знаний с возможностью выполнения запросов для оптимизации исследования кодовой базы. Индексируя проект в граф на базе SQLite, он позволяет агентам перемещаться по символам, директориям и файлам без высоких затрат токенов, характерных для традиционного поиска через grep и чтения файлов целиком. Такой подход значительно сокращает количество вызовов инструментов и объем нерелевантного контекста, отправляемого модели.
Разработчики могут интегрировать этот сервер в совместимые с MCP клиенты, такие как Claude Desktop, Claude Code или Cursor, настроив корневую директорию проекта в настройках MCP. Сервер предлагает два основных режима: структурированный режим MCP server для нативного использования инструментов и режим CLI для рабочих процессов в терминале. Он особенно полезен для больших кодовых баз, где агенты часто тратят токены впустую на задачи по поиску информации.
Помимо простой навигации, система поддерживает функцию обратной записи, позволяющую агентам сохранять резюме и заметки обратно в граф. Это гарантирует, что знания, полученные в ходе одной сессии, будут доступны для будущих взаимодействий, позволяя интеллекту кодовой базы расти со временем.
Что вы можете с ним делать
- 1Навигация по сложным структурам директорийАгент может просматривать уровни репозитория, чтобы найти конкретные файлы или директории с помощью инструмента маппинга.
- 2Извлечение исходного кода конкретных символовВместо чтения всего файла агент может запросить точный исходный код конкретной функции или класса.
- 3Анализ цепочек зависимостей кодаРазработчик может попросить агента проследить цепочки вызовов, чтобы понять, как взаимодействуют различные части системы.
- 4Сохранение полученных знаний о кодовой базеАгенты могут записывать резюме изученного ими файла обратно в граф, чтобы помочь в будущих сессиях.
Взято из README проекта. Каждый вариант использования проверен на соответствие цитате из него.
Как установить Codemesh MCP
Форматы проверены 10 ноя 2026Добавить в CursorДобавить в GooseУстановка Codemesh MCP в Claude Code
$ claude mcp add codemesh -- npx -y @pyalwin/codemeshУстановка Codemesh MCP в Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"codemesh": {
"command": "npx",
"args": [
"-y",
"@pyalwin/codemesh"
]
}
}
}Установка Codemesh MCP в VS Code
.vscode/mcp.json
{
"servers": {
"codemesh": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@pyalwin/codemesh"
]
}
}
}Установка Codemesh MCP в VS Code CLI
$ code --add-mcp '{"name":"codemesh","type":"stdio","command":"npx","args":["-y","@pyalwin/codemesh"]}'Установка Codemesh MCP в Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"codemesh": {
"command": "npx",
"args": [
"-y",
"@pyalwin/codemesh"
]
}
}
}Установка Codemesh MCP в Codex
$ codex mcp add codemesh -- npx -y @pyalwin/codemeshУстановка Codemesh MCP в Codex config.toml
~/.codex/config.toml
[mcp_servers.codemesh] command = "npx" args = ["-y", "@pyalwin/codemesh"]
Установка Codemesh MCP в Gemini CLI
$ gemini mcp add -s user codemesh npx -- -y @pyalwin/codemeshУстановка Codemesh MCP в Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"codemesh": {
"command": "npx",
"args": [
"-y",
"@pyalwin/codemesh"
]
}
}
}Инструменты Codemesh MCP 10
Определено из READMEcodemesh_mapcodemesh_sourcecodemesh_inspectcodemesh_hydratecodemesh_answercodemesh_explorecodemesh_tracecodemesh_enrichcodemesh_workflowcodemesh_status
| codemesh_map | — | |
| codemesh_source | — | |
| codemesh_inspect | — | |
| codemesh_hydrate | — | |
| codemesh_answer | — | |
| codemesh_explore | — | |
| codemesh_trace | — | |
| codemesh_enrich | — | |
| codemesh_workflow | — | |
| codemesh_status | — |
Конфигурация
CODEMESH_PROJECT_ROOTAbsolute path to the local codebase to index
| Название | Описание | Тип |
|---|---|---|
| CODEMESH_PROJECT_ROOT | Absolute path to the local codebase to index |
Автоматические проверки
Запущено 13 нояб. 2026 г.Полный отчёт →Прошло наши автоматизированные проверки. Это не аудит безопасности: изучите код и предоставьте серверу минимально необходимый доступ. Как работают проверки
- Связанный и доступный исходный репозиторийПройдено
- Open source лицензия (OSI)Пройдено
- Коммит или релиз за последний годПройдено
- Имя пакета не похоже на популярный пакетПройдено
- Удаленная конечная точка использует HTTPSНе проверялось
- Деструктивные инструменты помеченыПройдено
- Нет скрытых инструкций для моделиПройдено
- Нет критических предупреждений в пакете или его зависимостяхПройдено
README
Открыть на GitHubCodemesh
Intelligent code knowledge graph for AI coding agents
71% cheaper, 72% faster, 82% fewer tool calls vs baseline Grep+Read
on 6 real-world repos (Sonnet 4.6) — from a single codemesh index.
Benchmarks · Quick Start · Integrations · Write-Back · How It Works · API Reference · Full Results
The Problem
AI coding agents waste 40-80% of their tokens on discovery — grepping through files, reading irrelevant code, and rebuilding context they've already seen in previous sessions.
On a 600-file codebase, a typical exploration task involves 10+ file reads before the agent even knows what's relevant.
Before: Agent → Grep → 50 matches → Read 10 files → Understand → Work
After: Agent → codemesh_map → expand chosen branches → read exact symbols → Work
Codemesh is an MCP server that gives agents a persistent, queryable knowledge graph. The graph gets smarter over time: agents write back what they learn, so the next session starts informed.
Benchmarks
Benchmarked on 6 real-world codebases (Alamofire, Excalidraw, VS Code, Swift Compiler, pydantic-validators, pydantic-basemodel) with Claude Sonnet 4.6, compared alongside baseline and graph-based approaches for context.
Full methodology, per-repo breakdowns, and pairwise comparisons: docs/benchmark-results.md | Early pydantic evals
These historical runs used the earlier answer-first workflow. The map-first navigation workflow described below is evaluated in an exploratory Pydantic pilot; the figures in this section should not be read as its measured performance.
Cost
| Mode | Alamofire | Excalidraw | VS Code | Swift Compiler1 | pydantic-validators | pydantic-basemodel | Avg |
|---|---|---|---|---|---|---|---|
| Baseline | $0.54 | $0.89 | $0.21 | $0.83 | $1.32 | $0.78 | $0.76 |
| Codemesh MCP | $0.25 | $0.21 | $0.16 | $0.23 | $0.33 | $0.13 | $0.22 |
| Codemesh CLI | $0.67 | $0.51 | $0.16 | $0.83 | $1.00 | $0.18 | $0.56 |
| Codegraph | $0.37 | $0.56 | $0.57 | $0.74 | $0.29 | $0.19 | $0.45 |
Time
| Mode | Alamofire | Excalidraw | VS Code | Swift1 | pydantic-v | pydantic-b | Avg |
|---|---|---|---|---|---|---|---|
| Baseline | 180s | 191s | 87s | 199s | 352s | 232s | 207s |
| Codemesh MCP | 78s | 45s | 35s | 87s | 72s | 32s | 58s |
| Codemesh CLI | 226s | 177s | 62s | 227s | 235s | 51s | 163s |
| Codegraph | 134s | 180s | 192s | 199s | 75s | 60s | 140s |
Tool calls (agent turns)
| Mode | Alamofire | Excalidraw | VS Code | Swift1 | pydantic-v | pydantic-b | Avg |
|---|---|---|---|---|---|---|---|
| Baseline | 31 | 48 | 12 | 29 | 84 | 65 | 45 |
| Codemesh MCP | 9 | 5 | 3 | 14 | 14 | 3 | 8 |
| Codemesh CLI | 30 | 32 | 12 | 56 | 64 | 9 | 34 |
| Codegraph | 31 | 35 | 44 | 44 | 20 | 12 | 31 |
Quality (1–10, LLM-as-judge)
| Mode | Alamofire2 | Excalidraw | VS Code | Swift Compiler | pydantic-validators | pydantic-basemodel | Avg |
|---|---|---|---|---|---|---|---|
| Baseline | n/a | 9 | 8 | 7 | 2 | 9 | 7.0 |
| Codemesh MCP | 9 | 9 | 7 | 8 | 7 | 7.8 | 7.9 |
| Codemesh CLI | 9 | 7 | 7 | 9 | 1 | 8.4 | 6.9 |
| Codegraph | 8 | 9 | 8.7 | 8 | 8 | 9 | 8.4 |
Cost savings: Codemesh MCP vs Baseline
| Repo | Baseline | Codemesh MCP | Cost saved | Time saved |
|---|---|---|---|---|
| Alamofire | $0.54 | $0.25 | −54% | −57% (180s → 78s) |
| Excalidraw | $0.89 | $0.21 | −76% | −76% (191s → 45s) |
| VS Code | $0.21 | $0.16 | −24% | −60% (87s → 35s) |
| Swift Compiler1 | $0.83 | $0.23 | −72% | −56% (199s → 87s) |
| pydantic-validators | $1.32 | $0.33 | −75% | −79% (352s → 72s) |
| pydantic-basemodel | $0.78 | $0.13 | −83% | −86% (232s → 32s) |
| Average | $0.76 | $0.22 | −71% | −72% |
[!NOTE] Codemesh MCP achieves the lowest cost and fastest time of any mode tested — 71% cheaper and 72% faster than baseline on average across 6 repos, using 82% fewer tool calls (8 vs 45). Quality is comparable to baseline (7.9 vs 7.0); Codegraph edges Codemesh on quality (8.4) but at roughly double the cost ($0.45 vs $0.22). Every repo shows cost and time savings — including the comprehension-heavy queries (Excalidraw, pydantic-basemodel) that regressed in prior builds of codemesh.
Quick Start
1. Install
npm install -g @pyalwin/codemesh
Or run directly without installing:
npx -y @pyalwin/codemesh --help
git clone https://github.com/pyalwin/codemesh.git
cd codemesh
npm install && npm run build
npm link
Verify the install:
codemesh --versionshould print the package version.
2. Index your project
cd /your/project
codemesh index
The default index and retrieval path uses one SQLite database in .codemesh/.
It does not generate embeddings or require a vector database. Existing vector
artifacts from older runs are left untouched but are not used by this path.
Indexed 656 files
Symbols found: 16733
Edges created: 33266
Duration: 10009ms
PageRank: 13843 nodes scored
3. Choose your mode
Codemesh offers two ways to integrate with AI agents:
Add to your Claude Code MCP config (~/.claude/mcp-servers.json or project .mcp.json):
{
"mcpServers": {
"codemesh": {
"command": "npx",
"args": ["-y", "@pyalwin/codemesh"],
"env": {
"CODEMESH_PROJECT_ROOT": "/path/to/your/project"
}
}
}
}
The agent gets native MCP tools:
codemesh_map— browse one level of the indexed repository or follow a linkcodemesh_source— read a revision-checked source view by symbol ID;ifHashavoids repeat deliverycodemesh_inspect— inspect an exact symbol and its direct calls with bounded, exact source blockscodemesh_hydrate— verify saved symbol references and reopen exact source after a handoffcodemesh_answer— optional ranked context assemblycodemesh_explore— search, context (multi-target), impactcodemesh_trace— follow call chainscodemesh_enrich/codemesh_workflow— write backcodemesh_recall— retrieve notes and workflows with freshness statuscodemesh_status— health check
Best for: Opus, structured workflows, enrichment/write-back
No MCP config needed. The agent calls codemesh directly via Bash:
export CODEMESH_PROJECT_ROOT=/path/to/your/project
# Navigate one level at a time, then read a selected symbol:
codemesh explore map
codemesh explore map --node 'dir:src'
codemesh explore map --node 'file:src/server.ts'
codemesh explore source 'symbol:src/server.ts:createServer'
codemesh explore source 'symbol:src/server.ts:createServer' --mode preview
codemesh explore inspect 'symbol:src/server.ts:createServer' --depth 1 --max-symbols 4 --compact
codemesh explore hydrate --references '[{"id":"symbol:src/server.ts:createServer","bodyHash":"HASH"}]' --compact
# Other exploration commands:
codemesh explore search "request flow"
codemesh explore context Source/Core/Session.swift Source/Core/Request.swift
codemesh explore trace Session.request --depth 5
codemesh explore recall --path src/server.ts
codemesh remember --path src/server.ts --summary "Server tool registration" --session my-task
Exploration and write commands return JSON to stdout. No MCP server process is required.
Best for: Sonnet/Haiku, speed-sensitive workflows, simpler setup
Which mode should I use?
| MCP Server | CLI Mode | |
|---|---|---|
| Setup | MCP config file | Just export CODEMESH_PROJECT_ROOT |
| Invocation | Persistent MCP process | CLI subprocess |
| Enrichment | Native codemesh_enrich tool |
codemesh remember ... |
| Retrieval | Shared SQLite-backed handlers | Same handlers and JSON data |
| Recommended | Hosts with reliable MCP tool use | Deterministic shell workflows |
4. Use it
The agent can choose a path through the persistent graph before reading code:
You: "Find how pydantic handles validation"
Agent calls: codemesh_map({})
gets: immediate repository directories and files, each with an ID
Agent calls: codemesh_map({ node: "dir:pydantic" })
gets: immediate files and subdirectories
Agent calls: codemesh_map({ node: "file:pydantic/main.py" })
gets: top-level symbols, including BaseModel
Agent calls: codemesh_map({ node: "symbol:pydantic/main.py:BaseModel" })
gets: methods, including model_validate
Agent calls: codemesh_source({ id: "symbol:pydantic/main.py:BaseModel.model_validate" })
reads: only the selected symbol's source
Agent calls: codemesh_enrich({ path: "pydantic/functional_validators.py",
summary: "Primary V2 validator API..." })
saves: summary for next session
Client Integrations
Codemesh speaks the Model Context Protocol, so any MCP-compatible client can use it. Paste one of the snippets below, restart the client, and the codemesh_* tools show up in the agent's toolbox.
Add to ~/.claude/mcp-servers.json (user-wide) or .mcp.json (project-local):
{
"mcpServers": {
"codemesh": {
"command": "npx",
"args": ["-y", "@pyalwin/codemesh"],
"env": {
"CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project"
}
}
}
}
Edit claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"codemesh": {
"command": "npx",
"args": ["-y", "@pyalwin/codemesh"],
"env": {
"CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project"
}
}
}
}
Restart Claude Desktop. Codemesh's tools will appear in the tool picker (hammer icon).
Cursor reads .cursor/mcp.json per project (or ~/.cursor/mcp.json for all projects):
{
"mcpServers": {
"codemesh": {
"command": "npx",
"args": ["-y", "@pyalwin/codemesh"],
"env": {
"CODEMESH_PROJECT_ROOT": "${workspaceFolder}"
}
}
}
}
Open Settings → MCP, confirm codemesh is green, then mention it in a prompt (@codemesh how does auth work?) to nudge the agent toward graph queries instead of recursive Grep.
Add to ~/.continue/config.json under experimental.modelContextProtocolServers:
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@pyalwin/codemesh"],
"env": {
"CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project"
}
}
}
]
}
}
Agent Write-Back: the graph that gets smarter
Every other code-intelligence tool indexes your repo once and hands the agent a read-only view. Codemesh lets the agent teach the graph as it works — summaries, workflows, and cross-concept links persist across sessions and survive re-indexing.
// Session 1 — agent reads unfamiliar code, then writes back what it learned.
codemesh_enrich({
path: "pydantic/functional_validators.py",
summary: "Primary V2 validator API. `@field_validator` wraps "
+ "`_decorators.FieldValidatorDecoratorInfo`; `mode='before'|'after'` "
+ "toggles pre/post-coercion execution. Extends BaseValidator.",
sessionId: "validation-investigation-1"
})
// Session 1 — agent traces a multi-file flow, records the path.
codemesh_workflow({
name: "pydantic field validation",
description: "Request → BaseModel.__init__ → SchemaValidator → field_validator",
files: [
"pydantic/main.py",
"pydantic/_internal/_model_construction.py",
"pydantic/functional_validators.py"
]
})
// Session 2 (days later) — another agent navigates the same indexed code.
codemesh_map({ node: "file:pydantic/functional_validators.py" })
// → returns stable symbol IDs without reading their bodies.
codemesh_explore({ action: "context", path: "pydantic/functional_validators.py" })
// → includes the earlier agent's concept alongside indexed relationships.
The graph now knows things no static analyzer could infer: why a file matters, which files move together, what a maintainer called a concept. Re-indexing rebuilds the structural layer (files, symbols, imports, calls) but preserves every enrichment — entries only go stale when their referenced files change.
See codemesh_enrich and codemesh_workflow under MCP Tools.
How It Works
┌──────────────────────────────────┐
│ Knowledge Graph │
│ │
│ ┌──────────┐ ┌───────────────┐ │
│ │Structural│ │ Semantic │ │
│ │ (auto) │ │ (agents) │ │
│ │ │ │ │ │
│ │ files │ │ summaries │ │
│ │ symbols │ │ workflows │ │
│ │ imports │ │ concepts │ │
│ │ calls │ │ enrichments │ │
│ └──────────┘ └───────────────┘ │
│ │
│ ┌──────────┐ ┌───────────────┐ │
│ │ Git │ │ Search │ │
│ │ Intel │ │ │ │
│ │ │ │ FTS5 (exact) │ │
│ │ hotspots │ │ Trigram (fuzzy)│ │
│ │ co-change│ │ notes + cache │ │
│ │ churn │ │ PageRank │ │
│ └──────────┘ └───────────────┘ │
│ │
│ SQLite only │
└────────────┬──────────────────────┘
│
┌────────────┴──────────────────────┐
│ MCP Server / CLI (shared core) │
│ │
│ map · source · answer · explore │
│ trace · recall · enrich · workflow │
│ status │
└────────────────────────────────────┘
Structural layer (automatic) — Tree-sitter parses your code into files, symbols (functions, classes, methods), and relationships (imports, calls, extends). Rebuilt on each index.
Semantic layer (agent-built) — As agents work with your code, they write back summaries and workflow paths. These survive re-indexing and accumulate across sessions. Invalidated when referenced files change.
MCP Tools
| Tool | Purpose | Example |
|---|---|---|
codemesh_map |
Bounded, one-level navigation through directories, files, symbols, and graph links | codemesh_map({ node: "dir:src", limit: 30 }) |
codemesh_source |
Exact source for a selected symbol ID | codemesh_source({ id: "symbol:src/auth.ts:login" }) |
codemesh_inspect |
Exact source for a symbol plus direct call evidence, within a byte and symbol budget | codemesh_inspect({ id: "symbol:src/auth.ts:login", depth: 1 }) |
codemesh_hydrate |
Verify saved symbol references and reopen exact source after context loss | codemesh_hydrate({ references: [{ id: "symbol:src/auth.ts:login", bodyHash: "..." }] }) |
codemesh_answer |
Optional ranked context assembly with source snippets | codemesh_answer({ question: "How does auth work?" }) |
codemesh_explore |
Search, context (multi-target), impact analysis | codemesh_explore({ action: "search", query: "auth" }) |
codemesh_trace |
Follow call chains with source code | codemesh_trace({ symbol: "login", depth: 5 }) |
codemesh_enrich |
Write back what you learned for future sessions | codemesh_enrich({ path: "src/auth.py", summary: "..." }) |
codemesh_workflow |
Record multi-file workflow paths | codemesh_workflow({ name: "login flow", files: [...] }) |
codemesh_status |
Graph health check | codemesh_status() |
Footnotes
-
Swift Compiler's codemesh index failed to complete (indexer regression on 30k+ file codebases — see known issues). The codemesh numbers above reflect agent behavior with an empty retrieval graph, falling back to Read + LSP — still ahead of baseline, but unrepresentative of codemesh's capability on a properly-indexed Swift repo. ↩ ↩2 ↩3 ↩4
-
Baseline for Alamofire hit a judge error (score recorded as 0 but not meaningful); excluded from the Baseline average. ↩
Вопросы о Codemesh MCP
Как добавить Codemesh MCP в Claude Code?
Выполните claude mcp add codemesh -- npx -y @pyalwin/codemesh в терминале. Добавьте --scope user, чтобы сервер был доступен во всех проектах.
Как добавить Codemesh MCP в Cursor?
Откройте ~/.cursor/mcp.json и добавьте сервер в mcpServers, используя конфигурацию Cursor из раздела установки выше.
Какие инструменты предоставляет Codemesh MCP?
Он предоставляет 10 инструментов, включая codemesh_map, codemesh_source, codemesh_inspect, codemesh_hydrate, codemesh_answer.
Как Codemesh улучшает производительность AI-агентов?
Он предоставляет постоянный граф знаний, который позволяет агентам строить карту репозиториев и считывать конкретные символы вместо того, чтобы использовать grep по файлам и читать нерелевантный код.
Требуется ли для Codemesh векторная база данных?
Нет, он использует одну базу данных SQLite, расположенную в директории .codemesh/, и не генерирует эмбеддинги.