AGENTS.md

1# src/mcp/ — 5 Built-in MCPs
2 
3**Generated:** 2026-05-18
4 
5## OVERVIEW
6 
7Tier 1 of the three-tier MCP system. Built-ins are created by `createBuiltinMcps(disabledMcps, config, options)` and include remote MCPs plus the local `lsp` and `codegraph` stdio MCPs.
8 
9## BUILT-IN MCPs
10 
11| Name | Type | Endpoint / Command | Env Vars | Tools |
12|------|------|--------------------|----------|-------|
13| **websearch** | remote | `mcp.exa.ai` (default) or `mcp.tavily.com` | `EXA_API_KEY` (optional), `TAVILY_API_KEY` (if tavily) | Web search |
14| **context7** | remote | `mcp.context7.com/mcp` | `CONTEXT7_API_KEY` (optional) | Library documentation |
15| **grep_app** | remote | `mcp.grep.app` | None | GitHub code search |
16| **lsp** | local (stdio, node/bun) | `node packages/lsp-tools-mcp/dist/cli.js mcp` or `bun packages/lsp-tools-mcp/src/cli.ts mcp` | `LSP_TOOLS_MCP_PROJECT_CONFIG`, `LSP_TOOLS_MCP_USER_CONFIG`, `LSP_TOOLS_MCP_INSTALL_DECISIONS` | `status`, diagnostics, goto definition, references, symbols, prepare_rename, rename |
17| **codegraph** | local (stdio) | resolved `codegraph serve --mcp` (bundled npm / provisioned `~/.omo/codegraph` / PATH) | `CODEGRAPH_*` (download + telemetry off) | `codegraph_explore`, `codegraph_search`, `codegraph_node`, `codegraph_callers`, `codegraph_callees`, `codegraph_impact`, `codegraph_files`, `codegraph_status` |
18 
19## VENDORED LSP ARCHITECTURE
20 
21- The local `lsp` MCP is vendored at `packages/lsp-tools-mcp/`.
22- `packages/lsp-tools-mcp/` consumes extracted `packages/lsp-core/` + `packages/mcp-stdio-core/`; this directory only builds the OpenCode MCP config.
23- Upstream project: https://github.com/code-yeongyu/lsp-tools-mcp
24- OMO resolves the CLI path dynamically in `src/mcp/lsp.ts` so both `src/` and `dist/` runtime layouts work.
25- `lsp` is registered whenever it is not listed in `disabled_mcps`, even if its CLI artifact has not been built yet. Source checkouts fall back to the Bun source CLI; packaged builds prefer the Node dist CLI.
26- OpenCode supplies exactly three ordered project config paths to the standalone MCP translator: `<cwd>/.opencode/lsp.json`, `<cwd>/.omo/lsp.json`, and `<cwd>/.omo/lsp-client.json`.
27- The user-level inputs are OpenCode config paths: `$XDG_CONFIG_HOME/opencode/lsp.json` for server config and `$XDG_CONFIG_HOME/opencode/lsp-install-decisions.json` for install decisions. The MCP context advertises `installDecisionTool: true`.
28- The shared daemon runtime is configured only through `OMO_LSP_DAEMON_DIR`, or the paired `OMO_LSP_DAEMON_CLI` plus `OMO_LSP_DAEMON_VERSION` override. Source mode runs `packages/lsp-daemon/src/cli.ts` with Bun and sets the paired override; dist mode resolves the public `@code-yeongyu/lsp-daemon/cli` export rather than deep-running generated daemon files.
29 
30## THREE-TIER SYSTEM
31 
32| Tier | Source | Mechanism |
33|------|--------|-----------|
34| 1. Built-in | `src/mcp/` | 3 remote HTTP MCPs + 2 local stdio MCPs (`lsp`, `codegraph`) via `createBuiltinMcps()` |
35| 2. Claude Code | `.mcp.json` | `${VAR}` expansion via `claude-code-mcp-loader` |
36| 3. Skill-embedded | SKILL.md YAML | Managed by `SkillMcpManager` (stdio + HTTP) |
37 
38## FILES
39 
40| File | Purpose |
41|------|---------|
42| `index.ts` | `createBuiltinMcps()` registry for built-in MCPs |
43| `types.ts` | `McpNameSchema`: `"websearch" \| "context7" \| "grep_app" \| "lsp" \| "codegraph"` |
44| `websearch.ts` | Exa/Tavily provider with config |
45| `context7.ts` | Context7 with optional auth header |
46| `grep-app.ts` | Grep.app (no auth) |
47| `lsp.ts` | Local stdio MCP config for packaged `lsp-tools-mcp` |
48| `codegraph.ts` | Local stdio MCP config; resolves/gates the `codegraph` binary (gated by `config.codegraph.enabled`) |
49