From d8f6d59dc249c01c2fec85870c283fb0b1a68a4a Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Mon, 18 May 2026 21:20:13 +0900 Subject: [PATCH] docs: update rules and MCP inventories Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- AGENTS.md | 8 ++++---- docs/reference/configuration.md | 4 ++-- docs/reference/features.md | 6 +++++- src/AGENTS.md | 4 ++-- src/mcp/AGENTS.md | 12 +++++++----- src/plugin/AGENTS.md | 3 +-- src/tools/AGENTS.md | 11 +++++------ 7 files changed, 26 insertions(+), 22 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c2978da33..f6dd44e67 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/ # 15 native tool dirs; LSP tools now served via built-in MCP +│ ├── tools/ # 13 native tool dirs; LSP + AST-grep now served via built-in MCPs │ ├── 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/ # 4 built-in MCPs (3 remote + local stdio lsp) +│ ├── mcp/ # 5 built-in MCPs (3 remote + local stdio lsp + ast_grep) │ ├── 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,7 +87,7 @@ 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 `packages/lsp-tools-mcp`), preserving existing names through OpenCode MCP namespacing. +> Note: `lsp_*` and `ast_grep_*` tool names are now served by built-in MCP servers (`lsp` via `packages/lsp-tools-mcp`, `ast_grep` via `packages/ast-grep-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`). @@ -148,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 + 1 local stdio MCP (`lsp`) | +| 1. Built-in | `src/mcp/` | `createBuiltinMcps()` | 3 remote HTTP + 2 local stdio MCPs (`lsp`, `ast_grep`) | | 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 | diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index dd28c4e4f..0a2c33f25 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -614,10 +614,10 @@ Force-enable session notifications: ### MCPs -Built-in MCPs (enabled by default): `websearch` (Exa AI), `context7` (library docs), `grep_app` (GitHub code search). +Built-in MCPs (enabled by default): `websearch` (Exa AI), `context7` (library docs), `grep_app` (GitHub code search), `lsp` (local language-server tools), and `ast_grep` (local structural search/rewrite tools). ```json -{ "disabled_mcps": ["websearch", "context7", "grep_app"] } +{ "disabled_mcps": ["websearch", "context7", "grep_app", "lsp", "ast_grep"] } ``` ### LSP diff --git a/docs/reference/features.md b/docs/reference/features.md index c0c37d841..6d30ac907 100644 --- a/docs/reference/features.md +++ b/docs/reference/features.md @@ -611,6 +611,8 @@ Hashline IDs use characters from `ZPMQVRWSNKTXJBYH`. ### AST-Grep Tools +These user-facing tool names are served by the built-in local `ast_grep` MCP backed by `packages/ast-grep-mcp/`. + | Tool | Description | | -------------------- | -------------------------------------------- | | **ast_grep_search** | AST-aware code pattern search (25 languages) | @@ -905,7 +907,7 @@ Disable specific hooks in config: The plugin uses a three-tier MCP architecture: -1. Built-in remote MCPs from `src/mcp/` +1. Built-in MCPs from `src/mcp/` (remote plus local stdio) 2. Claude Code `.mcp.json` loader with `${VAR}` expansion 3. Skill-embedded MCP servers declared in `SKILL.md` frontmatter @@ -916,6 +918,8 @@ The plugin uses a three-tier MCP architecture: | **websearch** | Real-time web search powered by Exa AI | | **context7** | Official documentation lookup for any library/framework | | **grep_app** | Ultra-fast code search across public GitHub repos. Great for finding implementation examples. | +| **lsp** | Local LSP tools for diagnostics, symbols, references, and renames | +| **ast_grep** | Local AST-aware search and rewrite tools | ### Skill-Embedded MCPs diff --git a/src/AGENTS.md b/src/AGENTS.md index 5f1631628..f96ee65b7 100644 --- a/src/AGENTS.md +++ b/src/AGENTS.md @@ -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 | 14 native tool dirs (+1 shared utilities dir); LSP moved to built-in MCP | yes (+ ast-grep, background-task, call-omo-agent, delegate-task, hashline-edit, look-at, skill) | +| `tools/` | 317 | ~45k | 13 native tool dirs (+1 shared utilities dir); LSP + AST-grep moved to built-in MCPs | yes (+ 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/` | 8 | ~260 | 4 built-in MCPs (3 remote + local stdio lsp) | yes | +| `mcp/` | 8 | ~260 | 5 built-in MCPs (3 remote + local stdio lsp + ast_grep) | yes | | `testing/` | 3 | ~225 | Test utilities | — | ## NOTES diff --git a/src/mcp/AGENTS.md b/src/mcp/AGENTS.md index ef27f15f0..ec928cc7a 100644 --- a/src/mcp/AGENTS.md +++ b/src/mcp/AGENTS.md @@ -1,10 +1,10 @@ -# src/mcp/ — 4 Built-in MCPs +# src/mcp/ — 5 Built-in MCPs **Generated:** 2026-05-18 ## OVERVIEW -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. +Tier 1 of the three-tier MCP system. Built-ins are created by `createBuiltinMcps(disabledMcps, config, options)` and now include both remote MCPs and local stdio MCPs. ## BUILT-IN MCPs @@ -14,19 +14,20 @@ Tier 1 of the three-tier MCP system. Built-ins are created by `createBuiltinMcps | **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/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=.opencode/lsp.json` | `status`, diagnostics, goto definition, references, symbols, prepare_rename, rename | +| **ast_grep** | local (stdio, node/bun) | `node packages/ast-grep-mcp/dist/cli.js mcp` or `bun packages/ast-grep-mcp/src/cli.ts mcp` | `OMO_AST_GREP_WORKSPACE=` | `search`, `replace` | ## SUBMODULE ARCHITECTURE - The local `lsp` MCP is a git submodule at `packages/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. -- `lsp` is registered whenever it is not listed in `disabled_mcps`, even if the CLI artifact has not been built yet. Source checkouts fall back to the Bun source CLI; packaged builds prefer the Node dist CLI. +- `lsp` and `ast_grep` are registered whenever they are not listed in `disabled_mcps`, even if their CLI artifacts have not been built yet. Source checkouts fall back to the Bun source CLI; packaged builds prefer the Node dist CLI. ## THREE-TIER SYSTEM | Tier | Source | Mechanism | |------|--------|-----------| -| 1. Built-in | `src/mcp/` | 3 remote HTTP MCPs + 1 local stdio MCP (`lsp`) via `createBuiltinMcps()` | +| 1. Built-in | `src/mcp/` | 3 remote HTTP MCPs + 2 local stdio MCPs (`lsp`, `ast_grep`) 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) | @@ -35,8 +36,9 @@ Tier 1 of the three-tier MCP system. Built-ins are created by `createBuiltinMcps | File | Purpose | |------|---------| | `index.ts` | `createBuiltinMcps()` registry for built-in MCPs | -| `types.ts` | `McpNameSchema`: `"websearch" \| "context7" \| "grep_app" \| "lsp"` | +| `types.ts` | `McpNameSchema`: `"websearch" \| "context7" \| "grep_app" \| "lsp" \| "ast_grep"` | | `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 packaged `lsp-tools-mcp` | +| `ast-grep.ts` | Local stdio MCP config for packaged `ast-grep-mcp` | diff --git a/src/plugin/AGENTS.md b/src/plugin/AGENTS.md index 31b975e82..e568134bf 100644 --- a/src/plugin/AGENTS.md +++ b/src/plugin/AGENTS.md @@ -62,7 +62,6 @@ const interactiveBashTool = interactiveBashEnabled ? { interactive_bash } : {} const allTools = { ...createGrepTools(ctx), ...createGlobTools(ctx), - ...createAstGrepTools(ctx), ...createSessionManagerTools(ctx), ...backgroundTools, // 2 background_* call_omo_agent, task, @@ -74,7 +73,7 @@ const allTools = { ...hashlineToolsRecord, // +1 conditional } -// lsp_* tools are now supplied by built-in MCP server "lsp" +// lsp_* and ast_grep_* tools are supplied by built-in MCP servers "lsp" and "ast_grep" ``` ## KEY PATTERNS diff --git a/src/tools/AGENTS.md b/src/tools/AGENTS.md index 0ddddac90..9d8f3d17f 100644 --- a/src/tools/AGENTS.md +++ b/src/tools/AGENTS.md @@ -1,24 +1,24 @@ -# src/tools/ — 14–33 Native Tools Across 14 Tool Directories (+ shared utilities) +# src/tools/ — 12–31 Native Tools Across 13 Tool Directories (+ shared utilities) **Generated:** 2026-05-15 ## OVERVIEW -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.). +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 and AST-grep tools are no longer native `src/tools/` implementations; they are served by Tier-1 built-in MCPs `lsp` and `ast_grep` and keep the same exposed names (`lsp_diagnostics`, `ast_grep_search`, etc.). ## TOOL CATALOG -### Always On (14 native tools) +### Always On (12 native tools) | Group | Tools | |-------|-------| -| **Search** (4) | `grep`, `glob`, `ast_grep_search`, `ast_grep_replace` | +| **Search** (2) | `grep`, `glob` | | **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) | -> LSP tools are now provided by built-in MCP server `lsp` (Tier-1 stdio), backed by `packages/lsp-tools-mcp/`. OpenCode-compatible aliases remain available (`lsp_status`, `lsp_diagnostics`, `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_prepare_rename`, `lsp_rename`). +> LSP and AST-grep tools are now provided by built-in MCP servers `lsp` and `ast_grep` (Tier-1 stdio), backed by `packages/lsp-tools-mcp/` and `packages/ast-grep-mcp/`. OpenCode-compatible aliases remain available (`lsp_status`, `lsp_diagnostics`, `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_prepare_rename`, `lsp_rename`, `ast_grep_search`, `ast_grep_replace`). ### Conditional (up to +19 native tools) @@ -68,7 +68,6 @@ User-defined categories declared in `categories: { ... }` config override and ex ``` tools/ -├── ast-grep/ # ast_grep_search, ast_grep_replace ├── background-task/ # background_output, background_cancel (LLM interface; engine in features/background-agent) ├── call-omo-agent/ # call_omo_agent (explore + librarian only) ├── delegate-task/ # task — full delegation with categories + skills