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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

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

opened this

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 lists q first, and query stays as an alias. When both are sent, q wins. The tool's doc now says q.
  • 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> and archived (yes or no).
  • here manifest (src/actions/here.ts): the explore action now reads "explore apps and repositories (MCP: {q})". I updated the one assertion in test/here-manifest.test.ts that 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 the mcp-size, mcp and here-manifest tests 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.

Closes #9077

commented

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 lists q first, and query stays as an alias. When both are sent, q wins. The tool's doc now says q.
  • 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> and archived (yes or no).
  • here manifest (src/actions/here.ts): the explore action now reads "explore apps and repositories (MCP: {q})". I updated the one assertion in test/here-manifest.test.ts that 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 the mcp-size, mcp and here-manifest tests 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.

commented

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> and archived (yes or no).
  • here manifest: the explore action now reads "explore apps and repositories (MCP: {q})". I changed the matching assertion in test/here-manifest.test.ts, because that test pinned the old wording.
  • New test: test/explore-mcp-q.test.ts fails on main and passes here. It covers the q filter, the alias, q winning, q first in tools/list, and the /llms.txt keys.
  • Not done: docs/MCP.md may still say query; 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.

Changes requested — before the latest push

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.

commented

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 reads explore.q. It notes that query is the same argument and q wins, and it adds owner:name.
  • src/http/mcp/tools/explore.ts: the chosen line is split into const q and const line.
  • src/actions/here.ts: the do text is back to "explore apps and repositories". The manifest's Action type has no structured field for tool arguments, only mcp for the tool name. Adding one would be a new manifest field and out of scope for this fix. The q argument is documented in llms.txt, MCP.md and the tool's own schema. The here-manifest test 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.

Approved

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.

commented

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.).

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs