MeshMCP

MeshMCP is a local Model Context Protocol server, written in Rust, that indexes a multi-language, multi-service codebase and answers structural questions for an AI coding agent: where a symbol is declared, who depends on a contract, which services implement and call a gRPC method, who produces and consumes an event, and what the team's own documentation says. It runs on the developer's machine, reads only the directories it is configured with, and its runtime binaries (mesh-mcp, meshd) contain no network client code; only the installer downloads anything.

---

The problem

A coding agent explores a repository the way a newcomer does: it greps, opens files one at a time, and infers relationships from names. In a single-language repository this works. In a workspace where a .proto contract is implemented in Go, called from TypeScript and Java, and followed by Kafka events consumed in Python, the relationships the agent needs are spread across files it has no reason to open. The usual results are missed callers, changes that break a consumer in another service, and a context window filled with function bodies that were only read to find a signature.

MeshMCP builds that cross-service map once, keeps it in memory, updates it as files change, and exposes it through six MCP tools.

---

What it is for, and what it is not

Fits

• Cross-repository questions in a polyglot workspace: who imports this package, which services implement and call this RPC, who produces and consumes this event, what a route handler touches.
• Checking a change before making it: the blast radius of a contract, and whether an edit to a .proto breaks the wire format against a Git base.
• Reading less: declarations come back with function bodies stripped, ranked and paginated.
• Looking up the team's own ADRs and Markdown docs from the same server.

Does not do

• It is not a language server. There is no type inference and no intra-language call graph: it records declarations, imports and the contract idioms listed in docs/parser-support.md.
• It does not see what is built at runtime: a topic name read from a registry or config, a route assembled from variables, reflection, generated code outside the workspace. These show up as "not statically resolved", not as a fact.
• HTTP client calls (fetch, axios, HttpService) are not linked to the routes they hit.
• It does not link tests to the code they cover, and no MCP tool writes to your files (only the init and install-hooks commands do).

---

The six tools

| Tool | Answers | | :--- | :--- | | smart_search | Where is a symbol or an HTTP route (PATCH /events/:id/state) declared? Returns signatures with bodies stripped, ranked and paginated. | | find_dependents | Who imports or depends on this type, package or contract? One row per declaration, file or dependent package. | | analyze_grpc | Where is this RPC defined, implemented and called? Also checks the .proto for wire-format breaking changes against a Git base. | | analyze_impact | What is affected if this RPC, service, topic, event or HTTP route handler changes? One table row per impacted element, marked INTERNAL/EXTERNAL with edge confidence; depth follows re-emissions across hops. | | search_docs | What do our Markdown docs, ADRs and RFCs say about this term? | | visualize_mesh | Per-service topology as Mermaid, JSON or HTML, bounded in size, with zoom (a zoom also lists the service's HTTP routes in Mermaid). |

Arguments, output formats and error handling: docs/mcp-tools.md.

---

Installation

Prebuilt binaries (recommended). install.sh downloads the rolling latest build of main for macOS (arm64, x86-64), Linux x86-64 and Windows x86-64, and falls back to cargo install elsewhere:

curl -fsSL https://raw.githubusercontent.com/VictorAgahi/causalmesh/main/install.sh | bash

Connect an agent:

claude mcp add mesh-mcp -- mesh-mcp run          # Claude Code
mesh-mcp doctor                                   # config, roots, parsers, daemon, cache, index health

Pilot install from a checkout (macOS or Linux, x86-64 or arm64; builds locally, downloads nothing, idempotent):

git clone https://github.com/VictorAgahi/causalmesh.git
cd /path/to/your/workspace
/path/to/causalmesh/scripts/install_pilot.sh        # cargo build --release, then init after confirmation

It copies mesh-mcp and meshd into ~/.local/bin, runs mesh-mcp init --auto --write-ide-config (keeps an existing config, merges .mcp.json, .cursor/mcp.json and .vscode/mcp.json without removing other servers) and checks the result with mesh-mcp doctor --json. Building needs Rust 1.90 or newer (rust-version in Cargo.toml) and a C compiler.

The full walkthrough, including configuration of roots, docs vocabulary, custom patterns, skills and stop rules, is in SETUP.md. A five-language example workspace is in examples/polyglot-shop.

CLI

| Command | Purpose | | :--- | :--- | | mesh-mcp run [--standalone] | MCP server on stdio (daemon-backed by default). Refuses to scan /, a drive root or your home directory when no config file is found. | | mesh-mcp init --auto [--write-ide-config] [--force] | Generate .agents/mesh-mcp.toml from the directory layout (an existing one is kept unless --force); optionally write Claude Code / Cursor / VS Code MCP entries and a managed MeshMCP routing section in CLAUDE.md / AGENTS.md. | | mesh-mcp agent-guide | Print the setup guide for an AI agent installing MeshMCP for you (Markdown). | | mesh-mcp doctor [--fix] [--json] | Diagnose configuration (including custom patterns), index health, socket, daemon version and the config it serves, cache and sandbox; --fix repairs what is safe to repair (never the audit log). | | mesh-mcp graph [--format html\|mermaid\|json\|fingerprint] [--open] | Render the full topology, or print a content fingerprint of the index. | | mesh-mcp stats [--since 7d\|24h\|all] [--session ID] [--db PATH] [--json] | Local audit summary: calls per tool and per agent session, isError rate, p50/p95 latency per tool, cache hit rate, meshd restarts. MESH_AUDIT_DB moves the audit database. | | mesh-mcp install-hooks | Install the Git pre-commit hook. |

-c, --config <path> is accepted by every command. Logs go to stderr. Under mesh-mcp run, stdout carries only JSON-RPC frames.

---

How it works

flowchart TD
    subgraph Inputs["1. Workspace Roots & Watcher"]
        Config["roots in mesh-mcp.toml"]
        Watcher["File Watcher<br/>(changed files only, held during Git ops)"]
    end

    subgraph Pipeline["2. Indexing Pipeline"]
        Crawl["Crawler<br/>(gitignore-aware, no symlink following)"]
        Guard{"AstGuard Limits<br/>(size, binary, line-length, nesting)"}
        Rejected["Rejected Files List<br/>(surfaced in doctor & tools, never dropped silently)"]
        Parse["Tree-sitter Parse & Extractors<br/>(parallel Rayon workers)"]
        Cache[("SQLite Parse Cache<br/>(persistent per-workspace cache)")]
        Reconcile["Fold & Reconcile Edges<br/>(Imports, Implements, CallsRpc, Produces, Consumes)"]
    end

    subgraph State["3. In-Memory State"]
        Snapshot[("Immutable MeshSnapshot<br/>(atomically swapped in memory)")]
    end

    subgraph Serving["4. Query Serving"]
        Server["MCP Server / meshd Daemon<br/>(stdio JSON-RPC)"]
        Agent["AI Coding Agent<br/>(Claude Code, Cursor, etc.)"]
        Answers["Markdown Responses<br/>(strictly capped at 48 KB)"]
    end

    Config --> Crawl
    Watcher -.->|"incremental updates"| Crawl
    Crawl --> Guard
    Guard -->|"within limits"| Parse
    Guard -.->|"exceeds limits"| Rejected
    Parse <--> Cache
    Parse --> Reconcile
    Reconcile -->|"atomically swap"| Snapshot
    Snapshot --> Server
    Agent <-->|"JSON-RPC queries"| Server
    Server --> Answers

• Daemon mode (default). mesh-mcp run is a thin stdio proxy to a per-workspace meshd process (Unix socket on macOS/Linux, named pipe on Windows), so several editor windows on the same repository share one index. meshd is started on demand and exits after 30 idle minutes. mesh-mcp run --standalone keeps everything in one process (containers, CI).
• The daemon follows its config. Edit mesh-mcp.toml and meshd applies it without a restart, at the cost of what changed: display-only keys swap over the running index, a changed custom pattern re-extracts only the files it applies to, anything else rebuilds the index from the parse cache. The old state keeps serving until the new one is ready (SETUP.md).
• Persistent parse cache. One SQLite file per workspace under ~/.cache/mesh-mcp/workspaces/, with a size quota and LRU eviction, so a restart or a branch switch back to known content does not re-parse it.
• Details: docs/architecture.md.

---

Languages and what is extracted

Verified against crates/mesh-parsers/src/languages/ at the time of writing: this lists what the extractors recognise, not how accurate they are on your code. Depth per language, with what each one does not get: docs/parser-support.md. "Declarations" means classes, interfaces, functions/methods and similar symbols usable by smart_search.

| Language | Declarations | Imports (find_dependents) | gRPC | Events / messaging | HTTP endpoints | | :--- | :---: | :---: | :--- | :--- | :--- | | Java | yes | yes | *ImplBase servers, @GrpcService, newBlockingStub/newStub/newFutureStub clients | @KafkaListener, KafkaTemplate | Spring MVC / JAX-RS annotations | | Go | yes | yes | Register*Server, New*Client | kafka-go, sarama, confluent-kafka-go | chi / gin / echo-style route calls | | Python | yes | yes | *Servicer servers, *_pb2_grpc.*Stub(...) clients | confluent_kafka, aiokafka, Celery | Flask / FastAPI routes (path and method) | | TypeScript / JavaScript (.ts, .mts, .cts, .tsx, .js, .jsx, .mjs, .cjs; script blocks of .vue, .svelte, .astro) | yes; CommonJS require and dynamic import() count as imports, tsconfig/jsconfig paths and package.json imports aliases are resolved | yes | NestJS @GrpcMethod, getService<...>() and the method calls on the client it returns (this.users.signUp(…)), imported new XClient(...) (ts-proto, @grpc/grpc-js) | Rule table gated on the file's imports and on the client it built: Kafka family (kafkajs, node-rdkafka, ...), Redis (pub/sub, streams, list queues), NATS, MQTT, RabbitMQ, BullMQ / Bull, SQS / SNS, Kinesis, EventBridge, Google Pub/Sub, Pulsar, Azure Service Bus, STOMP, NestJS microservices (@EventPattern, @MessagePattern, client.emit) | Express, Fastify, Koa, Hono, Elysia, h3, restify, polka, itty-router, hapi; NestJS, routing-controllers, tsoa, inversify controllers; file-system routers (Next.js, Remix / React Router, SvelteKit, Nuxt / Nitro, Astro); tRPC procedures and GraphQL operations | | Rust | yes | yes | tonic service implementations (servers only) | rdkafka | axum route, actix-web attribute macros | | C++ | yes | yes (quoted #include) | servers deriving ::grpc::Service | — | — | | Kotlin | yes | — | @GrpcService classes tagged; no clients | @KafkaListener, kafka-clients subscribe/send | Spring annotations | | C# | yes | — | — | Confluent.Kafka producers/consumers (string-literal topics) | ASP.NET attributes ([HttpGet]) | | Ruby, PHP, Swift, Scala | yes | — | — | — | Rails routes, Symfony / Laravel, Vapor, Akka HTTP (one idiom each) | | Protobuf | services, methods, messages | import | contract source of truth | — | — | | OpenA