mcp-server-ts-analysis

MCP server for TypeScript type resolution and dependency graph analysis. Uses ts-morph for type intelligence and madge for dependency graphs. Stdio transport.

Setup

1. Clone and build

git clone https://github.com/akshay-nm/mcp-server-ts-analysis.git
cd mcp-server-ts-analysis
npm install
npm run build

2. Add to Claude Code

Global (all projects) — add to ~/.claude.json:

{
  "mcpServers": {
    "ts-analysis": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-ts-analysis/dist/bin/cli.js"]
    }
  }
}

Per project — add to .mcp.json in the project root:

{
  "mcpServers": {
    "ts-analysis": {
      "type": "stdio",
      "command": "node",
      "args": ["./path/to/mcp-server-ts-analysis/dist/bin/cli.js"]
    }
  }
}

3. Restart Claude Code

The server will appear in your MCP server list. No startup config needed — all paths (tsconfig, source_root, etc.) are passed per tool call, so one server instance works across all your projects.

Other MCP clients

Any MCP client that supports stdio transport can use this server. Point it at dist/bin/cli.js with Node.js as the command.

Tools

Type analysis

Tool	Description
resolve_type	Fully computed type at a source position
hover_info	Quick info similar to VS Code hover (type, docs, JSDoc tags)
type_diagnostics	TypeScript errors and warnings, optionally scoped to a file

Common parameters:

• file — absolute path to the TypeScript file
• line — line number (1-based)
• col — column number (1-based)
• tsconfig — path to tsconfig.json (optional, uses default compiler options if omitted)

Dependency analysis

Tool	Description
dep_graph	Full dependency tree as JSON
reverse_deps	All files that import a given file
forward_deps	All files that a given file imports
circular_deps	All circular dependency chains
import_path	Shortest import chain between two files

Common parameters:

• source_root — source root directory to analyze (required)
• tsconfig — path to tsconfig.json (optional)
• exclude — directories to exclude (defaults to node_modules, dist, .git)
• exclude_patterns — regex patterns to exclude files (e.g. ["\\.d\\.ts$"] to skip declaration files)

dep_graph extras:

• entry — entry file to start traversal from (defaults to auto-detected root nodes)
• max_depth — max traversal depth from entry/root nodes (omit for full graph)

Examples

Resolve the type of a variable at line 10, column 7:

{
  "tool": "resolve_type",
  "args": {
    "file": "/home/user/project/src/server.ts",
    "line": 10,
    "col": 7,
    "tsconfig": "/home/user/project/tsconfig.json"
  }
}

Get the top-level module boundaries (depth 1) without .d.ts files:

{
  "tool": "dep_graph",
  "args": {
    "source_root": "/home/user/project/src",
    "tsconfig": "/home/user/project/tsconfig.json",
    "exclude_patterns": ["\\.d\\.ts$"],
    "max_depth": 1
  }
}

Find how auth.ts reaches database.ts through imports:

{
  "tool": "import_path",
  "args": {
    "fileA": "auth.ts",
    "fileB": "database.ts",
    "source_root": "/home/user/project/src"
  }
}

Architecture

src/
  index.ts          — MCP server, tool registration, stdio transport
  type-analysis.ts  — ts-morph type resolution (cached by tsconfig path)
  dep-analysis.ts   — madge dependency graph analysis
  types.ts          — shared interfaces
  madge.d.ts        — type declarations for madge
bin/
  cli.ts            — entry point

License

MIT