Transcend

Docs: ldippo.github.io/transcend-mcp · Suite: transcend-harness

A code-intelligence MCP server for coding agents: a cheap static map of a repository (tree-sitter structural graph — clusters, hubs, budgeted subgraphs) plus precise live navigation (real language servers via LSP), bridged by stable symbol IDs. Every response is structured, token-budgeted, and anchored to file:line — never a raw file dump.

Languages: Python (pyright) and TypeScript/JavaScript (typescript-language-server). Adding a language = a tree-sitter grammar + .scm queries + an LSP command — no core changes.

Install & run

npm install
npm run build

# optional but recommended — without them the server runs map-only:
npm install -g pyright typescript-language-server typescript

node dist/src/index.js --root /path/to/repo        # stdio MCP server
node dist/src/index.js --root /path/to/repo --no-watch

On first run the server indexes the repo in the background (≈0.5s per 1k files) and persists the index under <repo>/.transcend/ (add it to .gitignore). A file watcher keeps the index fresh incrementally.

Wire into a harness

Any MCP-over-stdio harness works. Claude Code:

claude mcp add transcend -- node /path/to/transcend/dist/src/index.js --root /path/to/repo

Generic MCP config:

{
  "mcpServers": {
    "transcend": {
      "command": "node",
      "args": ["/path/to/transcend/dist/src/index.js", "--root", "/path/to/repo"]
    }
  }
}

Give the agent docs/AGENT_GUIDE.md — it documents the orient-with-map / confirm-with-LSP policy that the tool descriptions also encode.

Tool surface

All tools accept tokenBudget (default 2000, max 10000) and return a uniform envelope; see the agent guide.

Token savings

Every successful tool response is measured against the naive alternative — reading in full every file the response points into — and the delta is accumulated cumulatively in .transcend/metrics.json:

savings = baseline (full reads of referenced files) − actual (emitted tokens)

Baseline is an upper bound (an agent might not read whole files). View it three ways: the metrics_report tool (live, mid-session), a one-line stderr summary on shutdown, or the CLI report:

node dist/src/index.js report --root /path/to/repo          # per-tool table + total
node dist/src/index.js report --root /path/to/repo --json   # raw JSON

Development

npm test          # unit + integration (LSP tests auto-skip if servers absent)
npm run smoke     # build + scripted MCP client against the TS fixture
npx @modelcontextprotocol/inspector node dist/src/index.js --root test/fixtures/ts-mini

Architecture notes: docs/ARCHITECTURE.md.

No telemetry. No network calls. Secrets are never read; configuration is CLI flags only.