Compare commits
10 Commits
cc50c64423
...
0a362b37b1
| Author | SHA1 | Date | |
|---|---|---|---|
| 0a362b37b1 | |||
| 1ebc34764b | |||
| 5f7fc55d09 | |||
| 8a2f79dddb | |||
| dca14b1c9d | |||
| c0e76867a5 | |||
| d7c1111762 | |||
| 68b6067824 | |||
| 76f1180cde | |||
| 62f7f125d3 |
788
README.md
788
README.md
@@ -1,16 +1,32 @@
|
||||
# Appwrite MCP Server
|
||||
# 🚀 Appwrite MCP Server
|
||||
|
||||
A comprehensive Model Context Protocol (MCP) server that transforms Claude Code into an intelligent Appwrite management assistant.
|
||||
<div align="center">
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
**Transform Claude into your intelligent Appwrite management assistant**
|
||||
*135 powerful tools • Complete API coverage • Full Messaging & Locale Services • Production-ready*
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
A comprehensive **Model Context Protocol (MCP)** server that supercharges Claude with native Appwrite integration. Unlike the official implementation, this version includes advanced features like bulk operations, automatic schema validation, complete user management with MFA, storage file operations, function deployments & variables, full messaging service (topics, subscribers, providers), locale & avatars services, and comprehensive error handling.
|
||||
|
||||
## 🚀 Features
|
||||
|
||||
**Core Appwrite Management:**
|
||||
- Complete database and collection operations
|
||||
- Document CRUD with full query support
|
||||
- User management and authentication
|
||||
- Storage buckets and file operations
|
||||
- Serverless function management
|
||||
- Advanced user management with MFA, identities, preferences
|
||||
- Storage buckets and comprehensive file operations
|
||||
- Serverless function management with deployments & variables
|
||||
- Team and permission management
|
||||
- Complete messaging service (providers, messages, topics, subscribers)
|
||||
- Locale service (countries, currencies, languages, timezones)
|
||||
- Avatars service (icons, QR codes, initials, favicons)
|
||||
|
||||
**🧠 Intelligent Database Assistant:**
|
||||
- **Auto-detect schemas** from sample data
|
||||
@@ -19,233 +35,687 @@ A comprehensive Model Context Protocol (MCP) server that transforms Claude Code
|
||||
- **Index optimization** suggestions
|
||||
- **Schema migrations** with safety checks
|
||||
|
||||
## Installation
|
||||
**🔐 Advanced Authentication & Sessions:**
|
||||
- **Session management** (create, delete, list user sessions)
|
||||
- **Function execution** with logging and monitoring
|
||||
- **Health monitoring** for all Appwrite services
|
||||
|
||||
**⚡ Bulk Operations:**
|
||||
- **Bulk user management** (create, update, delete multiple users)
|
||||
- **Bulk document operations** (create, update, delete multiple documents)
|
||||
- **Efficient batch processing** with detailed success/error reporting
|
||||
|
||||
## 📦 Quick Start
|
||||
|
||||
### 1️⃣ Installation
|
||||
|
||||
1. Clone this repository:
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repository-url>
|
||||
cd appwrite-mcp-server
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
```
|
||||
|
||||
3. Build the TypeScript code:
|
||||
```bash
|
||||
# Build the TypeScript code
|
||||
npm run build
|
||||
```
|
||||
|
||||
4. Configure your Appwrite credentials by creating a `.env` file in your **current working directory** (where you run Claude Code from):
|
||||
### 2️⃣ Configuration
|
||||
|
||||
Create a `.env` file in your **current working directory** (where you run Claude Code from):
|
||||
|
||||
```bash
|
||||
# Copy the example file to your current working directory
|
||||
cp /path/to/app-write-mcp/.env.example ./.env
|
||||
```
|
||||
|
||||
5. Edit the `.env` file in your current directory with your Appwrite project details:
|
||||
```bash
|
||||
APPWRITE_PROJECT_ID=your-project-id
|
||||
Edit your `.env` file with your Appwrite credentials:
|
||||
|
||||
```env
|
||||
APPWRITE_PROJECT_ID=your-project-id-here
|
||||
APPWRITE_API_ENDPOINT=https://cloud.appwrite.io/v1
|
||||
APPWRITE_API_KEY=your-api-key
|
||||
APPWRITE_API_KEY=your-api-key-here
|
||||
```
|
||||
|
||||
**Important:** The MCP server looks for `.env` in the directory where Claude Code is currently running, not in the repository directory. This allows you to use different configurations for different projects without modifying the repository.
|
||||
> 💡 **Tip:** The MCP server looks for `.env` in the directory where Claude Code is running, allowing different configurations for different projects.
|
||||
|
||||
## Adding to Claude Code
|
||||
### 3️⃣ Integration Options
|
||||
|
||||
#### Option A: Claude Code (CLI) Integration
|
||||
|
||||
1. Add the MCP server to Claude Code:
|
||||
```bash
|
||||
# Add the MCP server to Claude Code
|
||||
claude mcp add appwrite-mcp-server "C:\path\to\your\app-write-mcp\dist\index.js"
|
||||
```
|
||||
|
||||
Replace the path with your actual project location. For example:
|
||||
```bash
|
||||
# Example with actual path
|
||||
claude mcp add appwrite-mcp-server "C:\Users\moh12\app-write-mcp\dist\index.js"
|
||||
```
|
||||
|
||||
3. Restart Claude Code if needed.
|
||||
#### Option B: Cursor IDE Integration
|
||||
|
||||
## Available Tools
|
||||
> 💡 **Note:** Cursor doesn't support `.env` files for MCP servers, so we pass environment variables directly in the configuration.
|
||||
|
||||
### 🗄️ Database Operations
|
||||
1. **Open Command Palette** (`Ctrl/Cmd + Shift + P`)
|
||||
|
||||
- **create_database**: Create a new database
|
||||
- **list_databases**: List all databases in your project
|
||||
- **delete_database**: Delete a database
|
||||
2. **Type "Preferences: Open Settings (JSON)"**
|
||||
|
||||
### 📁 Collection Operations
|
||||
3. **Add MCP Server Configuration to your settings.json:**
|
||||
```json
|
||||
{
|
||||
"mcp.servers": {
|
||||
"appwrite-mcp-server": {
|
||||
"command": "node",
|
||||
"args": ["C:\\path\\to\\your\\app-write-mcp\\dist\\index.js"],
|
||||
"env": {
|
||||
"APPWRITE_PROJECT_ID": "your-project-id-here",
|
||||
"APPWRITE_API_ENDPOINT": "https://cloud.appwrite.io/v1",
|
||||
"APPWRITE_API_KEY": "your-api-key-here"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- **create_collection**: Create a new collection in a database
|
||||
- **list_collections**: List all collections in a database
|
||||
- **delete_collection**: Delete a collection from a database
|
||||
4. **Replace the configuration values:**
|
||||
- **Path**: Update `C:\\path\\to\\your\\app-write-mcp\\dist\\index.js` with your actual path
|
||||
- **Project ID**: Your Appwrite project ID
|
||||
- **API Endpoint**: Your Appwrite endpoint (Cloud or self-hosted)
|
||||
- **API Key**: Your Appwrite API key with required permissions
|
||||
|
||||
### 🏷️ Attribute Management
|
||||
5. **Example configuration:**
|
||||
```json
|
||||
{
|
||||
"mcp.servers": {
|
||||
"appwrite-mcp-server": {
|
||||
"command": "node",
|
||||
"args": ["C:\\Users\\username\\app-write-mcp\\dist\\index.js"],
|
||||
"env": {
|
||||
"APPWRITE_PROJECT_ID": "6612345a000818bb9d2e",
|
||||
"APPWRITE_API_ENDPOINT": "https://cloud.appwrite.io/v1",
|
||||
"APPWRITE_API_KEY": "standard_1234567890abcdef..."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- **create_string_attribute**: Create a string attribute in a collection
|
||||
- **create_integer_attribute**: Create an integer attribute in a collection
|
||||
- **create_boolean_attribute**: Create a boolean attribute in a collection
|
||||
- **create_email_attribute**: Create an email attribute in a collection
|
||||
- **create_datetime_attribute**: Create a datetime attribute in a collection
|
||||
- **list_attributes**: List all attributes in a collection
|
||||
- **delete_attribute**: Delete an attribute from a collection
|
||||
6. **Save the file and restart Cursor** to load the MCP server
|
||||
|
||||
### 📊 Index Management
|
||||
#### Option C: Continue.dev Integration
|
||||
|
||||
- **create_index**: Create an index in a collection (key, fulltext, unique)
|
||||
- **list_indexes**: List all indexes in a collection
|
||||
- **delete_index**: Delete an index from a collection
|
||||
1. **Open your Continue configuration file** (`~/.continue/config.json`)
|
||||
|
||||
### 📄 Document Operations
|
||||
2. **Add the MCP server to your configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": [
|
||||
{
|
||||
"name": "appwrite-mcp-server",
|
||||
"command": "node",
|
||||
"args": ["C:\\path\\to\\your\\app-write-mcp\\dist\\index.js"],
|
||||
"env": {
|
||||
"APPWRITE_PROJECT_ID": "your-project-id-here",
|
||||
"APPWRITE_API_ENDPOINT": "https://cloud.appwrite.io/v1",
|
||||
"APPWRITE_API_KEY": "your-api-key-here"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- **create_document**: Create a new document in a collection
|
||||
- **get_document**: Get a document by ID
|
||||
- **list_documents**: List documents in a collection with optional queries
|
||||
- **update_document**: Update a document
|
||||
- **delete_document**: Delete a document
|
||||
3. **Replace with your actual credentials** (same as Cursor configuration above)
|
||||
|
||||
### 👥 User Management
|
||||
4. **Restart your IDE** to apply the changes
|
||||
|
||||
- **create_user**: Create a new user
|
||||
- **list_users**: List all users
|
||||
- **get_user**: Get a user by ID
|
||||
- **update_user_email**: Update user email
|
||||
- **update_user_name**: Update user name
|
||||
- **update_user_password**: Update user password
|
||||
- **delete_user**: Delete a user
|
||||
### 4️⃣ Verification
|
||||
|
||||
### 🗂️ Storage Operations
|
||||
Once integrated, you should be able to use commands like:
|
||||
- "List my Appwrite databases"
|
||||
- "Create a new user with email test@example.com"
|
||||
- "Show me all collections in my database"
|
||||
|
||||
- **create_bucket**: Create a storage bucket
|
||||
- **list_buckets**: List all storage buckets
|
||||
- **get_bucket**: Get a bucket by ID
|
||||
- **update_bucket**: Update a storage bucket
|
||||
- **delete_bucket**: Delete a storage bucket
|
||||
- **list_files**: List files in a storage bucket
|
||||
## 🛠️ Available Tools (135 Total)
|
||||
|
||||
### ⚡ Function Management
|
||||
<details>
|
||||
<summary><strong>🗄️ Database Operations (3 tools)</strong></summary>
|
||||
|
||||
- **create_function**: Create a new serverless function
|
||||
- **list_functions**: List all functions
|
||||
- **get_function**: Get a function by ID
|
||||
- **update_function**: Update a function
|
||||
- **delete_function**: Delete a function
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `create_database` | Create a new database |
|
||||
| `list_databases` | List all databases in your project |
|
||||
| `delete_database` | Delete a database |
|
||||
|
||||
### 👨👩👧👦 Team Management
|
||||
</details>
|
||||
|
||||
- **create_team**: Create a new team
|
||||
- **list_teams**: List all teams
|
||||
- **get_team**: Get a team by ID
|
||||
- **update_team**: Update a team
|
||||
- **delete_team**: Delete a team
|
||||
<details>
|
||||
<summary><strong>📁 Collection Operations (4 tools)</strong></summary>
|
||||
|
||||
### 🧠 Smart Schema Operations
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `create_collection` | Create a new collection in a database |
|
||||
| `get_collection` | ✨ Get collection details by ID |
|
||||
| `list_collections` | List all collections in a database |
|
||||
| `delete_collection` | Delete a collection from a database |
|
||||
|
||||
- **auto_detect_schema**: Analyze sample data and automatically create collection schema
|
||||
- **suggest_indexes**: Recommend optimal indexes based on collection usage patterns
|
||||
- **validate_document**: Check document data against collection schema before creation
|
||||
- **schema_migration**: Automatically migrate collection schema with data preservation
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🏷️ Attribute Management (5 tools)</strong></summary>
|
||||
|
||||
### 📊 Data Analysis & Insights
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `create_attribute` | ✨ Create any attribute type (string, integer, float, boolean, datetime, email, IP, URL, enum, relationship) |
|
||||
| `get_attribute` | ✨ Get attribute details by key |
|
||||
| `update_attribute` | ✨ Update any attribute type with unified interface |
|
||||
| `list_attributes` | List all attributes in a collection |
|
||||
| `delete_attribute` | Delete an attribute from a collection |
|
||||
|
||||
- **analyze_collection**: Get comprehensive data insights and patterns from collections
|
||||
- **detect_duplicates**: Find potential duplicate records with similarity scoring
|
||||
- **data_quality_check**: Analyze data quality (completeness, validity, consistency)
|
||||
- **usage_stats**: Get usage statistics and access patterns for collections
|
||||
</details>
|
||||
|
||||
## Configuration
|
||||
<details>
|
||||
<summary><strong>📊 Index Management (4 tools)</strong></summary>
|
||||
|
||||
### Getting Appwrite Credentials
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `create_index` | Create an index in a collection (key, fulltext, unique) |
|
||||
| `get_index` | ✨ Get index details by key |
|
||||
| `list_indexes` | List all indexes in a collection |
|
||||
| `delete_index` | Delete an index from a collection |
|
||||
|
||||
1. **Project ID**: Found in your Appwrite console under Settings > General
|
||||
2. **API Endpoint**:
|
||||
- For Appwrite Cloud: `https://cloud.appwrite.io/v1`
|
||||
- For self-hosted: `https://your-domain.com/v1`
|
||||
3. **API Key**: Create a new API key in your Appwrite console under Settings > API Keys
|
||||
- Make sure to give it appropriate permissions for databases and collections
|
||||
</details>
|
||||
|
||||
### Configuration File
|
||||
<details>
|
||||
<summary><strong>📄 Document Operations (5 tools)</strong></summary>
|
||||
|
||||
The `appwrite-config.json` file should be in the root directory of this project:
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `create_document` | Create a new document in a collection ✨ *with schema validation* |
|
||||
| `get_document` | Get a document by ID |
|
||||
| `list_documents` | List documents in a collection with optional queries |
|
||||
| `update_document` | Update a document |
|
||||
| `delete_document` | Delete a document |
|
||||
|
||||
```json
|
||||
{
|
||||
"projectId": "your-project-id-here",
|
||||
"apiEndpoint": "https://cloud.appwrite.io/v1",
|
||||
"apiKey": "your-api-key-here"
|
||||
}
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>👥 User Management (25 tools)</strong></summary>
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `create_user` | Create a new user |
|
||||
| `list_users` | ✨ List all users with email/phone verification columns |
|
||||
| `get_user` | Get a user by ID |
|
||||
| `update_user_email` | Update user email |
|
||||
| `update_user_name` | Update user name |
|
||||
| `update_user_password` | Update user password |
|
||||
| `update_user_password_hash` | ✨ Update password with specific hash algorithm |
|
||||
| `delete_user` | Delete a user |
|
||||
| `verify_user_email` | ✨ Verify a user's email address |
|
||||
| `unverify_user_email` | ✨ Unverify a user's email address |
|
||||
| `verify_user_phone` | ✨ Verify a user's phone number |
|
||||
| `unverify_user_phone` | ✨ Unverify a user's phone number |
|
||||
| `update_user_mfa` | ✨ Enable/disable MFA for users |
|
||||
| `create_user_mfa_recovery_codes` | ✨ Generate MFA recovery codes |
|
||||
| `update_user_phone_verification` | ✨ Update phone verification status |
|
||||
| `update_user_labels` | ✨ Update user labels for permissions |
|
||||
| `get_user_preferences` | ✨ Get user preferences |
|
||||
| `update_user_preferences` | ✨ Update user preferences |
|
||||
| `list_user_identities` | ✨ List user identities |
|
||||
| `delete_user_identity` | ✨ Delete user identity |
|
||||
| `create_user_target` | ✨ Create messaging targets |
|
||||
| `list_user_targets` | ✨ List messaging targets |
|
||||
| `get_user_target` | ✨ Get messaging target details |
|
||||
| `update_user_target` | ✨ Update messaging target |
|
||||
| `delete_user_target` | ✨ Delete messaging target |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🗂️ Storage Operations (13 tools)</strong></summary>
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `create_bucket` | Create a storage bucket |
|
||||
| `list_buckets` | List all storage buckets |
|
||||
| `get_bucket` | Get a bucket by ID |
|
||||
| `update_bucket` | Update a storage bucket |
|
||||
| `delete_bucket` | Delete a storage bucket |
|
||||
| `list_files` | List files in a storage bucket |
|
||||
| `get_file` | ✨ Get file details by ID |
|
||||
| `create_file` | ✨ Upload file to storage bucket |
|
||||
| `update_file` | ✨ Update file metadata |
|
||||
| `get_file_download` | ✨ Get file download URL |
|
||||
| `get_file_preview` | ✨ Get file preview URL with image transformations |
|
||||
| `get_file_view` | ✨ Get file view URL |
|
||||
| `delete_file` | ✨ Delete a file |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>⚡ Function Management (14 tools)</strong></summary>
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `create_function` | Create a new serverless function |
|
||||
| `list_functions` | List all functions |
|
||||
| `get_function` | Get a function by ID |
|
||||
| `update_function` | Update a function |
|
||||
| `delete_function` | Delete a function |
|
||||
| `list_function_deployments` | ✨ List function deployments |
|
||||
| `get_function_deployment` | ✨ Get deployment details |
|
||||
| `update_function_deployment` | ✨ Update deployment status |
|
||||
| `delete_function_deployment` | ✨ Delete deployment |
|
||||
| `create_function_variable` | ✨ Create function variables |
|
||||
| `list_function_variables` | ✨ List function variables |
|
||||
| `get_function_variable` | ✨ Get variable details |
|
||||
| `update_function_variable` | ✨ Update variables |
|
||||
| `delete_function_variable` | ✨ Delete variables |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>👨👩👧👦 Team Management (5 tools)</strong></summary>
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `create_team` | Create a new team |
|
||||
| `list_teams` | List all teams |
|
||||
| `get_team` | Get a team by ID |
|
||||
| `update_team` | Update a team |
|
||||
| `delete_team` | Delete a team |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>📧 Messaging Operations (20 tools)</strong></summary>
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `create_messaging_provider` | ✨ Create messaging provider |
|
||||
| `list_messaging_providers` | ✨ List messaging providers |
|
||||
| `get_messaging_provider` | ✨ Get messaging provider details |
|
||||
| `update_messaging_provider` | ✨ Update messaging provider |
|
||||
| `delete_messaging_provider` | ✨ Delete messaging provider |
|
||||
| `create_messaging_message` | ✨ Create and send message |
|
||||
| `list_messaging_messages` | ✨ List messages |
|
||||
| `get_messaging_message` | ✨ Get message details |
|
||||
| `update_messaging_message` | ✨ Update message |
|
||||
| `delete_messaging_message` | ✨ Delete message |
|
||||
| `create_messaging_topic` | ✨ Create messaging topic |
|
||||
| `list_messaging_topics` | ✨ List messaging topics |
|
||||
| `get_messaging_topic` | ✨ Get topic details |
|
||||
| `update_messaging_topic` | ✨ Update topic |
|
||||
| `delete_messaging_topic` | ✨ Delete topic |
|
||||
| `create_messaging_subscriber` | ✨ Create topic subscriber |
|
||||
| `list_messaging_subscribers` | ✨ List topic subscribers |
|
||||
| `get_messaging_subscriber` | ✨ Get subscriber details |
|
||||
| `delete_messaging_subscriber` | ✨ Delete subscriber |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🌍 Locale Operations (5 tools)</strong></summary>
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `list_countries` | ✨ List all countries with phone codes |
|
||||
| `list_continents` | ✨ List all continents |
|
||||
| `list_currencies` | ✨ List all currencies |
|
||||
| `list_languages` | ✨ List all languages |
|
||||
| `list_phone_codes` | ✨ List phone codes for countries |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🎨 Avatars Operations (7 tools)</strong></summary>
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `get_browser_icon` | ✨ Get browser icon URL |
|
||||
| `get_credit_card_icon` | ✨ Get credit card icon URL |
|
||||
| `get_favicon` | ✨ Get website favicon URL |
|
||||
| `get_flag_icon` | ✨ Get country flag icon URL |
|
||||
| `get_image_from_url` | ✨ Transform image from URL |
|
||||
| `get_initials_avatar` | ✨ Generate initials avatar URL |
|
||||
| `get_qr_code` | ✨ Generate QR code URL |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
### 🌟 **Exclusive Advanced Features**
|
||||
|
||||
<details>
|
||||
<summary><strong>🧠 Smart Schema Operations (4 tools)</strong></summary>
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `auto_detect_schema` | ✨ Analyze sample data and automatically create collection schema |
|
||||
| `suggest_indexes` | ✨ Recommend optimal indexes based on collection usage patterns |
|
||||
| `validate_document` | ✨ Check document data against collection schema before creation |
|
||||
| `schema_migration` | ✨ Automatically migrate collection schema with data preservation |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>📊 Data Analysis & Insights (4 tools)</strong></summary>
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `analyze_collection` | ✨ Get comprehensive data insights and patterns from collections |
|
||||
| `detect_duplicates` | ✨ Find potential duplicate records with similarity scoring |
|
||||
| `data_quality_check` | ✨ Analyze data quality (completeness, validity, consistency) |
|
||||
| `usage_stats` | ✨ Get usage statistics and access patterns for collections |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🔐 Authentication & Sessions (3 tools)</strong></summary>
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `create_session` | ✨ Create a new user session with email and password |
|
||||
| `delete_session` | ✨ Delete a user session |
|
||||
| `list_sessions` | ✨ List all sessions for a user |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>⚡ Function Execution (3 tools)</strong></summary>
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `execute_function` | ✨ Execute a function with optional data |
|
||||
| `list_executions` | ✨ List function executions with logs |
|
||||
| `get_execution` | ✨ Get details of a specific function execution |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🏥 Health Monitoring (3 tools)</strong></summary>
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `get_health` | ✨ Get overall health status of Appwrite services |
|
||||
| `get_health_db` | ✨ Get database health status |
|
||||
| `get_health_storage` | ✨ Get storage health status |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>⚡ Bulk Operations (8 tools)</strong></summary>
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `bulk_create_attributes` | ✨ Create multiple attributes at once in a collection |
|
||||
| `bulk_delete_attributes` | ✨ Delete multiple attributes at once from a collection |
|
||||
| `bulk_create_users` | ✨ Create multiple users at once |
|
||||
| `bulk_update_users` | ✨ Update multiple users at once |
|
||||
| `bulk_delete_users` | ✨ Delete multiple users at once |
|
||||
| `bulk_create_documents` | ✨ Create multiple documents at once |
|
||||
| `bulk_update_documents` | ✨ Update multiple documents at once |
|
||||
| `bulk_delete_documents` | ✨ Delete multiple documents at once |
|
||||
|
||||
</details>
|
||||
|
||||
> ✨ **Exclusive features** not available in the official Appwrite MCP implementation
|
||||
|
||||
## ⚙️ Configuration Guide
|
||||
|
||||
### 🔑 Getting Appwrite Credentials
|
||||
|
||||
1. **🆔 Project ID**: Found in your Appwrite console under **Settings > General**
|
||||
2. **🌐 API Endpoint**:
|
||||
- **Appwrite Cloud**: `https://cloud.appwrite.io/v1`
|
||||
- **Self-hosted**: `https://your-domain.com/v1`
|
||||
3. **🔐 API Key**: Create a new API key in your Appwrite console under **Settings > API Keys**
|
||||
- ✅ Enable all scopes for full functionality
|
||||
- ⚠️ Required scopes: `databases.read`, `databases.write`, `users.read`, `users.write`, `functions.read`, `functions.write`, `storage.read`, `storage.write`, `targets.read`, `targets.write`, `providers.read`, `providers.write`, `messages.read`, `messages.write`, `topics.read`, `topics.write`, `subscribers.read`, `subscribers.write`, `locale.read`, `avatars.read`, `health.read`
|
||||
|
||||
### 🎯 VS Official Implementation
|
||||
|
||||
| Feature | Our Implementation | Official Appwrite MCP |
|
||||
|---------|-------------------|----------------------|
|
||||
| **Tools Available** | 🟢 135 tools (complete coverage) | 🟡 195 tools (selective enabling) |
|
||||
| **Default Setup** | 🟢 Complete coverage out-of-box | 🟡 Database tools only (context limits) |
|
||||
| **Messaging Service** | 🟢 Complete (providers, messages, topics, subscribers) | 🟡 Selective enabling required |
|
||||
| **Locale & Avatars** | 🟢 Complete internationalization support | 🟡 Selective enabling required |
|
||||
| **Storage Operations** | 🟢 Complete file operations & uploads | 🟡 Basic bucket operations |
|
||||
| **User Management** | 🟢 MFA, identities, preferences, targets | 🟡 Basic CRUD only |
|
||||
| **Functions Service** | 🟢 Deployments & variables included | 🟡 Basic function management |
|
||||
| **Bulk Operations** | 🟢 Full support | 🔴 Not available |
|
||||
| **Schema Validation** | 🟢 Automatic | 🔴 Manual only |
|
||||
| **Error Handling** | 🟢 Comprehensive | 🟡 Basic |
|
||||
| **Language** | 🟡 TypeScript/Node.js | 🟢 Python |
|
||||
| **Context Efficiency** | 🟡 All tools use context | 🟢 Selective loading saves context |
|
||||
| **Self-Hosted Focus** | 🟢 Optimized for self-hosted | 🟡 Cloud-first approach |
|
||||
|
||||
## 🎯 Usage Examples
|
||||
|
||||
Once integrated, you can use natural language commands with Claude to interact with Appwrite:
|
||||
|
||||
<details>
|
||||
<summary><strong>🗄️ Database & Collection Management</strong></summary>
|
||||
|
||||
```
|
||||
✨ "Create a new database called 'ecommerce'"
|
||||
✨ "List all my databases"
|
||||
✨ "Create a collection called 'products' in the ecommerce database"
|
||||
✨ "Show me all collections in the ecommerce database"
|
||||
✨ "Delete the old 'test' database"
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
</details>
|
||||
|
||||
Once added to Claude Code, you can use natural language to interact with Appwrite:
|
||||
<details>
|
||||
<summary><strong>🏷️ Schema & Attributes</strong></summary>
|
||||
|
||||
**Database & Collection Management:**
|
||||
- "Create a new database called 'blog'"
|
||||
- "List all my databases"
|
||||
- "Create a collection called 'posts' in the blog database"
|
||||
- "Show me all collections in the blog database"
|
||||
```
|
||||
✨ "Create a string attribute called 'name' in the products collection with max size 255"
|
||||
✨ "Add a boolean attribute 'in_stock' to the products collection"
|
||||
✨ "Create an enum attribute 'status' with values active, inactive, pending"
|
||||
✨ "Add a relationship attribute linking products to categories"
|
||||
✨ "Bulk create attributes: name (string), price (float), in_stock (boolean)"
|
||||
✨ "Bulk delete attributes: old_field1, deprecated_field2, unused_field3"
|
||||
✨ "List all attributes in the products collection"
|
||||
✨ "Create a unique index on the 'sku' attribute"
|
||||
```
|
||||
|
||||
**Attribute & Schema Management:**
|
||||
- "Add a string attribute called 'title' to the posts collection with max size 255"
|
||||
- "Create a boolean attribute 'published' in the posts collection"
|
||||
- "List all attributes in the posts collection"
|
||||
- "Create a unique index on the 'slug' attribute"
|
||||
</details>
|
||||
|
||||
**Document Operations:**
|
||||
- "Create a new document in the posts collection with title 'Hello World'"
|
||||
- "List all documents in the posts collection"
|
||||
- "Update document xyz123 in the posts collection"
|
||||
- "Get document abc456 from the posts collection"
|
||||
<details>
|
||||
<summary><strong>📄 Document Operations</strong></summary>
|
||||
|
||||
**User Management:**
|
||||
- "Create a new user with email john@example.com"
|
||||
- "List all users in the project"
|
||||
- "Update user xyz123's name to 'John Doe'"
|
||||
- "Delete user abc456"
|
||||
```
|
||||
✨ "Create a new product document with name 'iPhone 15' and price 999"
|
||||
✨ "List all documents in the products collection"
|
||||
✨ "Update document xyz123's price to 899"
|
||||
✨ "Get document abc456 from the products collection"
|
||||
✨ "Delete all out-of-stock products"
|
||||
```
|
||||
|
||||
**Storage Management:**
|
||||
- "Create a storage bucket called 'images'"
|
||||
- "List all storage buckets"
|
||||
- "Show me all files in the images bucket"
|
||||
</details>
|
||||
|
||||
**Function Management:**
|
||||
- "Create a new function called 'sendEmail' with Node.js runtime"
|
||||
- "List all functions"
|
||||
- "Update function abc123's timeout to 300 seconds"
|
||||
<details>
|
||||
<summary><strong>👥 User & Authentication</strong></summary>
|
||||
|
||||
**Team Management:**
|
||||
- "Create a new team called 'Developers'"
|
||||
- "List all teams"
|
||||
- "Add user john@example.com to the Developers team"
|
||||
```
|
||||
✨ "Create a new user with email john@example.com and password SecurePass123"
|
||||
✨ "List all users in the project"
|
||||
✨ "Update user xyz123's name to 'John Doe'"
|
||||
✨ "Verify user abc123's email address"
|
||||
✨ "Enable MFA for user xyz123"
|
||||
✨ "Generate MFA recovery codes for user abc456"
|
||||
✨ "Update user labels for permissions: ['admin', 'moderator']"
|
||||
✨ "Get user preferences for user xyz123"
|
||||
✨ "Create messaging target for user notifications"
|
||||
✨ "List all identities for user abc123"
|
||||
✨ "Create a session for user john@example.com"
|
||||
✨ "Bulk create 10 test users for demo purposes"
|
||||
```
|
||||
|
||||
**🧠 Smart Schema Operations:**
|
||||
- "Analyze this sample data and create a collection for me"
|
||||
- "Suggest optimal indexes for my users collection"
|
||||
- "Validate this document before I create it"
|
||||
- "Migrate my collection to add these new fields safely"
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🗂️ Storage & File Management</strong></summary>
|
||||
|
||||
**📊 Data Analysis & Insights:**
|
||||
- "Analyze the health and patterns in my users collection"
|
||||
- "Find duplicate records in my products collection"
|
||||
- "Check the data quality of my orders collection"
|
||||
- "Show me usage statistics for my database"
|
||||
```
|
||||
✨ "Create a new storage bucket for user uploads"
|
||||
✨ "List all files in the images bucket"
|
||||
✨ "Get download URL for file abc123"
|
||||
✨ "Generate preview URL for image with 300x200 dimensions"
|
||||
✨ "Get file view URL for document xyz456"
|
||||
✨ "Delete old file from storage bucket"
|
||||
```
|
||||
|
||||
## Development
|
||||
</details>
|
||||
|
||||
- `npm run build`: Build TypeScript to JavaScript
|
||||
- `npm run dev`: Watch mode for development
|
||||
- `npm start`: Run the built server
|
||||
<details>
|
||||
<summary><strong>⚡ Functions & Deployments</strong></summary>
|
||||
|
||||
## Troubleshooting
|
||||
```
|
||||
✨ "Create a new function for email processing"
|
||||
✨ "List all deployments for function abc123"
|
||||
✨ "Create function variable API_KEY with secret value"
|
||||
✨ "Update function variable to new value"
|
||||
✨ "List all variables for function xyz456"
|
||||
✨ "Execute function with user data payload"
|
||||
```
|
||||
|
||||
1. **Configuration not found**: Make sure `appwrite-config.json` exists in the project root
|
||||
2. **API Key issues**: Ensure your API key has the correct permissions for database operations
|
||||
3. **Connection issues**: Verify your API endpoint is correct (especially for self-hosted instances)
|
||||
</details>
|
||||
|
||||
## License
|
||||
<details>
|
||||
<summary><strong>🚀 Advanced Features (Exclusive)</strong></summary>
|
||||
|
||||
MIT
|
||||
```
|
||||
🚀 "Create a complete product schema with string, enum, float, and relationship attributes"
|
||||
🚀 "Bulk create 10 attributes at once for my e-commerce collection"
|
||||
🚀 "Add a relationship attribute linking orders to customers with two-way binding"
|
||||
🚀 "Create an enum attribute for user roles with admin, user, moderator values"
|
||||
🚀 "Analyze this sample data and create a collection schema automatically"
|
||||
🚀 "Suggest optimal indexes for my users collection based on usage"
|
||||
🚀 "Validate this document data before creating it"
|
||||
🚀 "Find duplicate records in my customers collection"
|
||||
🚀 "Check the data quality of my orders collection"
|
||||
🚀 "Bulk create 100 user accounts from this CSV data"
|
||||
🚀 "Execute the 'sendWelcomeEmail' function with user data"
|
||||
🚀 "Show me the health status of all Appwrite services"
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>📧 Messaging & Communication</strong></summary>
|
||||
|
||||
```
|
||||
✨ "Create a messaging provider for email notifications"
|
||||
✨ "List all messaging topics"
|
||||
✨ "Create a topic for user announcements"
|
||||
✨ "Add subscribers to the announcements topic"
|
||||
✨ "Send a message to all subscribers"
|
||||
✨ "List all messages and their delivery status"
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🌍 Internationalization & Locale</strong></summary>
|
||||
|
||||
```
|
||||
✨ "List all supported countries"
|
||||
✨ "Get phone codes for all countries"
|
||||
✨ "Show me all available currencies"
|
||||
✨ "List all supported languages"
|
||||
✨ "Get continent information"
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🎨 Avatars & Visual Content</strong></summary>
|
||||
|
||||
```
|
||||
✨ "Generate QR code for this URL"
|
||||
✨ "Get flag icon for United States"
|
||||
✨ "Create initials avatar for John Doe"
|
||||
✨ "Get favicon for google.com"
|
||||
✨ "Generate browser icon for Chrome"
|
||||
✨ "Get credit card icon for Visa"
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### 🎬 **Real-World Scenarios**
|
||||
|
||||
**E-commerce Setup:**
|
||||
```
|
||||
1. "Create an ecommerce database"
|
||||
2. "Auto-detect schema from this product sample data"
|
||||
3. "Bulk import 500 products from my inventory"
|
||||
4. "Set up user authentication for customers"
|
||||
5. "Create indexes for search optimization"
|
||||
```
|
||||
|
||||
**Content Management:**
|
||||
```
|
||||
1. "Create a blog database with posts and comments collections"
|
||||
2. "Validate my blog post structure before saving"
|
||||
3. "Find duplicate content across my posts"
|
||||
4. "Analyze user engagement patterns"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Development
|
||||
|
||||
```bash
|
||||
# Build TypeScript to JavaScript
|
||||
npm run build
|
||||
|
||||
# Watch mode for development
|
||||
npm run dev
|
||||
|
||||
# Run the built server
|
||||
npm start
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
<details>
|
||||
<summary><strong>Common Issues & Solutions</strong></summary>
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| **❌ Configuration not found** | Make sure `.env` file exists in your working directory |
|
||||
| **❌ API Key issues** | Ensure your API key has all required scopes enabled |
|
||||
| **❌ Connection failed** | Verify your API endpoint is correct (check for typos) |
|
||||
| **❌ Tools not loading** | Restart your IDE after adding the MCP server |
|
||||
| **❌ Permission denied** | Check that your API key has `databases.write`, `users.write` permissions |
|
||||
| **❌ Schema validation errors** | Use `list_attributes` to check collection schema before creating documents |
|
||||
|
||||
</details>
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch: `git checkout -b feature/amazing-feature`
|
||||
3. Commit your changes: `git commit -m 'Add amazing feature'`
|
||||
4. Push to the branch: `git push origin feature/amazing-feature`
|
||||
5. Open a Pull Request
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - see [LICENSE](LICENSE) file for details
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**⭐ Star this repo if it helped you!**
|
||||
|
||||
Built with ❤️ for the Appwrite and Claude communities
|
||||
|
||||
[Report Bug](https://github.com/your-repo/issues) • [Request Feature](https://github.com/your-repo/issues) • [Documentation](https://github.com/your-repo/wiki)
|
||||
|
||||
</div>
|
||||
3639
src/index.ts
3639
src/index.ts
File diff suppressed because it is too large
Load Diff
@@ -1,8 +1,8 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "ESNext",
|
||||
"moduleResolution": "node",
|
||||
"module": "Node16",
|
||||
"moduleResolution": "node16",
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"strict": true,
|
||||
|
||||
Reference in New Issue
Block a user