app-write-mcp/README.md

# 🚀 Appwrite MCP Server

<div align="center">

![Appwrite MCP](https://img.shields.io/badge/Appwrite-MCP-red?style=for-the-badge&logo=appwrite)
![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)
![Claude](https://img.shields.io/badge/Claude-AI-orange?style=for-the-badge)

**Transform Claude into your intelligent Appwrite management assistant**  
*67 powerful tools • Schema validation • Bulk operations • 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, data quality checks, 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
- Team and permission management

**🧠 Intelligent Database Assistant:**
- **Auto-detect schemas** from sample data
- **Data quality analysis** and recommendations
- **Duplicate detection** with similarity matching
- **Index optimization** suggestions
- **Schema migrations** with safety checks

**🔐 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

```bash
# Clone the repository
git clone <repository-url>
cd appwrite-mcp-server

# Install dependencies
npm install

# Build the TypeScript code
npm run build
```

### 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
```

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-here
```

> 💡 **Tip:** The MCP server looks for `.env` in the directory where Claude Code is running, allowing different configurations for different projects.

### 3️⃣ Integration Options

#### Option A: Claude Code (CLI) Integration

```bash
# Add the MCP server to Claude Code
claude mcp add appwrite-mcp-server "C:\path\to\your\app-write-mcp\dist\index.js"

# Example with actual path
claude mcp add appwrite-mcp-server "C:\Users\moh12\app-write-mcp\dist\index.js"
```

#### Option B: Cursor IDE Integration

> 💡 **Note:** Cursor doesn't support `.env` files for MCP servers, so we pass environment variables directly in the configuration.

1. **Open Command Palette** (`Ctrl/Cmd + Shift + P`)

2. **Type "Preferences: Open Settings (JSON)"**

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"
         }
       }
     }
   }
   ```

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

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..."
         }
       }
     }
   }
   ```

6. **Save the file and restart Cursor** to load the MCP server

#### Option C: Continue.dev Integration

1. **Open your Continue configuration file** (`~/.continue/config.json`)

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"
         }
       }
     ]
   }
   ```

3. **Replace with your actual credentials** (same as Cursor configuration above)

4. **Restart your IDE** to apply the changes

### 4️⃣ Verification

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"

## 🛠️ Available Tools (67 Total)

<details>
<summary><strong>🗄️ Database Operations (3 tools)</strong></summary>

| Tool | Description |
|------|-------------|
| `create_database` | Create a new database |
| `list_databases` | List all databases in your project |
| `delete_database` | Delete a database |

</details>

<details>
<summary><strong>📁 Collection Operations (3 tools)</strong></summary>

| Tool | Description |
|------|-------------|
| `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 |

</details>

<details>
<summary><strong>🏷️ Attribute Management (3 tools)</strong></summary>

| Tool | Description |
|------|-------------|
| `create_attribute` | ✨ Create any attribute type (string, integer, float, boolean, datetime, email, IP, URL, enum, relationship) |
| `list_attributes` | List all attributes in a collection |
| `delete_attribute` | Delete an attribute from a collection |

</details>

<details>
<summary><strong>📊 Index Management (3 tools)</strong></summary>

| Tool | Description |
|------|-------------|
| `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 |

</details>

<details>
<summary><strong>📄 Document Operations (5 tools)</strong></summary>

| 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 |

</details>

<details>
<summary><strong>👥 User Management (9 tools)</strong></summary>

| Tool | Description |
|------|-------------|
| `create_user` | Create a new user |
| `list_users` | List all users ✨ *with verification status* |
| `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 |
| `verify_user_email` | ✨ Verify a user's email address |
| `unverify_user_email` | ✨ Unverify a user's email address |

</details>

<details>
<summary><strong>🗂️ Storage Operations (6 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 |

</details>

<details>
<summary><strong>⚡ Function Management (5 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 |

</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>

---

### 🌟 **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`

### 🎯 VS Official Implementation

| Feature | Our Implementation | Official Appwrite MCP |
|---------|-------------------|----------------------|
| **Tools Available** | 🟢 67 tools | 🟡 ~50 tools |
| **Bulk Operations** | 🟢 Full support | 🔴 Not available |
| **Schema Validation** | 🟢 Automatic | 🔴 Manual only |
| **Error Handling** | 🟢 Comprehensive | 🟡 Basic |
| **Language** | 🟡 TypeScript/Node.js | 🟢 Python |
| **Memory Usage** | 🟡 Higher (monolithic) | 🟢 Lower (modular) |
| **Deployment** | 🟢 Single executable | 🟡 Multiple dependencies |

## 🎯 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"
```

</details>

<details>
<summary><strong>🏷️ Schema & Attributes</strong></summary>

```
✨ "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"
```

</details>

<details>
<summary><strong>📄 Document Operations</strong></summary>

```
✨ "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"
```

</details>

<details>
<summary><strong>👥 User & Authentication</strong></summary>

```
✨ "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"
✨ "Unverify user xyz456's email verification"
✨ "Create a session for user john@example.com"
✨ "Bulk create 10 test users for demo purposes"
```

</details>

<details>
<summary><strong>⚡ Advanced Features (Exclusive)</strong></summary>

```
🚀 "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>

### 🎬 **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>