ts-mcp

MCP server that gives AI agents IDE-level TypeScript navigation. Structural queries like file structure, call chains, and impact analysis in a single call — instead of chained grep/read cycles.

Quick Start

npx ts-mcp --init

This sets up everything in your project:

• .claude/rules/ts-mcp-settings.md — agent tool selection guide
• .mcp.json — MCP server configuration

That's it. Your agent now has access to 13 TypeScript navigation tools.

Manual Setup

Add to your MCP configuration (.mcp.json or ~/.claude/mcp.json):

{
  "mcpServers": {
    "ts-mcp": {
      "command": "npx",
      "args": ["ts-mcp", "--workspace", "/path/to/your/project"]
    }
  }
}

When to Use

ts-mcp is not a replacement for Grep. It's a complement.

| Task | Best tool | Why | |------|-----------|-----| | Find where UserService is defined | Grep | Simple text match | | Find implements IRepository | Grep | Text pattern | | Understand what's in a 5000-line file | document_symbols | One call vs chunked reads | | Who calls processPayment? | call_hierarchy | Structured caller data | | What breaks if I rename userId? | impact_analysis | Reference count + risk level | | What type is this variable? | get_type_info | Resolved type + JSDoc |

Rule of thumb: Grep for "where is X?", ts-mcp for "what is X / what depends on X?"

Tools

Navigation

| Tool | Description | |------|-------------| | goto_definition | Jump to where a symbol is defined (need position) | | goto_type_definition | Jump to the type's source, not the variable | | find_references | Find all locations where a symbol is referenced | | workspace_symbols | Find declarations by exact name (case-insensitive) | | document_symbols | List all top-level symbols in a file |

Structural Analysis

| Tool | Description | |------|-------------| | call_hierarchy | Trace callers (incoming) or callees (outgoing) | | type_hierarchy | Find all implementations / subclasses | | impact_analysis | Assess blast radius before modifying a symbol |

Code Intelligence

| Tool | Description | |------|-------------| | get_type_info | Resolved type, docs, JSDoc tags (including @ts-mcp-*) | | signature_help | Parameter names, types, overloads for a function call | | rename_symbol | Compute all edits needed for a safe rename | | list_members | List properties and methods of a type |

Diagnostics

| Tool | Description | |------|-------------| | diagnostics | TypeScript errors and warnings |

Custom TSDoc Tags

Embed agent-readable metadata in your source code with @ts-mcp-* tags:

/**
 * @ts-mcp-context Requires authenticated session
 * @ts-mcp-related validateToken, refreshSession
 * @ts-mcp-risk Modifies user state — call impact_analysis before changing
 */
export function updateProfile(userId: string, data: ProfileData) { ... }

When an agent calls get_type_info on this function, the tags appear in the customTags field automatically. No extra tool calls needed.

Define whatever tags make sense for your project (@ts-mcp-owner, @ts-mcp-layer, etc.).

Multi-Project Support

ts-mcp auto-discovers tsconfig.json files up to 3 levels deep. Each gets its own language service — tools route to the correct project by file path.

To specify projects explicitly:

ts-mcp --workspace /path/to/monorepo \
       --projects /path/to/packages/app/tsconfig.json,/path/to/packages/shared/tsconfig.json

CLI Options

| Flag | Description | Default | |------|-------------|---------| | --workspace <path> | TypeScript project root | cwd | | --projects <paths> | Comma-separated tsconfig.json paths | auto-discover | | --no-cache | Bypass symbol index disk cache | false | | --watch | Watch for file changes | false | | --init | Generate agent config files | — |

Prerequisites

• Node.js 22+
• TypeScript project with tsconfig.json

Development

pnpm install
pnpm build        # Build with tsup
pnpm test         # Run tests with Vitest
pnpm dev          # Run with tsx (development)

License

MIT