AGENTS.md

1# src/features/skill-mcp-manager/ — Skill-Embedded MCP Client Lifecycle
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
7This module manages **tier 3** of the MCP system: skill-embedded MCP servers declared in SKILL.md YAML frontmatter. Per-session client isolation, dual transport (stdio + HTTP), OAuth 2.0 with step-up authentication, idle cleanup. Harness-neutral MCP client lifecycle and OAuth primitives are extracted to [`packages/mcp-client-core/`](../../../../../packages/mcp-client-core); this directory keeps the OpenCode manager wiring stable.
8 
9## THREE-TIER MCP CONTEXT
10 
11| Tier | Manager | Scope |
12|------|---------|-------|
13| 1. Built-in | `createBuiltinMcps()` (src/mcp/) | Global, 3 remote HTTP + 1 local stdio (`lsp`) |
14| 2. Claude Code | `claude-code-mcp-loader` (src/features/) | From `.mcp.json` |
15| 3. **Skill-embedded** | **`SkillMcpManager` (this module)** | **Per-session, from SKILL.md YAML** |
16 
17## CLIENT KEY FORMAT
18 
19```
20${sessionID}:${skillName}:${serverName}
21```
22 
23Enables: per-session isolation, same skill usable in multiple sessions concurrently, multiple servers per skill.
24 
25## DUAL TRANSPORT
26 
27| Type | File | Backend |
28|------|------|---------|
29| **stdio** | `stdio-client.ts` | `StdioClientTransport` (local process) |
30| **http** | `http-client.ts` | `StreamableHTTPClientTransport` (remote) |
31 
32**Detection** (connection-type.ts): explicit `type` field → URL presence → command presence. Legacy `"sse"` mapped to http.
33 
34## STATE
35 
36```typescript
37interface SkillMcpManagerState {
38  clients: Map<clientKey, ManagedClient>              // Active connections
39  pendingConnections: Map<clientKey, Promise<Client>> // Race prevention
40  disconnectedSessions: Map<sessionID, generation>    // Stale connection detection
41  authProviders: Map<url, OAuthProvider>              // OAuth state per server
42  inFlightConnections: Map<sessionID, count>          // Connection counting
43}
44```
45 
46## KEY FILES
47 
48| File | Purpose |
49|------|---------|
50| `manager.ts` | `SkillMcpManager` class — main API (getOrCreateClient, disconnectSession, listTools, callTool, etc.) |
51| `types.ts` | `ManagedStdioClient`, `ManagedHttpClient`, `SkillMcpManagerState`, `ConnectionType` |
52| `connection.ts` | Client factory with race prevention, retry, env var expansion |
53| `connection-type.ts` | Detect stdio vs http from config (legacy sse → http) |
54| `stdio-client.ts` | Stdio transport factory |
55| `http-client.ts` | HTTP transport factory |
56| `cleanup.ts` | SIGINT/SIGTERM handlers, idle timer (60s interval, 5min TTL) |
57| `oauth-handler.ts` | OAuth token management, refresh, step-up (403 scope escalation) |
58| `env-cleaner.ts` | Filter npm/pnpm/yarn config + 25+ secret patterns (_KEY, _SECRET, _TOKEN) |
59| `error-redaction.ts` | Redact sensitive data from error messages before logging |
60 
61## LIFECYCLE INTEGRATION
62 
63**Hook**: `src/plugin/event.ts` on `session.deleted`:
64```typescript
65await managers.skillMcpManager.disconnectSession(sessionInfo.id)
66```
67 
68## LIFECYCLE FLOW
69 
70```
711. session.created      → No action (lazy connection)
722. First MCP tool call  → getOrCreateClient() creates + caches
733. Ongoing use          → lastUsedAt timestamp updated
744. Idle >5min           → cleanup timer removes
755. session.deleted      → disconnectSession() closes session clients
766. Process exit         → disconnectAll() via SIGINT/SIGTERM handlers
77```
78 
79## RACE CONDITION PREVENTION
80 
81- **pendingConnections**: Deduplicates concurrent connection attempts for same key
82- **inFlightConnections**: Per-session counter, prevents premature cleanup during connection setup
83- **shutdownGeneration**: Counter-based stale connection detection after disconnect
84 
85## PUBLIC API
86 
87```typescript
88class SkillMcpManager {
89  constructor(options?: { createOAuthProvider? })
90  getOrCreateClient(info, config): Promise<Client>
91  disconnectSession(sessionID): Promise<void>
92  disconnectAll(): Promise<void>
93  listTools/Resources/Prompts(info, context): Promise<...[]>
94  callTool(info, context, name, args): Promise<unknown>
95  readResource(info, context, uri): Promise<unknown>
96  getPrompt(info, context, name, args): Promise<unknown>
97  getConnectedServers(): string[]
98  isConnected(info): boolean
99}
100```
101 
102## RETRY SEMANTICS
103 
104- `getOrCreateClientWithRetry()` — 3 attempts with force reconnect on failure
105- `withOperationRetry()` — OAuth-aware wrapper: step-up on 403, token refresh on 401
106 
107## SECURITY
108 
109- **env-cleaner.ts** — strips npm/pnpm config vars (prevents pnpm project isolation issues) and secret patterns before stdio spawn
110- **error-redaction.ts** — masks tokens/secrets in error messages before logger.log
111- **OAuth isolation** — auth providers keyed by server URL, tokens never cross servers
112