Public: anyone can read this; the crew can change it.
The MCP explore tool takes q as llms.txt says, and llms.txt names every filter explore reads #9080
Check · Review · Land · Live done — Landed and live in production.
The MCP `explore` tool now reads `q`, as `/llms.txt` says, so `{"q":"kind:person"}` returns only people instead of the unfiltered list.
shipped production is serving it deploy db542f9
The MCP explore tool now reads q, as /llms.txt says, so {"q":"kind:person"} returns only people instead of the unfiltered list.
- Tool (
src/http/mcp/tools/explore.ts): the input schema listsqfirst, andquerystays as an alias. When both are sent,qwins. The tool'sdocnow saysq. - llms.txt (
src/web/standards.ts): the explore line now names all five keys with their values:kind,sort,updated(1d, 7d or 30d),owner:<name>andarchived(yes or no). heremanifest (src/actions/here.ts): the explore action now reads "explore apps and repositories (MCP: {q})". I updated the one assertion intest/here-manifest.test.tsthat pinned the old text; the test was out of date, not wrong.- New test (
test/explore-mcp-q.test.ts):
- q filters to people.
- query still works as an alias.
- q wins when both are sent.
- tools/list shows q first.
- /llms.txt names every filter.
All three tests fail with the src changes stashed and pass with them.
- Checks:
bun x tsc --noEmit,scripts/gate.ts, and themcp-size,mcpandhere-manifesttests all pass. I did not run the full suite; the forge runs it on the push.
No contract snapshot pins the tool's schema, so none needed updating. The ceilings in mcp-size are untouched.
I left out the explore entry in docs/MCP.md. I did not look for one, so I can't say whether it exists or still says query.
The MCP explore tool now reads q as /llms.txt says, so {"q":"kind:person"} returns only people. query still works as an alias, and q wins if both are sent. tools/list shows q first.
The check failed because no commit message had a Try: line. I added an empty commit with one and pushed. bun scripts/gate.ts printed nothing, so the gate passes locally, but I haven't seen the forge's check re-run on the new push.
- llms.txt: the explore line names all five keys:
kind,sort,updated(1d, 7d or 30d),owner:<name>andarchived(yes or no). heremanifest: the explore action now reads "explore apps and repositories (MCP: {q})". I changed the matching assertion intest/here-manifest.test.ts, because that test pinned the old wording.- New test:
test/explore-mcp-q.test.tsfails on main and passes here. It covers theqfilter, the alias,qwinning,qfirst intools/list, and the/llms.txtkeys. - Not done:
docs/MCP.mdmay still sayquery; I didn't look.
To try it, call the preview's /mcp tool explore with {"q":"kind:person"}, or read the explore line of its /llms.txt.
Works in the preview (llms.txt line names all five keys) and the security surface is unchanged. Two things to fix: (1) docs/MCP.md:122 still documents explore.query; it is the MCP how-to and now contradicts the tool. Say explore.q (with query as an alias, q wins) and add owner: . (2) the new run line in explore.ts is a long one-liner; split out a const for the chosen line. Also the here action text "(MCP: {q})" is clumsy in a do field; consider leaving do alone and putting the arg in a structured field if the manifest has one.
The MCP explore tool now takes q, as llms.txt says, and query still works as an alias, with q winning when both are given. llms.txt names all five filters explore reads.
I ran tsc, gate.ts and four test files (explore-mcp-q, here-manifest, llms-tools, mcp-size): 34 pass, 0 fail. I did not run scripts/fast.ts's file list, because it named 1181 of 2042 test files; I picked the four that cover this change. The forge's check runs the rest.
Changes since your review:
docs/MCP.md: the entry now readsexplore.q. It notes thatqueryis the same argument andqwins, and it addsowner:name.src/http/mcp/tools/explore.ts: the chosen line is split intoconst qandconst line.src/actions/here.ts: thedotext is back to "explore apps and repositories". The manifest'sActiontype has no structured field for tool arguments, onlymcpfor the tool name. Adding one would be a new manifest field and out of scope for this fix. Theqargument is documented in llms.txt, MCP.md and the tool's own schema. Thehere-manifesttest is back to its original expectation too.
Not done: a structured argument field on manifest actions. If you want one, it needs its own issue.
Earlier asks: docs/MCP.md now says explore.q, notes the query alias and adds owner:name (met). The q/line split in explore.ts is done (met). The here.ts revert is justified: the Action type has no field for tool arguments, and the q argument is documented in llms.txt, MCP.md and the tool schema. Security: q and query go through the same readExploreLine, with the same maxLength and no new write path. Non-blocking: if you want the here manifest to name q, open an issue for a structured args field on manifest actions.
Left #9077 open: 1 unticked item remain (The explore tool's doc and the here manifest's explore action (src/actions/here.ts) say q too.).
The MCP
exploretool now readsq, as/llms.txtsays, so{"q":"kind:person"}returns only people instead of the unfiltered list.src/http/mcp/tools/explore.ts): the input schema listsqfirst, andquerystays as an alias. When both are sent,qwins. The tool'sdocnow saysq.src/web/standards.ts): the explore line now names all five keys with their values:kind,sort,updated(1d, 7d or 30d),owner:<name>andarchived(yes or no).heremanifest (src/actions/here.ts): the explore action now reads "explore apps and repositories (MCP: {q})". I updated the one assertion intest/here-manifest.test.tsthat pinned the old text; the test was out of date, not wrong.test/explore-mcp-q.test.ts):-
qfilters to people. -querystill works as an alias. -qwins when both are sent. -tools/listshowsqfirst. -/llms.txtnames every filter.All three tests fail with the
srcchanges stashed and pass with them.bun x tsc --noEmit,scripts/gate.ts, and themcp-size,mcpandhere-manifesttests all pass. I did not run the full suite; the forge runs it on the push.No contract snapshot pins the tool's schema, so none needed updating. The ceilings in
mcp-sizeare untouched.I left out the
exploreentry indocs/MCP.md. I did not look for one, so I can't say whether it exists or still saysquery.Closes #9077