mcp-server-ts-analysis

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