docs(mcp): add generated MCP tool reference - #1385
Conversation
Closes #404 Adds scripts/generate_tool_docs.py — an AST-based generator that introspects all registered MCP tools and emits docs/mcp-tools.md, a comprehensive reference covering every tool, its parameters, types, and usage notes. The generator has zero runtime dependencies (pure stdlib) and is idempotent — running it twice produces an identical file. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: FBISiri <masteragentsiri@gmail.com>
Follow-up to the generator and reference contributed in #1380, covering the three Codex findings there plus the wiring to make the artifact discoverable. - Fix the search_notes docstring examples. The signature is search_notes(query, project, ...) but every example passed the project first, so a caller following them searched for the project name inside a project named after the query. Examples now pass the query positionally and the project as a keyword; the generated reference inherits the fix. - Assign heading anchors in document order the way GitHub does, so the Search category and the search tool get #search and #search-1 instead of both pointing at the category. - Nest headings embedded in a tool docstring under the tool's own heading. search_notes' "## Search Syntax Examples" no longer closes the tool section, so its parameter table stays under the tool in rendered outlines. - Add a `just tool-docs` recipe, a README pointer to docs/mcp-tools.md, and tests for the generator (anchor disambiguation, heading nesting, and a deterministic run over the real tool package). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp Signed-off-by: phernandez <paul@basicmachines.co>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a8642d2951
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The generator tests compared two fresh renders, so a tool docstring or signature change could land without regenerating docs/mcp-tools.md and nothing would notice. Compare the checked-in file against the generator output and point the failure at `just tool-docs`. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp Signed-off-by: phernandez <paul@basicmachines.co>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d41dadc982
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The docstring wrote the example with \"exact phrase\" escapes. Python
resolves them when the module loads, so the tool description sent to
clients (and the generated reference) read
search_notes(""exact phrase" AND keyword", ...)
which is not valid Python and cannot be copied. Use single outer quotes
so the rendered call is valid as written.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp
Signed-off-by: phernandez <paul@basicmachines.co>
|
Converting to draft: direction change, not a problem with the branch. Basic Memory already has a per-tool manual — Unix-style pages as notes (#952; 23 section-3 pages, one per MCP tool,
Leaving this open as a draft for reference until the follow-up is filed. |
|
Makes sense — folding into the manual system is the right call. Thanks
for keeping this as a draft for reference.
|
|
Follow-up filed: #1389 ships the manual's section 3 in the package and serves it as |
2 participants
Closes #404
Supersedes #1380
What
Adds a generated MCP tool reference (
docs/mcp-tools.md) and the script that produces it (scripts/generate_tool_docs.py), then addresses the review findings on the original PR.This branch cherry-picks @FBISiri's commit from #1380 unchanged (authorship preserved) and adds one follow-up commit on top. Thanks @FBISiri for the generator — the AST-based, zero-dependency approach and the
__all__-as-source-of-truth rule are exactly right for this.Follow-up commit (Codex findings on #1380)
search_notesexamples passed arguments in the wrong order. The signature issearch_notes(query, project, ...)but every docstring example wassearch_notes("my-project", "keyword"), which binds the project name toqueryand the keyword toproject. This is the tool description LLMs see, not just the generated doc. Examples now readsearch_notes("keyword", project="my-project"); the reference inherits the fix on regeneration.Searchcategory and thesearchtool both slugged to#search, so the tool's TOC link landed on the category. Anchors are now assigned in document order with GitHub's-1,-2suffix rule.search_notescarries its own## Search Syntax Examples/### ...structure; emitted verbatim under the### search_notesheading it ended the tool's section and its parameter table fell under the last example heading. Embedded headings are now nested one level below the tool heading (fenced code untouched).Also:
just tool-docsrecipe, a README pointer under "MCP tools", andtests/test_generate_tool_docs.pycovering the two rendering rules plus a deterministic run over the real tool package.Verification
uv run pytest tests/test_generate_tool_docs.py— 4 passeduv run pytest tests/mcp/test_tool_search.py tests/mcp/test_tool_delete_note.py— 83 passedruff check src tests test-int scripts/generate_tool_docs.py,ruff format --check,ty check src tests test-int(with the milvus extra) — cleandocs/mcp-tools.mdNot in this PR
edit_noteanddelete_noteruntime error messages carry the samesearch_notes("{project}", "{identifier}")ordering (with tests asserting on the strings). Same bug class, separate code path — worth its own small fix.🤖 Generated with Claude Code
https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp