appwrite-mcp-server

v1.0.1

Published

18 days ago

MCP Server for Appwrite CLI - Enable AI agents to execute Appwrite CLI commands via Model Context Protocol

0High
0Medium
0Low

yaomian.ym

mcp model-context-protocol appwrite cli ai agent cursor

Appwrite CLI MCP Server

基于 Appwrite SDK for CLI 构建的 Model Context Protocol (MCP) Server，将 Appwrite 命令行工具封装成 MCP 工具，使 AI Agent（如 Cursor）能够通过 MCP 协议直接执行 Appwrite CLI 命令。

🎯 核心设计理念

将 CLI 命令封装为工具调用，而非为每个操作创建独立的工具。

这种设计方式相比 Appwrite 官方 MCP Server（200+ 个独立工具）具有显著优势：

🎯 极简工具集：仅 3 个工具（appwrite、appwrite_configure、appwrite_status），而非 200+ 个独立工具
🔄 100% 代码复用：直接调用 CLI 源码，无需重写，自动获得所有功能和更新
📚 动态学习能力：Agent 可通过 --help 参数动态学习命令用法，无需在上下文中预置所有命令描述
🛡️ 详细错误信息：所有命令执行错误都会返回详细的错误信息，便于 Agent 调试和修复
💾 上下文优化：节省 96% 的上下文空间（1.5KB vs 40KB），减少 Token 消耗

📖 详细架构文档：查看 ARCHITECTURE.md 了解完整的架构设计、实现原理和对比分析。

✨ 特性

🚀 100% CLI 能力 - 直接调用 CLI，不遗漏任何功能
📦 一键安装 - 只需 npm install -g appwrite-mcp-server，CLI 已内置
⚡ 零配置启动 - Cursor 中只需配置 "command": "appwrite-mcp" 即可
🤖 AI Agent 友好 - 支持通过 --help 动态学习命令用法

📦 安装

npm install -g appwrite-mcp-server

就这么简单！Appwrite CLI 已经作为依赖内置，无需额外安装。

⚙️ Cursor 配置

编辑 ~/.cursor/mcp.json（macOS/Linux）或 %APPDATA%\Cursor\mcp.json（Windows）：

使用 npx（无需全局安装）

{
  "mcpServers": {
    "appwrite": {
      "command": "npx",
      "args": ["appwrite-mcp-server"],
      "env": {
        "APPWRITE_ENDPOINT": "https://cloud.appwrite.io/v1",
        "APPWRITE_PROJECT_ID": "your-project-id",
        "APPWRITE_API_KEY": "your-api-key"
      }
    }
  }
}

自托管实例（允许自签名证书）

{
  "mcpServers": {
    "appwrite": {
      "command": "appwrite-mcp",
      "env": {
        "APPWRITE_ENDPOINT": "https://your-appwrite-server.com/v1",
        "APPWRITE_PROJECT_ID": "your-project-id",
        "APPWRITE_API_KEY": "your-api-key",
        "APPWRITE_SELF_SIGNED": "true"
      }
    }
  }
}

重启 Cursor 后即可使用！

🔧 从源码安装（开发模式）

# 1. 克隆仓库
git clone https://github.com/appwrite/sdk-for-cli.git
cd sdk-for-cli

# 2. 编译主项目 CLI
npm install
npm run build

# 3. 编译 MCP Server
cd mcp-server
npm install
npm run build

开发模式配置：

{
  "mcpServers": {
    "appwrite": {
      "command": "node",
      "args": ["/path/to/sdk-for-cli/mcp-server/dist/index-standalone.js"],
      "env": {
        "APPWRITE_ENDPOINT": "https://cloud.appwrite.io/v1",
        "APPWRITE_PROJECT_ID": "your-project-id",
        "APPWRITE_API_KEY": "your-api-key"
      }
    }
  }
}

🛠️ 可用工具

1. `appwrite` - 执行命令（核心工具）

直接输入 CLI 命令，像在终端中执行一样：

// 列出数据库
appwrite({ command: "databases list" })

// 获取文档
appwrite({ command: "databases get-document --database-id main --collection-id users --document-id abc123" })

// 创建文档
appwrite({ command: "databases create-document --database-id main --collection-id users --document-id unique() --data '{\"name\":\"John\"}'" })

// 执行函数
appwrite({ command: "functions create-execution --function-id my-func" })

// 获取帮助
appwrite({ command: "databases --help" })

2. `appwrite_configure` - 配置连接

动态配置（也可通过环境变量）：

appwrite_configure({
  endpoint: "https://appbuild.store/v1",
  projectId: "your-project-id",
  apiKey: "your-api-key",
  selfSigned: true
})

3. `appwrite_status` - 查看状态

查看当前配置和连接状态。

📚 常用命令速查

配置

client --endpoint <url> --project-id <id> --key <key>
client --debug
whoami

数据库

databases list
databases get --database-id <id>
databases create --database-id <id> --name <name>
databases list-collections --database-id <id>
databases list-documents --database-id <id> --collection-id <cid>
databases create-document --database-id <id> --collection-id <cid> --document-id unique() --data '{}'
databases update-document --database-id <id> --collection-id <cid> --document-id <did> --data '{}'
databases delete-document --database-id <id> --collection-id <cid> --document-id <did>

函数

functions list
functions get --function-id <id>
functions create-execution --function-id <id>
functions list-executions --function-id <id>

存储

storage list-buckets
storage list-files --bucket-id <id>
storage get-file --bucket-id <id> --file-id <fid>

用户

users list
users get --user-id <id>
users create --user-id <id> --email <email> --password <pass>

其他

teams list
messaging list-topics
sites list
projects list
health get
locale list-countries

获取帮助

--help                 # 主帮助
databases --help       # databases 子命令帮助
functions --help       # functions 子命令帮助

🔑 配置方式

方式 1：环境变量（推荐）

在 MCP 配置的 env 中设置：

APPWRITE_ENDPOINT - API 端点（例如：https://cloud.appwrite.io/v1）
APPWRITE_PROJECT_ID - 项目 ID
APPWRITE_API_KEY - API Key
APPWRITE_SELF_SIGNED - 是否允许自签名证书（"true" 或 "false"）

方式 2：工具配置

使用 appwrite_configure 工具配置，配置会保存到 ~/.appwrite-mcp/env.json。

方式 3：直接使用命令

appwrite({ command: "client --endpoint https://... --project-id xxx --key xxx" })

📝 发布到 npm

如果你想发布这个包到 npm：

cd mcp-server
npm login  # 如果还没有登录
npm publish --access public

注意： 包名是 appwrite-mcp-server，需要确保你有 @appwrite 组织的权限。

🆚 与官方 MCP Server 的对比

| 指标 | 官方 MCP Server | 本项目 | |------|---------------|--------| | 工具数量 | 200+ | 3 | | 上下文大小 | ~40KB | ~1.5KB | | 代码复用率 | 0% | 100% | | 维护成本 | 高（需同步 API） | 低（自动同步） | | 学习能力 | 静态（需预置） | 动态（--help） | | 错误信息 | 基础 | 详细 |

为什么选择 CLI 封装方式？

官方方式的问题：

每个 API 操作都是一个独立工具（如 databases_create_string_attribute）
databases 相关工具就有 70+ 个
上下文充满重复的工具描述，占用大量 Token
Agent 无法动态学习，必须预置所有命令描述

本项目的优势：

Agent 可以通过 appwrite({command: "databases --help"}) 探索命令
无需在上下文中预置所有命令描述
命令更新时无需更新上下文
最大程度利用 CLI 项目的代码和错误处理

详细对比请查看 ARCHITECTURE.md。

开发

# 开发模式
npm run dev

# 构建
npm run build

# 启动
npm start

📚 相关文档

架构文档 - 详细的架构设计、实现原理和对比分析
Appwrite SDK for CLI - 基础 CLI 项目
Model Context Protocol - MCP 协议规范

License

BSD-3-Clause