gabriel / musehub public
docs patch docs/209-mcp-reference-regeneration #1 / 1
AI Agent gabriel · 1 day ago · Oct 22, 2026 · Diff

docs: regenerate docs/reference/mcp.md's tool/resource catalogues from live registries (musehub#209)

docs/reference/mcp.md had drifted far past stale counts: only 38 of 127 live tools were documented at all (the 40-tool claim was never a rounding error, 70 percent of the real catalogue was simply missing), resources had both undocumented additions and at least one documented resource (musehub://me/starred) that no longer exists, and the ToC's own Read Tools (20) disagreed with its own section header Read Tools (21) before ever comparing against the live server.

Hand-transcribing ~150 tool/resource entries doesn't scale and re-drifts the moment anyone adds a tool without remembering to also update this file by hand -- exactly what happened here. Added scripts/gen_mcp_reference.py: introspects MCP_TOOLS/ MUSEHUB_WRITE_TOOL_NAMES/MUSEHUB_ELICITATION_TOOL_NAMES/ STATIC_RESOURCES/RESOURCE_TEMPLATES -- the same data the live server returns from tools/list -- and regenerates the per-item catalogue sections plus their counts between HTML comment markers, following the same generate/--check pattern as the existing scripts/gen_type_contracts.py.

Scoped to Tools and Resources only. Prompts (11/11 already documented with rich hand-curated workflow steps the registry's plain description field can't reproduce) was left alone -- only its stale count (10->11) and a pre-existing name typo (review_proposaloposal -> review_proposal) were hand-fixed, since regenerating it would be a content downgrade for zero coverage gain.

New tests/test_gen_mcp_reference.py guards against re-drift: asserts the committed doc matches what the generator would produce right now, and that every live tool/resource is actually documented -- the actual regression this ticket is about, not just the three summary numbers.

sha256:b3e654170421616945cf1599d6bb4e8e219c3c2189458ed7f41af4b2d685f87a sha
sha256:64298d820f83e03ad4a1d3dae5a5fe2e57d124c1ebd0d56e99d93e69b595dccc parent
+197 ~8 −67 symbols
3 changed · 1112 in snapshot files
sha256:5e29dcb3ffa360378ab924f5869119eb15c8938c8ae4329c0fa407f43c556453 snapshot
+197
symbols added
~8
symbols modified
−67
symbols removed
3
files changed
1112
files in snapshot
0
dead code introduced
Semantic Changes 272 symbols
~ scripts/gen_mcp_reference.py .py 19 symbols added
+ _DOC_PATH variable variable _DOC_PATH L57–57
+ _MARKER_RE_TEMPLATE variable variable _MARKER_RE_TEMPLATE L59–63
+ _REPO_ROOT variable variable _REPO_ROOT L56–56
+ _ToolRecord class class _ToolRecord L66–69
+ _classify_tools class function _classify_tools L104–120
+ _escape_table_cell function function _escape_table_cell L91–93
+ _param_rows function function _param_rows L72–88
+ _render_resource_entries function function _render_resource_entries L123–128
+ _render_tool_entries function function _render_tool_entries L96–101
+ _replace_region function function _replace_region L131–139
+ generate function function generate L142–189
+ Path import import Path L53–53
+ TypedDict import import TypedDict L54–54
+ annotations import import annotations L47–47
+ argparse import import argparse L49–49
+ difflib import import difflib L50–50
+ re import import re L51–51
+ sys import import sys L52–52
+ main function function main L192–228
~ tests/test_gen_mcp_reference.py .py 18 symbols added
+ TestDocStaysInSync class class TestDocStaysInSync L25–60
+ test_committed_doc_matches_generated_output method method test_committed_doc_matches_generated_output L26–28
+ test_every_live_resource_template_is_documented method method test_every_live_resource_template_is_documented L53–60
+ test_every_live_static_resource_is_documented method method test_every_live_static_resource_is_documented L47–51
+ test_every_live_tool_is_documented method method test_every_live_tool_is_documented L41–45
+ test_resource_counts_match_live_registry method method test_resource_counts_match_live_registry L35–39
+ test_tool_counts_match_live_registry method method test_tool_counts_match_live_registry L30–33
+ TestGeneratorUnit class class TestGeneratorUnit L63–99
+ test_check_passes_against_committed_doc method method test_check_passes_against_committed_doc L89–99
+ test_param_table_empty_schema_has_no_parameters_note method method test_param_table_empty_schema_has_no_parameters_note L78–79
+ test_param_table_escapes_literal_pipes method method test_param_table_escapes_literal_pipes L64–76
+ test_tool_classification_is_a_partition class method test_tool_classification_is_a_partition L81–87
+ committed_doc function function committed_doc L21–22
+ Path import import Path L12–12
+ annotations import import annotations L9–9
+ gen import import gen L17–17
+ pytest import import pytest L14–14
+ sys import import sys L11–11
~ docs/reference/mcp.md .md 160 symbols added, 67 symbols removed, 8 symbols modified
~ musehub/review_proposaloposal
− Static Resources (12) section Static Resources (12) L959–1000
− musehub://me section musehub://me L969–976
− musehub://me/feed section musehub://me/feed L993–1000
− musehub://me/notifications section musehub://me/notifications L977–984
− musehub://me/starred section musehub://me/starred L985–992
− musehub://trending section musehub://trending L961–968
− Templated Resources (17) section Templated Resources (17) L1001–1094
− musehub://repos/{owner}/{slug} section musehub://repos/{owner}/{slug} L1005–1010
− musehub://repos/{owner}/{slug}/analysis/{ref} section musehub://repos/{owner}/{slug}/analysis/{ref} L1077–1082
− musehub://repos/{owner}/{slug}/blob/{ref}/{path} section musehub://repos/{owner}/{slug}/blob/{ref}/{path} L1035–1040
− musehub://repos/{owner}/{slug}/branches section musehub://repos/{owner}/{slug}/branches L1011–1016
− musehub://repos/{owner}/{slug}/commits section musehub://repos/{owner}/{slug}/commits L1017–1022
− musehub://repos/{owner}/{slug}/commits/{commit_id} section musehub://repos/{owner}/{slug}/commits/{commit_id} L1023–1028
− musehub://repos/{owner}/{slug}/issues section musehub://repos/{owner}/{slug}/issues L1041–1046
− musehub://repos/{owner}/{slug}/issues/{number} section musehub://repos/{owner}/{slug}/issues/{number} L1047–1052
− musehub://repos/{owner}/{slug}/pulls section musehub://repos/{owner}/{slug}/pulls L1053–1058
− musehub://repos/{owner}/{slug}/pulls/{number} section musehub://repos/{owner}/{slug}/pulls/{number} L1059–1064
− musehub://repos/{owner}/{slug}/releases section musehub://repos/{owner}/{slug}/releases L1065–1070
− musehub://repos/{owner}/{slug}/releases/{tag} section musehub://repos/{owner}/{slug}/releases/{tag} L1071–1076
− musehub://repos/{owner}/{slug}/timeline section musehub://repos/{owner}/{slug}/timeline L1083–1088
− musehub://repos/{owner}/{slug}/tree/{ref} section musehub://repos/{owner}/{slug}/tree/{ref} L1029–1034
− musehub://users/{username} section musehub://users/{username} L1089–1094
− Elicitation-Powered Tools (5) section Elicitation-Powered Tools (5) L839–918
− musehub_create_release_interactive (chained form + URL elicitation | bypass: `tag`) section musehub_create_release_interactive (chained form + URL elicitation | bypass: `tag`) L886–918
− musehub_review_proposal_interactive (form elicitation | bypass: `dimension`, `depth`) section musehub_review_proposal_interactive (form elicitation | bypass: `dimension`, `depth`) L851–885
− Read Tools (21) section Read Tools (21) L266–530
− muse_pull section muse_pull L505–517
− muse_remote section muse_remote L518–530
− musehub_compare section musehub_compare L347–360
− musehub_get_commit section musehub_get_commit L334–346
− musehub_get_context section musehub_get_context L268–279
− musehub_get_domain section musehub_get_domain L451–460
− musehub_get_domain_insights section musehub_get_domain_insights L461–473
− musehub_get_issue section musehub_get_issue L376–388
− musehub_get_proposal section musehub_get_proposal L403–415
− musehub_get_view section musehub_get_view L474–486
− musehub_list_branches section musehub_list_branches L280–291
− musehub_list_commits section musehub_list_commits L292–305
− musehub_list_domains section musehub_list_domains L443–450
− musehub_list_issues section musehub_list_issues L361–375
− musehub_list_labels section musehub_list_labels L495–504
− musehub_list_proposals section musehub_list_proposals L389–402
− musehub_list_releases section musehub_list_releases L416–427
− musehub_read_file section musehub_read_file L306–319
− musehub_search section musehub_search L320–333
− musehub_search_repos section musehub_search_repos L428–442
− musehub_whoami section musehub_whoami L487–494
− Write Tools (22) section Write Tools (22) L531–838
− muse_config section muse_config L825–838
− muse_push section muse_push L761–824
− musehub_assign_issue section musehub_assign_issue L725–736
− musehub_close_issue section musehub_close_issue L703–713
− musehub_create_issue section musehub_create_issue L553–566
− musehub_create_issue_comment section musehub_create_issue_comment L583–594
− musehub_create_label section musehub_create_label L665–677
− musehub_create_proposal section musehub_create_proposal L595–608
− musehub_create_proposal_comment section musehub_create_proposal_comment L621–636
− musehub_create_release section musehub_create_release L650–664
− musehub_create_repo section musehub_create_repo L535–552
− musehub_delete_label section musehub_delete_label L692–702
− musehub_merge_proposal section musehub_merge_proposal L609–620
− musehub_remove_issue_label section musehub_remove_issue_label L749–760
− musehub_reopen_issue section musehub_reopen_issue L714–724
− musehub_set_issue_labels section musehub_set_issue_labels L737–748
− musehub_submit_proposal_review section musehub_submit_proposal_review L637–649
− musehub_update_issue section musehub_update_issue L567–582
− musehub_update_label section musehub_update_label L678–691
+ Static Resources (9) section Static Resources (9) L2038–2093
+ muse://docs/domains section muse://docs/domains L2040–2045
+ muse://docs/overview section muse://docs/overview L2046–2051
+ muse://docs/protocol section muse://docs/protocol L2052–2057
+ muse://domains section muse://domains L2058–2063
+ musehub://me section musehub://me L2064–2069
+ musehub://me/feed section musehub://me/feed L2070–2075
+ musehub://me/notifications section musehub://me/notifications L2076–2081
+ musehub://me/tokens section musehub://me/tokens L2082–2087
+ musehub://trending section musehub://trending L2088–2093
+ Templated Resources (19) section Templated Resources (19) L2094–2212
+ muse://domains/{author}/{slug} section muse://domains/{author}/{slug} L2098–2103
+ musehub://mists/{owner} section musehub://mists/{owner} L2104–2109
+ musehub://mists/{owner}/{mist_id} section musehub://mists/{owner}/{mist_id} L2110–2115
+ musehub://repos/{owner}/{slug} section musehub://repos/{owner}/{slug} L2116–2121
+ musehub://repos/{owner}/{slug}/blob/{ref}/{path} section musehub://repos/{owner}/{slug}/blob/{ref}/{path} L2122–2127
+ musehub://repos/{owner}/{slug}/branches section musehub://repos/{owner}/{slug}/branches L2128–2133
+ musehub://repos/{owner}/{slug}/commits section musehub://repos/{owner}/{slug}/commits L2134–2139
+ musehub://repos/{owner}/{slug}/commits/{commit_id} section musehub://repos/{owner}/{slug}/commits/{commit_id} L2140–2145
+ musehub://repos/{owner}/{slug}/insights/{ref} section musehub://repos/{owner}/{slug}/insights/{ref} L2146–2151
+ musehub://repos/{owner}/{slug}/issues section musehub://repos/{owner}/{slug}/issues L2152–2157
+ musehub://repos/{owner}/{slug}/issues/{number} section musehub://repos/{owner}/{slug}/issues/{number} L2158–2163
+ musehub://repos/{owner}/{slug}/proposals section musehub://repos/{owner}/{slug}/proposals L2164–2169
+ musehub://repos/{owner}/{slug}/proposals/{number} section musehub://repos/{owner}/{slug}/proposals/{number} L2170–2175
+ musehub://repos/{owner}/{slug}/releases section musehub://repos/{owner}/{slug}/releases L2176–2181
+ musehub://repos/{owner}/{slug}/releases/{tag} section musehub://repos/{owner}/{slug}/releases/{tag} L2182–2187
+ musehub://repos/{owner}/{slug}/remote section musehub://repos/{owner}/{slug}/remote L2188–2193
+ musehub://repos/{owner}/{slug}/timeline section musehub://repos/{owner}/{slug}/timeline L2194–2199
+ musehub://repos/{owner}/{slug}/tree/{ref} section musehub://repos/{owner}/{slug}/tree/{ref} L2200–2205
+ musehub://users/{username} section musehub://users/{username} L2206–2212
+ Elicitation-Powered Tools (2) section Elicitation-Powered Tools (2) L1963–1996
+ musehub_create_release_interactive section musehub_create_release_interactive L1965–1980
+ musehub_review_proposal_interactive section musehub_review_proposal_interactive L1981–1996
+ Read Tools (52) section Read Tools (52) L273–920
+ muse_mist_embed section muse_mist_embed L275–285
+ muse_mist_list section muse_mist_list L286–299
+ muse_mist_list_forks section muse_mist_list_forks L300–310
+ muse_mist_raw section muse_mist_raw L311–320
+ muse_mist_read section muse_mist_read L321–330
+ muse_pull section muse_pull L331–345
+ muse_remote section muse_remote L346–357
+ musehub_compare section musehub_compare L358–371
+ musehub_get_fork_network section musehub_get_fork_network L372–381
+ musehub_get_repo section musehub_get_repo L382–393
+ musehub_get_user_forks section musehub_get_user_forks L394–403
+ musehub_list_branches section musehub_list_branches L404–415
+ musehub_list_commits section musehub_list_commits L416–429
+ musehub_list_coord_reservations section musehub_list_coord_reservations L430–444
+ musehub_list_coord_tasks section musehub_list_coord_tasks L445–459
+ musehub_list_domains section musehub_list_domains L460–473
+ musehub_list_issues section musehub_list_issues L474–487
+ musehub_list_labels section musehub_list_labels L488–499
+ musehub_list_proposals section musehub_list_proposals L500–512
+ musehub_list_proposals_context section musehub_list_proposals_context L513–525
+ musehub_list_releases section musehub_list_releases L526–537
+ musehub_list_repo_forks section musehub_list_repo_forks L538–547
+ musehub_list_repos section musehub_list_repos L548–558
+ musehub_list_symbols section musehub_list_symbols L559–574
+ musehub_read_commit section musehub_read_commit L575–587
+ musehub_read_context section musehub_read_context L588–599
+ musehub_read_coord_conflicts section musehub_read_coord_conflicts L600–612
+ musehub_read_coord_swarm section musehub_read_coord_swarm L613–624
+ musehub_read_cross_repo_impact section musehub_read_cross_repo_impact L625–637
+ musehub_read_domain section musehub_read_domain L638–647
+ musehub_read_domain_insights section musehub_read_domain_insights L648–661
+ musehub_read_file section musehub_read_file L662–674
+ musehub_read_intel_blast_risk section musehub_read_intel_blast_risk L675–686
+ musehub_read_intel_dead section musehub_read_intel_dead L687–698
+ musehub_read_intel_health_score section musehub_read_intel_health_score L699–710
+ musehub_read_intel_hotspots section musehub_read_intel_hotspots L711–722
+ musehub_read_intel_index_status section musehub_read_intel_index_status L723–734
+ musehub_read_issue section musehub_read_issue L735–747
+ musehub_read_prompt section musehub_read_prompt L748–758
+ musehub_read_proposal section musehub_read_proposal L759–771
+ musehub_read_proposal_breakage section musehub_read_proposal_breakage L772–784
+ musehub_read_proposal_diff section musehub_read_proposal_diff L785–797
+ musehub_read_proposal_risk section musehub_read_proposal_risk L798–810
+ musehub_read_symbol section musehub_read_symbol L811–823
+ musehub_read_view section musehub_read_view L824–837
+ musehub_read_workspace_intel section musehub_read_workspace_intel L838–847
+ musehub_search section musehub_search L848–861
+ musehub_search_repos section musehub_search_repos L862–874
+ musehub_set_context section musehub_set_context L875–885
+ musehub_symbol_clones section musehub_symbol_clones L886–898
+ musehub_symbol_impact section musehub_symbol_impact L899–912
+ musehub_whoami section musehub_whoami L913–920
+ Write Tools (73) section Write Tools (73) L921–1962
+ muse_config section muse_config L923–933
+ muse_mist_create section muse_mist_create L934–951
+ muse_mist_delete section muse_mist_delete L952–961
+ muse_mist_fork section muse_mist_fork L962–971
+ muse_mist_update section muse_mist_update L972–986
+ muse_push section muse_push L987–1004
+ musehub_accept_collaborator_invite section musehub_accept_collaborator_invite L1005–1016
+ musehub_agent_broadcast section musehub_agent_broadcast L1017–1027
+ musehub_agent_notify section musehub_agent_notify L1028–1039
+ musehub_assign_issue section musehub_assign_issue L1040–1053
+ musehub_attach_release_asset section musehub_attach_release_asset L1054–1071
+ musehub_claim_coord_task section musehub_claim_coord_task L1072–1085
+ musehub_close_issue section musehub_close_issue L1086–1098
+ musehub_complete_coord_task section musehub_complete_coord_task L1099–1113
+ musehub_create_coord_reservation section musehub_create_coord_reservation L1114–1128
+ musehub_create_issue section musehub_create_issue L1129–1147
+ musehub_create_issue_comment section musehub_create_issue_comment L1148–1161
+ musehub_create_label section musehub_create_label L1162–1176
+ musehub_create_proposal section musehub_create_proposal L1177–1198
+ musehub_create_proposal_comment section musehub_create_proposal_comment L1199–1215
+ musehub_create_proposal_review section musehub_create_proposal_review L1216–1230
+ musehub_create_release section musehub_create_release L1231–1247
+ musehub_create_repo section musehub_create_repo L1248–1263
+ musehub_create_user_profile section musehub_create_user_profile L1264–1275
+ musehub_create_webhook section musehub_create_webhook L1276–1290
+ musehub_delete_coord_reservation section musehub_delete_coord_reservation L1291–1304
+ musehub_delete_issue_comment section musehub_delete_issue_comment L1305–1318
+ musehub_delete_label section musehub_delete_label L1319–1331
+ musehub_delete_release_asset section musehub_delete_release_asset L1332–1345
+ musehub_delete_repo section musehub_delete_repo L1346–1357
+ musehub_delete_user_account section musehub_delete_user_account L1358–1367
+ musehub_delete_webhook section musehub_delete_webhook L1368–1380
+ musehub_enqueue_coord_task section musehub_enqueue_coord_task L1381–1397
+ musehub_extend_coord_reservation section musehub_extend_coord_reservation L1398–1411
+ musehub_fail_coord_task section musehub_fail_coord_task L1412–1426
+ musehub_fork_repo section musehub_fork_repo L1427–1439
+ musehub_get_mpay_ledger section musehub_get_mpay_ledger L1440–1450
+ musehub_get_proposal section musehub_get_proposal L1451–1463
+ musehub_get_proposal_simulation section musehub_get_proposal_simulation L1464–1477
+ musehub_invite_collaborator section musehub_invite_collaborator L1478–1491
+ musehub_issue_attestation section musehub_issue_attestation L1492–1510
+ musehub_list_attestations section musehub_list_attestations L1511–1521
+ musehub_list_collaborators section musehub_list_collaborators L1522–1533
+ musehub_list_issue_comments section musehub_list_issue_comments L1534–1548
+ musehub_list_proposal_comments section musehub_list_proposal_comments L1549–1561
+ musehub_list_proposal_reviews section musehub_list_proposal_reviews L1562–1575
+ musehub_list_proposal_simulations section musehub_list_proposal_simulations L1576–1588
+ musehub_list_release_assets section musehub_list_release_assets L1589–1603
+ musehub_list_topics section musehub_list_topics L1604–1614
+ musehub_list_webhook_deliveries section musehub_list_webhook_deliveries L1615–1629
+ musehub_list_webhooks section musehub_list_webhooks L1630–1641
+ musehub_merge_proposal section musehub_merge_proposal L1642–1655
+ musehub_publish_domain section musehub_publish_domain L1656–1671
+ musehub_read_profile_manifest section musehub_read_profile_manifest L1672–1681
+ musehub_read_user_profile section musehub_read_user_profile L1682–1691
+ musehub_record_mpay_claim section musehub_record_mpay_claim L1692–1711
+ musehub_redeliver_webhook section musehub_redeliver_webhook L1712–1725
+ musehub_remove_collaborator section musehub_remove_collaborator L1726–1738
+ musehub_remove_issue_label section musehub_remove_issue_label L1739–1752
+ musehub_remove_proposal_reviewer section musehub_remove_proposal_reviewer L1753–1766
+ musehub_reopen_issue section musehub_reopen_issue L1767–1779
+ musehub_request_proposal_reviewers section musehub_request_proposal_reviewers L1780–1793
+ musehub_revoke_attestation section musehub_revoke_attestation L1794–1804
+ musehub_run_proposal_simulation section musehub_run_proposal_simulation L1805–1818
+ musehub_set_repo_topics section musehub_set_repo_topics L1819–1831
+ musehub_transfer_repo_ownership section musehub_transfer_repo_ownership L1832–1844
+ musehub_update_collaborator_permission section musehub_update_collaborator_permission L1845–1858
+ musehub_update_issue section musehub_update_issue L1859–1878
+ musehub_update_issue_labels section musehub_update_issue_labels L1879–1892
+ musehub_update_label section musehub_update_label L1893–1908
+ musehub_update_release section musehub_update_release L1909–1925
+ musehub_update_repo section musehub_update_repo L1926–1949
+ musehub_update_user_profile section musehub_update_user_profile L1950–1962
~ MuseHub MCP Reference
~ Prompts
~ Resources
~ Reading a resource
~ Table of Contents
~ Tools
~ Calling a tool
Files Changed
+2 ~1
1112 in snapshot
+ scripts/gen_mcp_reference.py .py
+ tests/test_gen_mcp_reference.py .py
~ docs/reference/mcp.md .md
← Older Oldest on docs/209-mcp-reference-regeneration
All commits
Newer → Latest on docs/209-mcp-reference-regeneration

0 comments

No comments yet. Be the first to start the discussion.

To add a comment, use the Muse CLI: muse hub commit comment sha256:b3e654170421616945cf1599d6bb4e8e219c3c2189458ed7f41af4b2d685f87a --body "your comment"