Ts Graph MCP
No description available
Ask AI about Ts Graph MCP
Powered by Claude Β· Grounded in docs
I know everything about Ts Graph MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
ts-graph-mcp
A TypeScript code graph tool that extracts code structure into a queryable database, with MCP integration for AI coding agents.
What It Does
ts-graph parses TypeScript source code using AST analysis and builds a graph database of your codebase structure. The graph captures code symbols (functions, classes, interfaces, types, variables) and their relationships (calls, imports, type usage, inheritance).
Semantic search included. On first run, ts-graph downloads an embedding model (~300MB) and generates embeddings for all symbols. AI agents can search by concept ("user validation", "database queries") not just exact symbol names.
AI agents query the graph through the searchGraph MCP tool to:
- Find code by concept (semantic search)
- Traverse call graphs (who calls this? what does this call?)
- Find paths between symbols
Quick Start
1. Configuration
Create ts-graph-mcp.config.json in your project root:
{
"packages": [
{ "name": "main", "tsconfig": "./tsconfig.json" }
],
"server": {
"port": 4000
}
}
For monorepos, list multiple packages:
{
"packages": [
{ "name": "shared", "tsconfig": "./shared/tsconfig.json" },
{ "name": "frontend", "tsconfig": "./frontend/tsconfig.json" },
{ "name": "backend", "tsconfig": "./backend/tsconfig.json" }
],
"server": {
"port": 4000
}
}
2. Start the HTTP Server
npx ts-graph-mcp
The server indexes your project on first run and watches for changes.
3. Configure Claude Code
claude mcp add ts-graph-mcp -- npx -y ts-graph-mcp --mcp
Or manually in .mcp.json:
{
"mcpServers": {
"ts-graph-mcp": {
"command": "npx",
"args": ["-y", "ts-graph-mcp", "--mcp"]
}
}
}
Note: Start the HTTP server first. The MCP wrapper connects to it.
MCP Tool: searchGraph
Unified search combining semantic search with graph traversal.
Query Patterns
// Find code by concept (semantic search)
{ topic: "user authentication" }
// What does handleRequest call? (forward traversal)
{ from: { symbol: "handleRequest" } }
// Who calls saveUser? (backward traversal)
{ to: { symbol: "saveUser" } }
// How does A reach B? (path finding)
{ from: { symbol: "handleRequest" }, to: { symbol: "saveUser" } }
Parameters
| Parameter | Required | Description |
|---|---|---|
topic | No* | Standalone semantic search (not combinable with from/to) |
from | No* | Start point: { symbol } or { query } with optional file_path |
to | No* | End point: { symbol } or { query } with optional file_path |
max_nodes | No | Output limit (default: 50) |
*At least one of topic, from, or to is required. topic is standalone
only β it cannot be combined with from/to.
Example Output
## Symbols matching "validation" (semantic search)
validateInput (Function) - src/validation.ts [score: 0.847]
checkUserData (Function) - src/user.ts [score: 0.721]
## Graph
handleRequest --CALLS--> validate --CALLS--> saveUser
## Nodes
validate:
type: Function
file: src/service.ts
offset: 10, limit: 5
snippet:
10: export function validate(data: Input) {
> 11: return saveUser(data);
12: }
CLI Options
ts-graph-mcp # Start HTTP server
ts-graph-mcp --mcp # Start MCP stdio server
ts-graph-mcp --reindex # Force clean reindex
Configuration Reference
Required
| Field | Description |
|---|---|
packages | Array of { name, tsconfig } |
server.port | HTTP server port (no default) |
Optional
| Field | Description | Default |
|---|---|---|
embedding.preset | Embedding model | "nomic-embed-text-v1.5" |
storage.type | Database type | "sqlite" |
storage.path | Database file path | .ts-graph-mcp/graph.db |
watch.debounce | Enable debouncing | true |
watch.debounceInterval | Debounce delay (ms) | 300 |
watch.polling | Use polling (for Docker/WSL2) | false |
watch.pollingInterval | Polling interval (ms) | 1000 |
watch.excludeDirectories | Directories to skip | [] |
watch.silent | Suppress reindex logs | false |
Embedding Models
| Preset | Size | Dimensions | Notes |
|---|---|---|---|
nomic-embed-text-v1.5 | ~300MB | 768 | Default, fast and effective |
qwen3-0.6b | ~650MB | 1024 | Higher quality, slower |
qwen3-4b | ~4GB | 2560 | Highest quality, needs more RAM |
jina-embeddings-v2-base-code | ~300MB | 768 | Optimized for code |
Add .ts-graph-mcp/ to your .gitignore.
Yarn PnP Support
ts-graph works with Yarn 4 PnP monorepos. When .pnp.cjs is detected, module
resolution uses Yarn's PnP API.
Requirements:
- Use base package imports (
@libs/utils, not@libs/utils/date) - Declare dependencies with
workspace:*protocol
Supported Types
Nodes: Function, Class, Method, Interface, TypeAlias, Variable, SyntheticType, Feature, Spec, TestSuite, Test
Edges: CALLS, IMPLEMENTS, EXTENDS, TAKES, RETURNS, HAS_TYPE, HAS_PROPERTY, DERIVES_FROM, ALIAS_FOR, REFERENCES, INCLUDES, CONTAINS, SPECIFIES, VERIFIED_BY
Development
npm run check # Run tests, build, and lint
npm test # Run tests
npm run build # Compile TypeScript
Project Structure
ts-graph-mcp/
βββ http/ # HTTP server, database, ingestion, queries
βββ mcp/ # MCP stdio wrapper
βββ shared/ # Shared types
βββ ui/ # Web UI (React + Vite)
βββ main.ts # Entry point
Windows Users
This package uses better-sqlite3, which requires compilation tools:
- Install Visual Studio Build Tools with "Desktop development with C++"
- Install Python 3.x
- Use Node.js LTS
Contributing
See ARCHITECTURE.md for technical internals and CLAUDE.md for code style guidelines.
License
MIT
