app-write-mcp/CLAUDE.md

CLAUDE.md

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

Commands

Build and Development

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

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.