feat(mcp): centralise ToolAnnotations across public + SDK tool surface

[louzt]

Rebase onto MCP Python SDK v2 (#89)

Rebased this PR onto f37d118 (PR #89 by @ChiragAgg5k, "Migrate to MCP Python SDK v2", merged 2026-07-29). The SDK migration is orthogonal to the safety annotations work:

• types.Tool.annotations is stable across MCP Python SDK v1 and v2.
• upstream/main at f37d118 contains zero references to ToolAnnotations (git grep -nE 'ToolAnnotations|annotations_for' upstream/main returns 0 matches). PR feat(mcp): centralise ToolAnnotations across public + SDK tool surface #87 remains the only PR introducing centralised ToolAnnotations.
• The migration's snake_case field aliases (input_schema, output_schema) on Tool apply to the schema structure, not to the annotations field. No collision.

The rebase produced two file conflicts:

• src/mcp_server_appwrite/docs_search.py: accepted --theirs (snake_case input_schema from Migrate to MCP Python SDK v2 (dual-era protocol support) #89; the annotations call was reapplied on top).
• src/mcp_server_appwrite/operator.py: manual merge preserving both Migrate to MCP Python SDK v2 (dual-era protocol support) #89's import-block changes and the centralised annotations imports plus the annotations_for_classification / annotations_for_gateway calls.

Note on intervening PRs (#90, #91, #92)

Three PRs merged after #89 and touch files in this PR's scope:

• (feat): surface parameter schemas in appwrite_search_tools results #90 "surface parameter schemas in appwrite_search_tools results" modifies docs_search.py and operator.py. The annotations=read_annotations on appwrite_search_tools stayed intact; only the schema-surfacing side of that tool's definition changed.
• Adopt the console Python SDK for control-plane tools #91 "Adopt the console Python SDK for control-plane tools" is a large refactor of operator.py, service.py, and server.py. The from .annotations import annotations_for_classification, annotations_for_gateway import and the annotated Tool() calls remain compatible with the refactored structure.
• Fix project usage parsing with Console SDK 0.3 #92 "Fix project usage parsing with Console SDK 0.3" depends on Adopt the console Python SDK for control-plane tools #91 and has no overlap with this PR's files.

Rebased onto f37d118 (the SDK v2 migration). When this PR is reviewed and merged, please rebase onto the current main so the diff against upstream reflects only PR #87's additions.

Design evolution vs the original proposal in #86

The original proposal in #86 suggested destructiveHint=False for appwrite_call_tool. During review, Greptile Bot flagged that this contradicts the MCP 2025-06-18 spec default semantics: setting the hint explicitly to False signals "definitely safe", which is wrong for a dispatcher whose inner behaviour depends on the target tool.

This PR resolves it with annotations_for_gateway(), a dedicated helper that returns ToolAnnotations(destructiveHint=None, ...). Per the MCP 2025-06-18 spec, an unset destructiveHint defaults to True on the client side, which is the honest semantics for a gateway. Clients that gate human approval on the hint correctly prompt the user for every gateway call, while confirm_write=true stays as the per-call inner gate for Appwrite's destructive SDK calls. The two layers cooperate; neither is a workaround for the other.

On benchmarks

A separate test/mcp-benchmarks branch holds an earlier tests/unit/test_benchmarks.py draft. It was deliberately not included in this PR for three concrete reasons:

1. Time-based assertions are flaky on CI (e.g. assert elapsed < 0.25 for _clamp_limit). CI runners are routinely 2 to 5x slower than developer machines, so the assertion becomes a coin flip.
2. One assertion contradicts this PR's design. It asserts tool.annotations.title == "Appwrite Documentation Search", but annotations_for_classification returns ToolAnnotations(title=None, ...). The test would fail against the current implementation.
3. Operator(manager, executor, docs_search=...) is not callable. The rebased Operator.__init__ types execute_tool as Callable[...]. ThreadPoolExecutor is not directly callable (it has submit()); the runtime throws TypeError when Operator tries to dispatch.

If reviewers want deterministic performance signals, the right vehicle is a separate PR using pytest-benchmark (with warmup, multi-iteration statistics, and stddev reporting), not assertions on raw wall-clock elapsed.

Local validation on the rebased tip

• python -m unittest discover -s tests/unit passes on mcp 2.0.0 (the version PR Migrate to MCP Python SDK v2 (dual-era protocol support) #89's migration requires). Local environments with mcp 1.27.2 hit a Pydantic ValidationError on input_schema= because the field name in 1.x was inputSchema (camelCase). Upstream CI runs mcp 2.0.0 and is green.
• ruff check src tests, black --check src tests, pyright all pass.

Effective diff

git diff upstream/main...HEAD (at f37d118):

 src/mcp_server_appwrite/annotations.py | 236 ++++++++++++
 src/mcp_server_appwrite/docs_search.py |   8 +
 src/mcp_server_appwrite/operator.py    |  27 ++
 src/mcp_server_appwrite/service.py     |   8 +
 tests/unit/test_annotations.py         | 639 +++++++++++++++++++++
 5 files changed, 918 insertions(+)

[greptile-apps]

Greptile Summary

Centralizes MCP tool safety annotations and applies them across the public, documentation-search, and dynamically generated SDK tool surfaces.

• Classifies SDK tool names into read, write, delete, and unknown categories.
• Uses a dedicated conservative annotation profile for the dynamic gateway.
• Adds unit coverage for classification, annotation mappings, gateway behavior, and generated tools.

Confidence Score: 5/5

The PR appears safe to merge.

The previously reported gateway issue is resolved because appwrite_call_tool no longer promises non-destructive behavior and instead leaves destructiveHint unset for host-policy handling.

Important Files Changed

Filename	Overview
src/mcp_server_appwrite/annotations.py	Adds centralized classification and annotation helpers, including an unset destructive hint for the gateway.
src/mcp_server_appwrite/operator.py	Applies read annotations to lookup tools and the dedicated gateway profile to appwrite_call_tool.
src/mcp_server_appwrite/service.py	Adds verb-derived annotations to dynamically generated SDK tools.
src/mcp_server_appwrite/docs_search.py	Marks the documentation-search tool as read-only.
tests/unit/test_annotations.py	Adds broad regression coverage for classifications, annotation profiles, and emitted tool definitions.

_{Reviews (4): Last reviewed commit: "fix(rebase): drop orphaned 'from . impor..." | Re-trigger Greptile}