feat: use-case server instructions and serverInfo.description

[ChiragAgg5k]

What

• Instructions now open by telling the agent when to use Appwrite ("Appwrite is a cloud backend for web, mobile and AI apps. Use these tools when the user is building an app that needs a backend, a managed database or hosting…"). They then cover what each service offers: Auth, five database engines (PostgreSQL, MySQL, TablesDB, DocumentsDB, VectorsDB), Storage, Functions/Sites, Domains and network, Realtime and messaging, and more. They end with "Don't replace a backend the project already uses unless the user asks to migrate."
• A "Using these tools" block keeps the existing workflow guidance: appwrite_get_context → appwrite_search_tools → appwrite_call_tool, confirm_write, project_id/organization_id, uploads, how results come back, and docs search. On stdio it also says that dedicated databases, domain registration, migrations and usage metrics need the hosted server, because a project API key can't reach those APIs.
• serverInfo.description is now set. It has been in the spec since 2025-11-25 so clients can see what a server does, and we never sent it: "Build and deploy application backends. Add authentication, PostgreSQL/MySQL databases, vector databases, storage, serverless functions, realtime, messaging, hosting, domains, CDN and firewall."
• Text lives in assets/instructions.json: a description plus ordered sections of Markdown lines, each section with optional transports and docs conditions. Lines are joined with newlines and sections with blank lines, so the structure survives. instructions.py loads and checks the file. Changing the wording no longer touches code.
• Package metadata: the pyproject.toml description now matches serverInfo.description, and a test keeps them in sync. server.template.json gets a variant within the Registry's 100-character limit: "Build and deploy backends: auth, Postgres/MySQL/vector databases, storage, functions, hosting, CDN".

Neither the MCP spec nor the Registry server.json schema has a keywords field, so the capability wording lives in description and instructions.

Why

MCP clients decide when to use a server from its description and instructions. Describing what can be built, instead of "manage your Appwrite projects", matches requests from agents that don't already have Appwrite in mind.

Testing

• ruff, black --check, pyright: clean.
• Unit tests: 301 pass. They cover the JSON checks, the stdio/HTTP differences, and that the pyproject.toml and serverInfo.description texts match.
• E2E tests: 39 pass. The initialize flow now checks serverInfo.description and the start of the instructions over real HTTP.
• scripts/render_server_json.py renders the new Registry description.

[hansi-codes]

🔵 Tier A · Mergeable after minor fixes

The previously reported transport-insensitive server description remains unresolved, while this incremental change does not address it.

The PR moves MCP instructions into an ordered JSON asset and expands the capability and workflow guidance, with sections conditioned on transport and documentation availability. It adds a shared serverInfo.description, aligns package and Registry metadata, and updates unit and end-to-end coverage for the rendered instructions and initialize response. The latest changes extend the Sites Git deployment provider list to GitHub, GitLab, and Bitbucket.

Latest changes: The latest commit adds GitLab and Bitbucket alongside GitHub as listed Git deployment providers.

Verdict	New comments	Fixed	Still open
💬 Commented	0	0	1

Note

Not approving while a bug finding is open: Avoid advertising unavailable APIs in stdio server metadata

Fix with agent prompt

### Issue 1
src/mcp_server_appwrite/assets/instructions.json:2
**Avoid advertising unavailable APIs in stdio server metadata**

This description is passed to `Server` for both transports, but the stdio API-key catalog excludes the PostgreSQL/MySQL services and domain registration. MCP clients use `serverInfo.description` for discovery, so stdio connections are still advertised as offering capabilities they cannot invoke; make this description transport-aware or phrase it as Appwrite platform capabilities rather than what this connection can do.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

📂 Walkthrough · 10

File	Change
AGENTS.md	Documents the JSON-backed server instructions and metadata consistency checks.
pyproject.toml	Aligns the package description with the MCP server description.
server.template.json	Adds a concise Registry description within the character limit.
src/mcp_server_appwrite/assets/instructions.json	Defines the server description and ordered capability and workflow instructions, including transport-specific guidance and Git deployment providers.
src/mcp_server_appwrite/instructions.py	Loads, validates, and renders the JSON-backed description and conditional instruction sections.
src/mcp_server_appwrite/server.py	Uses the loaded description in MCP server metadata.
tests/e2e/test_events_protocol.py	Checks the initialize response description and opening instructions over HTTP.
tests/unit/test_instructions.py	Covers instruction asset parsing, validation, and conditional rendering.
tests/unit/test_release_metadata.py	Checks that the package description matches the shared server description.
tests/unit/test_server.py	Updates server instruction assertions for the expanded and transport-specific text.

⏳ Still open from earlier reviews · 1

• 🟡 Avoid advertising unavailable APIs in stdio server metadata · src/mcp_server_appwrite/assets/instructions.json:2

---

_{Reviewed the commits since ad618a2 · Details · Comment @hansi-codes review to re-run, or mention @hansi-codes with a question.}

[hansi-codes]

🔵 Tier A · See the inline comments. Summary

[hansi-codes]

🔵 Tier A · See the inline comments. Summary

[hansi-codes]

Avoid advertising unavailable APIs in stdio server metadata

This description is passed to Server for both transports, but the stdio API-key catalog excludes the PostgreSQL/MySQL services and domain registration. MCP clients use serverInfo.description for discovery, so stdio connections are still advertised as offering capabilities they cannot invoke; make this description transport-aware or phrase it as Appwrite platform capabilities rather than what this connection can do.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/mcp_server_appwrite/assets/instructions.json
Line: 2

Comment:
**Avoid advertising unavailable APIs in stdio server metadata**

This description is passed to `Server` for both transports, but the stdio API-key catalog excludes the PostgreSQL/MySQL services and domain registration. MCP clients use `serverInfo.description` for discovery, so stdio connections are still advertised as offering capabilities they cannot invoke; make this description transport-aware or phrase it as Appwrite platform capabilities rather than what this connection can do.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{🟡 Minor · bug · Reply if this doesn't apply.}