mcpField
S
Spec Migrator 2511

Spec Migrator 2511

本地服务
matthiasmeyer.tech开发工具01 周前更新
代码仓库访问官网

关于 Spec Migrator 2511

Spec Migrator 2511 是面向 MCP 服务仓库的只读迁移工具包。它可检测规范版本、比较版本、生成迁移计划并检查完成情况，提供命令行、库和包含六种工具的 MCP 服务。

主要功能

  1. 01检测仓库的规范版本
  2. 02比较规范版本
  3. 03生成迁移计划
  4. 04检查迁移是否完成
  5. 05提供命令行、库和六种 MCP 工具

适用场景

  1. 01迁移前评估 MCP 服务仓库
  2. 02为目标规范生成迁移计划
  3. 03将迁移状态检查用作提交前门禁

MCP 相关

通过 stdio 提供六种只读工具，用于版本检测、兼容性矩阵、迁移计划与检查、支持版本查询和版本差异比较。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "spec-migrator-2511": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-spec-migrator"
      ]
    }
  }
}
启动命令npx -y mcp-spec-migrator

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npmmcp-spec-migrator

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

属于 StudioMeyer MCP Stack — 在马略卡岛打造 🌴 · 如果你在使用，请点 ⭐

mcp-spec-migrator

npm version npm downloads License Last commit GitHub stars 用于在不同规范版本间迁移 MCP 服务仓库的代码迁移工具和兼容性矩阵工具。

检测仓库面向的 MCP 规范版本，计算与目标版本之间的差异，生成 MIGRATION.md 迁移计划，并验证迁移是否完成。只读——绝不会向你的仓库写入补丁。

我们想说的话

过去两年，我们一直在为自己构建工具和系统。这个仓库规模小、星标少，并不是因为它刚刚诞生，而是因为我们最近才决定分享已经构建好的内容。这并非一个新鲜的实验，而是一段漫长故事中的近期提交。

我们热爱构建和分享，不喜欢社交媒体策略、增长黑客，也不热衷追逐星标和关注者。所以这个仓库规模不大。代码是真实的，确实有人在用，问题也会得到解答。请自行判断。

如果它对你有帮助，分享、测试和反馈都会帮到我们。如果你觉得它可以做得更好，提一个 issue 会更有帮助。如果你用它构建了什么，请发邮件告诉我们：[email protected]。这真的会让我们开心一整天。

来自马略卡岛帕尔马的一间小型工作室。

安装

npm install -g mcp-spec-migrator
# or one-shot
npx mcp-spec-migrator detect /path/to/your-mcp-server

库：

npm install mcp-spec-migrator

import { detect, computeMatrix, generatePlan } from "mcp-spec-migrator";

const result = await detect("/path/to/repo");
console.log(result.detected, result.confidence);

需要 Node 20+。

支持的规范版本

VersionStatusReleased
2024-11-05legacy2024-11-05
2025-03-26legacy2025-03-26
2025-06-18reference2025-06-18
2025-11-25current2025-11-25

迁移工具本身运行在 2025-06-18 版本上。在 Inspector 和 Claude Desktop 采用新规范之前，我们有意不升级到 2025-11-25，以保持迁移工具与旧版客户端的兼容性。

命令行

mcp-spec-migrator versions
mcp-spec-migrator detect <repo>          [--json]
mcp-spec-migrator plan <repo>            --target <version>  [--json]
mcp-spec-migrator check <repo>           --target <version>  [--json]
mcp-spec-migrator diff <v1> <v2>         [--format markdown|json]

示例：

mcp-spec-migrator detect ./my-mcp-server
mcp-spec-migrator plan ./my-mcp-server --target 2025-11-25 > MIGRATION.md
mcp-spec-migrator check ./my-mcp-server --target 2025-11-25
mcp-spec-migrator diff 2025-06-18 2025-11-25

如果迁移尚未完成，check 会以代码 1 退出，可用作提交前的检查关卡。

MCP 服务

同一套逻辑通过 stdio 暴露为包含 6 个工具的 MCP 服务。所有工具的 readOnlyHint: true 且 destructiveHint: false。

工具参数返回
detect_spec_version{ repo_path }{ detected, confidence, evidence[], sdkVersion, candidates[] }
compatibility_matrix{ from, to }{ breaking[], soft_deprecations[], new_features[], experimental[], unchanged_areas[] }
generate_migration_plan{ repo_path, target_version }{ plan_markdown, files_to_touch[], estimated_diff_kb, unscanned_files[] }
check_migration_complete{ repo_path, target_version }{ complete, missing_steps[], warnings[] }
list_supported_versions{}{ versions[], current_reference, latest, detail[] }
diff_spec_versions{ v1, v2, format? }{ diff, summary }

在 Claude Desktop / VS Code MCP / Inspector 中进行配置：

{
  "mcpServers": {
    "spec-migrator": {
      "command": "npx",
      "args": ["-y", "mcp-spec-migrator"]
    }
  }
}

兼容性矩阵

Migrator 版本MCP SDKNode运行的规范版本可检测并规划的规范版本
0.1.x^1.29.020+2025-06-182024-11-05, 2025-03-26, 2025-06-18, 2025-11-25

检测策略

置信度范围为 [0, 1]。置信度低于 0.50 时，Migrator 会返回 unknown，而不是猜测。

  1. 1.00 — 服务器构造函数中显式指定了 meta.specVersion。
  2. 0.85 — @modelcontextprotocol/sdk 的 semver 范围明确对应一个规范版本。
  3. 0.60 — AST 指纹模式（请求处理函数名称、注解字段名称）。
  4. <0.50 → 返回 unknown，并附上完整的证据列表。

不会扫描 src/、lib/、server/ 目录之外的源文件。大小超过 256 KB 的文件会被跳过。ts-morph 解析失败时会按文件捕获错误，因此单个源文件出错不会中断检测。

StudioMeyer 车队的推荐迁移顺序

  1. Memory（56 个工具，覆盖面最大）
  2. CRM（33 个工具）
  3. GEO（24 个工具）
  4. Crew（10 个工具）

推荐的钩子配置

事件工具使用场景
Stopdetect_spec_version会话结束时自动检测。发现过时的规范时发出警告。
UserPromptSubmitlist_supported_versions在出现短语 "spec version?" 时触发 — 直接回答。
PreCompactgenerate_migration_plan在上下文压缩前将计划保存到记忆中。
Stopcheck_migration_complete提交前检查：目标规范未完成时阻止提交。
UserPromptSubmitdiff_spec_versions在出现短语 "diff 2025-X 2025-Y" 时触发。

所有工具均为只读、确定性工具，在典型代码仓库中运行时间少于 10 秒。不进行网络调用。不收集遥测数据。

不在范围内

  • --apply 标志（自动应用补丁）。作为单独的构建内容，特意延后实现。
  • Python SDK 的 MCP 服务。v2。
  • 运行时实时获取规范。规范数据以代码形式提交。
  • 托管式 SaaS 包装层。仅提供 CLI 和库。

许可证

MIT — 版权所有 (c) 2026 Matthias Meyer (StudioMeyer)。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。