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:

  npm install -g @typescript/native-preview
  # or run without installing:
  npx @typescript/native-preview --version
  

Installation

go install github.com/paulvanbrenk/typescript-mcp/cmd/typescript-mcp@latest

Or build from source:

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):

{
  "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:

{
  "file": "/home/user/project/src/index.ts",
  "maxResults": 10
}

Example response:

{
  "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:

{
  "file": "/home/user/project/src/index.ts",
  "line": 10,
  "column": 15
}

Example response:

[
  {
    "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:

{
  "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:

{
  "file": "/home/user/project/src/utils.ts",
  "line": 3,
  "column": 17
}

Example response:

{
  "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:

{
  "file": "/home/user/project/src/utils.ts"
}

Example response:

[
  {
    "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:

{
  "file": "/home/user/project/src/store.ts",
  "line": 42,
  "column": 14,
  "newName": "repository"
}

Example response:

{
  "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:

{
  "cwd": "/home/user/project"
}

Example response:

{
  "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:

1. Edit a file (e.g., change a function signature)
2. Call ts_diagnostics with the file path to get errors
3. Fix the reported errors
4. Call ts_diagnostics again to confirm zero errors

Code exploration

Navigate unfamiliar code using symbols, hover, and go-to-definition:

1. Call ts_document_symbols to get an overview of a file's structure
2. Call ts_hover on an interesting symbol to see its type signature
3. Call ts_definition to jump to the symbol's source definition

Safe refactoring

Rename a symbol across the entire project in one step:

1. Call ts_rename with the symbol's location and the new name
2. Call ts_diagnostics on affected files to verify correctness

Or for manual refactoring, find all usages first:

1. Call ts_references on the symbol you want to change
2. Edit all returned locations
3. Call ts_diagnostics on 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

go build ./cmd/typescript-mcp

Test

go test ./...

Run locally

# 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.