BitzSaury 迁移 MCP 是 tooling/mcp-bitzsaury 下的开发期检索工具集，辅助团队把 Saury / BitzOrcas 老系统迁移到 BitzOrcasVNext。它通过 MCP 把底座契约、老代码和 PRD 暴露为结构化查询工具，减少手工跨仓库搜索。

运行模型

项	当前实现
运行时	.NET 10
MCP SDK	`ModelContextProtocol` 2.1.0
传输	stdio；编辑器或 Agent 以子进程启动
检索引擎	本机 `rg`（ripgrep）
路径配置	全部使用环境变量，不硬编码开发者路径
日志边界	stdout 只写 MCP JSON-RPC；日志、ready 与配置错误写 stderr
包版本	子树自带 `Directory.Packages.props`，与产品中央包版本账本隔离

Agent / editor
  ├─ bitzsaury-base   → BitzOrcasVNext Framework / Platform / CONTEXT
  ├─ bitzsaury-legacy → Saury 与 BitzOrcas 老代码
  └─ bitzsaury-prd    → BusinessModulesPRD 与 LegacyPRD-BitzOrcas

Server 与环境变量

Server	DLL	工具数	必需环境变量	可选环境变量
`BitzSaury.Mcp.BaseContracts`	`BitzSaury.Mcp.BaseContracts.dll`	5	`BITZSAURY_BASE_REPO`	无
`BitzSaury.Mcp.LegacyCode`	`BitzSaury.Mcp.LegacyCode.dll`	3	`BITZSAURY_BITZORCAS_REPO`	`BITZSAURY_SAURY_REPO`
`BitzSaury.Mcp.Prd`	`BitzSaury.Mcp.Prd.dll`	4	`BITZSAURY_DOCS_REPO`	无

环境变量必须指向真实存在的文件或目录：

BITZSAURY_BASE_REPO：BitzOrcasVNext 根目录，包含 src/Platform、src/Framework、CONTEXT.md 与架构规则；
BITZSAURY_BITZORCAS_REPO：BitzOrcas 老项目根目录；
BITZSAURY_SAURY_REPO：Saury 老项目根目录。未设置时 Legacy Server 仍可只查 BitzOrcas；
BITZSAURY_DOCS_REPO：知识库仓库根目录，其下应有 projects/BitzSaury.Modern/BusinessModulesPRD 与 LegacyPRD-BitzOrcas。

必需变量为空或路径不存在时，Server 在启动阶段向 stderr 输出 CONFIG ERROR 并以非零状态退出。不要把绝对路径提交到仓库；在每位开发者本地的 MCP 配置中维护。

构建

从 BitzOrcasVNext 根目录执行：

# Core 先编译，三个 Server 随后复用同一基础程序集。
cd tooling/mcp-bitzsaury/src

dotnet build BitzSaury.Mcp.Core/BitzSaury.Mcp.Core.csproj -c Release
dotnet build BitzSaury.Mcp.BaseContracts/BitzSaury.Mcp.BaseContracts.csproj -c Release
dotnet build BitzSaury.Mcp.LegacyCode/BitzSaury.Mcp.LegacyCode.csproj -c Release
dotnet build BitzSaury.Mcp.Prd/BitzSaury.Mcp.Prd.csproj -c Release

先构建 Core，随后构建三个 Server。产物位于各项目的 bin/Release/net10.0/。运行机还必须能在 PATH 中找到 rg。

MCP 客户端配置

下面示例沿用 ZCode 的 mcp.json 形状。将占位路径替换为本机绝对路径；其他支持 stdio MCP 的客户端可映射为等价配置。

{
  "mcpServers": {
    "bitzsaury-base": {
      "command": "dotnet",
      "args": [
        "<base-repo>/tooling/mcp-bitzsaury/src/BitzSaury.Mcp.BaseContracts/bin/Release/net10.0/BitzSaury.Mcp.BaseContracts.dll"
      ],
      "env": { "BITZSAURY_BASE_REPO": "<base-repo>" }
    },
    "bitzsaury-legacy": {
      "command": "dotnet",
      "args": [
        "<base-repo>/tooling/mcp-bitzsaury/src/BitzSaury.Mcp.LegacyCode/bin/Release/net10.0/BitzSaury.Mcp.LegacyCode.dll"
      ],
      "env": {
        "BITZSAURY_BITZORCAS_REPO": "<legacy-bitzorcas-repo>",
        "BITZSAURY_SAURY_REPO": "<legacy-saury-repo>"
      }
    },
    "bitzsaury-prd": {
      "command": "dotnet",
      "args": [
        "<base-repo>/tooling/mcp-bitzsaury/src/BitzSaury.Mcp.Prd/bin/Release/net10.0/BitzSaury.Mcp.Prd.dll"
      ],
      "env": { "BITZSAURY_DOCS_REPO": "<knowledge-repo>" }
    }
  }
}

启用后，工具名通常带客户端生成的 Server 前缀，例如 mcp__bitzsaury-base__find_contract。实际前缀由 MCP 客户端决定。

12 个工具

BaseContracts：底座契约与红线

工具	主要参数	返回内容
`find_contract`	`query`, `maxResults?`	Framework/Platform 接口、聚合、Port 与 `CONTEXT-MAP` 线索
`find_aggregate`	`name`, `contextLines?`	聚合根/实体位置及上下文
`query_extension_points`	`domain`, `maxResults?`	Contributor、Provider、Adapter、Resolver、Hook、Store、Port 扩展点
`check_redline`	`code`, `filePath?`	对代码片段执行架构红线与禁用模式检查
`suggest_base_reuse`	`legacyPattern`	复用、扩展或新建建议，以及相关 PRD/Skill 线索

check_redline 检查调用方提交的文本，不会自行修改文件。suggest_base_reuse 是迁移导航，不是架构批准；最终以当前契约、测试与红线审计为准。

LegacyCode：旧系统导航

工具	主要参数	返回内容
`find_legacy_entity`	`name`, `project?`, `maxResults?`	Saury `T_*`、BitzOrcas `[SugarTable]` 等实体命中
`find_legacy_service`	`name`, `project?`, `maxResults?`	AppService、Manage、Manager 与服务实现命中
`get_legacy_file`	`path`, `project?`, `maxLines?`	绝对路径或仓库相对路径的受限行数内容

project 可取 saury、bitzorcas 或 both。只配置 BitzOrcas 根目录时，不要请求 saury 范围。

Prd：迁移知识库

工具	主要参数	返回内容
`list_modules`	无	BusinessModulesPRD 的模块编号、标题与文档数
`query_module_prd`	`query`, `includeContent?`	按编号、名称或关键词定位模块与 Overview
`search_prd`	`query`, `maxResults?`	两套 PRD 目录的全文检索结果
`read_prd`	`path`, `maxLines?`	指定 PRD 文件的受限行数内容

建议迁移顺序

用 query_module_prd 明确模块边界与术语，必要时通过 read_prd 读取权威章节；
用 find_legacy_entity、find_legacy_service 和 get_legacy_file 建立旧行为证据；
用 find_contract、find_aggregate 与 query_extension_points 查找底座现有能力；
用 suggest_base_reuse 形成候选方案，再由工程师核对实际契约；
完成代码后，把变更片段交给 check_redline，并运行仓库正式架构测试与合并门禁。

MCP 提供“当前有什么”的动态检索；迁移 Skill 提供“按什么步骤做”的工作流。两者互补，但都不能替代业务验收。

故障定位

现象	检查项
Server 启动后立即退出	stderr 中的缺失变量名；路径是否存在
客户端报协议 JSON 无效	是否把日志写到了 stdout；当前实现必须把 Console Logger 定向 stderr
工具找不到已存在代码	`rg` 是否安装、环境变量是否指向仓库根、文件是否在搜索范围内
Legacy 查询只返回一个老项目	`project` 参数与 `BITZSAURY_SAURY_REPO` 是否匹配
PRD 返回目录不存在	`BITZSAURY_DOCS_REPO` 是否为知识库根，而不是 `BusinessModulesPRD` 子目录
更新源码后工具仍是旧行为	重新执行 Release build，并确认 MCP 配置指向当前 DLL

源码定位

tooling/mcp-bitzsaury/README.md
tooling/mcp-bitzsaury/src/BitzSaury.Mcp.Core/McpPaths.cs
tooling/mcp-bitzsaury/src/BitzSaury.Mcp.Core/Ripgrep.cs
tooling/mcp-bitzsaury/src/BitzSaury.Mcp.BaseContracts/Tools/
tooling/mcp-bitzsaury/src/BitzSaury.Mcp.LegacyCode/Tools/
tooling/mcp-bitzsaury/src/BitzSaury.Mcp.Prd/Tools/

查到 Saury T_WorkflowDefinition* 或 StepBody 类型后，定义迁移交给 Workflow Migrator 的 source saury 路径。MCP 只检索，不写出 DSL。