docs(agents): refresh AGENTS.md hierarchy via /init-deep

Updated root + 14 core subdirectory AGENTS.md files to reflect current state (commit 2892ca4a on dev). Added 4 new AGENTS.md files for gap directories: hooks/comment-checker (AI slop blocker), features/claude- code-plugin-loader (CC compat layer), features/claude-code-mcp-loader (tier 2 MCP loader), cli/doctor (health diagnostics with 25 check files).
2026-04-18 01:21:20 +09:00
parent 2892ca4adf
commit 5759a9c503
19 changed files with 316 additions and 16 deletions
@@ -0,0 +1,78 @@
+# src/features/claude-code-mcp-loader/ — Tier 2 MCP Loader (.mcp.json)
+
+**Generated:** 2026-04-18
+
+## OVERVIEW
+
+11 files. Loads `.mcp.json` files from project/user scopes and expands `${VAR}` env vars. Feeds Tier 2 of the 3-tier MCP system into `mcp-config-handler.ts` during Phase 5 of config loading.
+
+## WHY IT EXISTS
+
+Claude Code ecosystem ships MCPs via `.mcp.json` files with `${VAR}` env var placeholders. OmO consumes these unchanged so existing Claude Code MCP configs work.
+
+## LOAD PIPELINE
+
+```
+loadMcpConfigs(ctx)
+  → scope-filter.ts: discover .mcp.json at project + user scopes
+  → loader.ts: parse JSON
+  → env-expander.ts: replace ${VAR} with process.env[VAR]
+  → transformer.ts: map Claude Code format → OpenCode McpLocal / McpRemote shape
+  → return LoadedMcpServer[]
+```
+
+## MCP FORMAT
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "my-stdio": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["server.js"],
+      "env": {
+        "API_KEY": "${MY_API_KEY}"
+      }
+    },
+    "my-http": {
+      "type": "http",       // "sse" legacy → mapped to http
+      "url": "https://example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${MY_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Barrel: `loadMcpConfigs`, types |
+| `loader.ts` | `loadMcpConfigs()` main entry |
+| `types.ts` | `ClaudeCodeMcpServer`, `LoadedMcpServer`, `McpScope` |
+| `env-expander.ts` | `expandEnvVarsInObject()` — recursive `${VAR}` substitution |
+| `transformer.ts` | Claude Code format → OpenCode `Mcp` shape |
+| `scope-filter.ts` | Project vs user scope precedence |
+
+## THREE-TIER MCP CONTEXT
+
+| Tier | Loader | Scope |
+|------|--------|-------|
+| 1. Built-in | `src/mcp/` `createBuiltinMcps()` | Global, 3 remote HTTP MCPs |
+| 2. **Claude Code** | **This module** | **From `.mcp.json`, project + user** |
+| 3. Skill-embedded | `src/features/skill-mcp-manager/` | Per-session, from SKILL.md YAML |
+
+## SECURITY
+
+- **Env var allowlist**: `mcp_env_allowlist` config restricts which env vars can be expanded
+- **No shell execution**: `${VAR}` is string replacement only, not shell `$()`
+- **Secrets redaction**: `env-cleaner.ts` (in skill-mcp-manager) filters known secret patterns from logs
+
+## RELATED
+
+- Phase 5 integration: `src/plugin-handlers/mcp-config-handler.ts`
+- Skill-embedded MCPs (Tier 3): `src/features/skill-mcp-manager/`
+- Built-in MCPs (Tier 1): `src/mcp/`