STARWARCLOUD STARWAR.AI
返回市场
麦克普-ts形变

麦克普-ts形变

作者：SiroSuzume12 星标更新：2025-09-03
安装使用来源：spider==github.com

项目介绍

技术文档摘要

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 路径。
  • 应用场景: 当需要更改文件结构并相应地修正 import 路径时；或者希望一次性重命名或移动多个文件/文件夹时。
  • 所需信息: 项目的 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 命令可以自动使用已安装的最新版本。

{
  "mcpServers": {
    "mcp-tsmorph-refactor": { // 任意的服务器名称
      "command": "npx",
      "args": ["-y", "@sirosuzume/mcp-tsmorph-refactor"],
      "env": {} // 根据需要添加日志设置等
    }
  }
}

开发者指南（本地开发和运行）

若要在本地从源码启动服务器，首先需要构建。

# 安装依赖（仅首次）
pnpm install

# 构建 TypeScript 代码
pnpm run build

构建完成后，可以在 mcp.json 中做如下设置，然后使用 node 直接运行。

{
  "mcpServers": {
    "mcp-tsmorph-refactor-dev": { // 推荐使用不同的名称，如开发用
      "command": "node",
      // 项目根目录下的相对路径或绝对路径
      "args": ["/path/to/your/local/repo/dist/index.js"],
      "env": {
        // 开发时的日志设置等
        "LOG_LEVEL": "debug"
      }
    }
  }
}

日志设置（环境变量）

可以通过环境变量控制服务器的操作日志输出级别和输出目标。在 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 中）:

// ... (mcp.json 的其他设置)
      "env": {
        "LOG_LEVEL": "debug", // 设置调试级别的日志
        "LOG_OUTPUT": "file",  // 输出到文件
        "LOG_FILE_PATH": "/Users/yourname/logs/mcp-t-alias.log" // 指定日志文件的路径
      }
// ...

开发者信息

前提条件

  • Node.js（版本参考 .node-version 或 package.json 的 volta 字段）
  • pnpm（版本参考 package.json 的 packageManager 字段）

设置

克隆仓库并安装依赖。

git clone https://github.com/sirosuzume/mcp-tsmorph-refactor.git
cd mcp-tsmorph-refactor
pnpm install

构建

编译 TypeScript 代码为 JavaScript。

pnpm build

构建产物将输出到 dist 目录。

测试

运行单元测试。

pnpm test

静态分析和格式化

对代码进行静态分析和格式化。

# 进行 lint 检查
pnpm lint

# 自动修复 lint 错误
pnpm lint:fix

# 进行格式化
pnpm format

使用调试包装器

在开发过程中，若需详细查看 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 的路径（项目根目录下的相对路径或绝对路径）
      "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 令牌: 确保具有发布权限的 npm 访问令牌已设置在仓库的 Actions 密钥中（Settings > Secrets and variables > Actions），命名为 NPM_TOKEN。
  • 版本更新: 在发布前，请根据语义化版本（SemVer）更新 package.json 中的 version 字段。

发布方法

通过推送 Git 标签触发发布工作流。

方法: 推送 Git 标签（推荐用于发布）

  • 适用场景: 正常的版本发布（主要、次要、补丁）。由于 Git 历史记录和版本明确对应，建议作为标准发布流程。
  1. 更新版本: 修改 package.json 中的 version（例如：0.3.0）。
  2. 提交并推送: 提交 package.json 的更改，并推送到 main 分支。
  3. 创建并推送标签: 创建与版本匹配的 Git 标签（带 v 前缀），并推送。 
    git tag v0.3.0
git push origin v0.3.0
  4. 自动化: 推送标签后，Release Package 工作流将被触发，执行包的构建、测试及发布到 npm。
  5. 确认: 在 Actions 标签中检查工作流状态，并在 npmjs.com 上确认包。

注意事项

  • 版本一致性: 当通过推送标签触发时，标签名（例如：v0.3.0）必须与 package.json 中的 version（例如：0.3.0）完全一致。不一致会导致工作流失败。
  • 预检查: 虽然 CI 工作流包含构建和测试步骤，但在更新版本前，建议在本地执行 pnpm run build 和 pnpm run test 以尽早发现潜在问题。

许可证

此项目在 MIT 许可证下发布。详情请参阅 LICENSE 文件。