Fournit aux agents de codage IA un graphe de connaissances de code persistant et interrogeable pour réduire la consommation de tokens et accélérer l'exploration des bases de code.
Aussi connu sous pyalwin/codemesh, @pyalwin/codemesh
- Étoiles
- 0
- Outils
- 10
- Téléchargements, 30 jours
- —
- Dernière version
- 0.1.2
- Dernier commit
- 2 nov. 2026
- Licence
- MIT
Qu'est-ce que Codemesh MCP ?
Fournit aux agents de codage IA un graphe de connaissances de code persistant et interrogeable pour réduire la consommation de tokens et accélérer l'exploration des bases de code. Il expose 10 outils, comme codemesh_map, codemesh_source, codemesh_inspect.
Résumé généré à partir du README du projet
À propos du MCP server Codemesh
Codemesh fournit aux agents de codage IA un graphe de connaissances persistant et interrogeable pour simplifier l'exploration des bases de code. En indexant un projet dans un graphe basé sur SQLite, il permet aux agents de naviguer à travers les symboles, les répertoires et les fichiers sans les coûts élevés en tokens associés au grepping traditionnel et à la lecture de fichiers entiers. Cette approche réduit considérablement le nombre d'appels d'outils et la quantité de contexte non pertinent envoyée au modèle.
Les développeurs peuvent intégrer ce serveur dans des clients compatibles MCP tels que Claude Desktop, Claude Code ou Cursor en configurant la racine du projet dans leurs paramètres MCP. Le serveur propose deux modes principaux : un mode MCP server structuré pour une utilisation native des outils et un mode CLI pour les flux de travail basés sur le shell. Il est particulièrement utile pour les bases de code volumineuses où les agents gaspillent souvent des tokens lors des tâches de découverte.
Au-delà de la simple navigation, le système prend en charge une fonctionnalité d'écriture (write-back) permettant aux agents d'enregistrer des résumés et des notes directement dans le graphe. Cela garantit que les connaissances acquises lors d'une session sont disponibles pour éclairer les interactions futures, permettant ainsi à l'intelligence de la base de code de croître avec le temps.
Ce que vous pouvez faire avec
- 1Naviguer dans des structures de répertoires complexesUn agent peut parcourir les niveaux du dépôt pour localiser des fichiers ou des répertoires spécifiques en utilisant l'outil de mapping.
- 2Extraire le code source d'un symbole spécifiqueAu lieu de lire un fichier entier, un agent peut demander le code source exact d'une fonction ou d'une classe spécifique.
- 3Analyser les chaînes de dépendance du codeUn développeur peut demander à un agent de suivre les chaînes d'appels pour comprendre comment les différentes parties du système interagissent.
- 4Persister les connaissances acquises sur la base de codeLes agents peuvent écrire des résumés de ce qu'ils ont appris sur un fichier dans le graphe pour faciliter les sessions futures.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Comment installer Codemesh MCP
Formats vérifiés le 10 nov. 2026Ajouter à CursorAjouter à GooseInstaller Codemesh MCP dans Claude Code
$ claude mcp add codemesh -- npx -y @pyalwin/codemeshInstaller Codemesh MCP dans Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"codemesh": {
"command": "npx",
"args": [
"-y",
"@pyalwin/codemesh"
]
}
}
}Installer Codemesh MCP dans VS Code
.vscode/mcp.json
{
"servers": {
"codemesh": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@pyalwin/codemesh"
]
}
}
}Installer Codemesh MCP dans VS Code CLI
$ code --add-mcp '{"name":"codemesh","type":"stdio","command":"npx","args":["-y","@pyalwin/codemesh"]}'Installer Codemesh MCP dans Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"codemesh": {
"command": "npx",
"args": [
"-y",
"@pyalwin/codemesh"
]
}
}
}Installer Codemesh MCP dans Codex
$ codex mcp add codemesh -- npx -y @pyalwin/codemeshInstaller Codemesh MCP dans Codex config.toml
~/.codex/config.toml
[mcp_servers.codemesh] command = "npx" args = ["-y", "@pyalwin/codemesh"]
Installer Codemesh MCP dans Gemini CLI
$ gemini mcp add -s user codemesh npx -- -y @pyalwin/codemeshInstaller Codemesh MCP dans Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"codemesh": {
"command": "npx",
"args": [
"-y",
"@pyalwin/codemesh"
]
}
}
}Outils MCP Codemesh 10
Détectés depuis le 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 | — |
Configuration
CODEMESH_PROJECT_ROOTAbsolute path to the local codebase to index
| Nom | Description | Type |
|---|---|---|
| CODEMESH_PROJECT_ROOT | Absolute path to the local codebase to index |
Vérifications automatisées
Exécuté le 13 nov. 2026Rapport complet →A passé nos vérifications automatisées. Il ne s'agit pas d'un audit de sécurité : lisez le code et donnez au serveur l'accès le plus restreint dont il a besoin. Fonctionnement des vérifications
- Dépôt source lié et accessibleRéussi
- Licence open source (OSI)Réussi
- Commit ou version publiée au cours de l'année écouléeRéussi
- Nom du package non proche d'un package populaireRéussi
- L'endpoint distant utilise HTTPSNon vérifié
- Les outils destructifs sont étiquetésRéussi
- Aucune instruction cachée destinée au modèleRéussi
- Aucun avis critique dans le package ou ses dépendancesRéussi
README
Voir sur 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. ↩
Questions sur Codemesh MCP
Comment ajouter Codemesh MCP à Claude Code ?
Exécutez claude mcp add codemesh -- npx -y @pyalwin/codemesh dans votre terminal. Ajoutez --scope user pour le rendre disponible dans tous les projets.
Comment ajouter Codemesh MCP à Cursor ?
Ouvrez ~/.cursor/mcp.json et ajoutez le serveur sous mcpServers, avec la configuration Cursor indiquée dans la section d'installation ci-dessus.
Quels outils Codemesh MCP fournit-il ?
Il expose 10 outils, dont codemesh_map, codemesh_source, codemesh_inspect, codemesh_hydrate, codemesh_answer.
Comment Codemesh améliore-t-il les performances des agents IA ?
Il fournit un graphe de connaissances persistant qui permet aux agents de cartographier les dépôts et de lire des symboles précis au lieu de parcourir les fichiers avec grep et de lire du code non pertinent.
Codemesh nécessite-t-il une base de données vectorielle ?
Non, il utilise une base de données SQLite unique située dans un répertoire .codemesh/ et ne génère pas d'embeddings.