AGENTS.md

1# mcp-client-core — MCP Client + Skill-Embedded MCP (Core)
2 
3**Generated:** 2026-06-16
4 
5## OVERVIEW
6 
7Harness-neutral MCP client lifecycle and OAuth primitives. Consumed by `omo-opencode` via `features/skill-mcp-manager` and `features/mcp-oauth` / `cli/mcp-oauth`. Private package `@oh-my-opencode/mcp-client-core`; 30 source files under `src/`.
8 
9## KEY FILES
10 
11| File | Role |
12|------|------|
13| `skill-mcp-manager/manager.ts` | `SkillMcpManager` — per-session client registry, listTools/callTool/readResource/getPrompt, retry loop with OAuth step-up |
14| `skill-mcp-manager/connection.ts` | `getOrCreateClient()` / `getOrCreateClientWithRetryImpl()` — race-safe connection, dispatch to stdio or HTTP |
15| `skill-mcp-manager/stdio-client.ts` | `createStdioClient()` — `StdioClientTransport`, env cleaning, process cleanup registration |
16| `skill-mcp-manager/http-client.ts` | `createHttpClient()` — `StreamableHTTPClientTransport`, request init with OAuth headers, URL redaction |
17| `skill-mcp-manager/oauth-handler.ts` | `buildHttpRequestInit()`, `handleStepUpIfNeeded()`, `handlePostRequestAuthError()` — token refresh, scope merge, 401/403 retry |
18| `skill-mcp-manager/cleanup.ts` | `disconnectSession()`, `disconnectAll()`, `forceReconnect()`, idle timeout (5 min), SIGTERM/SIGINT handlers |
19| `skill-mcp-manager/types.ts` | `SkillMcpClientInfo`, `ManagedClient`, `ConnectionType`, `SkillMcpManagerState` |
20| `mcp-oauth/provider.ts` | `McpOAuthProvider` — login (DCR + PKCE redirect), refresh, token storage |
21| `mcp-oauth/oauth-authorization-flow.ts` | PKCE verifier/challenge, browser open, 5-min timeout |
22| `mcp-oauth/discovery.ts` | `discoverOAuthServerMetadata()` — `.well-known/oauth-protected-resource` + `oauth-authorization-server` with cache |
23| `mcp-oauth/dcr.ts` | `getOrRegisterClient()` — Dynamic Client Registration, fallback to static clientId |
24| `mcp-oauth/step-up.ts` | `isStepUpRequired()`, `mergeScopes()`, `parseWwwAuthenticate()` — 403 scope escalation |
25| `mcp-oauth/callback-server.ts` | `findAvailablePort()`, `startCallbackServer()` for local OAuth callback |
26| `mcp-oauth/storage.ts` | `loadToken()` / `saveToken()` — keyed by server URL |
27| `index.ts` | Barrel: re-exports `mcp-oauth/*` and `skill-mcp-manager/*` |
28 
29## NOTES
30 
31- **Per-session isolation:** client key is `${sessionID}:${skillName}:${serverName}`. The same skill in two sessions does not share state.
32- **Transports:** stdio (local process via `StdioClientTransport`) and HTTP (remote via `StreamableHTTPClientTransport`). Connection type inferred from `url` vs `command`, or explicit `type` field.
33- **OAuth flow:** PKCE + optional DCR. Step-up authentication on 403 merges new scopes and re-authenticates. Refresh mutex prevents concurrent refresh storms.
34- **Cleanup:** idle clients evicted after 5 minutes. Process signal handlers close all transports on SIGINT/SIGTERM. `disconnectAll()` is safe across plugin reloads.
35- **Consumers:** `packages/omo-opencode/src/features/skill-mcp-manager/`, `packages/omo-opencode/src/features/mcp-oauth/`, and `packages/omo-opencode/src/cli/mcp-oauth/` import this Core package.
36 
37Parent: [`packages/AGENTS.md`](../AGENTS.md)
38