V48 (specification-implementation): MCP hierarchy as mcp-generics + generic-mcps/bitcode

Split packages/executions-mcp into:
- @bitcode/mcp-generics — product-neutral McpConfig/schema/validate primitives
- @bitcode/generic-mcps-bitcode — Bitcode Exchange MCP server (was mcp-server)

BC barrels: @bitcode/mcp → mcp-generics; @bitcode/mcp-server → generic-mcps-bitcode
(packages/executions-mcp remains the @bitcode/mcp compatibility package).
Path strings in BTD contracts, gate scripts, docs:refresh, and layout docs updated.
Jest mapper depth fixed for the deeper package path. Unit MCP contract/auth tests pass.

Author: geraldarthurdavis

BITCODE_SPEC_V48_NOTES.md

@@ -1618,3 +1618,13 @@ not provider packages.
 HostKind `local` replaces `inline` (BITCODE_PIPELINE_HOST; `inline` accepted as alias).
 Spec G3-4 tables updated to LocalHost / hostKind `local`.
 
+## MCP hierarchy modularization (Garrett, 2026-07-13)
+
+```
+@bitcode/mcp-generics                          # packages/mcp-generics (was executions-mcp primitives)
+  → @bitcode/generic-mcps-bitcode              # packages/generic-mcps/bitcode (was executions-mcp/mcp-server)
+```
+
+Compatibility barrels: `@bitcode/mcp` → mcp-generics; `@bitcode/mcp-server` → generic-mcps-bitcode.
+Active proof/catalog path strings and docs:refresh scripts point at the new layout.
+

FAMILIARIZATION.md

@@ -210,6 +210,18 @@ pipeline-local tools            e.g. AssetPackLexicalDepositorySearchTool
 
 `BITCODE_PIPELINE_HOST`: unset|`local` (default; `inline` alias) | `sandbox`.
 
+### 3.2.2 MCP
+
+```
+@bitcode/mcp-generics                          MCP primitives (McpConfig, schema, validate)
+        ↑
+@bitcode/generic-mcps-bitcode                  Bitcode Exchange-facing MCP server
+        ↑
+@bitcode/mcp / @bitcode/mcp-server             BC re-exports (was packages/executions-mcp)
+```
+
+Package paths: `packages/mcp-generics/`, `packages/generic-mcps/bitcode/`.
+
 ### 3.3 Pipelines
 
 **Hierarchy naming law:** names always encode full ancestry
@@ -399,7 +411,9 @@ public entries remain stable (`./deposit-asset-pack-options`, `./depository-sear
 | --- | --- |
 | `conversations-generics` | Conversation domain types |
 | `chatgptapp` | ChatGPT App MCP scaffolding (commercialization deferred) |
-| `executions-mcp` | MCP server for executions |
+| `mcp-generics` | MCP primitives (`McpConfig`, validation) |
+| `generic-mcps-bitcode` | Bitcode Exchange MCP server (`packages/generic-mcps/bitcode`) |
+| `mcp` / `mcp-server` | BC re-exports of mcp-generics / generic-mcps-bitcode |
 | `templates-generics`, `attachments-generics` | Template / attachment types |
 | `styling`, `responses`, `networking` | Shared UI/HTTP utilities |
 | `models` | Pricing / model registry helpers |

internal-docs/BITCODE_CONNECTED_SERVICES.md

@@ -33,5 +33,5 @@ Examples:
 - `packages/github/*`
 - `packages/jira/*`
 - `packages/chatgptapp/*`
-- `packages/executions-mcp/*`
+- `packages/mcp-generics/* + packages/generic-mcps/bitcode/*`
 - `packages/api/src/routes/*`

internal-docs/BITCODE_SOURCE_LAYOUT.md

@@ -214,6 +214,8 @@ packages/generic-<family>/          # README only (no package.json)
 | `vcs-generics/` | (package root) | `@bitcode/vcs-generics` |
 | `host-generics/` | (package root) | `@bitcode/host-generics` |
 | `generic-hosts/` | `Local/`, `VercelSandbox/` | `@bitcode/generic-hosts-*` |
+| `mcp-generics/` | (package root) | `@bitcode/mcp-generics` |
+| `generic-mcps/` | `bitcode/` | `@bitcode/generic-mcps-bitcode` |
 | `asset-packs/` | `synthesis/`, `settle/` | `@bitcode/asset-packs-synthesis`, `-settle` |
 | `generic-doc-comment-plugins/` | `doc-developing/` | `@bitcode/doc-comment-developing` |
 

package.json

@@ -17,6 +17,7 @@
     "packages/generic-measurements/*",
     "packages/generic-vcs/*",
     "packages/generic-hosts/*",
+    "packages/generic-mcps/*",
     "packages/asset-packs/*",
     "packages/generic-doc-comment-plugins/*",
     "packages/pipelines/*",
@@ -40,7 +41,7 @@
     }
   },
   "scripts": {
-    "docs:refresh": "npm --prefix packages/executions-mcp/src/mcp-server run docs:generate && npm --prefix packages/executions-mcp/src/mcp-server run docs:openapi",
+    "docs:refresh": "npm --prefix packages/generic-mcps/bitcode run docs:generate && npm --prefix packages/generic-mcps/bitcode run docs:openapi",
     "verify:ui": "node scripts/verify-ui-ssot.mjs",
     "generate:proven": "node scripts/generate-bitcode-proven.mjs",
     "promote:canon": "node scripts/promote-bitcode-canon.mjs",

packages/api/src/routes/__tests__/btd-crypto.test.ts

@@ -313,7 +313,7 @@ function interfaceIntegrationRegressionBody(overrides: Record<string, unknown> =
         surface: 'mcp',
         consumerId: 'bitcode-mcp-interface',
         packageExport: '@bitcode/btd/interface-integration-contract',
-        adapterPath: 'packages/executions-mcp/src/mcp-server/src/interface-integration.ts',
+        adapterPath: 'packages/generic-mcps/bitcode/src/interface-integration.ts',
         objectFamilies: ['source_to_shares_proof', 'organization_authority'],
         proofRoot: 'mcp-interface-proof-root',
       },

packages/btd/__tests__/interface-integration.test.ts

@@ -46,7 +46,7 @@ function records(): BtdInterfaceIntegrationRecordInput[] {
       surface: 'mcp',
       consumerId: 'bitcode-mcp-interface',
       packageExport: '@bitcode/btd/interface-integration-contract',
-      adapterPath: 'packages/executions-mcp/src/mcp-server/src/interface-integration.ts',
+      adapterPath: 'packages/generic-mcps/bitcode/src/interface-integration.ts',
       objectFamilies: ['source_to_shares_proof', 'organization_authority'],
     }),
     record({

packages/btd/src/api-schema-compatibility-matrix.ts

@@ -226,10 +226,10 @@ export function buildBtdApiSchemaCompatibilityRows(): BtdApiSchemaCompatibilityR
       examplePosture: 'success',
       exampleId: 'mcp-asset-pack-create-success',
       examplePath:
-        'packages/executions-mcp/src/mcp-server/src/__tests__/unit/pipeline-ingress-contract.test.ts#queues-asset-pack-create',
-      fixturePath: 'packages/executions-mcp/src/mcp-server/src/__tests__/unit/pipeline-ingress-contract.test.ts',
+        'packages/generic-mcps/bitcode/src/__tests__/unit/pipeline-ingress-contract.test.ts#queues-asset-pack-create',
+      fixturePath: 'packages/generic-mcps/bitcode/src/__tests__/unit/pipeline-ingress-contract.test.ts',
       validationCommand:
-        'pnpm --dir packages/executions-mcp/src/mcp-server run test:mcp -- --runTestsByPath src/__tests__/unit/pipeline-ingress-contract.test.ts --runInBand',
+        'pnpm --dir packages/generic-mcps/bitcode run test:mcp -- --runTestsByPath src/__tests__/unit/pipeline-ingress-contract.test.ts --runInBand',
       example: {
         request: {
           task: 'Synthesize a source-safe AssetPack preview for a reviewed ReadNeed.',

packages/btd/src/deployment-host-capability-catalog.ts

@@ -283,7 +283,7 @@ export function buildDeploymentHostCapabilityRows(): DeploymentHostCapabilityRow
     {
       hostId: 'mcp_api',
       runtimeSurface: 'mcp_api',
-      ownerPackage: 'packages/executions-mcp/src/mcp-server',
+      ownerPackage: 'packages/generic-mcps/bitcode',
       runtimeCarrier: 'mcp-server-process',
       requiredPackages: ['@bitcode/btd', '@bitcode/pipeline-asset-pack'],
       outboundNetworkPosture: 'outbound_restricted',
@@ -294,7 +294,7 @@ export function buildDeploymentHostCapabilityRows(): DeploymentHostCapabilityRow
       repairCapability: 'supported',
       proofOutputPaths: ['.bitcode/v33-mcp-api-tool-contracts.json'],
       validationCommand:
-        'pnpm --dir packages/executions-mcp/src/mcp-server run test:mcp -- --runTestsByPath src/__tests__/unit/pipeline-ingress-contract.test.ts --runInBand',
+        'pnpm --dir packages/generic-mcps/bitcode run test:mcp -- --runTestsByPath src/__tests__/unit/pipeline-ingress-contract.test.ts --runInBand',
       supportedLaneIds: ['local', 'staging-testnet', 'public-testnet'],
       admissionStatus: 'admitted_non_value_lanes',
       failureMode: 'mcp-api-host-without-tool-contract-or-permission-proof',

packages/btd/src/deployment-readiness-rehearsal.ts

@@ -383,7 +383,7 @@ function fullStackRow(
     validationCommands: [
       'pnpm --dir uapi run test:e2e:terminal-ux',
       'pnpm --filter @bitcode/api build',
-      'pnpm --dir packages/executions-mcp/src/mcp-server run test:mcp -- --runTestsByPath src/__tests__/unit/pipeline-ingress-contract.test.ts --runInBand',
+      'pnpm --dir packages/generic-mcps/bitcode run test:mcp -- --runTestsByPath src/__tests__/unit/pipeline-ingress-contract.test.ts --runInBand',
       'pnpm --dir packages/chatgptapp exec jest --runTestsByPath src/__tests__/chatgpt-action-contract.test.ts src/__tests__/tools.test.ts --runInBand',
       'pnpm run qa:pipeline-readback',
       'pnpm --filter @bitcode/btd test -- --runTestsByPath __tests__/deployment-storage-posture.test.ts',