Writbase - MCP Task Management for AI Agent Fleets

WritBase

面向 AI Agent 群组的 MCP 原生任务管理

为 AI Agent 和人工主管提供控制平面。通过持久化任务注册表、范围化权限、Agent 间委派和完整溯源，一切均可通过 MCP 访问。

为什么选择 WritBase？

AI Agent 需要共享的持久化任务注册表，而不是会在会话之间消失的临时内存状态。WritBase 为你的 Agent 群组提供：

• 单一事实来源 — 任务存储在 Postgres 中，而不是散落在文件和聊天记录里
• 范围化权限 — 每个 Agent 仅获得所需的访问权限，不多给
• 完整溯源 — 记录每一项更改：谁、做了什么、何时以及原因
• Agent 间委派 — Agent 可以相互分配任务，并受深度限制和循环检测保护
• MCP 原生 — Agent 通过 Model Context Protocol 连接，无需自定义集成

开始使用

选项 A：CLI 设置（推荐）

无需克隆代码仓库，只需使用 npx：

npx writbase init        # Interactive setup — configures Supabase credentials
npx writbase migrate     # Apply database schema
npx writbase key create  # Create your first agent key

完成。你的 MCP 端点已在以下地址上线：

https://<project-ref>.supabase.co/functions/v1/mcp-server/mcp

前提条件：Node 18+、Supabase CLI、一个 Supabase 项目（免费套餐即可）

部署 Edge Function：npx supabase functions deploy mcp-server --no-verify-jwt

所有命令请参阅 CLI README。

选项 B：手动设置

git clone https://github.com/Writbase/writbase.git
cd writbase && npm install

# Create a free project at supabase.com/dashboard, then:
npx supabase link --project-ref <your-project-ref>
npx supabase db push
npx supabase functions deploy mcp-server --no-verify-jwt

2. 创建项目和 Agent 密钥

通过 CLI（npx writbase key create）、仪表板或管理 Agent 操作：

1. 创建项目 — 例如 my-app。也可以添加部门（backend、frontend、devops）
2. 创建 Agent 密钥 — 为其命名，选择 worker 角色，并保存密钥（wb_<key_id>_<secret> — 仅显示一次）
3. 授予权限 — writbase key permit my-agent --grant --project my-app --can-read --can-create --can-update（或通过仪表板操作）

3. 连接 MCP 客户端

claude mcp add writbase \
  --transport http \
  --url https://<project-ref>.supabase.co/functions/v1/mcp-server/mcp \
  --header "Authorization: Bearer wb_<key_id>_<secret>"

{
  "mcpServers": {
    "writbase": {
      "type": "streamableHttp",
      "url": "https://<project-ref>.supabase.co/functions/v1/mcp-server/mcp",
      "headers": { "Authorization": "Bearer wb_<key_id>_<secret>" }
    }
  }
}

{
  "servers": {
    "writbase": {
      "type": "http",
      "url": "https://<project-ref>.supabase.co/functions/v1/mcp-server/mcp",
      "headers": { "Authorization": "Bearer wb_<key_id>_<secret>" }
    }
  }
}

4. 开始使用

向你的 Agent 提问：

"Check my WritBase permissions"          → calls info
"Create a task in my-app: Fix login bug" → calls add_task
"Mark it as in_progress"                 → calls update_task (with version for concurrency)
"Show all high priority tasks"           → calls get_tasks with priority filter

5. 扩展规模

每个 Agent 都有自己的密钥，并且只具备所需权限，不多给。

完整指南：入门指南 — 权限、部门、故障排除

MCP 工具

Worker Tools（所有 Agent）

Manager Tools（仅限管理者 Agent）

功能

• 多租户工作区 — 注册后自动配置隔离的工作区
• 动态 MCP schema — 工具可见性和参数枚举会根据每个 Agent 的角色和权限调整
• 6 种权限类型 — can_read、can_create、can_update、can_assign、can_comment、can_archive
• 项目 + 部门范围限定 — 权限按（项目、部门）组合授予
• 乐观并发 — 基于版本的冲突检测可防止静默覆盖
• 游标分页 — 高效遍历大量任务
• 速率限制 — 对每个 Agent 密钥的请求进行限流
• 请求日志记录 — 记录每次 MCP 调用的延迟、状态和 Agent 上下文

架构

┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
│  MCP Client │────▶│  Edge Function   │────▶│   Postgres   │
│  (Agent)    │◀────│  (Hono + MCP SDK)│◀────│  (Supabase)  │
└─────────────┘     └──────────────────┘     └──────────────┘
                           │
                    ┌──────┴──────┐
                    │  Next.js 16 │
                    │  Dashboard  │
                    └─────────────┘

• 后端：Supabase（Postgres + 使用 Deno 运行时的 Edge Functions）
• 传输：Streamable HTTP（MCP SDK）
• 前端：Next.js 16（App Router）+ Tailwind CSS
• 身份验证：Supabase Auth（人工用户）+ SHA-256 Agent 密钥（Agent）

部署选项

详细设置说明请参阅 docs/deployment.md。

文档

• 快速入门 — 部署、创建 Agent 密钥、连接 MCP 客户端并管理任务
• CLI 参考 — npx writbase init、migrate、key、status
• 部署指南 — Supabase Cloud、Vercel 和自托管设置
• 核心概念 — 权限、来源记录、错误代码、委派
• MCP 配置参考 — Claude Code、Cursor、VS Code、Windsurf 的客户端配置

贡献

开发环境设置、测试和 PR 指南请参阅 CONTRIBUTING.md。

安全

漏洞报告请参阅 SECURITY.md。

许可证

Apache 2.0 — 详见 LICENSE。