# AgentBridge

A fast, simple Kanban board where humans and AI agents collaborate on tasks. AgentBridge runs on Cloudflare Workers and speaks the Model Context Protocol (MCP), so Claude, Cursor, Codex, and your team can work from the same source of truth.

Live demo: https://agent-bridge.0xkaz.com/

## Features

- **MCP server** over HTTP/SSE (`/mcp`)
- **REST API** with revocable tokens
- **Real-time board** updates via SSE
- **Google OAuth** sign-in
- **Personal org** per user (no accidental domain sharing)
- **Multi-project** Kanban boards
- **Custom lists** (columns) per project
- **Drag-and-drop** task movement
- **Task comments** for agent memory and context
- **Organization member invitations**

## MCP Tools

- `list_orgs` — list organizations
- `list_projects` — list projects in an organization
- `create_task` — create a task in a project
- `update_status` — change a task status
- `comment` — add a comment to a task

## REST API

Most endpoints require `Authorization: Bearer <token>`. Invitation info and accept endpoints are public.

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/auth/google` | Sign in with a Google ID token |
| GET | `/api/auth/me` | Current user |
| GET | `/api/orgs` | List organizations |
| POST | `/api/orgs` | Create organization |
| PATCH | `/api/users/me/org` | Switch active organization |
| GET | `/api/orgs/:org/projects` | List projects |
| POST | `/api/orgs/:org/projects` | Create project |
| GET | `/api/projects/:project` | Get project |
| GET | `/api/projects/:project/columns` | List columns/lists |
| POST | `/api/projects/:project/columns` | Create column/list |
| PATCH | `/api/projects/:project/columns/:column` | Rename column/list |
| PATCH | `/api/projects/:project/columns/:column/position` | Reorder column/list |
| DELETE | `/api/projects/:project/columns/:column` | Archive empty column/list |
| GET | `/api/projects/:project/tasks` | List tasks |
| POST | `/api/projects/:project/tasks` | Create task |
| PATCH | `/api/tasks/:task` | Move task to another column/list |
| GET | `/api/projects/:project/history` | Project activity history |
| GET | `/api/tasks/:task/comments` | List comments |
| POST | `/api/tasks/:task/comments` | Add comment |
| GET | `/api/tokens` | List API/MCP tokens |
| POST | `/api/tokens` | Generate token |
| DELETE | `/api/tokens/:id` | Revoke token |
| POST | `/api/orgs/:org/invitations` | Invite a user to an organization |
| GET | `/api/orgs/:org/invitations` | List pending invitations |
| GET | `/api/invitations/:token` | Get invitation info (public) |
| POST | `/api/invitations/:token/accept` | Accept an invitation (public) |
| GET | `/api/events?token=<token>` | SSE event stream |

## Setup

```bash
npm install
cp .env.example .env
cp wrangler.example.toml wrangler.toml
# Edit .env with your Google OAuth client ID
# Edit wrangler.toml with your Cloudflare account_id, D1 database_id, and custom domain
npm run db:seed
```

### Google Cloud Console configuration

This app uses Google Identity Services (ID token flow). You do **not** need to configure a `redirect_uri`.

1. Create an OAuth 2.0 Web application client ID at https://console.cloud.google.com/apis/credentials
2. Add the following **Authorized JavaScript origins**:
   - `http://localhost:8787` (local `wrangler dev`)
   - `https://<your-worker>.workers.dev` (production)
3. Copy the **Client ID** into `.env` as `VITE_GOOGLE_CLIENT_ID` and into `.dev.vars` as `GOOGLE_CLIENT_ID`
4. Copy `wrangler.example.toml` to `wrangler.toml` and fill in your Cloudflare `account_id`, D1 `database_id`, and custom domain

The Client Secret is not used by this app because verification is done with Google's public JWKS.

## Development

```bash
npm run dev
```

Open http://localhost:8787 and sign in with Google.

For MCP clients, configure the endpoint:

```json
{
  "mcpServers": {
    "agentbridge": {
      "url": "http://localhost:8787/mcp"
    }
  }
}
```

Generate an API token on the Settings page and use it as `Authorization: Bearer <token>`.

## End-to-end tests

```bash
make e2e
```

This starts the dev server automatically and runs Playwright against Chromium.

## Migrating an existing database

`src/db/schema.sql` only contains the final schema for fresh databases. If you are updating an existing D1 database from a version that stored plaintext `token` values, run the token-hash migration before deploying:

```bash
# Local
make db-migrate-token-hash

# Remote (production)
make db-migrate-token-hash-remote
```

These commands hash any remaining plaintext tokens, then recreate the `tokens` table with `token_hash` only.

## Deploy

```bash
npm run deploy
```

Before deploying, make sure `wrangler.toml` is filled in (see Setup step 4).

Set secrets:

```bash
wrangler secret put GOOGLE_CLIENT_ID
```

## Commands

- `make lint` — TypeScript type check
- `make test` — run tests
- `make build` — build frontend
- `make db-seed` — apply D1 schema locally
- `make db-migrate-token-hash` — migrate local D1 tokens to hashed schema
- `make db-migrate-token-hash-remote` — migrate remote D1 tokens to hashed schema
- `make e2e` — run Playwright end-to-end tests
- `make dev` — start dev server

## License

MIT