luna/oh-my-opencode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update AGENTS docs for MCP-backed LSP architecture

Browse Source
This commit is contained in:
YeonGyu-Kim
2026-05-18 12:13:21 +09:00
parent 54eb3963af
commit b149ce5331
7 changed files with 36 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+7 -5
View File
@@ -19,12 +19,12 @@ oh-my-opencode/
│ ├── create-hooks.ts # 5-tier hook composition
│ ├── agents/ # 11 agents (Sisyphus, Hephaestus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus, Multimodal-Looker, Sisyphus-Junior)
│ ├── hooks/ # ~52 lifecycle hooks across 59 dirs (incl. 5 zauc-mocks + 1 shared + 1 `.sisyphus/` legacy state)
│ ├── tools/ # 16 tool dirs; produces 20–39 tools (config-gated)
│ ├── tools/ # 15 native tool dirs; LSP tools now served via built-in MCP
│ ├── features/ # 20 feature modules (incl. team-mode, background-agent, skill-mcp-manager, opencode-skill-loader, tmux-subagent, mcp-oauth, claude-code-plugin-loader, boulder-state, etc.)
│ ├── shared/ # 278 utility files (170 non-test); logger → oh-my-opencode.log in os.tmpdir() (50 MB cap, .1/.2 backups)
│ ├── config/ # Zod v4 schema system (30 schema files)
│ ├── cli/ # CLI: install, run, doctor, mcp-oauth, refresh-model-capabilities, get-local-version, boulder
│ ├── mcp/ # 3 built-in remote MCPs (websearch, context7, grep_app)
│ ├── mcp/ # 4 built-in MCPs (3 remote + local stdio lsp)
│ ├── plugin/ # 10 OpenCode hook handlers + 5-tier hook composition
│ ├── plugin-handlers/ # 6-phase config loading pipeline
│ ├── openclaw/ # Bidirectional external integration (Discord/Telegram/HTTP/shell + reply listener daemon)
@@ -87,6 +87,8 @@ pluginModule.server(input, options)
**Always on (20):** `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_diagnostics`, `lsp_prepare_rename`, `lsp_rename`, `grep`, `glob`, `ast_grep_search`, `ast_grep_replace`, `session_list`, `session_read`, `session_search`, `session_info`, `background_output`, `background_cancel`, `call_omo_agent`, `task` (delegate), `skill`, `skill_mcp`.
> Note: `lsp_*` tool names are now served by built-in MCP server `lsp` (via `vendor/lsp-tools-mcp`), preserving existing names through OpenCode MCP namespacing.
**Conditional:** `look_at` (+1, multimodal-looker not disabled), `interactive_bash` (+1, `tmux` binary available on PATH via `isInteractiveBashEnabled()`), `task_create`/`task_get`/`task_list`/`task_update` (+4, `experimental.task_system`), `edit` (+1, `hashline_edit`), `team_create`/`team_delete`/`team_shutdown_request`/`team_approve_shutdown`/`team_reject_shutdown`/`team_send_message`/`team_task_create`/`team_task_list`/`team_task_update`/`team_task_get`/`team_status`/`team_list` (+12, `team_mode.enabled`).
## TEAM MODE
@@ -146,7 +148,7 @@ Schema autocomplete: `"$schema": "https://raw.githubusercontent.com/code-yeongyu
| Tier | Source | Loader | Mechanism |
|------|--------|--------|-----------|
| 1. Built-in | `src/mcp/` | `createBuiltinMcps()` | 3 remote HTTP: websearch (Exa/Tavily), context7, grep_app |
| 1. Built-in | `src/mcp/` | `createBuiltinMcps()` | 3 remote HTTP + 1 local stdio MCP (`lsp`) |
| 2. Claude Code | `.mcp.json` (project + user) | `claude-code-mcp-loader` | `${VAR}` env expansion (allowlist via `mcp_env_allowlist`) |
| 3. Skill-embedded | SKILL.md YAML frontmatter | `SkillMcpManager` (per-session) | stdio + HTTP, OAuth 2.0 + PKCE + DCR step-up |
@@ -156,9 +158,9 @@ Schema autocomplete: `"$schema": "https://raw.githubusercontent.com/code-yeongyu
|------|----------|-------|
| Add new agent | `src/agents/` + `src/agents/builtin-agents/` | `createXXXAgent` factory + `mode: "primary" \| "subagent" \| "all"` |
| Add new hook | `src/hooks/{name}/` + register in `src/plugin/hooks/create-*-hooks.ts` | Pick the right tier (Session/ToolGuard/Transform/Continuation/Skill) |
| Add new tool | `src/tools/{name}/` + register in `src/plugin/tool-registry.ts` | Factory `createXXXTool` (most) or direct `ToolDefinition` (LSP, interactive_bash) |
| Add new tool | `src/tools/{name}/` + register in `src/plugin/tool-registry.ts` | Factory `createXXXTool` (most) or direct `ToolDefinition` (interactive_bash) |
| Add new feature module | `src/features/{name}/` | Standalone module wired into `plugin/` layer |
| Add new MCP (tier 1) | `src/mcp/` + register in `createBuiltinMcps()` | Remote HTTP only |
| Add new MCP (tier 1) | `src/mcp/` + register in `createBuiltinMcps()` | Remote HTTP or local stdio |
| Add new built-in skill | `src/features/builtin-skills/skills/{name}.ts` + register in `skills.ts` | Implement `BuiltinSkill` interface |
| Add new command | `src/features/builtin-commands/` | Templates in `templates/` |
| Add new CLI subcommand | `src/cli/cli-program.ts` | Commander.js subcommand |
src/AGENTS.md
+2 -2
View File
@@ -90,7 +90,7 @@ Total: 54 base, 61 with team-mode. Each tier produces an object whose values are
|--------|-------------|-----|---------|---------------|
| `agents/` | 104 | ~20k | 11 agent factories + dynamic prompt builder | yes (+ atlas, hephaestus, prometheus, sisyphus, sisyphus-junior, builtin-agents) |
| `hooks/` | 596 | ~78k | ~52 lifecycle hooks across 58 dirs | yes (+ atlas, anthropic-context-window-limit-recovery, auto-update-checker, claude-code-hooks, comment-checker, compaction-context-injector, keyword-detector, ralph-loop, rules-injector, runtime-fallback, session-recovery, todo-continuation-enforcer) |
| `tools/` | 317 | ~45k | 16 tool dirs producing 20–39 tools | yes (+ ast-grep, background-task, call-omo-agent, delegate-task, hashline-edit, look-at, lsp, skill) |
| `tools/` | 317 | ~45k | 15 native tool dirs (LSP moved to built-in MCP) producing 14–33 native tools | yes (+ ast-grep, background-task, call-omo-agent, delegate-task, hashline-edit, look-at, skill) |
| `features/` | 404 | ~71k | 20 feature modules (team-mode, background-agent, boulder-state, etc.) | yes (+ 11 sub-AGENTS.md including builtin-skills, team-mode, background-agent, claude-code-*) |
| `shared/` | 290 | ~33k | Cross-cutting utilities, barrel-exported | yes |
| `cli/` | 158 | ~18k | Commander.js CLI: install, run, doctor, mcp-oauth, boulder | yes (+ config-manager, doctor, run) |
@@ -99,7 +99,7 @@ Total: 54 base, 61 with team-mode. Each tier produces an object whose values are
| `plugin-handlers/` | 27 | ~6k | 6-phase config loading pipeline | yes |
| `openclaw/` | 26 | ~3k | Bidirectional Discord/Telegram/HTTP integration | yes |
| `__tests__/` | 22 | ~300 | Plugin-level integration tests + perf fixtures | — |
| `mcp/` | 7 | ~200 | 3 built-in remote MCPs | yes |
| `mcp/` | 8 | ~260 | 4 built-in MCPs (3 remote + local stdio lsp) | yes |
| `testing/` | 3 | ~225 | Test utilities | — |
## NOTES
src/features/claude-code-mcp-loader/AGENTS.md
+1 -1
View File
@@ -61,7 +61,7 @@ loadMcpConfigs(ctx)
| Tier | Loader | Scope |
|------|--------|-------|
| 1. Built-in | `src/mcp/` `createBuiltinMcps()` | Global, 3 remote HTTP MCPs |
| 1. Built-in | `src/mcp/` `createBuiltinMcps()` | Global, 3 remote HTTP MCPs + local stdio `lsp` |
| 2. **Claude Code** | **This module** | **From `.mcp.json`, project + user** |
| 3. Skill-embedded | `src/features/skill-mcp-manager/` | Per-session, from SKILL.md YAML |
src/features/skill-mcp-manager/AGENTS.md
+1 -1
View File
@@ -10,7 +10,7 @@
| Tier | Manager | Scope |
|------|---------|-------|
| 1. Built-in | `createBuiltinMcps()` (src/mcp/) | Global, 3 remote HTTP |
| 1. Built-in | `createBuiltinMcps()` (src/mcp/) | Global, 3 remote HTTP + 1 local stdio (`lsp`) |
| 2. Claude Code | `claude-code-mcp-loader` (src/features/) | From `.mcp.json` |
| 3. **Skill-embedded** | **`SkillMcpManager` (this module)** | **Per-session, from SKILL.md YAML** |
src/mcp/AGENTS.md
+17 -34
View File
@@ -1,49 +1,31 @@
# src/mcp/ — 3 Built-in Remote MCPs
# src/mcp/ — 4 Built-in MCPs
**Generated:** 2026-05-15
**Generated:** 2026-05-18
## OVERVIEW
Tier 1 of the three-tier MCP system. 3 remote HTTP MCPs created via `createBuiltinMcps(disabledMcps, config)`.
Tier 1 of the three-tier MCP system. Built-ins are created by `createBuiltinMcps(disabledMcps, config)` and now include both remote MCPs and one local stdio MCP.
## BUILT-IN MCPs
| Name | URL | Env Vars | Tools |
|------|-----|----------|-------|
| **websearch** | `mcp.exa.ai` (default) or `mcp.tavily.com` | `EXA_API_KEY` (optional), `TAVILY_API_KEY` (if tavily) | Web search |
| **context7** | `mcp.context7.com/mcp` | `CONTEXT7_API_KEY` (optional) | Library documentation |
| **grep_app** | `mcp.grep.app` | None | GitHub code search |
| Name | Type | Endpoint / Command | Env Vars | Tools |
|------|------|--------------------|----------|-------|
| **websearch** | remote | `mcp.exa.ai` (default) or `mcp.tavily.com` | `EXA_API_KEY` (optional), `TAVILY_API_KEY` (if tavily) | Web search |
| **context7** | remote | `mcp.context7.com/mcp` | `CONTEXT7_API_KEY` (optional) | Library documentation |
| **grep_app** | remote | `mcp.grep.app` | None | GitHub code search |
| **lsp** | local (stdio, node) | `node vendor/lsp-tools-mcp/dist/cli.js mcp` | `LSP_TOOLS_MCP_PROJECT_CONFIG=.opencode/lsp.json` | `status`, diagnostics, goto definition, references, symbols, prepare_rename, rename |
## REGISTRATION PATTERN
## SUBMODULE ARCHITECTURE
```typescript
// Static export (context7, grep_app)
export const context7 = {
type: "remote" as const,
url: "https://mcp.context7.com/mcp",
enabled: true,
oauth: false as const,
}
// Factory with config (websearch)
export function createWebsearchConfig(config?: WebsearchConfig): RemoteMcpConfig
```
## ENABLE/DISABLE
```jsonc
// Method 1: disabled_mcps array
{ "disabled_mcps": ["websearch", "context7"] }
// Method 2: enabled flag
{ "mcp": { "websearch": { "enabled": false } } }
```
- The local `lsp` MCP is vendored as a git submodule at `vendor/lsp-tools-mcp/`.
- Upstream project: https://github.com/code-yeongyu/lsp-tools-mcp
- OMO resolves the CLI path dynamically in `src/mcp/lsp.ts` so both `src/` and `dist/` runtime layouts work.
## THREE-TIER SYSTEM
| Tier | Source | Mechanism |
|------|--------|-----------|
| 1. Built-in | `src/mcp/` | 3 remote HTTP, created by `createBuiltinMcps()` |
| 1. Built-in | `src/mcp/` | 3 remote HTTP MCPs + 1 local stdio MCP (`lsp`) via `createBuiltinMcps()` |
| 2. Claude Code | `.mcp.json` | `${VAR}` expansion via `claude-code-mcp-loader` |
| 3. Skill-embedded | SKILL.md YAML | Managed by `SkillMcpManager` (stdio + HTTP) |
@@ -51,8 +33,9 @@ export function createWebsearchConfig(config?: WebsearchConfig): RemoteMcpConfig
| File | Purpose |
|------|---------|
| `index.ts` | `createBuiltinMcps()` factory |
| `types.ts` | `McpNameSchema`: "websearch" \| "context7" \| "grep_app" |
| `index.ts` | `createBuiltinMcps()` registry for built-in MCPs |
| `types.ts` | `McpNameSchema`: `"websearch" \| "context7" \| "grep_app" \| "lsp"` |
| `websearch.ts` | Exa/Tavily provider with config |
| `context7.ts` | Context7 with optional auth header |
| `grep-app.ts` | Grep.app (no auth) |
| `lsp.ts` | Local stdio MCP config for vendored `lsp-tools-mcp` |
src/plugin/AGENTS.md
+2 -1
View File
@@ -60,7 +60,6 @@ const lookAt = isMultimodalLookerEnabled ? { look_at: createLookAt(ctx) } : {}
const interactiveBashTool = interactiveBashEnabled ? { interactive_bash } : {}
const allTools = {
...builtinTools, // 6 LSP
...createGrepTools(ctx),
...createGlobTools(ctx),
...createAstGrepTools(ctx),
@@ -74,6 +73,8 @@ const allTools = {
...taskToolsRecord, // +4 conditional
...hashlineToolsRecord, // +1 conditional
}
// lsp_* tools are now supplied by built-in MCP server "lsp"
```
## KEY PATTERNS
src/tools/AGENTS.md
+6 -6
View File
@@ -1,25 +1,26 @@
# src/tools/ — 20–39 Tools Across 16 Directories
# src/tools/ — 14–33 Native Tools Across 15 Directories
**Generated:** 2026-05-15
## OVERVIEW
Tools registered via [`createToolRegistry()`](file:///Users/yeongyu/local-workspaces/omo/src/plugin/tool-registry.ts) in `src/plugin/`. Two patterns: factory functions (`createXXXTool`) for most tools, direct `ToolDefinition` exports for the 6 LSP tools and `interactive_bash`. The total exposed count varies between 20 (minimum) and 39 (with all flags on) based on config gates listed below.
Tools registered via [`createToolRegistry()`](file:///Users/yeongyu/local-workspaces/omo/src/plugin/tool-registry.ts) in `src/plugin/`. Native tools are factory-based (`createXXXTool`) except `interactive_bash` (`ToolDefinition`). LSP tools are no longer native `src/tools/` implementations; they are served by Tier-1 built-in MCP `lsp` and keep the same exposed names (`lsp_diagnostics`, `lsp_goto_definition`, etc.).
## TOOL CATALOG
### Always On (20)
### Always On (14 native tools)
| Group | Tools |
|-------|-------|
| **LSP** (6) | `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_diagnostics`, `lsp_prepare_rename`, `lsp_rename` |
| **Search** (4) | `grep`, `glob`, `ast_grep_search`, `ast_grep_replace` |
| **Sessions** (4) | `session_list`, `session_read`, `session_search`, `session_info` |
| **Background tasks** (2) | `background_output`, `background_cancel` |
| **Delegation** (2) | `task` (delegate, full skill+category support), `call_omo_agent` (named agent only: explore, librarian) |
| **Skills/MCP** (2) | `skill` (load skill or invoke command), `skill_mcp` (call skill-embedded MCP tool/resource/prompt) |
### Conditional (up to +19)
> LSP tools (`lsp_status`, `lsp_diagnostics`, `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_prepare_rename`, `lsp_rename`) are now provided by built-in MCP server `lsp` (Tier-1 stdio), backed by `vendor/lsp-tools-mcp/`.
### Conditional (up to +19 native tools)
| Tool(s) | Gate | Source |
|---------|------|--------|
@@ -76,7 +77,6 @@ tools/
├── hashline-edit/ # edit — hash-anchored line edits with LINE#ID validation
├── interactive-bash/ # interactive_bash — tmux session control
├── look-at/ # look_at — image/PDF analysis
├── lsp/ # 6 LSP tools (direct ToolDefinition)
├── session-manager/ # 4 session_* tools
├── skill/ # skill — load skill or run command
├── skill-mcp/ # skill_mcp — call skill-embedded MCP servers