{
  "markdown": "<div align=\"center\">\n\n# WritBase\n\n**MCP-native task management for AI agent fleets**\n\nA control plane for AI agents and human supervisors. Persistent task registry with scoped permissions, inter-agent delegation, and full provenance — all accessible via MCP.\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![CI](https://img.shields.io/github/actions/workflow/status/Writbase/writbase/ci.yml?label=CI)](https://github.com/Writbase/writbase/actions)\n[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)\n\n<br/>\n\n<img src=\"docs/assets/demo.svg\" alt=\"WritBase MCP demo — agent creates a task and delegates to another agent\" width=\"100%\"/>\n\n</div>\n\n---\n\n## Why WritBase?\n\nAI agents need a shared, persistent task registry — not ephemeral in-memory state that vanishes between sessions. WritBase gives your agent fleet:\n\n- **One source of truth** — Tasks live in Postgres, not scattered across files and chat threads\n- **Scoped permissions** — Each agent gets exactly the access it needs, nothing more\n- **Full provenance** — Every change is recorded: who, what, when, and why\n- **Inter-agent delegation** — Agents can assign tasks to each other with depth limits and cycle detection\n- **MCP-native** — Agents connect via the Model Context Protocol, no custom integration needed\n\n## Getting Started\n\n### Option A: CLI Setup (recommended)\n\nNo repo clone needed. Just `npx`:\n\n```bash\nnpx writbase init        # Interactive setup — configures Supabase credentials\nnpx writbase migrate     # Apply database schema\nnpx writbase key create  # Create your first agent key\n```\n\nThat's it. Your MCP endpoint is live at:\n\n```\nhttps://<project-ref>.supabase.co/functions/v1/mcp-server/mcp\n```\n\n> **Prerequisites**: Node 18+, [Supabase CLI](https://supabase.com/docs/guides/cli), a Supabase project ([free tier](https://supabase.com/pricing) works)\n>\n> Deploy the Edge Function: `npx supabase functions deploy mcp-server --no-verify-jwt`\n>\n> See the [CLI README](cli/README.md) for all commands.\n\n### Option B: Manual Setup\n\n<details>\n<summary>Clone and deploy manually</summary>\n\n```bash\ngit clone https://github.com/Writbase/writbase.git\ncd writbase && npm install\n\n# Create a free project at supabase.com/dashboard, then:\nnpx supabase link --project-ref <your-project-ref>\nnpx supabase db push\nnpx supabase functions deploy mcp-server --no-verify-jwt\n```\n\n> **Optional dashboard**: `cp .env.example .env.local` → edit with your Supabase URL + anon key → `npm run dev`\n>\n> See the [Deployment Guide](docs/deployment.md) for Vercel hosting and self-hosted Supabase.\n\n</details>\n\n### 2. Create a project and agent key\n\nVia the CLI (`npx writbase key create`), the dashboard, or a manager agent:\n\n1. **Create a project** — e.g., `my-app`. Optionally add departments (`backend`, `frontend`, `devops`)\n2. **Create an agent key** — name it, pick the `worker` role, save the key (`wb_<key_id>_<secret>` — shown once)\n3. **Grant permissions** — `writbase key permit my-agent --grant --project my-app --can-read --can-create --can-update` (or via dashboard)\n\n### 3. Connect your MCP client\n\n<details>\n<summary><strong>Claude Code</strong></summary>\n\n```bash\nclaude mcp add writbase \\\n  --transport http \\\n  --url https://<project-ref>.supabase.co/functions/v1/mcp-server/mcp \\\n  --header \"Authorization: Bearer wb_<key_id>_<secret>\"\n```\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"writbase\": {\n      \"type\": \"streamableHttp\",\n      \"url\": \"https://<project-ref>.supabase.co/functions/v1/mcp-server/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer wb_<key_id>_<secret>\" }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>VS Code / Copilot</strong></summary>\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"writbase\": {\n      \"type\": \"http\",\n      \"url\": \"https://<project-ref>.supabase.co/functions/v1/mcp-server/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer wb_<key_id>_<secret>\" }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Windsurf / Claude Desktop / Other</strong></summary>\n\nSee the [MCP Config Reference](docs/mcp-config-reference.md) for all supported clients.\n</details>\n\n### 4. Use it\n\nAsk your agent:\n\n```\n\"Check my WritBase permissions\"          → calls info\n\"Create a task in my-app: Fix login bug\" → calls add_task\n\"Mark it as in_progress\"                 → calls update_task (with version for concurrency)\n\"Show all high priority tasks\"           → calls get_tasks with priority filter\n```\n\n### 5. Scale up\n\n| Agent | Role | Scoped to | Use case |\n|-------|------|-----------|----------|\n| `ci-bot` | worker | `my-app/devops` — can_create | CI creates tasks on build failure |\n| `triage-agent` | worker | `my-app` (all depts) — can_comment | Reviews tasks, adds notes |\n| `ops-manager` | manager | (workspace-wide) | Manages keys, permissions, projects |\n\nEach agent gets its own key with exactly the permissions it needs — nothing more.\n\n> **Full walkthrough**: [Getting Started Guide](docs/quickstart.md) — permissions, departments, troubleshooting\n\n## MCP Tools\n\n### Worker Tools (all agents)\n\n| Tool | Description |\n|------|-------------|\n| `info` | Agent identity, permissions, and system metadata |\n| `get_tasks` | List tasks with filtering, pagination, and full-text search |\n| `add_task` | Create a task in permitted scope |\n| `update_task` | Update a task with optimistic concurrency control |\n\n### Manager Tools (manager agents only)\n\n| Tool | Description |\n|------|-------------|\n| `manage_agent_keys` | Create, update, deactivate, rotate agent keys |\n| `manage_agent_permissions` | Grant/revoke permissions with subset enforcement |\n| `get_provenance` | Query the append-only audit log |\n| `manage_projects` | Create, rename, archive projects |\n| `manage_departments` | Create, rename, archive departments |\n| `subscribe` | Register webhooks for task event notifications |\n| `discover_agents` | Find agents by capability and skill |\n\n## Features\n\n- **Multi-tenant workspaces** — Signup auto-provisions an isolated workspace\n- **Dynamic MCP schema** — Tool visibility and parameter enums adapt per agent's role and permissions\n- **6 permission types** — `can_read`, `can_create`, `can_update`, `can_assign`, `can_comment`, `can_archive`\n- **Project + department scoping** — Permissions are granted per (project, department) pair\n- **Optimistic concurrency** — Version-based conflict detection prevents silent overwrites\n- **Cursor pagination** — Efficient traversal of large task sets\n- **Rate limiting** — Per-agent-key request throttling\n- **Request logging** — Every MCP call logged with latency, status, and agent context\n\n## Architecture\n\n```\n┌─────────────┐     ┌──────────────────┐     ┌──────────────┐\n│  MCP Client │────▶│  Edge Function   │────▶│   Postgres   │\n│  (Agent)    │◀────│  (Hono + MCP SDK)│◀────│  (Supabase)  │\n└─────────────┘     └──────────────────┘     └──────────────┘\n                           │\n                    ┌──────┴──────┐\n                    │  Next.js 16 │\n                    │  Dashboard  │\n                    └─────────────┘\n```\n\n- **Backend**: Supabase (Postgres + Edge Functions with Deno runtime)\n- **Transport**: Streamable HTTP (MCP SDK)\n- **Frontend**: Next.js 16 (App Router) + Tailwind CSS\n- **Auth**: Supabase Auth (humans) + SHA-256 agent keys (agents)\n\n## Deployment Options\n\n| | Supabase Cloud (recommended) | Self-Hosted Supabase |\n|---|---|---|\n| Setup | `npx writbase init` → `npx writbase migrate` → done | Docker Compose (5 containers) |\n| Cost | [Free tier](https://supabase.com/pricing): 500MB DB, 50K MAUs | Your infrastructure |\n| Dashboard | Deploy to Vercel (free) | Self-host Next.js |\n| Updates | Automatic platform updates | Manual |\n| Control | Supabase-managed | Full |\n\nSee [docs/deployment.md](docs/deployment.md) for detailed setup instructions.\n\n## Documentation\n\n- [Getting Started](docs/quickstart.md) — Deploy, create an agent key, connect your MCP client, and manage tasks\n- [CLI Reference](cli/README.md) — `npx writbase init`, `migrate`, `key`, `status`\n- [Deployment Guide](docs/deployment.md) — Supabase Cloud, Vercel, and self-hosted setup\n- [Core Concepts](docs/concepts.md) — Permissions, provenance, error codes, delegation\n- [MCP Config Reference](docs/mcp-config-reference.md) — Client configs for Claude Code, Cursor, VS Code, Windsurf\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and PR guidelines.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for vulnerability reporting.\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n",
  "bytes": 8664,
  "sha": "fcbee1018dce3e3a7ec366c7c918644bb8929e50896c3413103195e86e90d8d8",
  "repo_slug": "writbase/writbase",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_writbase_writbase_67a9f0a1/readme"
}