# ts-mcp

MCP server providing AI-invocable tools for semantic navigation of TypeScript and JavaScript source files. Addresses code by name (via the TypeScript compiler AST) rather than by line number or raw string, making it practical to locate and read specific declarations in large files without loading the entire file.

## Tools

### `ts-symbols`

List all named declarations in a file.

**Parameters:**
- `filename` — absolute path to a `.ts`, `.tsx`, `.js`, or `.jsx` file
- `exported_only` — (optional, default `false`) when true, omit unexported symbols

**Returns:** array of symbol objects with `name`, `kind`, `className` (for methods/properties), `exported`, `startLine`, `endLine`.

Kinds: `function`, `class`, `interface`, `type`, `enum`, `const`, `let`, `method`, `property`.

Use this first to orient in a file, then call `ts-read` with the name you need.

### `ts-read`

Return the full source text of a named declaration including its leading JSDoc comment.

**Parameters:**
- `filename` — absolute path to a `.ts`, `.tsx`, `.js`, or `.jsx` file
- `name` — declaration name, or `ClassName.methodName` for class methods

**Returns:** object with `name`, `kind`, `source` (full text), and `overloaded` (true when the function has multiple overload signatures — in that case `source` includes all signatures plus the implementation body).

### `ts-imports`

Return all import declarations as structured data.

**Parameters:**
- `filename` — absolute path to a `.ts`, `.tsx`, `.js`, or `.jsx` file

**Returns:** array of import objects with `moduleSpecifier`, `defaultImport`, `namedImports`, `namespaceImport`, `isTypeOnly`, `line`.

### `ts-replace`

Replace a named declaration with new source text. Writes atomically (temp file + rename).

**Parameters:**
- `filename` — absolute path to a `.ts`, `.tsx`, `.js`, or `.jsx` file
- `name` — declaration name, or `ClassName.methodName` for class methods
- `source` — complete replacement declaration text (include JSDoc if it should be preserved)
- `allow_kind_change` — (optional, default `false`) when true, allow replacing with a declaration of a different kind

**Returns:** object with `message` and `linesChanged`. Returns an error (file untouched) when the name is not found, the kind does not match, or an unexpected error occurs.

For overloaded functions, `source` must include all overload signatures plus the implementation body. The entire group is replaced atomically.

### `ts-diagnostics`

Run TypeScript type-checking on a file and return structured diagnostics.

**Parameters:**
- `filename` — absolute path to a `.ts`, `.tsx`, `.js`, or `.jsx` file

**Returns:** object with `diagnostics` (array), `tsconfig` (path used or `null` if none found), and `message`.

Each diagnostic has `file`, `line`, `column`, `code`, `category` (`"error"`, `"warning"`, or `"suggestion"`), and `message`.

Walks up the directory tree from `filename` to find the nearest `tsconfig.json`. Falls back to permissive defaults if none is found. Always excludes errors from `node_modules`.

## Build

Requires Docker and Make.

```sh
make install   # install npm dependencies
make compile   # compile TypeScript
make test      # run unit tests
make clean     # remove build artifacts
```

## Usage

Run the server directly:

```sh
node dist/index.js
```

Or install globally via npm:

```sh
npm install -g .
ts-mcp
```

The server communicates over stdio using the MCP JSON-RPC protocol. Configure it in your MCP client (e.g., Claude Code's `claude_desktop_config.json` or `.claude/mcp.json`) as a stdio server.