Repository navigation
✨ feat: rich MCP tool metadata — annotations, param descriptions, usage guidance (WP13) - #11
Merged
Merged
Conversation
…ge guidance (WP12) Directory graders (Glama audit: memory_search 3.2/5, memory_add 3.3/5) and agent clients judge tools on exactly what tools/list ships. All seven server tools now declare honest ToolAnnotations (readOnly/destructive/idempotent, openWorldHint=False), describe every inputSchema parameter (was 0% coverage), cross-reference sibling tools for when-to-use guidance, and disclose side effects: extraction on add, first-call model download, the empty-store file a search can create, and review_queue's lazy proposal expiry. No call-behavior change except memory_search.k and memory_review_queue.limit now carry a schema minimum of 1. Contract pinned in tests/test_mcp_tool_metadata.py (18 tests; core 319 + console 153 green). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VgxNBms5npMWXD2krUofs3
Resolves the import-block conflict in mcp_server.py: keep the compat factory (make_stdio_server) AND the metadata imports (ToolAnnotations, Field). Renumbers this packet WP12 → WP13 — the mcp 2.0 migration claimed WP12 concurrently and merged first (PR #10). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VgxNBms5npMWXD2krUofs3
…p majors mcp 2.0 renamed ToolAnnotations fields to snake_case with camelCase serialization aliases; attribute reads like .readOnlyHint only exist on 1.x. model_dump(by_alias=True) yields the camelCase wire names on both majors. Full core suite verified green under mcp 1.28.0 and 2.0.0 (scratch venv), with the served tools/list payload spot-checked on 2.0. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VgxNBms5npMWXD2krUofs3
Owner
Author
|
Renumbered WP12 → WP13: the mcp 2.0 dual-path migration (PR #10) claimed WP12 concurrently and merged first. main is merged into this branch (one import-block conflict resolved: compat factory + metadata imports coexist). Verified on both SDK majors: core 319 passed on mcp 1.28.0, 318 passed + 1 skipped on mcp 2.0.0 (scratch venv), console 153 passed; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The Glama directory audit scores each MCP tool on exactly what
tools/listships, and graded us down hard:memory_search3.2/5,memory_add3.3/5 — Behavior 2/5 ("No annotations are present"), Parameters 2/5 ("Schema coverage is 0%"), Usage Guidelines 2/5 (no when-to-use-vs-alternatives). The cause: one-line docstrings and bare type hints, so FastMCP shipped schemas with zero parameter descriptions and no annotations. Notably,memory_clear— the tool with a rich docstring — scored highest (3.6, "A"), confirming the diagnosis.What
All seven tools in
src/lean_memory/mcp_server.pynow ship:ToolAnnotations, honest per tool:readOnlyHint=Truefor search/status;destructiveHint=True, idempotentHint=Truefor clear;readOnlyHint=Falseonmemory_review_queuebecause listing lazily expires overdue proposals (a write);openWorldHint=Falseeverywhere (local SQLite, closed world).Annotated[..., Field(description=...)], including a shared definition of what anamespaceis (isolation key → one local SQLite file).[models]/[extract]extras; search's empty-store-file side effect on a missing namespace; sibling cross-references (search ↔ add ↔ clear, queue → decide).No call-behavior change except
memory_search.kandmemory_review_queue.limitnow declare a schema minimum of 1.Contract test
tests/test_mcp_tool_metadata.py(18 tests, TDD — watched red then green) pins the whole surface: annotation correctness per tool, 100% parameter-description coverage, namespace semantics everywhere, cross-references, and side-effect disclosure. The set-equality pin goes red if a tool is added or dropped without metadata.Verification
tools/listwire payload via an in-memory client session to confirm descriptions, param descriptions, andminimumland as servedOut of scope
The console stdio wrapper (
observe_mcp.py,routes/mcp.py, lane D) defines its own tool metadata; iflean-memory-consoleis also directory-graded it deserves the same treatment as a follow-up. Glama re-scans on release, so the score improves when this ships in the next tag.🤖 Generated with Claude Code
https://claude.ai/code/session_01VgxNBms5npMWXD2krUofs3