# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

### Build and Development
```bash
# Build TypeScript to JavaScript
npm run build

# Watch mode for development
npm run dev

# Run the built server
npm start
```

### Testing and Validation
Before committing changes, ensure the TypeScript compiles without errors:
```bash
npm run build
```

## Architecture Overview

This is an Appwrite Model Context Protocol (MCP) server that provides a comprehensive interface between Claude and Appwrite services. The server is built in TypeScript and uses the official Appwrite Node.js SDK.

### Key Components

1. **MCP Server Core** (`src/index.ts`): 
   - Main server class `AppwriteMCPServer` that initializes all Appwrite service clients
   - Implements 135 tools covering all major Appwrite services
   - Uses environment variables for configuration (loaded from `.env` in current working directory)

2. **Service Clients**:
   - Databases, Users, Storage, Functions, Teams, Account, Health, Messaging, Locale, Avatars
   - All clients are initialized with API key authentication

3. **Tool Categories**:
   - Database operations (create, list, delete databases)
   - Collection management with attribute and index operations
   - Document CRUD with query support
   - User management including MFA, preferences, identities, and messaging targets
   - Storage bucket and file operations
   - Function management with deployments and variables
   - Messaging service (providers, messages, topics, subscribers)
   - Locale service for internationalization
   - Avatar generation utilities
   - Bulk operations for efficient batch processing
   - Advanced features like schema auto-detection and data analysis

### Configuration

The server reads configuration from environment variables:
- `APPWRITE_PROJECT_ID`: Target Appwrite project
- `APPWRITE_API_ENDPOINT`: Appwrite API endpoint (cloud or self-hosted)
- `APPWRITE_API_KEY`: API key with necessary scopes

The `.env` file is loaded from the current working directory where Claude Code is run, allowing project-specific configurations.

### Tool Implementation Pattern

Tools follow a consistent pattern:
1. Parse and validate input parameters
2. Initialize appropriate Appwrite service client
3. Execute the operation with error handling
4. Return formatted response with relevant data

### Error Handling

All tools implement comprehensive error handling:
- Configuration validation before operations
- Detailed error messages for debugging
- Graceful fallbacks for missing optional parameters

## Development Guidelines

1. **Adding New Tools**: Follow the existing pattern in `src/index.ts`, ensuring proper parameter validation and error handling.

2. **Type Safety**: Leverage TypeScript's strict mode for all new code. The project uses ES2022 target with Node16 module resolution.

3. **Environment Variables**: Never commit `.env` files. Use `.env.example` as a template for configuration.

4. **Build Output**: Compiled JavaScript goes to `dist/` directory. Source maps are generated for debugging.

## Integration Notes

This server can be integrated with:
- Claude Code (CLI) via `claude mcp add` command
- Cursor IDE via settings.json configuration
- Continue.dev via config.json

Each integration method supports different configuration approaches, with Claude Code using `.env` files and IDEs requiring inline environment variable configuration.