ts-mcp-server：让AI助手精准调用TypeScript编译器实现可靠重构-平芜编程栈

1. 项目概述：当AI助手遇上TypeScript的“大脑”

如果你和我一样，日常开发重度依赖TypeScript，同时又在尝试各种AI编程助手（Claude、Cursor、Copilot），那你肯定遇到过这个痛点：AI能帮你写代码片段，但一旦涉及到跨文件的结构化重构，比如重命名一个被多处引用的函数、把一个组件挪到新文件夹、或者提取一段通用逻辑，AI就很容易“翻车”。它可能会漏改某个import路径，或者没更新某个深层嵌套的引用，结果就是编译错误或者运行时bug。这种“牵一发而动全身”的改动，对AI来说是个巨大的挑战，因为它缺乏对整个项目类型系统和模块依赖的全局、精确理解。

这正是ts-mcp-server要解决的核心问题。简单来说，它是一个基于Model Context Protocol的服务器，但它不自己“思考”如何重构代码。它的设计哲学非常聪明：直接让AI助手调用TypeScript编译器自己的“大脑”——tsserver。tsserver是什么？它就是VS Code、WebStorm这些IDE背后，为你提供代码补全、错误检查、跳转定义、重构等所有智能功能的语言服务。ts-mcp-server充当了一个“翻译官”和“接线员”的角色，将AI助手的自然语言指令，翻译成tsserver能理解的协议命令，再把tsserver返回的、绝对精确的修改方案原封不动地交给AI去执行。

这意味着，当你通过Claude或Cursor告诉它“把formatUser函数改名为formatUserProfile”时，AI不再需要自己去猜测和搜索，而是通过ts-mcp-server向tsserver发起一个rename请求。tsserver会基于完整的类型信息和项目引用图，计算出所有需要修改的位置（包括定义、调用、导入导出），并生成一个包含具体文件、行号、偏移量和替换文本的编辑操作列表。AI助手要做的，只是按这个列表去应用修改。准确率是100%的，因为这是TypeScript编译器自己算出来的。

所以，ts-mcp-server的价值在于，它把AI助手的“创意”和“意图”与TypeScript编译器的“精确”和“权威”无缝连接了起来。它不是为了替代现有的IDE工具链，而是为了增强AI助手在复杂代码操作上的可靠性和能力边界，让你能更放心地把大型重构任务交给AI去完成。

2. 核心设计思路与架构解析

2.1 为什么是MCP？协议的力量

要理解ts-mcp-server，必须先理解Model Context Protocol。你可以把MCP想象成AI世界里的“USB协议”。在没有统一协议之前，每个AI应用（Claude Desktop、Cursor、Windsurf）想要连接外部工具（如文件系统、数据库、编译器），都需要自己实现一套复杂的集成逻辑，这导致了大量的重复工作和兼容性问题。

MCP定义了一套标准化的通信方式，让工具提供者（比如ts-mcp-server）可以一次开发，到处运行。只要一个AI客户端支持MCP，它就能自动发现、加载并使用所有遵循MCP协议的工具服务器。ts-mcp-server正是这样一个“工具提供者”，它通过MCP向AI客户端暴露了40个与TypeScript代码操作相关的“工具”（Tools）。

这些工具不是魔法，每一个都严格对应着tsserver协议中的一个命令。这种1:1映射的设计是项目最核心的架构决策，它带来了几个关键优势：

零信息损耗：AI客户端得到的是tsserver的原生响应，没有经过任何二次加工、过滤或格式化，保证了信息的完整性和准确性。
极致的稳定性：ts-mcp-server自身的逻辑非常薄，几乎就是一个协议转发层。所有的复杂逻辑（类型推断、引用分析、路径解析）都交给了久经考验的tsserver，极大降低了bug出现的概率。
与IDE行为一致：你在VS Code里通过右键菜单执行的“重命名符号”，底层调用的就是同一个tsserver命令。这意味着通过ts-mcp-server执行的重构，其结果与你在IDE中手动操作的结果是完全一致的，消除了行为不一致的困惑。

2.2 核心工作流程拆解

让我们深入看看，当你通过AI客户端发起一个重构请求时，数据是如何流动的：

用户意图 -> AI客户端：你在聊天窗口输入：“帮我把src/utils/date.ts文件里的formatDate函数改名为formatTimestamp。”
AI客户端 -> ts-mcp-server：AI客户端（如Claude）理解你的意图后，它不会自己去写正则表达式匹配代码，而是通过MCP协议，调用ts-mcp-server提供的rename工具，并附上参数：file=“src/utils/date.ts”,line=...,offset=...,newName=“formatTimestamp”。
ts-mcp-server -> tsserver：ts-mcp-server收到请求，通过Node.js的IPC（进程间通信）与一个独立的tsserver进程建立连接。它将参数组装成tsserver协议规定的JSON-RPC格式，发送rename请求。
tsserver -> ts-mcp-server：tsserver加载项目，分析类型，找到所有formatDate的引用，生成一个TextChange数组。这个数组详细描述了在哪个文件的哪一行哪一列，需要将哪段文本替换成什么。然后它把这个原生响应返回给ts-mcp-server。
ts-mcp-server -> AI客户端：ts-mcp-server不做任何处理，直接将这个TextChange数组包装成MCP约定的格式，返回给AI客户端。
AI客户端 -> 文件系统：AI客户端拿到这个精确的编辑列表，在内存中或直接对磁盘文件执行这些文本替换操作。最后，它可能会在聊天窗口告诉你：“已完成重命名，共修改了5个文件。”

整个过程中，ts-mcp-server就像一个无比可靠的邮差，只负责准确传递消息，绝不篡改内容。所有的“智能”都来自于两端的tsserver和 AI 模型。

2.3 与现有AI编码插件的本质区别

你可能会问，VS Code Copilot 和 Cursor 本身不就有代码补全和重构建议吗？为什么还需要这个？

这里的关键区别在于操作权限和上下文范围。以 Copilot Chat 为例，它运行在 VS Code 扩展的沙盒环境中，虽然能访问当前打开的文件，但其重构操作（如重命名）通常是通过调用 VS Code 自己的命令来实现的。这没问题，但它的能力被限制在了单个 IDE 实例内。

而ts-mcp-server通过 MCP 暴露了一个标准化、跨客户端的 API 接口。这意味着：

独立性：它不依赖任何特定 IDE 的 API，只要客户端支持 MCP，就能使用。
深度集成：AI 模型可以将这些工具作为“思考”的一部分，在生成回答的中间步骤中调用它们来获取精确信息（例如，“这个函数被哪些地方调用了？” -> 调用references工具），然后再基于这些信息生成最终建议或直接执行修改。
批处理与组合：AI 可以灵活地组合多个工具。例如，先extractFunction提取一个函数，然后立即用rename给它起个好名字，再moveSymbol把它移到共享工具库中。这是一个连贯的、由 AI 驱动的重构工作流。

简言之，现有的 AI 插件是“增强型编辑器”，而ts-mcp-server是“AI 的专用编译器工具包”，让 AI 在代码操作上拥有了与 IDE 同等级别、甚至更灵活的精确控制能力。

3. 环境配置与工具链集成实战

3.1 安装与基础配置

ts-mcp-server的安装简单到极致，因为它是一个命令行工具，通过 npm 分发。你不需要全局安装，推荐使用npx按需运行，这能保证你总是使用最新版本。

# 最简运行方式，会在当前目录启动服务器 npx ts-mcp-server

运行后，它会启动一个 MCP 服务器进程，默认通过 stdio（标准输入输出）与调用它的客户端通信。但通常我们不会手动在命令行运行它，而是将其配置到你的 AI 客户端中，让客户端在需要时自动启动它。

配置的核心是在你的 AI 客户端配置文件中，声明这个 MCP 服务器。以下是主流客户端的配置方法：

VS Code (搭配 Continue 插件或其他 MCP 客户端扩展):在项目根目录或用户全局配置中创建或编辑.vscode/mcp.json：

{ "servers": { "ts-mcp-server": { "command": "npx", "args": ["ts-mcp-server"], "env": { // 可选：禁用不需要的工具 // "todoComments": "false", // "getOutliningSpans": "false" } } } }

Claude Desktop:找到 Claude Desktop 的配置目录（macOS:~/Library/Application Support/Claude， Windows:%APPDATA%\Claude），编辑claude_desktop_config.json：

{ "mcpServers": { "ts-mcp-server": { "command": "npx", "args": ["ts-mcp-server"], "env": { // 可选环境变量配置 } } } }

Cursor:Cursor 内置了 MCP 支持。你可以在 Cursor 的设置中搜索 “MCP”，或在其配置文件（如cursor.json）中添加类似配置，具体格式请参考 Cursor 官方文档。

配置完成后，重启你的 AI 客户端。客户端会自动发现并加载ts-mcp-server。你通常可以在客户端的 UI 中看到已加载的工具列表，或者在聊天中尝试输入相关指令来触发工具调用。

3.2 项目发现与多项目工作区

一个非常出色的设计是ts-mcp-server的自动项目发现机制。你不需要在配置里指定tsconfig.json的路径。它是如何工作的？

启动与上下文：当 AI 客户端通过 MCP 调用一个工具（例如rename）时，会附带一个工作目录（通常是当前聊天界面所在的项目根目录）。
向上查找：ts-mcp-server会从这个工作目录开始，向上级目录查找tsconfig.json或jsconfig.json文件。
启动 tsserver：找到配置文件后，它会用这个配置文件的路径作为项目根目录，启动一个tsserver进程。这个tsserver进程就拥有了对整个项目的完整视图。
多项目支持：对于 Monorepo 或使用了 TypeScript 项目引用（Project References）的复杂工程，tsserver本身就能处理这种关系。ts-mcp-server只需将请求转发给正确的tsserver实例（通常是根据请求的文件路径来路由）。这意味着你在一个子项目里执行重构，它能自动处理好跨项目的引用更新。

实操心得：配置文件的优先级有时候项目里可能有多个tsconfig.json（比如tsconfig.json和tsconfig.app.json）。tsserver的标准行为是，当你请求一个特定文件时，它会找到管理该文件的最近层级的tsconfig.json。为了确保ts-mcp-server的行为符合你的预期，最好在项目根目录通过tsconfig.json的references或extends来明确项目结构。如果遇到工具行为异常，首先检查当前工作目录下ts-mcp-server实际加载的是哪个配置文件。

3.3 工具的精简与禁用

ts-mcp-server默认启用了全部 40 个工具。但在某些场景下，你可能希望禁用一部分。例如：

减少干扰：todoComments工具会返回文件中的所有 TODO 注释，如果你不常需要AI来管理TODO，可以禁用它。
性能考量：某些工具在超大项目上可能有性能开销（虽然很小），你可以选择性地禁用。
安全/隐私：在严格的环境中，你可能不希望AI能通过navto搜索所有符号。

禁用工具非常简单，只需在客户端的 MCP 配置的env字段中，将工具名设置为"false"。

{ "servers": { "ts-mcp-server": { "command": "npx", "args": ["ts-mcp-server"], "env": { "todoComments": "false", "getOutliningSpans": "false", "docCommentTemplate": "false", "navto": "false" // 禁用全局符号搜索 } } } }

重要提示：工具名必须严格匹配文档中的名称（小写，驼峰命名）。只有显式设置为"false"的才会被禁用，省略或设置为其他值（如"true",0）都意味着启用。

4. 核心重构工具深度解析与应用场景

ts-mcp-server的 40 个工具可以大致分为重构和代码智能两大类。我们先深入看看那些能直接改变代码结构的重构工具，它们也是AI助手最能发挥价值的地方。

4.1 基石操作：重命名与移动

rename和renameFileOrDirectory是两个最常用、也最体现价值的工具。

rename工具详解：这个工具处理的是符号（Symbol）重命名。什么是符号？变量、函数、类、接口、类型别名、枚举、模块别名等等。它的强大之处在于跨文件的引用更新。

工作流程示例：假设我们有一个工具函数calculateDiscount(price: number, rate: number): number，在项目的 3 个不同文件中被调用和导入。

AI 客户端调用：rename file=“src/utils/price.ts” line=10 offset=5 newName=“calculateFinalPrice”
tsserver会做以下事情：
- 找到calculateDiscount的定义位置。
- 通过类型系统和导入导出关系，构建出该符号的完整引用图。
- 生成一个编辑列表，内容包括：
  - 修改定义处的函数名。
  - 修改所有调用处的函数名。
  - 如果该函数被导出，修改所有导入语句中的引用名（例如import { calculateDiscount } from ‘./utils/price‘->import { calculateFinalPrice } from ‘./utils/price‘）。
  - 甚至更新 JSDoc/TSDoc 中对该函数的引用（如果注释中写了函数名）。
返回这个包含所有修改的列表。

renameFileOrDirectory工具详解：重命名或移动文件/文件夹，并自动更新所有导入路径。这是手动操作中最容易出错的地方之一。

场景：你想把src/components/Button.tsx移动到src/components/ui/Button.tsx。

AI 客户端调用：renameFileOrDirectory from=“src/components/Button.tsx” to=“src/components/ui/Button.tsx”
tsserver会：
- 扫描整个项目，找到所有导入‘./Button‘或‘../components/Button‘的语句。
- 根据新的相对路径，计算出每个导入语句应该更新成什么样子（例如‘./Button‘->‘./ui/Button‘）。
- 生成更新这些导入语句的编辑。
- 注意：它只更新导入语句，不移动文件本身。移动文件的操作通常由AI客户端或用户根据工具返回的“建议”来执行。这是一种“预览-确认”的安全模式。

注意事项：路径解析的陷阱工具使用相对路径进行计算。确保你提供的from和to参数是相对于当前工作目录的正确路径。如果路径错误，tsserver可能找不到文件，或者计算出错误的更新路径。在复杂项目（如符号链接、Monorepo）中，建议先使用绝对路径进行测试。另外，对于目录移动，它只能更新对该目录内文件的引用，无法更新对该目录本身的引用（因为这在TypeScript中通常不是直接引用的）。

4.2 代码提取与内联：提升代码质量

这组工具帮助你将代码块转化为更可复用的结构，或反之简化结构。

extractFunction/extractConstant/extractType：这三个工具逻辑相似：你选中一段代码（表达式或类型注解），工具将其提取成一个独立的声明（函数、常量、类型别名）。

以extractFunction为例的深层解析：假设你有一段重复的订单金额格式化代码散落在多处。

// 在文件A const displayAmount = `$${(amount * taxRate).toFixed(2)}`; // 在文件B console.log(`Total: $${(cartTotal * taxRate).toFixed(2)}`);

AI 选中(amount * taxRate).toFixed(2)这个表达式。
调用extractFunction，参数需要精确的起止行列号。
tsserver会分析这段代码：
- 识别依赖：发现amount和taxRate是外部变量，它们将成为新函数的参数。
- 推断返回类型：分析表达式(amount * taxRate).toFixed(2)，推断出返回类型为string。
- 生成函数：创建一个新函数，如function newFunction(amount: number, taxRate: number): string { return (amount * taxRate).toFixed(2); }。
- 替换原处：用newFunction(amount, taxRate)替换选中的代码。
- 提供重命名点：在响应中，会包含新生成函数名的位置信息，方便你紧接着调用rename工具将其改为formatTaxedAmount。

inlineVariable：与提取相反。如果一个变量只被使用了一次，或者其存在反而让代码更难读，可以将其内联。

const discountMultiplier = 0.9; const finalPrice = price * discountMultiplier;

内联discountMultiplier后，代码变为const finalPrice = price * 0.9;。工具会自动删除该变量的声明，并将所有引用处替换为其初始化表达式。这对于简化临时变量或反向重构非常有用。

实操心得：提取的粒度与命名AI 在调用提取工具时，选择的代码范围至关重要。选择过小（如只选toFixed(2)）会导致提取出的函数无意义；选择过大可能包含不相关的语句。最好的实践是，先让 AI 使用quickinfo或selectionRange工具来确认符号的精确边界。提取后，务必立即使用rename工具给新符号一个语义化的名字，这是保证代码可读性的关键一步。tsserver在响应中提供的renameLocation正是为此设计。

4.3 代码组织与格式化

organizeImports：这个工具非常实用。它会：

删除未使用的导入。
合并来自同一模块的多个导入语句。
按字母顺序对导入进行排序（根据你的 TypeScript/编辑器格式化配置）。这对于保持文件头部整洁、消除无用依赖非常有效。可以配置 AI 在完成一系列修改后，自动对相关文件运行此工具。

format：对指定范围的代码进行格式化。它调用的是 TypeScript 内置的格式化器，规则与你的tsconfig.json或.editorconfig中的配置相关。虽然 AI 生成的代码通常格式尚可，但在复杂的重构后，使用此工具进行局部格式化能让代码风格保持一致。

getCodeFixes与getCombinedCodeFix：这两个工具是“自动修复”的核心。getDiagnostics可以获取文件中的错误和警告（诊断信息）。每个诊断都有一个错误码（如2304表示“找不到名称”）。

getCodeFixes：针对某个特定位置的特定错误码，获取可用的修复操作。例如，对于2304错误，可能的修复是“添加从 ‘xxx‘ 的导入”。
getCombinedCodeFix：针对整个文件中某个特定类型的所有错误，应用批量修复。例如，fixId为“fixMissingImport“可以一次性添加所有缺失的导入。

这为 AI 提供了强大的“纠错”能力。AI 可以先用getDiagnostics扫描文件，发现错误，然后用这些工具获取修复方案，并选择性地应用它们，从而让 AI 不仅会写代码，还会修复代码。

5. 代码智能工具：为AI装上“透视镜”

如果说重构工具是AI的“手术刀”，那么代码智能工具就是它的“透视镜”和“导航仪”。这些工具本身不修改代码，但它们为AI提供了深入理解代码库的能力。

5.1 符号导航与定义查找

definition/typeDefinition/implementation：这三个工具解决了“跳转到定义”的问题，但对AI来说，意义远不止于此。

definition：跳转到符号的声明处。对于变量const user: User = ...，跳转到user的声明。
typeDefinition：跳转到类型的定义处。对于同一个user，跳转到User接口或类型的定义处。这能帮助AI理解数据的结构。
implementation：查找接口或抽象类的所有具体实现。当AI需要了解某个抽象有多少种具体形态时，这个工具非常关键。

references：查找一个符号在项目中的所有引用。这是进行影响分析（Impact Analysis）的基础。在重命名、移动或删除一个函数前，AI 可以通过此工具快速评估改动的影响范围。

navto：项目范围的符号搜索。AI 可以像在 IDE 中按Cmd+P一样搜索符号。例如，AI 可以搜索所有名为“Handler“的函数或接口，来理解项目的命名模式或查找特定入口点。

fileReferences：查找引用了某个文件的所有其他文件。这相当于查看一个文件的“反向依赖图”。当AI考虑移动或删除一个文件时，这个工具能立刻告诉它有哪些文件会受到影响。

5.2 类型信息与文档获取

quickinfo：获取光标悬停信息。这是AI理解一段代码“是什么”的最直接方式。返回的信息包括：符号的类型字符串、文档注释（JSDoc）、符号种类（函数、变量、类等）。AI 在生成代码或解释代码时，可以随时调用此工具来获取准确的类型信息，避免幻觉。

navtree：获取文件的完整导航树。它返回一个结构化的列表，包含文件中的所有顶级声明及其嵌套结构（类中的方法、命名空间中的函数等）。这为AI提供了文件的“大纲视图”，对于快速理解一个陌生文件的结构非常有帮助。

completionInfo与signatureHelp：

completionInfo：获取代码补全建议。AI 可以模拟用户在某个位置按下Ctrl+Space的行为，获取可能的补全项列表。这在AI需要推断接下来可能写什么，或者需要知道某个模块下有哪些导出时非常有用。
signatureHelp：获取函数签名帮助。当光标位于函数调用括号内时，返回参数信息和重载列表。这能确保AI生成的函数调用参数顺序和类型是正确的。

5.3 高级代码分析

prepareCallHierarchy/provideCallHierarchyIncomingCalls/provideCallHierarchyOutgoingCalls：这一组工具提供了完整的调用链分析能力。

prepareCallHierarchy：在某个函数位置“建立”一个调用层次查询的入口点。
provideCallHierarchyIncomingCalls：查询谁调用了这个函数（入向调用）。用于理解一个函数的调用方，评估修改的影响。
provideCallHierarchyOutgoingCalls：查询这个函数调用了谁（出向调用）。用于理解一个函数的内部依赖，或者在提取函数时判断需要传入哪些参数。

这对于AI进行代码理解、重构（如提取函数时确定参数）、或者生成调用流程图描述至关重要。

getApplicableRefactors：查询在代码的某个位置或选中区域，有哪些重构操作是可用的。这相当于把VS Code的重构菜单暴露给了AI。AI可以先询问“这里可以做什么重构？”，然后根据返回的选项（如“提取到函数”、“提取到常量”、“转换为箭头函数”等）来选择执行哪个操作，使得AI的重构建议更加上下文感知和精准。

6. 实战工作流：从需求到AI驱动的重构

理论说了这么多，我们来看一个完整的、结合了多个工具的真实场景。假设我们有一个简单的电商应用，发现计算含税价格的逻辑散落在多处，我们想通过AI助手将其重构。

初始代码片段 (src/utils/price.ts):

export function calculatePrice(quantity: number, unitPrice: number): number { const taxRate = 0.08; // ... 其他逻辑 const taxedAmount = unitPrice * quantity * (1 + taxRate); return taxedAmount; }

另一处 (src/components/OrderSummary.tsx):

const displayPrice = (item.quantity * item.unitPrice * 1.08).toFixed(2);

我们的目标：将税率定义为常量，并创建一个专门计算含税价格的函数，替换所有硬编码的计算。

AI 驱动的工作流可能如下：

发现代码异味：AI 通过navto搜索 “tax” 或 “0.08”，或者我们直接告诉AI：“查找所有直接使用 0.08 或 1.08 进行税率计算的地方。”
理解上下文：AI 选中src/utils/price.ts中的taxRate变量，使用quickinfo查看其类型和上下文。使用references工具查找这个变量的所有引用，发现它只在本函数内使用。
提取税率常量：AI 决定将税率提取为模块级常量。它选中0.08，调用extractConstant工具。工具生成const extractedConstant = 0.08;并替换原处。AI 紧接着使用返回的renameLocation调用rename工具，将其重命名为STANDARD_TAX_RATE。
创建计算函数：AI 选中unitPrice * quantity * (1 + taxRate)这个表达式（现在taxRate已替换为STANDARD_TAX_RATE）。调用extractFunction工具。tsserver分析出依赖unitPrice,quantity,STANDARD_TAX_RATE，生成新函数。AI 将其重命名为calculateTaxedAmount。
```
export const STANDARD_TAX_RATE = 0.08; export function calculateTaxedAmount(unitPrice: number, quantity: number): number { return unitPrice * quantity * (1 + STANDARD_TAX_RATE); }
```
更新原函数：AI 修改calculatePrice函数，使其调用新的calculateTaxedAmount。
查找并替换硬编码：AI 使用navto或全文搜索（结合AI自己的文本理解）找到src/components/OrderSummary.tsx中的硬编码1.08。
应用替换：AI 调用getCodeFixes？不，这里没有错误。AI 需要执行一个自定义替换。但它可以先用quickinfo确认item.unitPrice和item.quantity的类型，然后直接生成正确的代码：const displayPrice = calculateTaxedAmount(item.unitPrice, item.quantity).toFixed(2);。同时，它需要为这个文件添加导入语句：import { calculateTaxedAmount } from ‘../utils/price‘;。AI 可以调用getCodeFixes来辅助添加导入（如果缺失），或者直接生成正确的 import 语句。
最终整理：AI 对修改过的文件调用organizeImports整理导入语句，可能再调用format进行局部格式化。

在整个过程中，ts-mcp-server提供的工具确保了第3、4步（提取和重命名）的绝对正确性，并为第2、7步（查找引用、获取类型信息）提供了精确的数据支持。AI 则负责串联这些操作、理解自然语言意图、并在没有直接工具支持的地方（如第6步的语义搜索和第8步的决策）发挥其创造性。

7. 常见问题、排查技巧与性能优化

7.1 工具无响应或返回空结果

问题：调用rename或references等工具时，返回空数组或没有预期的结果。
排查步骤：
1. 检查文件路径和位置：确保file参数是相对于当前工作目录的正确路径。line和offset必须是符号名称上的精确位置（而不是注释或空格）。使用quickinfo工具在相同位置测试，如果能返回信息，说明位置正确。
2. 确认tsconfig.json被正确加载：在项目根目录运行npx tsc --showConfig可以查看 TypeScript 实际使用的配置。确保includes/files包含了你要操作的文件。
3. 检查项目依赖：如果是node_modules中的类型定义，tsserver也能分析，但某些操作（如重命名）可能被限制。确保你的代码在项目源文件目录内。
4. 查看客户端日志：大多数 MCP 客户端会有日志输出。查看是否有来自ts-mcp-server的错误信息，例如tsserver启动失败或协议通信错误。

7.2 重构结果不符合预期

问题：重命名后，某些引用没更新，或者导入路径更新错了。
原因与解决：
- 动态导入或字符串引用：tsserver基于静态分析，无法处理运行时动态生成的字符串（如import(modulePath)中的变量modulePath）。这类引用需要手动处理。
- 非TypeScript/JavaScript文件：如果引用来自.json,.css,.html等文件，tsserver不会处理。需要配合其他工具或手动更新。
- 项目引用配置复杂：在 Monorepo 中，如果项目引用 (references) 配置不当，tsserver可能无法正确解析跨项目的符号。检查tsconfig.json的references和composite设置。
- 始终使用预览模式：在执行破坏性重构（如重命名、移动文件）前，务必先使用preview=true参数。这会返回将要进行的更改而不实际应用，让你有机会审查。

7.3 性能问题

问题：在大型项目（数千个文件）中，某些工具（如navto全局搜索）响应较慢。
优化建议：
1. 禁用非必要工具：如前所述，在配置中禁用你不需要的工具（如todoComments,getOutliningSpans）。
2. 使用currentFileOnly参数：navto工具支持currentFileOnly=true，将搜索范围限制在当前文件，速度极快。
3. 限制maxResultCount：对于navto，设置一个合理的maxResultCount（如 50），避免返回过多结果。
4. 确保 SSD 和足够内存：tsserver的性能与磁盘 I/O 和内存密切相关。确保项目在 SSD 上，并且 Node.js 进程有足够的内存。
5. 项目配置优化：使用tsconfig.json的exclude字段排除node_modules和构建输出目录（如dist,build），减少tsserver需要分析的文件数。

7.4 与AI客户端集成的技巧

提示工程：在给AI助手的指令中，可以明确引导它使用特定工具。例如：“请使用references工具查看formatUser函数都在哪里被调用了，然后我们再来讨论是否重命名它。”
分步执行：对于复杂重构，不要要求AI一步到位。拆解成“分析 -> 预览 -> 确认执行”多个步骤。例如：“第一步，用extractFunction预览将这段逻辑提取成函数的结果。第二步，如果预览结果正确，执行提取并重命名。”
错误处理：教导AI处理工具可能返回的错误。例如，如果moveSymbol失败（因为目标文件有冲突），AI 应该能够解析错误信息，并向用户建议替代方案（如先重命名冲突的符号）。

ts-mcp-server不是一个魔法黑盒，而是一个将 TypeScript 编译器强大能力暴露给 AI 的精密接口。理解其工作原理、熟悉每个工具的特性、并在实践中积累排查经验，你将能极大地提升与 AI 结对编程时的效率和代码质量，真正实现“1+1>2”的效果。它标志着AI编程助手从“代码片段生成器”向“系统级代码协作者”演进的重要一步。