app-write-mcp/README.md

# Appwrite MCP Server

A comprehensive Model Context Protocol (MCP) server that transforms Claude Code into an intelligent Appwrite management assistant.

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

## Installation

1. Clone this repository:
```bash
git clone <repository-url>
cd appwrite-mcp-server
```

2. Install dependencies:
```bash
npm install
```

3. Build the TypeScript code:
```bash
npm run build
```

4. Configure your Appwrite credentials by creating 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
APPWRITE_API_ENDPOINT=https://cloud.appwrite.io/v1
APPWRITE_API_KEY=your-api-key
```

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

## Adding to Claude Code

1. Add the MCP server to Claude Code:
```bash
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
claude mcp add appwrite-mcp-server "C:\Users\moh12\app-write-mcp\dist\index.js"
```

3. Restart Claude Code if needed.

## Available Tools

### 🗄️ Database Operations

- **create_database**: Create a new database
- **list_databases**: List all databases in your project
- **delete_database**: Delete a database

### 📁 Collection Operations

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

### 🏷️ Attribute Management

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

### 📊 Index Management

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

### 📄 Document Operations

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

### 👥 User Management

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

### 🗂️ Storage Operations

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

### ⚡ Function Management

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

### 👨‍👩‍👧‍👦 Team Management

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

### 🧠 Smart Schema Operations

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


### 📊 Data Analysis & Insights

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

## Configuration

### Getting Appwrite Credentials

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

### Configuration File

The `appwrite-config.json` file should be in the root directory of this project:

```json
{
  "projectId": "your-project-id-here",
  "apiEndpoint": "https://cloud.appwrite.io/v1",
  "apiKey": "your-api-key-here"
}
```

## Usage Examples

Once added to Claude Code, you can use natural language to interact with Appwrite:

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

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

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

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

**Storage Management:**
- "Create a storage bucket called 'images'"
- "List all storage buckets"
- "Show me all files in the images bucket"

**Function Management:**
- "Create a new function called 'sendEmail' with Node.js runtime"
- "List all functions"
- "Update function abc123's timeout to 300 seconds"

**Team Management:**
- "Create a new team called 'Developers'"
- "List all teams"
- "Add user john@example.com to the Developers team"

**🧠 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"


**📊 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"

## Development

- `npm run build`: Build TypeScript to JavaScript
- `npm run dev`: Watch mode for development
- `npm start`: Run the built server

## Troubleshooting

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)

## License

MIT