94 lines
3.4 KiB
Markdown
94 lines
3.4 KiB
Markdown
# 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. |