Skip to content

Commit 5f2c6a2

Browse files
committed
docs(plans): settle Q-1 — show ships as a dedicated MCP tool
Mirrors the every-verb-becomes-a-tool pattern from PR #35. Discoverability win matters for agents that don't know the symbols schema; token savings compound. ~25 LOC registration; reuses the engine helper.
1 parent 002ef7b commit 5f2c6a2

1 file changed

Lines changed: 1 addition & 2 deletions

File tree

docs/plans/targeted-read-cli.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -114,11 +114,10 @@ Estimated total: ~half day across 4 commits.
114114

115115
### Settled
116116

117-
_None yet — see § 8 for the grill round before code._
117+
- **Q-1. MCP `show` tool?****(a) Dedicated MCP tool.** Every CLI verb maps to an MCP tool today (set in PR [#35](https://github.com/stainless-code/codemap/pull/35)) — `show` joins the pattern. Discoverability is the killer feature: agents reading `tools/list` see `show` exists without needing the SQL schema. Token savings compound at scale (~50 tokens/call vs the equivalent `query({sql: …})` for agents doing precise reads hundreds of times per session). Cost is trivial (~25 LOC; reuses engine helper). Output shape stays uniform with the CLI's `show --json` per plan § 4.
118118

119119
### Still open
120120

121-
- **Q-1. MCP `show` tool — separate from `query`?** Three options: (a) Ship `show` as a dedicated MCP tool (parallels CLI 1:1); (b) Skip MCP — agents call `query` with the SQL directly (one fewer tool to discover); (c) Add `show` only as a tool description hint, no separate registration. Bias toward (a) — uniform with how every other CLI verb maps to an MCP tool, plus the discoverability win is real (the tool listing teaches the agent `show` exists).
122121
- **Q-2. Multiple matches — error or list-with-confirm?** Current proposal: error unless `--all` is set. Alternative: always list, prefix the first row with a "(N matches; use --kind to narrow)" hint. Bias toward "error by default" — agents that get a list back on a `name=foo` query may pick the wrong row; an explicit error forces them to add `--kind` or `--all`.
123122
- **Q-3. Exact-match only or substring/regex?** Current proposal: `name = ?` exact match. Alternative: `name LIKE '%<name>%'` for fuzzy ("agent searches for `runQuery` and gets `runQueryCmd`"). Bias toward exact — fuzzy is what `query` is for; `show` is the precise read.
124123
- **Q-4. Should `show` accept a file scope (`--in <path>`)?** Use case: same name in multiple files, agent knows which file. Could be `codemap show foo --in src/cli/cmd-query.ts`. Bias toward yes — cheap to add (just `AND file_path LIKE ?`) and the alternative is making the agent write SQL.

0 commit comments

Comments
 (0)