Summary

Adds MCP tool annotations (readOnlyHint, destructiveHint, title) to all 19 tools to help LLMs better understand tool behavior and make safer decisions about tool execution.

Changes

• Added readOnlyHint: true to GET operations (9 tools: get_user, get_users, get_self, retrieve_a_block, retrieve_a_page, retrieve_a_database, retrieve_a_page_property, retrieve_a_comment, get_block_children)
• Added destructiveHint: true to POST/PATCH/DELETE operations (10 tools: post_database_query, post_search, patch_block_children, update_a_block, delete_a_block, patch_page, post_page, create_a_database, update_a_database, create_a_comment)
• Added title annotations derived from operationId for human-readable display
• Annotations are dynamically determined from OpenAPI spec HTTP methods

Why This Matters

• Annotations provide semantic metadata that helps LLMs understand tool behavior
• MCP clients like Claude Code can auto-approve read-only tools while prompting for confirmation on destructive operations
• Enables safer tool execution by distinguishing read-only from destructive operations
• Human-readable titles improve tool display in client UIs

Testing

• Server builds successfully (npm run build)
• All proxy tests pass (npx vitest run src/openapi-mcp-server/mcp/__tests__/)
• Live verification: Started server and confirmed tools/list returns annotations for all 19 tools
• Annotation values match HTTP methods (GET = readOnly, POST/PATCH/DELETE = destructive)

Example Output

Tool Name                                          Title                          ReadOnly   Destructive
----------------------------------------------------------------------------------------------------
API-get-user                                       Get User                       True       N/A       
API-retrieve-a-page                                Retrieve A Page                True       N/A       
API-post-page                                      Post Page                      N/A        True      
API-delete-a-block                                 Delete A Block                 N/A        True      

🤖 Generated with Claude Code