Introduce the Appwrite operator workflow and refresh CI

[ChiragAgg5k]

Summary

This PR fundamentally changes how the Appwrite MCP server is exposed to MCP clients.

Instead of surfacing the full reflected Appwrite SDK as hundreds of top-level MCP tools, the server now presents a compact operator-style workflow and keeps the raw Appwrite catalog internal. The model interacts through search and explicit tool invocation rather than selecting from an overloaded public tool list.

In parallel, this PR refreshes the local/runtime behavior around startup, argument handling, formatting, and CI so the new operator flow is testable and maintainable.

What changed

1. Introduce a native Appwrite operator surface

The public MCP surface is now reduced to:

• appwrite_search_tools
• appwrite_call_tool

The full Appwrite tool catalog is still generated internally from the SDK, but it is no longer exposed directly as the primary client-facing surface. The operator layer:

• searches and ranks hidden Appwrite tools
• classifies tools as read/write/delete
• requires confirm_write=true for mutating calls
• stores large results as MCP resources instead of flooding tool output
• exposes catalog and stored-result resources under the appwrite://operator/... namespace

This is the main architectural change in the PR.

2. Simplify server startup and runtime behavior

The server no longer supports service-selection or mode flags. It now has a single default behavior built around the operator workflow.

Other runtime changes included in this PR:

• load .env from the current working directory for local development
• avoid eager server import at package import time
• add startup logging so the stdio server does not appear hung during validation
• keep startup validation minimal so startup stays fast
• exit cleanly on Ctrl-C without dumping asyncio tracebacks
• log the configured Appwrite API endpoint and MCP transport at startup

3. Improve tool argument handling

A significant source of friction was the mismatch between Appwrite API response fields and SDK method parameter names.

This PR adds normalization at the MCP boundary so hidden tool calls can accept:

• canonical snake_case SDK parameters
• common camelCase aliases such as rowSecurity, fileSecurity, and maximumFileSize
• Appwrite response-style fields such as $permissions
• simple $id to *_id mapping when it is unambiguous

The execution path now also fails early with clearer validation errors for unsupported copied response fields instead of leaking Python unexpected keyword argument errors from the SDK.

4. Improve search behavior for write tools

The original operator search behavior made mutating tools hard to discover unless the caller already knew the required parameter names.

This PR updates the search/ranking logic so:

• create/update/delete intent is inferred from natural language queries
• mutating tools can surface without explicitly setting include_mutating
• action-verb matches are ranked more strongly
• required parameters are not treated as missing when no argument_hints were provided

This makes queries like create function or create string column resolve to the expected Appwrite write tools.

5. Rework tests into unit and integration layers

The old layout was restructured to separate fast local coverage from live Appwrite coverage:

• tests/unit now holds the fast always-on tests
• tests/integration now holds the live Appwrite integration suite

The integration tests are organized per service rather than as one monolithic script. The old long-running surface-matrix script used for local exploration was removed from the repo.

6. Add formatting and refresh CI

This PR adds black as the formatter for the repo and introduces a general CI workflow.

The workflow now has separate jobs for:

• format
• unit
• integration
• release publish to PyPI

The older publish-only workflow file was replaced by a general ci.yml, and the MCP Registry publish job was removed.

Behavior changes / migration notes

This PR is intentionally not backward-compatible in a few areas:

• the server no longer exposes the old overload-heavy public tool surface as the default interaction model
• old CLI/service-selection flags were removed
• clients are expected to use the operator workflow (appwrite_search_tools -> appwrite_call_tool)
• mutating hidden tools now require confirm_write=true

If there are existing MCP client configs or prompts that rely on the old raw-tool behavior or removed flags, they will need to be updated.

Testing

Verified locally with:

• uv run python -m unittest discover -s tests/unit -v
• uv run --group dev black src tests

Live Appwrite integration coverage was also exercised during development, and the repo now contains the reorganized tests/integration suite for that path.

[greptile-apps]

Greptile Summary

This PR replaces the flat hundreds-of-tools MCP surface with a compact two-tool operator workflow (appwrite_search_tools + appwrite_call_tool), keeping the full Appwrite SDK catalog internal. It also adds argument normalization, a result store, restructured tests, and a refreshed CI pipeline.

Confidence Score: 5/5

Safe to merge; only P2 findings remain, all prior P0/P1 concerns from earlier review rounds have been addressed in this revision.

The architectural change is coherent and well-tested. The two remaining findings are P2: a silent argument-collision edge case in _normalize_arguments and a test touching a private SDK attribute. Neither blocks correctness of the primary operator flow.

src/mcp_server_appwrite/operator.py (_normalize_arguments conflict handling) and tests/unit/test_server.py (private attribute access)

Important Files Changed

Filename	Overview
src/mcp_server_appwrite/operator.py	Core operator surface: catalog building, search/ranking, result store, and public tool routing — well-structured; one silent argument-collision issue in _normalize_arguments
src/mcp_server_appwrite/server.py	Startup, argument normalization, and tool execution; endpoint logging now correctly uses config.endpoint; argument key normalization and conflict detection are well implemented
.github/workflows/ci.yml	New CI workflow with format, unit, and integration jobs; integration job has fork guard (head.repo.full_name == github.repository); cleanly structured
tests/unit/test_server.py	Good unit coverage for argument normalization, coercion, and startup validation; test accesses private client._endpoint which could silently break on SDK changes
tests/unit/test_operator.py	Covers search ranking, confirm_write guard, top-level argument merging, and result storage/retrieval; well-isolated with stub executor
tests/integration/support.py	Solid integration harness with retry logic, outcome tracking, and public-surface smoke test; requires_live_integration skip decorator handles missing credentials cleanly

_{Reviews (2): Last reviewed commit: "Address PR feedback and bump release to ..." | Re-trigger Greptile}

[greptile-apps]

Tip:

Greploop — Automatically fix all review issues by running /greploops in Claude Code. It iterates: fix, push, re-review, repeat until 5/5 confidence.

Use the Greptile plugin for Claude Code to query reviews, search comments, and manage custom context directly from your terminal.