The BitzSaury migration MCP suite is a development-time search tool under tooling/mcp-bitzsaury. It helps teams migrate Saury and BitzOrcas legacy systems onto BitzOrcasVNext by exposing foundation contracts, legacy code, and PRDs as structured MCP tools.

Runtime model

Item	Current implementation
Runtime	.NET 10
MCP SDK	`ModelContextProtocol` 2.1.0
Transport	stdio; an editor or agent launches each server as a child process
Search engine	local `rg` (ripgrep)
Path configuration	environment variables only; no developer path is hard-coded
Logging boundary	stdout carries MCP JSON-RPC only; logs, ready messages, and configuration errors go to stderr
Package versions	the subtree owns `Directory.Packages.props`, isolated from the product package ledger

Agent / editor
  ├─ bitzsaury-base   → BitzOrcasVNext Framework / Platform / CONTEXT
  ├─ bitzsaury-legacy → Saury and BitzOrcas legacy code
  └─ bitzsaury-prd    → BusinessModulesPRD and LegacyPRD-BitzOrcas

Servers and environment variables

Server	DLL	Tools	Required variable	Optional variable
`BitzSaury.Mcp.BaseContracts`	`BitzSaury.Mcp.BaseContracts.dll`	5	`BITZSAURY_BASE_REPO`	None
`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`	None

Each variable must point to an existing file or directory:

BITZSAURY_BASE_REPO: BitzOrcasVNext root containing src/Platform, src/Framework, CONTEXT.md, and architecture rules;
BITZSAURY_BITZORCAS_REPO: BitzOrcas legacy repository root;
BITZSAURY_SAURY_REPO: Saury legacy repository root. The Legacy server can search BitzOrcas alone when it is absent;
BITZSAURY_DOCS_REPO: knowledge-repository root containing projects/BitzSaury.Modern/BusinessModulesPRD and LegacyPRD-BitzOrcas.

If a required variable is empty or the path does not exist, startup writes CONFIG ERROR to stderr and exits non-zero. Keep absolute paths in each developer’s local MCP configuration, never in the repository.

Build

Run from the BitzOrcasVNext root:

# Build Core first; all three servers consume the same base assembly.
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

Build Core first, followed by the three servers. DLLs are written under each project’s bin/Release/net10.0/. The runtime machine must also resolve rg from PATH.

MCP client configuration

This example uses ZCode’s mcp.json shape. Replace placeholders with local absolute paths; other stdio MCP clients can map the same command, arguments, and environment.

{
  "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>" }
    }
  }
}

After activation, a client normally prefixes tool names, for example mcp__bitzsaury-base__find_contract. The exact prefix is client-defined.

12 tools

BaseContracts: foundation contracts and red lines

Tool	Main parameters	Returns
`find_contract`	`query`, `maxResults?`	Framework/Platform interfaces, aggregates, ports, and `CONTEXT-MAP` clues
`find_aggregate`	`name`, `contextLines?`	aggregate/entity locations and context
`query_extension_points`	`domain`, `maxResults?`	Contributor, Provider, Adapter, Resolver, Hook, Store, and Port extension points
`check_redline`	`code`, `filePath?`	architecture-red-line and prohibited-pattern findings for submitted code
`suggest_base_reuse`	`legacyPattern`	reuse, extend, or build guidance with related PRD/Skill references

check_redline inspects caller-supplied text and does not edit files. suggest_base_reuse is navigation, not architecture approval; confirm its proposal against current contracts, tests, and the formal compliance audit.

Tool	Main parameters	Returns
`find_legacy_entity`	`name`, `project?`, `maxResults?`	Saury `T_*`, BitzOrcas `[SugarTable]`, and related entity hits
`find_legacy_service`	`name`, `project?`, `maxResults?`	AppService, Manage, Manager, and service hits
`get_legacy_file`	`path`, `project?`, `maxLines?`	bounded content from an absolute or repository-relative path

project accepts saury, bitzorcas, or both. Do not request the Saury scope when only the BitzOrcas root is configured.

Prd: migration knowledge base

Tool	Main parameters	Returns
`list_modules`	None	BusinessModulesPRD module number, title, and document count
`query_module_prd`	`query`, `includeContent?`	module and Overview matches by number, name, or keyword
`search_prd`	`query`, `maxResults?`	full-text matches across both PRD trees
`read_prd`	`path`, `maxLines?`	bounded content from a selected PRD file

Recommended migration sequence

Establish module scope and terminology with query_module_prd; use read_prd for the authoritative section.
Build evidence for legacy behavior with find_legacy_entity, find_legacy_service, and get_legacy_file.
Locate existing foundation capabilities through find_contract, find_aggregate, and query_extension_points.
Use suggest_base_reuse to form a candidate, then inspect the actual contracts.
After implementation, submit changed code to check_redline and run the repository’s formal architecture and merge gates.

MCP supplies a dynamic view of “what exists now.” Migration Skills supply procedural guidance for “how to transform it.” Neither replaces business acceptance.

Troubleshooting

Symptom	Inspect
Server exits immediately	missing variable named in stderr; whether its path exists
Client reports invalid protocol JSON	whether any logger writes stdout; the current implementation routes Console Logger to stderr
Tool misses code that exists	`rg` installation, repository-root variable, and search scope
Legacy search returns only one system	`project` and `BITZSAURY_SAURY_REPO`
PRD reports a missing directory	`BITZSAURY_DOCS_REPO` must be the knowledge root, not the `BusinessModulesPRD` child
Tool behavior remains stale after source changes	rebuild Release and verify the MCP configuration points to the current DLL

Source locations

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/

After you locate Saury T_WorkflowDefinition* or StepBody types, hand definition migration to the Workflow Migrator source saury path. The MCP servers only search; they do not emit DSL.

BitzSaury migration MCP servers