typescript-mcp
TypeScript type checking and code navigation for AI coding agents, powered by tsgo.
Architecture```
Coding Agent (Claude Code, etc.)
| MCP (stdio)
typescript-mcp (Go)
| LSP JSON-RPC (stdio)
tsgo (TypeScript 7, native Go compiler)
`typescript-mcp` is a Go MCP server that bridges
Model Context Protocol tool calls to
tsgo's built-in LSP
server. It gives coding agents real TypeScript type checking and code navigation
without relying on regex or heuristics.
The server spawns `tsgo --lsp --stdio` as a child process, communicates over
JSON-RPC, and translates LSP responses into concise, agent-friendly JSON.
## Prerequisites
- **Go 1.24+**
- **tsgo** -- install globally or use npx:```bash
npm install -g @typescript/native-preview
# or run without installing:
npx @typescript/native-preview --version
```
## Installation```bash
go install github.com/paulvanbrenk/typescript-mcp/cmd/typescript-mcp@latest
Or build from source:```bash
git clone https://github.com/paulvanbrenk/typescript-mcp.git
cd typescript-mcp
go build -o typescript-mcp ./cmd/typescript-mcp
## Configuration for Claude Code
Add the following to your MCP configuration (`.mcp.json` or Claude Code settings):```json
{
"mcpServers": {
"typescript": {
"command": "typescript-mcp",
"args": []
}
}
}
If typescript-mcp is not on your PATH, use the full path to the binary.
Tools Reference
Line and column numbers are 1-based.
ts_diagnostics
Get TypeScript errors and warnings for a file.
| Parameter | Type | Required | Description |
|---|---|---|---|
file |
string | yes | Absolute path to check a single file |
tsconfig |
string | no | Path to tsconfig.json (auto-detected if omitted) |
maxResults |
number | no | Maximum errors to return (default 50) |
Example request:```json
{
"file": "/home/user/project/src/index.ts",
"maxResults": 10
}
**Example response:**```json
{
"diagnostics": [
{
"file": "/home/user/project/src/index.ts",
"line": 12,
"column": 5,
"severity": "error",
"code": 2322,
"message": "Type 'string' is not assignable to type 'number'."
}
],
"totalCount": 1,
"truncated": false
}
ts_definition
Go to the definition of a symbol. Returns the file and position where the symbol
is defined, with a preview of the source line.
| Parameter | Type | Required | Description |
|---|---|---|---|
file |
string | yes | Absolute file path |
line |
number | yes | Line number (1-based) |
column |
number | yes | Column number (1-based) |
tsconfig |
string | no | Path to tsconfig.json |
Example request:```json
{
"file": "/home/user/project/src/index.ts",
"line": 10,
"column": 15
}
**Example response:**```json
[
{
"file": "/home/user/project/src/utils.ts",
"line": 3,
"column": 17,
"preview": "export function formatDate(date: Date): string {"
}
]
ts_hover
Get type information and documentation for a symbol at a position. Returns the
resolved type signature.
| Parameter | Type | Required | Description |
|---|---|---|---|
file |
string | yes | Absolute file path |
line |
number | yes | Line number (1-based) |
column |
number | yes | Column number (1-based) |
tsconfig |
string | no | Path to tsconfig.json |
Example request:```json
{
"file": "/home/user/project/src/index.ts",
"line": 5,
"column": 10
}
**Example response (plain text):**```
(property) AppConfig.port: number
The response is the extracted type signature from the hover content. Markdown
code fences are stripped to return just the type information.
ts_references
Find all references to a symbol across the project. Returns every location where
the symbol is used, including the declaration.
| Parameter | Type | Required | Description |
|---|---|---|---|
file |
string | yes | Absolute file path |
line |
number | yes | Line number (1-based) |
column |
number | yes | Column number (1-based) |
maxResults |
number | no | Maximum references to return (default 50) |
tsconfig |
string | no | Path to tsconfig.json |
Example request:```json
{
"file": "/home/user/project/src/utils.ts",
"line": 3,
"column": 17
}
**Example response:**```json
{
"references": [
{
"file": "/home/user/project/src/utils.ts",
"line": 3,
"column": 17,
"preview": "export function formatDate(date: Date): string {"
},
{
"file": "/home/user/project/src/index.ts",
"line": 10,
"column": 15,
"preview": "const result = formatDate(new Date());"
}
],
"totalCount": 2,
"truncated": false
}
ts_document_symbols
Get the symbol outline of a file. Returns a tree of all functions, classes,
interfaces, and variables with their types.
| Parameter | Type | Required | Description |
|---|---|---|---|
file |
string | yes | Absolute file path |
tsconfig |
string | no | Path to tsconfig.json |
Example request:```json
{
"file": "/home/user/project/src/utils.ts"
}
**Example response:**```json
[
{
"name": "formatDate",
"kind": "function",
"line": 3,
"detail": "(date: Date) => string"
},
{
"name": "AppConfig",
"kind": "interface",
"line": 8,
"children": [
{
"name": "port",
"kind": "property",
"line": 9,
"detail": "number"
},
{
"name": "host",
"kind": "property",
"line": 10,
"detail": "string"
}
]
}
]
ts_rename
Rename a symbol across the project. This tool writes to disk — all files
containing the symbol are updated atomically (with rollback on failure). The LSP
is re-synced after edits are applied.
| Parameter | Type | Required | Description |
|---|---|---|---|
file |
string | yes | Absolute file path |
line |
number | yes | Line number (1-based) |
column |
number | yes | Column number (1-based) |
newName |
string | yes | New name for the symbol |
tsconfig |
string | no | Path to tsconfig.json |
Example request:```json
{
"file": "/home/user/project/src/store.ts",
"line": 42,
"column": 14,
"newName": "repository"
}
**Example response:**```json
{
"newName": "repository",
"totalEdits": 9,
"changes": [
{
"file": "/home/user/project/src/actions.ts",
"edits": 8,
"preview": "import { repository } from '@/lib/store';"
},
{
"file": "/home/user/project/src/store.ts",
"edits": 1,
"preview": "export const repository = new Store();"
}
]
}
ts_project_info
Get TypeScript project configuration info. Returns the tsconfig path and project
root directory.
| Parameter | Type | Required | Description |
|---|---|---|---|
tsconfig |
string | no | Path to tsconfig.json |
cwd |
string | no | Working directory for tsconfig discovery |
Example request:```json
{
"cwd": "/home/user/project"
}
**Example response:**```json
{
"tsconfigPath": "/home/user/project/tsconfig.json",
"projectRoot": "/home/user/project"
}
Workflow Examples
Edit-check-fix cycle
After editing TypeScript files, use ts_diagnostics to check for type errors,
fix them, and verify again:
- Edit a file (e.g., change a function signature)
- Call
ts_diagnosticswith the file path to get errors - Fix the reported errors
- Call
ts_diagnosticsagain to confirm zero errors
Code exploration
Navigate unfamiliar code using symbols, hover, and go-to-definition:
- Call
ts_document_symbolsto get an overview of a file's structure - Call
ts_hoveron an interesting symbol to see its type signature - Call
ts_definitionto jump to the symbol's source definition
Safe refactoring
Rename a symbol across the entire project in one step:
- Call
ts_renamewith the symbol's location and the new name - Call
ts_diagnosticson affected files to verify correctness
Or for manual refactoring, find all usages first:
- Call
ts_referenceson the symbol you want to change - Edit all returned locations
- Call
ts_diagnosticson affected files to verify correctness
Environment Variables
| Variable | Description |
|---|---|
TYPESCRIPT_MCP_DEBUG |
Set to 1 to enable verbose debug logging (uses zap development logger) |
Development
Build```bash
go build ./cmd/typescript-mcp
### Test```bash
go test ./...
Run locally```bash
Ensure tsgo is available
tsgo --version
Run the MCP server (communicates over stdio)
./typescript-mcp
### Project structure```
cmd/typescript-mcp/ Entry point and MCP server setup
internal/
lsp/ LSP client and tsgo process management
client.go JSON-RPC connection, LSP method wrappers
process.go tsgo process lifecycle (spawn, stop, resolve)
docsync/ Document synchronization with the LSP server
sync.go Open/change/close notifications
uri.go File path <-> URI conversion
tools/ MCP tool handlers
tools.go Tool registration (schemas and descriptions)
diagnostics.go ts_diagnostics handler
definition.go ts_definition handler
hover.go ts_hover handler
references.go ts_references handler
rename.go ts_rename handler (write tool)
symbols.go ts_document_symbols handler
project.go ts_project_info handler
util.go Shared utilities (readLine)
cmd/test-client/ CLI for manual testing against real projects
License
See LICENSE for details.
