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.

Related MCP server: @aiready/ast-mcp-server

Build

Requires Docker and Make.

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

Usage

Run the server directly:

node dist/index.js

Or install globally via npm:

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.