docs(mcp): add downloadable MCP tool reference artifact - #1380
Conversation
Closes basicmachines-co#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>
![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: 556dfadbee
ℹ️ About Codex in GitHub
Codex has been enabled to automatically 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 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| - `search_notes("my-project", "keyword")` - Find any content containing "keyword" | ||
| - `search_notes("work-docs", "'exact phrase'")` - Search for exact phrase match |
There was a problem hiding this comment.
When a reader follows these two-positional-argument examples, the actual search_notes(query, project, ...) signature binds "my-project" to query and "keyword" to project, causing a search for the wrong text in a likely nonexistent project. Rewrite all such examples using explicit query=... and project=... arguments, or reverse their positional order.
AGENTS.md reference: AGENTS.md:L466-L467
Useful? React with 👍 / 👎.
| continue | ||
| out.append(f"- [{category}](#{_anchor(category)})") | ||
| for tool in entries: | ||
| out.append(f" - [`{tool.name}`](#{_anchor(tool.name)})") |
There was a problem hiding this comment.
When a category and tool have the same name, as with the existing Search category and search tool, both TOC entries are emitted as #search. Markdown renderers disambiguate the later heading, so the tool link jumps to the category rather than the tool documentation; track duplicate slugs or emit explicit unique anchors.
Useful? React with 👍 / 👎.
| out.append(f"{tool.summary}\n") | ||
| detail = tool.description.strip() | ||
| if detail: | ||
| out.append(f"{detail}\n") |
There was a problem hiding this comment.
When a tool description contains Markdown headings, as search_notes already does, appending it verbatim allows ## Search Syntax Examples to close the surrounding ### search_notes section. Its example headings consequently appear as peer tool entries and the parameter table falls under the final example heading in rendered outlines; normalize or demote embedded headings relative to the tool heading before rendering.
Useful? React with 👍 / 👎.
1 participant
Closes #404
What
Adds a generated MCP tool reference document (
docs/mcp-tools.md) andthe script that produces it (
scripts/generate_tool_docs.py).Why
Issue #404 requested a downloadable tool usage documentation artifact.
This PR provides a comprehensive reference for all 20+ registered MCP tools,
auto-generated from source to stay current as tools evolve.
How
scripts/generate_tool_docs.pyuses AST parsing (zero runtime deps) toextract tool names, docstrings, parameters, types, and defaults from
src/basic_memory/mcp/tools/__all__(no internal helpers)uv run scripts/generate_tool_docs.pyTesting