# tsserver-mcp-server

> ⚠️ Early development: this project is in an early stage and currently supports **only a single TypeScript project** at a time.

An MCP (Model Context Protocol) server built on the TypeScript Language Service. It exposes tools for completions, go-to-definition, type info, diagnostics, and more for use by AI or IDE clients.

## Install dependencies

```bash
bun install
```

## Run

```bash
bun serve
```

Runs in stdio mode for MCP client connections.

## Tools

| Tool | Description |
|------|-------------|
| `get_completions` | Get completion suggestions at the cursor position |
| `get_definition` | Get the definition location of a symbol (Go to Definition) |
| `get_type_definition` | Get the definition location of a type |
| `get_quick_info` | Get type and documentation at the cursor (Hover) |
| `get_signature_help` | Get signature help (parameter hints) at a function call |
| `get_references` | Get all reference locations of a symbol (Find References) |
| `get_diagnostics` | Get syntactic and semantic diagnostics (errors/warnings) for a file |

## Input parameters (shared by most tools)

- **filePath**: File path (absolute or relative to project root)
- **fileContent**: File content (TypeScript/JavaScript source code)
- **line** / **offset**: Cursor line and column (1-based)
- **projectPath** (optional): Project root directory (the one that contains `node_modules` / `tsconfig`). When set, the server reads other project files from disk so that imports (e.g. `zod`), go-to-definition, and find-references work across the project. If omitted, only the in-memory `fileContent` is used.

## Cursor MCP configuration example

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "tsserver": {
      "command": "bun",
      "args": ["run", "/path/to/tsserver-mcp-server/index.ts"]
    }
  }
}
```

Replace `/path/to/tsserver-mcp-server` with the actual path to this project.

## Technical notes

- Uses TypeScript’s built-in `ts.createLanguageService`; does not depend on a separate tsserver process.
- **Project mode**: Pass `projectPath` (your repo root) so the host reads from disk. Then `node_modules`, cross-file definitions, and references work.
- **Single-file mode**: Omit `projectPath` (or only pass `filePath` + `fileContent`) to analyze one file in isolation without disk access.