mcp-server-appwrite 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

mcp_server_appwrite/server.py

@@ -1,5 +1,8 @@
+from __future__ import annotations
+from typing import List
 import asyncio
 import os
+import argparse
 import mcp.server.stdio
 import mcp.types as types
 from mcp.server import NotificationOptions, Server
@@ -19,6 +22,19 @@ from appwrite.exception import AppwriteException
 from .tool_manager import ToolManager
 from .service import Service
 
+def parse_args():
+    parser = argparse.ArgumentParser(description='Appwrite MCP Server')
+    parser.add_argument('--databases', action='store_true', help='Enable Databases service')
+    parser.add_argument('--users', action='store_true', help='Enable Users service')
+    parser.add_argument('--teams', action='store_true', help='Enable Teams service')
+    parser.add_argument('--storage', action='store_true', help='Enable Storage service')
+    parser.add_argument('--functions', action='store_true', help='Enable Functions service')
+    parser.add_argument('--messaging', action='store_true', help='Enable Messaging service')
+    parser.add_argument('--locale', action='store_true', help='Enable Locale service')
+    parser.add_argument('--avatars', action='store_true', help='Enable Avatars service')
+    parser.add_argument('--all', action='store_true', help='Enable all services')
+    return parser.parse_args()
+
 # Load environment variables from .env file
 load_dotenv()
 
@@ -36,14 +52,37 @@ client.set_endpoint(endpoint)
 client.set_project(project_id)
 client.set_key(api_key)
 
-# Initialize tools manager and register services
+# Initialize tools manager
 tools_manager = ToolManager()
-tools_manager.register_service(Service(Users(client), "users"))
-# tools_manager.register_service(Service(Teams(client), "teams"))
-tools_manager.register_service(Service(Databases(client), "databases"))
-# tools_manager.register_service(Service(Storage(client), "storage"))
-# tools_manager.register_service(Service(Functions(client), "functions"))
-# tools_manager.register_service(Service(Messaging(client), "messaging"))
+
+def register_services(args):
+    # If --all is specified, enable all services
+    if args.all:
+        args.databases = args.users = args.teams = args.storage = True
+        args.functions = args.messaging = args.locale = args.avatars = True
+
+    # Register services based on CLI arguments
+    if args.databases:
+        tools_manager.register_service(Service(Databases(client), "databases"))
+    if args.users:
+        tools_manager.register_service(Service(Users(client), "users"))
+    if args.teams:
+        tools_manager.register_service(Service(Teams(client), "teams"))
+    if args.storage:
+        tools_manager.register_service(Service(Storage(client), "storage"))
+    if args.functions:
+        tools_manager.register_service(Service(Functions(client), "functions"))
+    if args.messaging:
+        tools_manager.register_service(Service(Messaging(client), "messaging"))
+    if args.locale:
+        tools_manager.register_service(Service(Locale(client), "locale"))
+    if args.avatars:
+        tools_manager.register_service(Service(Avatars(client), "avatars"))
+
+    # If no services were specified, enable databases by default
+    if not any([args.databases, args.users, args.teams, args.storage,
+                args.functions, args.messaging, args.locale, args.avatars]):
+        tools_manager.register_service(Service(Databases(client), "databases"))
 
 async def serve() -> Server:
     server = Server("Appwrite MCP Server")
@@ -76,6 +115,9 @@ async def serve() -> Server:
     return server
 
 async def _run():
+    args = parse_args()
+    register_services(args)
+    
     async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
         server = await serve()
         await server.run(
@@ -83,7 +125,7 @@ async def _run():
             write_stream,
             InitializationOptions(
                 server_name="appwrite",
-                server_version="0.1.0",
+                server_version="0.1.4",
                 capabilities=server.get_capabilities(
                     notification_options=NotificationOptions(),
                     experimental_capabilities={},

mcp_server_appwrite/service.py

@@ -1,6 +1,7 @@
-from typing import Any, get_type_hints, Dict
+from typing import Any, get_type_hints, Dict, List, Optional, Union
 import inspect
 from mcp.types import Tool
+from docstring_parser import parse
 
 class Service():
     """Base class for all Appwrite services"""
@@ -29,7 +30,45 @@ class Service():
             list: "array",
             dict: "object"
         }
-        return {"type": type_mapping.get(py_type, "string")}
+        
+        # Handle basic types
+        if py_type in type_mapping:
+            return {"type": type_mapping[py_type]}
+        
+        # Handle Optional types (Union[type, None])
+        if hasattr(py_type, "__origin__") and py_type.__origin__ is Union:
+            args = getattr(py_type, "__args__", ())
+            if len(args) == 2 and args[1] is type(None):
+                schema = self.python_type_to_json_schema(args[0])
+                return schema
+        
+        # Handle List, Dict, and other generic types
+        if hasattr(py_type, "__origin__"):
+            origin = py_type.__origin__
+            args = getattr(py_type, "__args__", ())
+            
+            # Handle List[T]
+            if origin is list or origin is List:
+                if args:
+                    item_schema = self.python_type_to_json_schema(args[0])
+                    return {
+                        "type": "array",
+                        "items": item_schema
+                    }
+                return {"type": "array"}
+            
+            # Handle Dict[K, V]
+            if origin is dict or origin is Dict:
+                if len(args) >= 2:
+                    value_schema = self.python_type_to_json_schema(args[1])
+                    return {
+                        "type": "object",
+                        "additionalProperties": value_schema
+                    }
+                return {"type": "object"}
+        
+        # Default to string for unknown types
+        return {"type": "string"}
 
     def list_tools(self) -> Dict[str, Dict]:
         """Lists all available tools for this service"""
@@ -48,7 +87,7 @@ class Service():
             # Get the overridden name if it exists
             tool_name = self._method_name_overrides.get(name, f"{self.service_name}_{name}")
 
-            docstring = (original_func.__doc__ or "No description available").strip()
+            docstring = parse(original_func.__doc__)
             signature = inspect.signature(original_func)
             type_hints = get_type_hints(original_func)
 
@@ -62,13 +101,17 @@ class Service():
                 param_type = type_hints.get(param_name, str)
                 properties[param_name] = self.python_type_to_json_schema(param_type)
                 properties[param_name]["description"] = f"Parameter '{param_name}'"
+                
+                for doc_param in docstring.params:
+                    if doc_param.arg_name == param_name:
+                        properties[param_name]["description"] = doc_param.description
 
                 if param.default is param.empty:
                     required.append(param_name)
 
             tool_definition = Tool(
                 name=tool_name,
-                description=f"{docstring}",
+                description=f"{docstring.short_description or "No description available"}",
                 inputSchema={
                     "type": "object",
                     "properties": properties,

mcp_server_appwrite-0.1.4.dist-info/METADATA

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: mcp-server-appwrite
+Version: 0.1.4
+Summary: MCP (Model Context Protocol) server for Appwrite
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: appwrite>=9.0.3
+Requires-Dist: docstring-parser>=0.16
+Requires-Dist: mcp[cli]>=1.3.0
+Description-Content-Type: text/markdown
+
+# Appwrite MCP server
+
+<!-- Cover image will go here once available -->
+
+<a href="https://glama.ai/mcp/servers/xkj2px7r0v">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/xkj2px7r0v/badge" alt="Appwrite MCP server" />
+</a>
+
+## Overview
+
+A Model Context Protocol server for interacting with Appwrite's API. This server provides tools to manage databases, users, functions, teams, and more within your Appwrite project.
+
+## Quick Links
+- [Configuration](#configuration)
+- [Installation](#installation)
+- IDE Integration:
+  - [Claude Desktop](#usage-with-claude-desktop)
+  - [Cursor](#usage-with-cursor)
+  - [Windsurf Editor](#usage-with-windsurf-editor)
+- [Local Development](#local-development)
+- [Debugging](#debugging)
+
+## Configuration
+
+> Before launching the MCP server, you must setup an [Appwrite project](https://cloud.appwrite.io/) and create an API key with the necessary scopes enabled.
+
+Create a `.env` file in your working directory and add the following:
+
+```env
+APPWRITE_PROJECT_ID=your-project-id
+APPWRITE_API_KEY=your-api-key
+APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
+```
+
+Then, open your terminal and run the following command
+
+### Linux and MacOS
+
+```sh
+source .env
+```
+
+### Windows
+
+#### Command Prompt
+
+```cmd
+for /f "tokens=1,2 delims==" %A in (.env) do set %A=%B
+```
+
+#### PowerShell
+
+```powershell
+Get-Content .\.env | ForEach-Object {
+  if ($_ -match '^(.*?)=(.*)$') {
+    [System.Environment]::SetEnvironmentVariable($matches[1], $matches[2], "Process")
+  }
+}
+```
+
+## Installation
+
+### Using uv (recommended)
+When using [`uv`](https://docs.astral.sh/uv/) no specific installation is needed. We will
+use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run *mcp-server-appwrite*.
+
+```bash
+uvx mcp-server-appwrite [args]
+```
+
+### Using pip
+
+```bash
+pip install mcp-server-appwrite
+```
+Then run the server using 
+
+```bash
+python -m mcp_server_appwrite [args]
+```
+
+### Command-line arguments
+
+Both the `uv` and `pip` setup processes require certain arguments to enable MCP tools for various Appwrite APIs.
+
+> When an MCP tool is enabled, the tool's definition is passed to the LLM, using up tokens from the model's available context window. As a result, the effective context window is reduced.  
+>  
+> The default Appwrite MCP server ships with only the Databases tools (our most commonly used API) enabled to stay within these limits. Additional tools can be enabled by using the flags below.
+
+| Argument | Description |
+| --- | --- |
+| `--databases` | Enables the Databases API |
+| `--users` | Enables the Users API |
+| `--teams` | Enables the Teams API |
+| `--storage` | Enables the Storage API |
+| `--functions` | Enables the Functions API |
+| `--messaging` | Enables the Messaging API |
+| `--locale` | Enables the Locale API |
+| `--avatars` | Enables the Avatars API |
+| `--all` | Enables all Appwrite APIs |
+
+## Usage with Claude Desktop
+
+In the Claude Desktop app, open the app's **Settings** page (press `CTRL + ,` on Windows or `CMD + ,` on MacOS) and head to the **Developer** tab. Clicking on the **Edit Config** button will take you to the `claude_desktop_config.json` file, where you must add the following:
+
+```json
+{
+  "mcpServers": {
+    "appwrite": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-appwrite"
+      ],
+      "env": {
+        "APPWRITE_PROJECT_ID": "your-project-id",
+        "APPWRITE_API_KEY": "your-api-key",
+        "APPWRITE_ENDPOINT": "https://cloud.appwrite.io/v1" // Optional
+      }
+    }
+  }
+}
+
+```
+
+> Note: In case you see a `uvx ENOENT` error, ensure that you either add `uvx` to the `PATH` environment variable on your system or use the full path to your `uvx` installation in the config file.
+
+Upon successful configuration, you should be able to see the server in the list of available servers in Claude Desktop.
+
+![Claude Desktop Config](images/claude-desktop-integration.png)
+
+## Usage with [Cursor](https://www.cursor.com/)
+
+Head to Cursor `Settings > MCP` and click on **Add new MCP server**. Choose the type as `Command` and add the command below to the **Command** field.
+
+- **MacOS**
+
+```bash
+env APPWRITE_API_KEY=your-api-key env APPWRITE_PROJECT_ID=your-project-id uvx mcp-server-appwrite
+```
+
+- **Windows**
+
+```cmd
+cmd /c SET APPWRITE_PROJECT_ID=your-project-id && SET APPWRITE_API_KEY=your-api-key && uvx mcp-server-appwrite
+```
+
+![Cursor Settings](./images/cursor-integration.png)
+
+## Usage with [Windsurf Editor](https://codeium.com/windsurf)
+
+Head to Windsurf `Settings > Cascade > Model Context Protocol (MCP) Servers` and click on **View raw config**. Update the `mcp_config.json` file to include the following:
+
+```json
+{
+  "mcpServers": {
+    "appwrite": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-appwrite"
+      ],
+      "env": {
+        "APPWRITE_PROJECT_ID": "your-project-id",
+        "APPWRITE_API_KEY": "your-api-key",
+        "APPWRITE_ENDPOINT": "https://cloud.appwrite.io/v1" // Optional
+      }
+    }
+  }
+}
+```
+
+![Windsurf Settings](./images/windsurf-integration.png)
+
+## Local Development
+
+### Clone the repository
+
+```bash
+git clone https://github.com/appwrite/mcp.git
+```
+
+### Install `uv`
+
+- Linux or MacOS
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+- Windows (PowerShell)
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### Prepare virtual environment
+
+First, create a virtual environment.
+
+```bash
+uv venv
+```
+
+Next, activate the virtual environment.
+
+- Linux or MacOS
+
+```bash
+source .venv/bin/activate
+```
+
+- Windows
+
+```powershell
+.venv\Scripts\activate
+```
+
+### Run the server
+
+```bash
+uv run -v --directory ./ mcp-server-appwrite
+```
+
+## Debugging
+
+You can use the MCP inspector to debug the server. 
+
+```bash
+npx @modelcontextprotocol/inspector \
+  uv \
+  --directory . \
+  run mcp-server-appwrite
+```
+
+Make sure your `.env` file is properly configured before running the inspector. You can then access the inspector at `http://localhost:5173`.
+
+## License
+
+This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

mcp_server_appwrite-0.1.4.dist-info/RECORD

@@ -0,0 +1,10 @@
+mcp_server_appwrite/__init__.py,sha256=Od9oaUg_ckgJ4jIGa2HijocyauWDPjIC7cBRiV0P4s8,214
+mcp_server_appwrite/__main__.py,sha256=bdaX6xMmFugzSR2QMdXJqanRx_Jh25jACJDqjE9cKEc,75
+mcp_server_appwrite/server.py,sha256=JxNLY1O5lMUXUkBd2_kvN5mrh6dWsRPzX1VHi-XwCFs,5498
+mcp_server_appwrite/service.py,sha256=H_Qr8bYFyXuJVwsPsWFi1xx12-aPM75yblKj11L4V2c,4640
+mcp_server_appwrite/tool_manager.py,sha256=AfRjLyMpplYjF2VJna7frXDiDUZKRN8WQu9R8j3dxPc,718
+mcp_server_appwrite-0.1.4.dist-info/METADATA,sha256=Kxq2jAAuvpUz1P1rBRNuauSf3Ipg0TIJx01NFt2JMpY,6565
+mcp_server_appwrite-0.1.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcp_server_appwrite-0.1.4.dist-info/entry_points.txt,sha256=-FBKUOp-Qmo9FldmiT3JUyF7djSeo8lLhxljOosuHkQ,74
+mcp_server_appwrite-0.1.4.dist-info/licenses/LICENSE,sha256=PXzk1HbuQMAkLdHzwnBLTBIHFmgDZM0Ez2lw2gX2UQs,1096
+mcp_server_appwrite-0.1.4.dist-info/RECORD,,

mcp_server_appwrite-0.1.2.dist-info/METADATA

@@ -1,161 +0,0 @@
-Metadata-Version: 2.4
-Name: mcp-server-appwrite
-Version: 0.1.2
-Summary: MCP (Model Context Protocol) server for Appwrite
-License-File: LICENSE
-Requires-Python: >=3.12
-Requires-Dist: appwrite>=7.1.0
-Requires-Dist: mcp[cli]>=1.3.0
-Description-Content-Type: text/markdown
-
-# Appwrite MCP server
-
-## Overview
-
-A Model Context Protocol server for interacting with Appwrite's API. This server provides tools to manage databases, users, functions, teams, and more within your Appwrite project.
-
-Currently the server supports the following tools:
-
-- [x] Databases
-- [x] Users
-
-> Please note that adding a lot of tools exceeds the context window of the LLM. As a result, we will make available a curated list of tools that are most commonly used.
-
-## Configuration
-
-Create a `.env` file in the directory you're runing the server from:
-
-```env
-APPWRITE_API_KEY=your-api-key
-APPWRITE_PROJECT_ID=your-project-id
-APPWRITE_ENDPOINT=your-endpoint  # Optional, defaults to https://cloud.appwrite.io/v1
-```
-> Note: Ensure that your API Key has the necessary scopes to access the resources you want to use.
-
-## Installation
-
-### Using uv (recommended)
-When using [`uv`](https://docs.astral.sh/uv/) no specific installation is needed. We will
-use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run *mcp-server-sentry*.
-
-```bash
-uvx run mcp-server-appwrite
-```
-
-### Using pip
-
-```bash
-pip install mcp-server-appwrite
-```
-Then run the server using 
-
-```bash
-python -m mcp_server_appwrite
-```
-
-## Usage with Claude Desktop
-
-Add this to your `claude_desktop_config.json`:
-
-```json
-"mcpServers": {
-  "appwrite": {
-    "command": "uvx",
-    "args": [
-      "mcp-server-appwrite"
-    ],
-    "env": {
-      "APPWRITE_PROJECT_ID": "your-project-id",
-      "APPWRITE_API_KEY": "your-api-key",
-      "APPWRITE_ENDPOINT": "your-endpoint"  // Optional
-    }
-  }
-}
-```
-Upon successful configuration, you should be able to see the server in the list of available servers in Claude Desktop.
-
-![Claude Desktop Config](images/claude-desktop-integration.png)
-
-## Usage with [Zed](https://github.com/zed-industries/zed)
-
-Add to your Zed settings.json:
-
-```json
-"context_servers": {
-  "appwrite": {
-    "command": "uvx",
-    "args": [
-      "mcp-server-appwrite"
-    ],
-    "env": {
-      "APPWRITE_PROJECT_ID": "your-project-id",
-      "APPWRITE_API_KEY": "your-api-key",
-      "APPWRITE_ENDPOINT": "your-endpoint"  // Optional
-    }
-  }
-}
-```
-
-## Usage with [Cursor](https://www.cursor.com/)
-
-Head to Cursor `Settings > Features > MCP Servers` and click on **Add New MCP Server**. Choose the type as `Command` and add the command below to the **Command** field.
-
-```bash
-APPWRITE_PROJECT_ID=your-project-id APPWRITE_API_KEY=your-api-key uvx mcp-server-appwrite
-```
-
-![Cursor Settings](./images/cursor-integration.png)
-
-## Local Development
-
-Clone the repository
-
-```bash
-git clone https://github.com/appwrite/mcp.git
-```
-
-Install `uv`
-
-```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
-```
-
-Create virtual environment
-
-```bash
-uv venv
-source .venv/bin/activate
-```
-
-Run the server
-
-```bash
-uv run -v --directory ./ mcp-server-appwrite
-```
-
-## Debugging
-
-You can use the MCP inspector to debug the server. 
-
-```bash
-npx @modelcontextprotocol/inspector \
-  uv \
-  --directory . \
-  run mcp-server-appwrite
-```
-
-Make sure your `.env` file is properly configured before running the inspector. You can then access the inspector at `http://localhost:5173`.
-
-## License
-
-This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
-
-## Todos
-- Add MCP server to registries
-  - Glama
-  - https://github.com/chatmcp/mcp-directory
-  - https://mcp.so/
-  - https://github.com/punkpeye/awesome-mcp-servers
-  - https://portkey.ai/mcp-servers
-  - https://www.claudemcp.com/servers
-- Add support for SSE server

mcp_server_appwrite-0.1.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-mcp_server_appwrite/__init__.py,sha256=Od9oaUg_ckgJ4jIGa2HijocyauWDPjIC7cBRiV0P4s8,214
-mcp_server_appwrite/__main__.py,sha256=bdaX6xMmFugzSR2QMdXJqanRx_Jh25jACJDqjE9cKEc,75
-mcp_server_appwrite/server.py,sha256=a6y26aJXQ-NbaUwq3Yud2XT3xlxD6QTBgALDAkz2Cfo,3527
-mcp_server_appwrite/service.py,sha256=WwKoh9o7W7ZOmhY0yg6k4R2cghQRe-yMTNbFtB6TFT8,2895
-mcp_server_appwrite/tool_manager.py,sha256=AfRjLyMpplYjF2VJna7frXDiDUZKRN8WQu9R8j3dxPc,718
-mcp_server_appwrite-0.1.2.dist-info/METADATA,sha256=VA_JFBLw_fdqFghwgqX3YvHmTWksvQlV4H-ycsFcLtA,3964
-mcp_server_appwrite-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mcp_server_appwrite-0.1.2.dist-info/entry_points.txt,sha256=-FBKUOp-Qmo9FldmiT3JUyF7djSeo8lLhxljOosuHkQ,74
-mcp_server_appwrite-0.1.2.dist-info/licenses/LICENSE,sha256=PXzk1HbuQMAkLdHzwnBLTBIHFmgDZM0Ez2lw2gX2UQs,1096
-mcp_server_appwrite-0.1.2.dist-info/RECORD,,