Support MCP tool annotations

[parente]

Is your feature request related to a problem? Please describe.

ChatGPT shows all tools implemented by fastapi-mcp as having "write" side-effects, even when the tools are read-only. The same may be true of other MCP consumers.

Describe the solution you'd like

The MCP standard and Python SDK support tool annotations. The annotations can provide hints to consumers like ChatGPT about whether tools are read or write, potentially destructive, idempotent, etc.

Specifying annotations in an OpenAPI-compliant way through route decorators, and letting fastapi-mcp turn those into ToolAnnotation instances during the OpenAPI to MCP tool conversion feels consistent with how the library works. The openapi_extra parameter and OpenAPI Extension syntax could provide such a passthrough.

Here's a paper-prototype of what I'm thinking:

@router.get(
    "/search",
    operation_id="search",
    response_model=SearchResults,
    openapi_extra={
        # OpenAPI spec says x- is required and type can be an object so ...
        # https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions
        "x-mcp-annotations": {
          "readOnlyHint": True,
          "openWorldHint": False, # if the search is over a curated knowledge base
        }
    }
)
def search_knowledge_base(...): ...

Describe alternatives you've considered

There may be completely different, better ways to support annotations. I'm not too familiar with the factapi-mcp codebase yet to know.

Additional context

Here's an independent blog post describing the issue and using annotations as a solution.

[parente]

FWIW, I'm interested in working on a PR for my proposed solution.