feat(mcp): categorize and group loopover-mcp tools output (#6301)

[nghetienhiep]

Summary

Adds a coarse category to every MCP tool on both servers and groups the loopover-mcp tools
output by it, so a user scanning the full tool surface can find the relevant subset instead of
reading one long flat list (#6301, part of the MCP Platform Wave 1 milestone).

• Local server (packages/loopover-mcp/bin/loopover-mcp.js): each STDIO_TOOL_DESCRIPTORS
  entry now carries a category id, and a single STDIO_TOOL_CATEGORIES list is the source of truth
  for the category order + human labels. loopover-mcp tools prints tools under category headers in
  that canonical order; tools --json gains a categories summary ({ id, label, count }) and a
  category field per tool.
• Remote server (src/mcp/server.ts): the same category ids live in an exported
  MCP_TOOL_CATEGORIES map, attached to each tool as MCP _meta.category via a thin registration
  wrapper, so tools/list clients see the same grouping. No tool is added, removed, or renamed.
• Category names follow the repo's own conceptual surfaces (contributor discovery/planning, local
  branch & PR prep, review/gate prediction, agent automation, maintainer/repo-owner, and
  registry/config utility) rather than an invented taxonomy.

Every registered tool maps to exactly one category; the tests fail loudly if a new tool is ever added
without one, or if the map drifts from the registered set.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves (Closes #6301).

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally — the tools/list _meta.category wiring, the MCP_TOOL_CATEGORIES map, and the registration wrapper in src/mcp/server.ts are fully covered with no partial branches (verified against the v8 report). New tests: test/unit/mcp-tool-categories.test.ts and an added case in test/unit/mcp-cli-tools.test.ts.
• npm run build:mcp
• npm run test:mcp-pack
• npm run command-reference:check, npm run docs:drift-check, npm run manifest:drift-check
• npm audit --audit-level=moderate (0 vulnerabilities)
• New behavior has unit tests for both servers (grouped CLI output + _meta.category parity)

If any required check was skipped, explain why:

• npm run test:workers / ui:* (ui:lint, ui:typecheck, ui:build, ui:openapi:check): this change touches only the MCP server metadata and the local CLI's tools output — no worker route, OpenAPI schema, or UI surface changed, so those checks are unaffected.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. — n/a, no auth/session surface touched.
• API/OpenAPI/MCP behavior is updated and tested where needed (MCP tools/list now exposes _meta.category; covered by tests).
• UI changes use live API data or real empty/error/loading states. — n/a, no UI change.
• Visible UI changes include a UI Evidence section. — n/a, no visible UI/frontend/docs-site change.
• Public docs/changelogs are updated where needed (the loopover-mcp README tools section now documents the grouped output and the new --json shape); no changelog edited.

Notes

• Composes with the sibling loopover-mcp tools search command (feat(mcp): add tools search <query> for fuzzy tool discovery #6317): the default tools listing
  is now grouped by category, while tools search <query> keeps its flat ranked results unchanged.
• The remote server attaches the category via MCP _meta (the spec-sanctioned place for arbitrary
  tool metadata), so it rides along in every tools/list response without changing any tool's input
  or output schema. The two servers keep their own category maps for now (they live in separate
  packages); this can consolidate onto a shared registration point if Spec: should local (@loopover/mcp) and remote (src/mcp/server.ts) MCP tool implementations share a core? #6227's shared-core work lands.

Closes #6301

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Warning

⏸️ LoopOver review result - manual review recommended

_{Review updated: 2026-07-16 02:15:09 UTC}

5 files · 1 AI reviewer · no blockers · CI green · dirty

⏸️ Suggested Action - Manual Review

Review summary
This PR adds a coarse `category` to every MCP tool on both the local stdio CLI and the remote server, and groups `loopover-mcp tools` output by category with matching `_meta.category` on `tools/list`. The mechanical `server.registerTool` → `register(...)` conversion across ~88 tool registrations is consistent, the `MCP_TOOL_CATEGORIES` map appears to cover every registered tool name seen in the diff, and the added test suite (`mcp-tool-categories.test.ts`) asserts exact map/registered-set parity plus category-id validity — which is the right way to guard against silent drift. No tool is added/removed/renamed and no schema/migration is implicated.

Nits — 5 non-blocking

• src/mcp/server.ts: the `register` wrapper does `{ ...config, _meta: { category: ... } }`, which will silently clobber any pre-existing `_meta` a future tool registration sets — worth a defensive merge (`_meta: { ...config._meta, category }`) even though no current call site sets `_meta`.
• src/mcp/server.ts: `MCP_TOOL_CATEGORIES: Record<string, McpToolCategory>` permits indexing with any string and yields `undefined` at runtime for an unmapped tool without a type error; the added test catches this at CI time but a stricter `satisfies Record<ToolName, McpToolCategory>` (if a tool-name union exists) would catch it at compile time instead.
• packages/loopover-mcp/bin/loopover-mcp.js and test/unit/mcp-cli-tools.test.ts both hardcode the same `STDIO_TOOL_CATEGORIES` id/label list — consider exporting the list from the CLI module so the test imports it instead of duplicating it, to avoid silent drift between the two.
• packages/loopover-mcp/README.md: the updated one-line description of `tools --json` output is now fairly dense; consider a short fenced JSON example matching the pattern used earlier in the same README section for the plain `tools` output.
• Consider exporting `STDIO_TOOL_CATEGORIES` from loopover-mcp.js for reuse in mcp-cli-tools.test.ts (src note above).

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#6301
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 112 registered-repo PR(s), 64 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	nghetienhiep; Gittensor profile; 112 PR(s), 0 issue(s).
Improvement	✅ Minor	risk: clean · value: minor

Review context

• Author: nghetienhiep
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 112 PR(s), 0 issue(s).
• Related work: Titles/paths share 10 meaningful terms. (issue #6235, issue #6236)
• Related work: Titles/paths share 7 meaningful terms. (issue #6301, issue #6238)
• Related work: Titles/paths share 7 meaningful terms. (issue #6301, issue #6237)
• Additional title-only matches omitted; title-only overlap does not block.

Contributor next steps

• Start here: Review top overlaps.
• Then work through the remaining 2 steps in the Signals table above.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

LoopOver approves — the gate is satisfied and CI is green.

[loopover-orb]

LoopOver is closing this pull request on the maintainer's behalf (conflicts with the base branch — resolve and open a fresh PR). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.60%. Comparing base (44570d0) to head (5bc4e93).
⚠️ Report is 42 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6327   +/-   ##
=======================================
  Coverage   95.60%   95.60%           
=======================================
  Files         596      596           
  Lines       47121    47126    +5     
  Branches    14999    14999           
=======================================
+ Hits        45049    45054    +5     
  Misses       1290     1290           
  Partials      782      782           

Flag	Coverage Δ
shard-1	44.14% <100.00%> (+<0.01%)	⬆️
shard-2	36.52% <100.00%> (+<0.01%)	⬆️
shard-3	32.41% <100.00%> (+<0.01%)	⬆️
shard-4	34.40% <100.00%> (+<0.01%)	⬆️
shard-5	31.89% <100.00%> (+<0.01%)	⬆️
shard-6	44.78% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/mcp/server.ts	96.31% <100.00%> (+0.01%)	⬆️