ts-mcp-server: Instructions file for Codex

ts-mcp-server Codebase Instructions

Philosophy

This is a pure MCP server that wraps TypeScript's tsserver protocol. The core principles are:

1. Zero Custom Logic

• No custom types — All types are imported directly from typescript (ts.server.protocol.*)
• No wrappers — User input is passed directly to tsserver commands with no transformation
• No heuristics — No regex, path resolution tricks, or "smart" behavior
• No output formatting — Raw tsserver responses are returned as-is, serialized to JSON

2. One Tool Per tsserver Command

• Each tool maps 1:1 to a single tsserver protocol command
• Tool names must match the exact CommandTypes string value from the tsserver protocol (e.g., references, completionInfo, getCodeFixes)
• Never combine multiple tsserver commands into a single "convenience" tool

3. Raw Output

Every tool returns the exact response from tsserver:

return {
  content: [{ type: "text", text: JSON.stringify(body) }],
};

Never:

• Filter, group, sort, or truncate the response
• Add custom fields or metadata
• Format or pretty-print beyond JSON.stringify
• Trim whitespace or normalize paths

4. Minimal Shared Infrastructure

The only shared code is in tsserver.ts:

• send<T, A>() — Send a command to tsserver and await the response
• open(file) — Open a file in tsserver's project
• writeEdits(edits) — Apply file edits to disk and reload
• applyRefactor(opts, preview) — Shared helper for refactor tools only

Tool Definitions (MCP Best Practices)

Follow the Model Context Protocol specification and MCP tool best practices for all tool definitions.

Tool Name (name)

• Unique identifier for the tool
• Naming rules depend on whether the tool is read-only or an edit tool

Read-Only Tools

For tools that only query/read (no preview parameter, readOnlyHint: true):