MCP ts-morph Refactoring Tools

MCP ts-morph 重构工具

概述

该 MCP 服务器利用ts-morph为 TypeScript 和 JavaScript 代码库提供重构操作。它与 Cursor 等编辑器扩展配合使用，允许基于 AST 的符号重命名、文件/文件夹重命名和参考查找。

提供的功能

该 MCP 服务器提供以下重构功能：每个功能都使用ts-morph来分析 AST 并进行更改，同时保持整个项目的一致性。

重命名符号（ rename_symbol_by_tsmorph ）

• 作用：在整个项目中，全局重命名指定文件中特定位置的符号（函数、变量、类、接口等）。
• 用例：您想要更改函数或变量的名称，但对它有很多引用，手动更改它会很困难。
• 所需信息：项目的tsconfig.json路径、目标文件的路径、符号的位置（行和列）、当前符号名称、新符号名称

重命名文件/文件夹（ rename_filesystem_entry_by_tsmorph ）

• 功能：重命名多个指定的文件和/或文件夹，并自动更新项目中所有import / export语句中的路径。
• 用例：您更改文件结构并想相应地修改导入路径。如果您想一次重命名/移动多个文件/文件夹。
• 所需信息：项目的tsconfig.json路径，重命名操作数组（ renames: { oldPath: string, newPath: string }[] ）。
• 评论：
  • 引用主要通过符号解析来解析。
  • 包含路径别名（例如@/ ）的引用将被更新但转换为相对路径。
  • 引用目录索引文件（例如../components ）的导入将更新为明确的文件路径（例如../components/index.tsx ） 。
  • 它还在重命名操作之前执行路径碰撞检查（现有路径和操作中的重复）。
• **注意（执行时间）：**当同时处理许多文件和文件夹，或者对于非常大的项目时，解析和更新引用可能需要一些时间。
• **注意（已知限制）：**目前，对形式为export default Identifier;可能无法正确更新。

查找引用（ find_references_by_tsmorph ）

• 其作用：查找并列出指定文件中特定位置的符号定义，以及整个项目中的所有引用。
• 用例：您想知道函数或变量在哪里使用。您想探索重构的范围。
• 所需信息：项目的tsconfig.json路径、目标文件路径、符号位置（行、列）。

删除路径别名（ remove_path_alias_by_tsmorph ）

• 功能：将指定文件或目录中的import / export语句中的路径别名（如@/components ）替换为相对路径（如../../components ）。
• 用例：您想让您的项目更具可移植性或符合特定的编码标准。
• 所需信息：项目的tsconfig.json路径，要处理的文件或目录的路径。

在文件之间移动符号（ move_symbol_to_file_by_tsmorph ）

• 功能：将指定的符号（函数、变量、类、接口、类型别名、枚举）从当前文件移动到另一个指定的文件。在您移动时自动更新整个项目的引用（包括导入/导出路径）。
• 用例：您想将某些功能提取到单独的文件中以重新组织您的代码。
• 所需信息：项目的tsconfig.json路径、源文件路径、目标文件路径、要移动的符号的名称。或者，您可以指定符号的类型（ declarationKindString ）来消除同名符号的歧义。
• 注意：符号的内部依赖项（仅在该符号内使用的其他声明）会随之移动。源文件中剩余的其他符号所引用的依赖项将保留在源中，并根据需要添加export ，并将其导入目标文件。
• 注意： export default导出的符号不能使用此工具移动。

环境搭建

对于用户（作为 npm 包使用时）

将以下设置添加到mcp.json 。使用npx命令将自动使用您已安装的最新版本。

对于开发人员（用于本地开发和执行）

如果您想从源代码在本地运行服务器，则需要先构建它。

构建完成后，您可以通过在mcp.json中设置以下内容直接在node中运行它：

日志设置（环境变量）

可以使用以下环境变量来控制服务器操作日志的输出级别和目的地。在mcp.json的env块中设置它。

• LOG_LEVEL ：设置日志详细程度。
  • 可用级别： fatal 、 error 、 warn 、 info （默认）、 debug 、 trace 、 silent
  • 例如： "LOG_LEVEL": "debug"
• LOG_OUTPUT ：指定日志输出目的地。
  • console （默认）：记录到标准输出。如果您处于开发环境（ NODE_ENV !== 'production' ）并且安装了pino-pretty ，则输出将采用漂亮的格式。
  • file ：将日志输出到指定的文件。设置此项以避免影响 MCP 客户端。
  • 例如： "LOG_OUTPUT": "file"
• LOG_FILE_PATH ：如果LOG_OUTPUT设置为file ，则指定日志文件的绝对路径。
  • 默认值： [プロジェクトルート]/app.log
  • 例如： "LOG_FILE_PATH": "/var/log/mcp-tsmorph.log"

示例配置（在mcp.json中）：

开发者信息

先决条件

• Node.js（有关版本，请参阅.node-version或package.json中的volta字段）
• pnpm（查看package.json中的packageManager字段了解版本）

设置

克隆存储库并安装依赖项：

建造

将 TypeScript 代码编译为 JavaScript。

构建产物输出到dist目录。

测试

运行单元测试。

代码检查和格式化

它静态分析并格式化您的代码。

使用调试包装器

如果您在开发过程中想要详细检查 MCP 服务器的启动顺序、标准输入/输出以及错误输出，可以使用位于项目scripts目录中的mcp_launcher.js 。

该包装脚本将原始 MCP 服务器进程（ npx -y @sirosuzume/mcp-tsmorph-refactor ）作为子进程启动，并将启动信息和输出记录到项目根目录中的.logs/mcp_launcher.log文件中。

使用方法：

1. 在mcp.json文件中，将mcp-tsmorph-refactor服务器配置更改如下：
   • 将command设置为"node" 。
   • 在args中，指定scripts/mcp_launcher.js的路径（例如， ["path/to/your_project_root/scripts/mcp_launcher.js"] ）。您还可以使用相对于项目根目录的路径（ ["scripts/mcp_launcher.js"] ）。

   示例配置（ mcp.json ）：

   { "mcpServers": { "mcp-tsmorph-refactor": { "command": "node", // scripts/mcp_launcher.js へのパス (プロジェクトルートからの相対パス or 絶対パス) "args": ["path/to/your_project_root/scripts/mcp_launcher.js"], "env": { // 元の環境変数設定はそのまま活かせます // 例: // "LOG_LEVEL": "trace", // "LOG_OUTPUT": "file", // "LOG_FILE_PATH": ".logs/mcp-ts-morph.log" } } // ... 他のサーバー設定 ... } }
2. 重新启动或重新加载 MCP 客户端（例如 Cursor）。
3. 请确认日志已输出到项目根目录中的.logs/mcp_launcher.log 。如果已配置，您还可以检查 MCP 服务器本身的日志（例如.logs/mcp-ts-morph.log ）。

使用此包装器可以帮助您诊断 MCP 服务器未按预期启动的原因。

发布到 npm

该包将通过 GitHub Actions 工作流程（ .github/workflows/release.yml ）自动发布到 npm。

先决条件

• NPM 令牌：确保您拥有一个在存储库的操作机密（ Settings > Secrets and variables > Actions ）中设置了公共权限的 npm 访问令牌，其名称为NPM_TOKEN 。
• 更新您的版本：在发布之前，根据语义版本控制（SemVer）更新package.json中的version字段。

如何发布

要触发发布工作流程，请使用 Git 标签推送。

如何：推送 Git 标签（建议发布时使用）

• **预期用途：**常规版本发布（主要版本、次要版本、补丁版本）。 Git 是推荐的标准发布流程，因为它提供了历史记录和版本之间的清晰对应关系。

1. 更新版本：更改package.json中的version （例如0.3.0 ）。
2. 提交并推送：提交对package.json的更改并将其推送到主分支。
3. 创建标签并推送：创建与版本匹配的 Git 标签（带有v前缀）并推送。
   git tag v0.3.0 git push origin v0.3.0
4. 自动化：推送标签会触发Release Package工作流程，该工作流程会构建、测试并将包发布到 npm。
5. 验证：在“操作”选项卡中检查工作流程的状态，并在 npmjs.com 上验证您的包。

防范措施

• 版本一致性：在标签推送时触发，标签名称（例如v0.3.0 ）必须与package.json中的version完全匹配（例如0.3.0 ）。如果不匹配，工作流程将失败。
• 预检：尽管您的 CI 工作流程包括构建和测试步骤，但我们建议在更新版本之前在本地运行pnpm run build和pnpm run test以便尽早发现潜在问题。

执照

该项目根据 MIT 许可证发布。请参阅LICENSE文件以了解详细信息。