sofia-cli 0.1.1

package/specs/003-mcp-transport-integration/contracts/mcp-transport.md

@@ -0,0 +1,288 @@
+# Contract: MCP Transport Layer
+
+**Feature**: 003-mcp-transport-integration  
+**Module**: `src/mcp/mcpTransport.ts`, `src/mcp/mcpManager.ts`, `src/mcp/retryPolicy.ts`  
+**Status**: Authoritative design document
+
+---
+
+## Overview
+
+This contract defines the interface and behavior of `McpManager.callTool()` and the underlying transport layer (`McpTransport`). All MCP adapters and enrichers call `mcpManager.callTool()` — this is the single point of entry for **programmatic** MCP tool invocations (i.e., deterministic application-layer calls that bypass the LLM).
+
+### Scope: Programmatic Adapter Calls Only
+
+The custom transport layer described in this contract handles **only** direct tool calls made by adapters (GitHub adapter, Context7 enricher, Azure enricher) that need deterministic, application-controlled MCP invocations. These calls bypass the LLM conversation loop.
+
+**LLM-initiated tool calls** (e.g., web search during conversation, MCP tools invoked by the LLM during `sendAndWait()`) are handled by the **Copilot SDK's native MCP support**. The SDK manages server lifecycle (spawn, connect, JSON-RPC) for these calls via `SessionConfig.mcpServers` passed to `CopilotClient.createSession()`. See `research.md` Topic 1 for details.
+
+**⚠️ Dual-lifecycle note**: If the same MCP server is used in both paths (e.g., `context7` queried by the LLM and by `McpContextEnricher`), two separate subprocess instances will be spawned — one by the SDK and one by the custom transport. This is acceptable for Feature 003 scope.
+
+---
+
+## McpTransport Interface
+
+```typescript
+// src/mcp/mcpTransport.ts
+
+export interface McpTransport {
+  callTool(
+    toolName: string,
+    args: Record<string, unknown>,
+    timeoutMs: number,
+  ): Promise<ToolCallResponse>;
+  isConnected(): boolean;
+  disconnect(): Promise<void>;
+}
+
+export interface ToolCallResponse {
+  content: Record<string, unknown> | string;
+  raw?: unknown;
+  wasRetried?: boolean;
+}
+
+export class McpTransportError extends Error {
+  constructor(
+    message: string,
+    public readonly serverName: string,
+    public readonly toolName: string,
+    public readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = 'McpTransportError';
+  }
+}
+```
+
+---
+
+## StdioMcpTransport Contract
+
+**Constructor**: `new StdioMcpTransport(config: StdioServerConfig, logger: pino.Logger)`
+
+### `connect(): Promise<void>`
+
+| Step | Behavior                                                                                                              |
+| ---- | --------------------------------------------------------------------------------------------------------------------- |
+| 1    | Spawn subprocess: `spawn(config.command, config.args, { stdio: ['pipe','pipe','pipe'], env: process.env })`           |
+| 2    | Send JSON-RPC `initialize` request with `{ protocolVersion: '1.0', clientInfo: { name: 'sofIA', version: '0.1.0' } }` |
+| 3    | Wait for any JSON-RPC response with matching id within **5 seconds**                                                  |
+| 4    | On success: set `connected = true`; log info `'MCP stdio server connected: {name}'`                                   |
+| 5    | On timeout: kill subprocess, throw `McpTransportError` classified as `timeout`                                        |
+| 6    | On subprocess exit before init: throw `McpTransportError` classified as `connection-refused`                          |
+
+### `callTool(toolName, args, timeoutMs): Promise<ToolCallResponse>`
+
+**Preconditions**: `connect()` must have been called and succeeded.
+
+| Step | Behavior                                                                                                                                     |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | Generate `id = this.nextId++`                                                                                                                |
+| 2    | Register pending request: `pendingRequests.set(id, { resolve, reject, timer })`                                                              |
+| 3    | Start timeout: after `timeoutMs` ms, reject pending request with timeout error                                                               |
+| 4    | Write to `process.stdin`: `JSON.stringify({ jsonrpc: '2.0', id, method: 'tools/call', params: { name: toolName, arguments: args } }) + '\n'` |
+| 5    | On `process.stdout` line: parse JSON; if `line.id === id`, resolve/reject pending request                                                    |
+| 6    | On JSON-RPC error response: throw `McpTransportError(error.message)`                                                                         |
+| 7    | On malformed line (JSON parse fails): skip, log debug `'Skipping non-JSON stdout line'`                                                      |
+| 8    | Map `result.content[0].text` → `ToolCallResponse.content` (or `result` directly if no content array)                                         |
+
+### `disconnect(): Promise<void>`
+
+| Step | Behavior                                                                       |
+| ---- | ------------------------------------------------------------------------------ |
+| 1    | Reject all pending requests with `McpTransportError('transport disconnected')` |
+| 2    | Kill subprocess: `process.kill('SIGTERM')`                                     |
+| 3    | Set `connected = false`                                                        |
+
+---
+
+## HttpMcpTransport Contract
+
+**Constructor**: `new HttpMcpTransport(config: HttpServerConfig, logger: pino.Logger)`
+
+### `callTool(toolName, args, timeoutMs): Promise<ToolCallResponse>`
+
+| Step | Behavior                                                                                                                                                  |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | Build request body: `{ jsonrpc: '2.0', id: nextId++, method: 'tools/call', params: { name: toolName, arguments: args } }`                                 |
+| 2    | Build headers: `{ 'Content-Type': 'application/json', ...(token ? { 'Authorization': 'Bearer <token>' } : {}) }` where token = `process.env.GITHUB_TOKEN` |
+| 3    | Create `AbortController`, schedule `abort()` after `timeoutMs` ms                                                                                         |
+| 4    | `fetch(config.url, { method: 'POST', headers, body: JSON.stringify(body), signal: controller.signal })`                                                   |
+| 5    | On abort: throw `McpTransportError` classified as `timeout`                                                                                               |
+| 6    | On HTTP 401/403: throw `McpTransportError` classified as `auth-failure`                                                                                   |
+| 7    | On HTTP 5xx: throw `McpTransportError` classified as `unknown`                                                                                            |
+| 8    | Parse response body as JSON; extract `result.content` → `ToolCallResponse`                                                                                |
+| 9    | On JSON-RPC error: throw `McpTransportError(error.message)`                                                                                               |
+
+### `isConnected(): boolean`
+
+Returns `true` always (HTTP is stateless).
+
+### `disconnect(): Promise<void>`
+
+No-op (no persistent connection to close).
+
+---
+
+## McpManager.callTool() Contract
+
+```typescript
+// src/mcp/mcpManager.ts
+
+async callTool(
+  serverName: string,
+  toolName: string,
+  args: Record<string, unknown>,
+  options?: { timeoutMs?: number; retryOnTransient?: boolean }
+): Promise<Record<string, unknown>>
+```
+
+### Behavior
+
+| Step | Behavior                                                                                                                                         |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1    | Validate `serverName` is in `this.config.servers`; throw `Error('Unknown MCP server: {serverName}')` if not                                      |
+| 2    | Get or create transport: `this.getOrCreateTransport(serverName)`                                                                                 |
+| 3    | For stdio transports: if not connected, call `transport.connect()` and `markConnected(serverName)`                                               |
+| 4    | Determine timeout: `options.timeoutMs ?? this.defaultTimeouts[serverName] ?? 30_000`                                                             |
+| 5    | Apply retry policy (if `retryOnTransient !== false`): `withRetry(() => transport.callTool(toolName, args, timeoutMs), { serverName, toolName })` |
+| 6    | Normalize response: cast `ToolCallResponse.content` to `Record<string, unknown>` (if string, wrap as `{ text: content }`)                        |
+| 7    | On transport error: call `markDisconnected(serverName)`; re-throw `McpTransportError` to caller                                                  |
+
+### Default Timeouts
+
+| Server              | Default Timeout                         |
+| ------------------- | --------------------------------------- |
+| `github`            | 60,000 ms (repo operations can be slow) |
+| `context7`          | 30,000 ms                               |
+| `azure`             | 30,000 ms                               |
+| `workiq`            | 30,000 ms                               |
+| `microsoftdocs/mcp` | 30,000 ms                               |
+| any other           | 30,000 ms                               |
+
+### Error Propagation
+
+`McpManager.callTool()` does **not** swallow errors. Callers (adapters, enrichers) are responsible for catching `McpTransportError` and degrading gracefully. This keeps the transport layer simple and the caller's error handling explicit.
+
+---
+
+## RetryPolicy Contract
+
+```typescript
+// src/mcp/retryPolicy.ts
+
+export interface RetryOptions {
+  serverName: string;
+  toolName: string;
+  /** Initial delay in ms before first retry. Default: 1000 */
+  initialDelayMs?: number;
+  /** Jitter fraction (0–1). Default: 0.2 (±20%) */
+  jitter?: number;
+  logger?: pino.Logger;
+}
+
+/**
+ * Wrap an async function with a single-retry policy for transient MCP errors.
+ *
+ * Retryable errors: connection-refused, timeout, dns-failure
+ * Non-retryable: auth-failure, unknown, validation errors
+ *
+ * On retry: waits initialDelayMs ± jitter, then calls fn() again once.
+ * If the retry also fails, the second error is thrown (not the first).
+ */
+export async function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+```
+
+### Retry Decision Table
+
+| `classifyMcpError()` result | Retried?                  |
+| --------------------------- | ------------------------- |
+| `connection-refused`        | ✅ Yes, once              |
+| `timeout`                   | ✅ Yes, once              |
+| `dns-failure`               | ✅ Yes, once              |
+| `auth-failure`              | ❌ No — throw immediately |
+| `unknown`                   | ❌ No — throw immediately |
+| Not a `McpTransportError`   | ❌ No — throw immediately |
+
+### Logging on Retry
+
+When a retry is triggered, log at `warn` level:
+
+```
+{ server: serverName, tool: toolName, attempt: 1, delayMs: N, errorClass: '...' }
+MCP transient error — retrying after {N}ms
+```
+
+---
+
+## Transport Factory
+
+```typescript
+// src/mcp/mcpTransport.ts
+
+/**
+ * Create the correct transport implementation for a server config.
+ */
+export function createTransport(config: McpServerConfig, logger: pino.Logger): McpTransport {
+  if (config.type === 'stdio') return new StdioMcpTransport(config, logger);
+  if (config.type === 'http') return new HttpMcpTransport(config, logger);
+  throw new Error(`Unsupported MCP transport type: ${(config as McpServerConfig).type}`);
+}
+```
+
+---
+
+## Test Doubles
+
+### FakeMcpTransport (for unit tests)
+
+```typescript
+// tests/helpers/fakeMcpTransport.ts
+
+export class FakeMcpTransport implements McpTransport {
+  private readonly responses: Map<string, Record<string, unknown>>;
+  public callCount = 0;
+  public connected = true;
+  public callLog: Array<{ toolName: string; args: Record<string, unknown> }> = [];
+
+  constructor(responses: Map<string, Record<string, unknown>>) {
+    this.responses = responses;
+  }
+
+  async callTool(toolName: string, args: Record<string, unknown>): Promise<ToolCallResponse> {
+    this.callCount++;
+    this.callLog.push({ toolName, args });
+    const response = this.responses.get(toolName);
+    if (!response)
+      throw new McpTransportError(`No fake response for tool: ${toolName}`, 'fake', toolName);
+    return { content: response };
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+  async disconnect(): Promise<void> {
+    this.connected = false;
+  }
+}
+```
+
+---
+
+## Acceptance Tests (Unit + Integration)
+
+| Test                                                               | Type        | Description                                           |
+| ------------------------------------------------------------------ | ----------- | ----------------------------------------------------- |
+| `callTool routes to StdioTransport for stdio servers`              | unit        | Verify transport factory creates correct type         |
+| `callTool routes to HttpTransport for HTTP servers`                | unit        | Verify transport factory creates correct type         |
+| `StdioMcpTransport sends JSON-RPC and parses response`             | unit        | Mock subprocess stdout returns valid response         |
+| `StdioMcpTransport times out after timeoutMs`                      | unit        | Mock subprocess that never responds                   |
+| `HttpMcpTransport POSTs correct JSON-RPC and parses response`      | unit        | Mock `fetch` returns valid response                   |
+| `HttpMcpTransport sets Authorization header when GITHUB_TOKEN set` | unit        | Verify header presence                                |
+| `HttpMcpTransport throws auth-failure on 401`                      | unit        | Mock `fetch` returns 401                              |
+| `withRetry retries once on connection-refused`                     | unit        | First call throws connection-refused, second succeeds |
+| `withRetry does NOT retry on auth-failure`                         | unit        | Throws immediately                                    |
+| `McpManager.callTool unknown server throws`                        | unit        | Verify guard                                          |
+| `McpManager.callTool creates and caches transport`                 | unit        | Second call reuses same transport                     |
+| `McpManager.disconnectAll terminates all transports`               | unit        | Both transports disconnected                          |
+| `End-to-end transport with mock MCP server`                        | integration | Node.js echo server over stdin/stdout                 |

package/specs/003-mcp-transport-integration/data-model.md

@@ -0,0 +1,326 @@
+# Data Model: MCP Transport Integration
+
+**Feature ID**: 003-mcp-transport-integration  
+**Date**: 2026-03-01  
+**Status**: Complete
+
+---
+
+## Overview
+
+This feature introduces three new logical entities and extends two existing ones:
+
+| Entity | Status | Module |
+|--------|--------|--------|
+| `McpTransport` | **NEW** | `src/mcp/mcpTransport.ts` |
+| `ToolCallRequest` | **NEW** | `src/mcp/mcpTransport.ts` |
+| `ToolCallResponse` | **NEW** | `src/mcp/mcpTransport.ts` |
+| `DiscoveryEnrichment` | **NEW** | `src/shared/schemas/session.ts` |
+| `McpManager` | **EXTENDED** | `src/mcp/mcpManager.ts` |
+| `DiscoveryState` | **EXTENDED** | `src/shared/schemas/session.ts` |
+
+---
+
+## Entity 1: McpTransport (Interface + Implementations)
+
+**Purpose**: Abstracts the communication channel to a single MCP server. Handles connection lifecycle and JSON-RPC framing.
+
+### Interface
+
+```typescript
+/**
+ * Common interface for all MCP transport implementations.
+ * A transport represents a live connection to one MCP server.
+ */
+export interface McpTransport {
+  /** 
+   * Invoke a named tool on this MCP server. 
+   * Throws McpTransportError on failure (callers use classifyMcpError).
+   */
+  callTool(
+    toolName: string, 
+    args: Record<string, unknown>, 
+    timeoutMs: number
+  ): Promise<ToolCallResponse>;
+
+  /** Whether the transport is currently connected and able to accept calls. */
+  isConnected(): boolean;
+
+  /** Gracefully disconnect (terminate subprocess or close HTTP keepalive). */
+  disconnect(): Promise<void>;
+}
+```
+
+### StdioMcpTransport
+
+**Module**: `src/mcp/mcpTransport.ts`  
+**Description**: Manages a long-lived child process for stdio-based MCP servers (Context7, Azure MCP, WorkIQ, Playwright).
+
+**Fields**:
+| Field | Type | Description |
+|-------|------|-------------|
+| `config` | `StdioServerConfig` | Server name, command, args from `.vscode/mcp.json` |
+| `process` | `ChildProcess \| null` | The spawned subprocess |
+| `pendingRequests` | `Map<number, PendingRequest>` | In-flight JSON-RPC requests keyed by id |
+| `nextId` | `number` | Auto-incrementing JSON-RPC request id counter |
+| `connected` | `boolean` | Whether the initialization handshake completed |
+
+**Lifecycle**:
+1. `connect()`: `spawn()` subprocess, send `initialize` JSON-RPC request, wait for `initialized` response. Sets `connected = true`.
+2. `callTool()`: Generate next id, create `PendingRequest` with resolve/reject + timeout, write JSON-RPC request to `process.stdin`, wait for matching response id on `process.stdout`.
+3. `disconnect()`: Send `shutdown` request (optional), then `process.kill()`, clear pending requests with `McpTransportError`.
+
+**Validation rules**:
+- Subprocess must respond to `initialize` within 5 seconds or `connect()` throws.
+- Malformed stdout (non-JSON lines) are silently skipped (debug-logged).
+- If subprocess exits unexpectedly, all pending requests are rejected with `connection-refused` class error.
+
+### HttpMcpTransport
+
+**Module**: `src/mcp/mcpTransport.ts`  
+**Description**: Stateless HTTPS tool calls for HTTP-based MCP servers (GitHub MCP, Microsoft Docs MCP).
+
+**Fields**:
+| Field | Type | Description |
+|-------|------|-------------|
+| `config` | `HttpServerConfig` | Server name and URL from `.vscode/mcp.json` |
+| `nextId` | `number` | Auto-incrementing request id |
+
+**Behavior**:
+- Each `callTool()` makes one `fetch()` POST to `config.url`.
+- `AbortController` enforces `timeoutMs`.
+- `Authorization: Bearer <GITHUB_TOKEN>` added when `process.env.GITHUB_TOKEN` is set.
+- No persistent connection (`isConnected()` always returns `true` if the URL is reachable).
+
+**Validation rules**:
+- HTTP 4xx responses with status 401/403 → `auth-failure` error class.
+- HTTP 5xx responses → `unknown` error class (not retried).
+- Non-JSON response body → `unknown` error class.
+- Missing `GITHUB_TOKEN` for authenticated endpoints → `auth-failure` (immediate, no retry).
+
+---
+
+## Entity 2: ToolCallRequest
+
+**Purpose**: Structured input for a tool call — server, tool, args, and policy configuration.
+
+```typescript
+export interface ToolCallRequest {
+  /** MCP server name as defined in .vscode/mcp.json (e.g., 'github', 'context7') */
+  serverName: string;
+  /** Tool name to invoke on the server (e.g., 'create_repository', 'resolve-library-id') */
+  toolName: string;
+  /** Tool arguments — must match the tool's declared JSON Schema */
+  args: Record<string, unknown>;
+  /** 
+   * Timeout in milliseconds. 
+   * Default: 30_000 for query tools, 60_000 for repo operations.
+   */
+  timeoutMs?: number;
+  /**
+   * Whether to apply retry policy for transient errors.
+   * Default: true
+   */
+  retryOnTransient?: boolean;
+}
+```
+
+**Validation rules**:
+- `serverName` must be a key in the loaded `McpConfig.servers` — throws `Error` if unknown.
+- `toolName` must be a non-empty string.
+- `args` must be a plain object (no prototype chain, no Functions).
+- `timeoutMs` must be between 1_000 and 120_000 ms when provided.
+
+---
+
+## Entity 3: ToolCallResponse
+
+**Purpose**: Parsed and normalized output from an MCP tool call.
+
+```typescript
+export interface ToolCallResponse {
+  /** 
+   * The tool's result content. For MCP protocol, this is the parsed 
+   * `result.content[0].text` value (or the full `result` object if no content array).
+   */
+  content: Record<string, unknown> | string;
+  /** Raw MCP response for debugging (not logged in production) */
+  raw?: unknown;
+  /** Whether this response came from a retry attempt */
+  wasRetried?: boolean;
+}
+```
+
+**Validation rules**:
+- If the MCP JSON-RPC response contains `error`, throw `McpTransportError` with the error message.
+- If `result.content` is an array, use `content[0].text` as the content (standard MCP protocol format).
+- If `result.content` is an object (some servers return directly), use it as-is.
+- `content` must never be undefined in a successful response — throw if result is empty.
+
+---
+
+## Entity 4: DiscoveryEnrichment
+
+**Purpose**: Optional context gathered during the discovery phase, stored in the session for downstream phases (ideation, planning).
+
+**Module**: `src/shared/schemas/session.ts`
+
+### Zod Schema
+
+```typescript
+export const DiscoveryEnrichmentSchema = z.object({
+  /** Raw web search summary text (combined from all queries) */
+  webSearchResults: z.string().optional(),
+  /** Recent news headlines/snippets about the company */
+  companyNews: z.array(z.string()).optional(),
+  /** Competitor activity summaries */
+  competitorInfo: z.array(z.string()).optional(),
+  /** Industry trend descriptions */
+  industryTrends: z.array(z.string()).optional(),
+  /** WorkIQ-derived team insights (only present if user consented) */
+  workiqInsights: z.object({
+    /** Identified team skill areas */
+    teamExpertise: z.array(z.string()).optional(),
+    /** Meeting/communication patterns identified */
+    collaborationPatterns: z.array(z.string()).optional(),
+    /** Areas lacking internal documentation */
+    documentationGaps: z.array(z.string()).optional(),
+  }).optional(),
+  /** ISO 8601 timestamp when enrichment was collected */
+  enrichedAt: z.string().optional(),
+  /** Which sources were queried ('websearch', 'workiq') */
+  sourcesUsed: z.array(z.string()).optional(),
+});
+
+export type DiscoveryEnrichment = z.infer<typeof DiscoveryEnrichmentSchema>;
+```
+
+### Relationships
+
+- **Belongs to `DiscoveryState`**: Added as `enrichment?: DiscoveryEnrichment` on the existing `DiscoveryState` schema.
+- **Referenced by ideation/planning phases**: The enrichment fields are injected into LLM prompts as additional context when non-empty.
+
+### State Transitions
+
+```
+DiscoveryEnrichment states:
+  absent    → populated   (after user provides Step 1 input and enrichment completes)
+  populated → updated     (if user re-runs Step 1; enrichment is replaced, not merged)
+```
+
+**Validation rules**:
+- All fields are optional; a completely empty `DiscoveryEnrichment` is valid (means enrichment was attempted but returned no results or was declined).
+- `enrichedAt` must be a valid ISO 8601 string when present.
+- `sourcesUsed` entries must be lowercase strings (e.g., `'websearch'`, `'workiq'`).
+- Maximum 10 items per array field to avoid unbounded session growth.
+
+---
+
+## Entity 5: McpManager (Extended)
+
+**Purpose**: Existing class extended with `callTool()` implementation and transport registry.
+
+### New Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `transports` | `Map<string, McpTransport>` | One transport per connected server name |
+| `defaultTimeouts` | `Record<string, number>` | Default timeout per server (30s or 60s) |
+
+### New Methods
+
+```typescript
+/**
+ * Call a tool on a named MCP server.
+ * Creates and caches a transport for the server on first call.
+ * Applies retry policy for transient errors.
+ * 
+ * @throws Error if serverName not in config
+ * @throws McpTransportError if tool call fails after retries
+ */
+async callTool(
+  serverName: string,
+  toolName: string, 
+  args: Record<string, unknown>,
+  options?: { timeoutMs?: number; retryOnTransient?: boolean }
+): Promise<Record<string, unknown>>;
+
+/**
+ * Disconnect all active transports. Call on process exit.
+ */
+async disconnectAll(): Promise<void>;
+```
+
+### Transport Registry Rules
+
+- Transports are lazily created on first `callTool()` for a server.
+- `StdioMcpTransport` servers: subprocess is started and kept alive for the session.
+- `HttpMcpTransport` servers: stateless; no persistent connection to manage.
+- `markConnected()` is called after a successful `initialize` handshake for stdio, or after a successful HTTP call for HTTP servers.
+- `markDisconnected()` is called when a transport errors or disconnects.
+
+---
+
+## Entity 6: DiscoveryState (Extended)
+
+**Existing entity** in `src/shared/schemas/session.ts`.
+
+### Change
+
+Add `enrichment?: DiscoveryEnrichment` field to the existing `DiscoveryState` Zod schema.
+
+```typescript
+// Before:
+export const DiscoveryStateSchema = z.object({
+  steps: z.record(z.string(), z.unknown()),
+  currentStep: z.number(),
+  // ...
+});
+
+// After: (add one field)
+export const DiscoveryStateSchema = z.object({
+  steps: z.record(z.string(), z.unknown()),
+  currentStep: z.number(),
+  // ...
+  enrichment: DiscoveryEnrichmentSchema.optional(),
+});
+```
+
+**Backward compatibility**: The field is optional; existing sessions without enrichment remain valid and parse without errors.
+
+---
+
+## Entity Relationships Diagram
+
+```
+McpConfig (loaded from .vscode/mcp.json)
+  └── servers: Record<string, McpServerConfig>
+        ├── StdioServerConfig → StdioMcpTransport (spawns subprocess)
+        └── HttpServerConfig  → HttpMcpTransport  (stateless fetch)
+
+McpManager
+  ├── config: McpConfig
+  ├── transports: Map<serverName, McpTransport>
+  └── callTool(serverName, toolName, args)
+        ├── withRetry (retryPolicy.ts)
+        └── transport.callTool(toolName, args, timeoutMs)
+              └── returns: ToolCallResponse
+
+GitHubMcpAdapter
+  └── mcpManager.callTool('github', ...) → ToolCallResponse
+
+McpContextEnricher
+  ├── mcpManager.callTool('context7', 'resolve-library-id', ...) → ToolCallResponse
+  ├── mcpManager.callTool('context7', 'query-docs', ...) → ToolCallResponse
+  ├── mcpManager.callTool('azure', 'documentation', ...) → ToolCallResponse
+  └── mcpManager.callTool('websearch', 'search', ...) → ToolCallResponse
+
+DiscoveryEnricher
+  ├── webSearch.searchWeb(...) → WebSearchResult
+  └── mcpManager.callTool('workiq', ...) → ToolCallResponse
+        → DiscoveryEnrichment stored in WorkshopSession.discovery.enrichment
+
+WorkshopSession
+  └── discovery: DiscoveryState
+        └── enrichment?: DiscoveryEnrichment  ← NEW FIELD
+```