AGENTS.md

1# packages/ast-grep-mcp - ast-grep stdio MCP
2 
3## OVERVIEW
4 
5Local stdio MCP server (`@oh-my-opencode/ast-grep-mcp`, private, bin `omo-ast-grep`) exposing structural code search/rewrite via the `sg` (ast-grep) CLI. Server name `ast_grep`, 3 tools: `search`, `rewrite`, `scan`. Built on `mcp-stdio-core` + `utils`.
6 
7## STRUCTURE
8 
9```
10src/
11├── cli.ts          # stdio entry (bundled to dist/cli.js by `bun run build`)
12├── index.ts        # barrel: AST_GREP_MCP_NAME + mcp exports
13├── mcp.ts          # tool defs, JSON-RPC handling, runMcpStdioServer
14├── sg-runner.ts    # spawns sg with JSON output, bounded timeout
15├── normalize.ts    # match/diagnostic normalization
16├── pattern-hints.ts# rejects likely-invalid patterns ($$NAME etc.); `force` bypasses
17└── tools/          # search.ts / rewrite.ts / scan.ts implementations
18```
19 
20## WHERE TO LOOK
21 
22| Task | Location |
23|------|----------|
24| Add/modify a tool schema | `src/mcp.ts` (tool defs) + `src/tools/*.ts` |
25| sg process invocation, timeouts | `src/sg-runner.ts` |
26| Pattern validation hints | `src/pattern-hints.ts` |
27| Senpi plugin staging | `packages/omo-senpi/plugin/scripts/stage-ast-grep-mcp-runtime.mjs` (copies `dist/cli.js` to plugin `runtime/ast-grep-mcp/`) |
28 
29## CONVENTIONS
30 
31- Rewrite/scan apply is two-phase: bounded JSON preview first, then a separate `--update-all` pass; truncated previews are never applied.
32- `rewrite` may only reference metavariables captured by the pattern; empty replacement deletes the match.
33- Byte-counted limits: pattern 16 KiB, rewrite/inlineRules 64 KiB (UTF-8 bytes, not chars).
34- Build with `bun run build:ast-grep-mcp` (root) before staging into the senpi plugin (`build:senpi-plugin` chains it).
35 
36## ANTI-PATTERNS
37 
38- Never combine JSON output and mutation in one `sg` invocation (sg cannot do both safely).
39- No ambient `sgconfig.yml` discovery in `scan`: exactly one explicit rule source (`ruleFile` XOR `inlineRules`).
40