AGENTS.md

1# src/features/claude-code-mcp-loader/ — Tier 2 MCP Loader (.mcp.json)
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
7This module loads `.mcp.json` files from project/user scopes and expands `${VAR}` env vars. It feeds Tier 2 of the 3-tier MCP system into `mcp-config-handler.ts` during Phase 5 of config loading. Shared parsing, env expansion, and transform primitives are extracted to [`packages/claude-code-compat-core/`](../../../../../packages/claude-code-compat-core); this directory keeps the OpenCode adapter path stable.
8 
9## WHY IT EXISTS
10 
11Claude Code ecosystem ships MCPs via `.mcp.json` files with `${VAR}` env var placeholders. OmO consumes these unchanged so existing Claude Code MCP configs work.
12 
13## LOAD PIPELINE
14 
15```
16loadMcpConfigs(ctx)
17  → scope-filter.ts: discover .mcp.json at project + user scopes
18  → loader.ts: parse JSON
19  → env-expander.ts: replace ${VAR} with process.env[VAR]
20  → transformer.ts: map Claude Code format → OpenCode McpLocal / McpRemote shape
21  → return LoadedMcpServer[]
22```
23 
24## MCP FORMAT
25 
26```jsonc
27// .mcp.json
28{
29  "mcpServers": {
30    "my-stdio": {
31      "type": "stdio",
32      "command": "node",
33      "args": ["server.js"],
34      "env": {
35        "API_KEY": "${MY_API_KEY}"
36      }
37    },
38    "my-http": {
39      "type": "http",       // "sse" legacy → mapped to http
40      "url": "https://example.com/mcp",
41      "headers": {
42        "Authorization": "Bearer ${MY_TOKEN}"
43      }
44    }
45  }
46}
47```
48 
49## KEY FILES
50 
51| File | Purpose |
52|------|---------|
53| `index.ts` | Barrel: `loadMcpConfigs`, types |
54| `loader.ts` | `loadMcpConfigs()` main entry |
55| `types.ts` | `ClaudeCodeMcpServer`, `LoadedMcpServer`, `McpScope` |
56| `env-expander.ts` | `expandEnvVarsInObject()` — recursive `${VAR}` substitution |
57| `transformer.ts` | Claude Code format → OpenCode `Mcp` shape |
58| `scope-filter.ts` | Project vs user scope precedence |
59 
60## THREE-TIER MCP CONTEXT
61 
62| Tier | Loader | Scope |
63|------|--------|-------|
64| 1. Built-in | `src/mcp/` `createBuiltinMcps()` | Global, 3 remote HTTP MCPs + 2 local stdio MCPs (`lsp`, `codegraph`) |
65| 2. **Claude Code** | **This module** | **From `.mcp.json`, project + user** |
66| 3. Skill-embedded | `src/features/skill-mcp-manager/` | Per-session, from SKILL.md YAML |
67 
68## SECURITY
69 
70- **Env var allowlist**: `mcp_env_allowlist` config restricts which env vars can be expanded
71- **No shell execution**: `${VAR}` is string replacement only, not shell `$()`
72- **Secrets redaction**: `env-cleaner.ts` (in skill-mcp-manager) filters known secret patterns from logs
73 
74## RELATED
75 
76- Phase 5 integration: `src/plugin-handlers/mcp-config-handler.ts`
77- Skill-embedded MCPs (Tier 3): `src/features/skill-mcp-manager/`
78- Built-in MCPs (Tier 1): `src/mcp/`
79