feat: Add tool annotations to mcp-neo4j-data-modeling server

[triepod-ai]

Summary

Adds MCP tool annotations (readOnlyHint, destructiveHint, title, idempotentHint, openWorldHint) to all 16 tools in the mcp-neo4j-data-modeling server to help LLMs better understand tool behavior and make safer decisions about tool execution.

Changes

• Added ToolAnnotations import from mcp.types
• Added readOnlyHint: true to all tools (all are read-only validation/transformation tools)
• Added destructiveHint: false to all tools (none modify external state)
• Added title annotations for human-readable display
• Added idempotentHint: true and openWorldHint: false for all tools

Tools Annotated

Tool Name	Title
validate_node	Validate Node
validate_relationship	Validate Relationship
validate_data_model	Validate Data Model
load_from_arrows_json	Load from Arrows JSON
export_to_arrows_json	Export to Arrows JSON
get_mermaid_config_str	Get Mermaid Config
get_node_cypher_ingest_query	Get Node Cypher Ingest Query
get_relationship_cypher_ingest_query	Get Relationship Cypher Ingest Query
get_constraints_cypher_queries	Get Constraints Cypher Queries
get_example_data_model	Get Example Data Model
list_example_data_models	List Example Data Models
load_from_owl_turtle	Load from OWL Turtle
export_to_owl_turtle	Export to OWL Turtle
export_to_pydantic_models	Export to Pydantic Models
export_to_neo4j_graphrag_pkg_schema	Export to Neo4j GraphRAG Schema
load_from_neo4j_graphrag_pkg_schema	Load from Neo4j GraphRAG Schema

Why This Matters

Tool annotations provide semantic metadata that helps MCP clients:

• Safety automation: Clients can auto-approve read-only tools without user confirmation
• UI/UX improvements: Display appropriate warnings/icons based on destructive hints
• Tool discovery: Filter/group tools by characteristics

Testing

• Server builds successfully (uv sync)
• Linter passes (ruff check src/)
• Live verification: Started server and confirmed annotations appear on all 16 tools
• Annotation values match actual tool behavior (all read-only, none destructive)

Note on Pre-existing Type Errors

There are pre-existing pyright type errors in the codebase (related to parse_dict_from_json_input type signatures). These errors exist on the main branch and are not introduced by this PR.

Before/After

Before:

@mcp.tool(name=namespace_prefix + "validate_node")
def validate_node(node: Union[str, Node], ...) -> bool | dict[str, Any]:
    ...

After:

@mcp.tool(
    name=namespace_prefix + "validate_node",
    annotations=ToolAnnotations(
        title="Validate Node",
        readOnlyHint=True,
        destructiveHint=False,
        idempotentHint=True,
        openWorldHint=False,
    ),
)
def validate_node(node: Union[str, Node], ...) -> bool | dict[str, Any]:
    ...

🤖 Generated with Claude Code