tsserver-mcp-server
by Chia1104
README.md
# 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.
TDQS
A3.6/5.0
Scored across 7 tools
Disambiguation5/5
Each tool targets a distinct IDE feature: completions, definition, type definition, hover info, diagnostics, signature help, and references. There is no overlap in their purposes.
Naming Consistency5/5
All tool names follow the get_verb_noun pattern, making them predictable and consistent. The naming convention is uniform throughout.
Tool Count5/5
Seven tools is a well-scoped count for a language server toolkit, covering the core navigation and diagnostic features without being excessive.
Completeness4/5
The set covers most common language server operations (navigation, hover, diagnostics, references), but misses features like rename or code actions. These gaps are minor and agents can work around them.