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]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-16 02:44:14 UTC}

5 files · 1 AI reviewer · no blockers · readiness 80/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds a coarse `category` tag to every MCP tool on both the local stdio server and the remote worker, and groups the `loopover-mcp tools` output and `tools/list` `_meta` by that category. The remote-server wiring goes through a thin `register` wrapper that merges `_meta.category` into each tool's config, and a dedicated test suite (`mcp-tool-categories.test.ts`) asserts every registered tool has exactly one known category and that `MCP_TOOL_CATEGORIES` stays in exact sync with the live tool set — this is the right way to prevent drift since TS can't statically check that a `Record<string, McpToolCategory>` covers every registered name. The CLI side mirrors the same category ids/labels and is exercised by a new test asserting header order and per-category counts sum correctly. No tool is added/removed/renamed, and the change is scoped tightly to the linked issue (#6301).

Nits — 5 non-blocking

• src/mcp/server.ts:1808-1810 — the `register` wrapper does `{ ...config, _meta: { category: ... } }`, which silently overwrites any `_meta` a call site might already set; worth a comment or a merge (`_meta: { ...config._meta, category }`) so a future caller with its own `_meta` doesn't get clobbered.
• The canonical `{ id, label }` category list is hand-duplicated three times (server.ts test, loopover-mcp.js `STDIO_TOOL_CATEGORIES`, and mcp-cli-tools.test.ts) — since the local and remote category sets are meant to mirror each other per the PR description, consider sharing one source list to avoid the two drifting silently.
• packages/loopover-mcp/bin/loopover-mcp.js — confirm `printToolRows` is still used elsewhere in the file; if the grouped-printing change was its only caller, it's now dead code.
• `MCP_TOOL_CATEGORIES: Record<string, McpToolCategory>` in src/mcp/server.ts gives no compile-time guarantee of completeness — fine given the runtime test, but worth a one-line comment noting the guarantee is test-enforced, not type-enforced, since a reader might assume otherwise.
• Consider a small shared `TOOL_CATEGORIES` constant (id+label pairs) imported by both the stdio CLI and its test, and similarly for the remote server test, to remove the triplicated category-label list.

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 · LLM: moderate

Linked issue satisfaction

Addressed
The PR adds a category field to every tool in both STDIO_TOOL_DESCRIPTORS and src/mcp/server.ts's registration, groups the CLI 'tools' human and --json output by category with headers/summary, uses repo-derived category names (discovery/branch/review/agent/maintainer/utility), and includes tests asserting every tool has exactly one valid category and that grouped output reflects it.

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: Python, Vue, C#, JavaScript, C, C++, Go, Objective-C
• Official Gittensor activity: 112 PR(s), 0 issue(s).
• Related work: Titles/paths share 7 meaningful terms. (issue #6301, issue #6238)
• Related work: Titles/paths share 7 meaningful terms. (issue #6301, issue #6237)
• Related work: Titles/paths share 7 meaningful terms. (issue #6301, issue #6239)
• 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.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.60%. Comparing base (c23639b) to head (ac0911f).
⚠️ Report is 40 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6336   +/-   ##
=======================================
  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.47% <100.00%> (+0.06%)	⬆️
shard-4	34.47% <100.00%> (-0.11%)	⬇️
shard-5	31.69% <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%)	⬆️