workstream-mcp

# workstream-mcp

[![ci](https://github.com/ahmad-codex/workstream-mcp/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/ahmad-codex/workstream-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![.NET 10](https://img.shields.io/badge/.NET-10-512BD4.svg)](https://dotnet.microsoft.com/)
[![MCP](https://img.shields.io/badge/MCP-server-black.svg)](https://modelcontextprotocol.io/)

An MCP server that keeps the state of record for work done by AI agents and humans together:
plans, tasks, claims, findings, fix attempts and verdicts, stored in Postgres, mirrored to
GitHub Projects and Slack.

## Try it in 30 seconds

One container with Postgres and the server in demo mode, seeded with a project, an active plan
and three tasks:

```bash
docker run --rm -p 127.0.0.1:8080:8080 ghcr.io/ahmad-codex/workstream-mcp:demo
claude mcp add --transport http workstream-demo http://localhost:8080/demo-insecure-token/mcp
```

Then ask Claude to "list the workstream projects and claim the next task on the demo plan".
The demo token is public and gives admin rights, so keep the port on `127.0.0.1`; the server
refuses that token whenever demo mode is off. Data is gone when the container stops.

## Set it up with Claude Code

Clone the repo, open Claude Code in it, and paste:

```text
Set up workstream-mcp for me on this machine. Follow the README quick start using the
published Docker image, create an admin user for me, and connect this Claude Code session
to it. Then create a project and a development plan with three sample tasks, activate it,
and claim one task to show it works. When that is done, ask me whether I want GitHub
Projects or Slack sync, and walk me through docs/github-setup.md or docs/slack-setup.md
step by step, telling me exactly what to click and which values to paste back.
```

Prefer to do it by hand? See the [quick start](#quick-start-about-5-minutes).

## Why

A common way to coordinate agent work is a markdown plan in the repo: a checklist the agent
reads, edits and commits. That works for one agent in one session. It breaks down when several
agents and people work the same plan at once:

- Two agents pick the same item, because nothing stops them.
- An agent dies mid-task and the item stays "in progress" forever.
- Edits to the file race each other, and the history of who did what lives in git diffs.
- The plan does not show up where the team already looks: the project board and Slack.

workstream-mcp replaces the file with a small service. Agents call MCP tools to claim work,
submit results and record verdicts. Claims are atomic and expire, transitions are checked
against a state graph, every change is written to an append-only event log, and GitHub and
Slack are updated from an outbox so an outage on their side never blocks the agents.

## Features

What the code does today:

- **Atomic claims with TTLs.** `SELECT ... FOR UPDATE SKIP LOCKED` in one transaction, so
  concurrent claimers never get the same task and never block each other. A claim that is not
  refreshed expires and the work returns to the pool. Covered by a 32-claimer concurrency test suite.
- **Data-driven state machine.** Statuses, legal transitions, allowed roles, role TTLs, retry
  caps and board column mappings live in `plan_types.state_graph` (JSONB). Two plan types ship:
  `audit` (find, verify, fix, re-verify) and `development` (implement, review). An illegal
  transition returns `illegal_transition` with `allowed_next`, so the calling model can correct itself.
- **Append-only event log.** Every state change writes an `events` row. Triggers block `UPDATE`
  and `DELETE` on `events` and `verdicts`.
- **GitHub Projects V2 sync.** Tasks become issues (or draft items for repo-less projects) on a
  Projects V2 board, columns follow task status, and audit plans get a milestone. Inbound board
  moves arrive through a signed webhook. Uses a GitHub App.
- **Slack notifications.** Block Kit messages per project channel, threaded per task, with role
  personas for agent posts, and interactive buttons verified with the Slack signing secret.
- **Outboxes.** GitHub and Slack calls are queued in `board_sync_log` and `slack_notify_log`
  inside the request transaction and drained by background workers with retries.
- **URL-as-credential auth.** Each user gets a URL like `https://host/<token>/mcp`. Pasting it
  into an MCP client is the whole setup. Tokens can be rotated; the token is stripped from the
  path and from logs.
- **Audit dispatcher (optional).** `request_audit` queues an audit run; a sidecar container
  clones the repo and starts the project's audit orchestrator in a tmux session with Claude Code.
- **Admin API and CLI.** `/admin/*` endpoints behind a static bearer token for users and
  boards, plus a `workstream-admin` CLI for user management. Projects and plans are set up
  through the admin-gated MCP tools.
- **Stuck-work report.** An hourly job writes counts of expired claims, stale findings and idle
  plans to `stuck_work_reports`.

## Architecture

```mermaid
flowchart LR
    subgraph Clients
        CC[Claude Code / Desktop / Cursor]
        ORCH[Orchestrator agents]
    end

    CC -- "POST /&lt;token&gt;/mcp<br/>JSON-RPC 2.0" --> API
    ORCH -- "POST /&lt;token&gt;/mcp" --> API

    subgraph Server
        API[Workstream.Api<br/>token middleware, MCP tools,<br/>state machine, claims]
        BSW[BoardSyncWorker]
        SNW[SlackNotifyWorker]
        DISP[AuditDispatchWorker<br/>dispatcher role]
    end

    API -- "one transaction:<br/>state + events + outbox rows" --> PGB[(PgBouncer)]
    PGB --> PG[(Postgres 16)]
    BSW -- drain board_sync_log --> PG
    SNW -- drain slack_notify_log --> PG
    DISP -- drain audit_dispatch_log --> PG

    BSW -- GraphQL / REST --> GH[GitHub Projects V2,<br/>issues, milestones]
    SNW -- chat.postMessage --> SL[Slack]
    GH -- signed webhook --> API
    SL -- signed interactivity --> API
    DISP -- tmux + claude --> REPO[checked-out repos]
```

| Project | Responsibility |
|---|---|
| `src/Workstream.Api` | ASP.NET Core host, token middleware, JSON-RPC endpoint, admin API, webhooks, dispatcher |
| `src/Workstream.Core` | Domain model, state graph parser, `StateMachineService`, claim rules |
| `src/Workstream.Data` | Npgsql + Dapper repositories, outbox, SQL migration runner |
| `src/Workstream.Mcp` | The MCP tool classes and their registration |
| `src/Workstream.GitHub` | GitHub App auth, Projects V2 client, board sync worker |
| `src/Workstream.Slack` | Slack client, Block Kit builders, notify worker, signature check |
| `src/Workstream.Telemetry` | OpenTelemetry setup and metric definitions |
| `tools/workstream-admin` | Operator CLI |
| `deploy/` | Dockerfiles, compose files, migrations, plan-type profiles, Caddy, PgBouncer, Grafana and Prometheus config |

More in [docs/architecture.md](./docs/architecture.md) and [docs/state-machine.md](./docs/state-machine.md).

## Quick start (about 5 minutes)

Needs Docker. This starts Postgres and the API only; GitHub, Slack and the dispatcher stay off.

```bash
git clone https://github.com/ahmad-codex/workstream-mcp.git
cd workstream-mcp
docker compose -f deploy/docker-compose.quickstart.yml up -d --build
curl http://localhost:8080/healthz
# {"ok":true}
```

To skip the local build, run the published image instead:

```bash
WORKSTREAM_IMAGE=ghcr.io/ahmad-codex/workstream-mcp:latest \
  docker compose -f deploy/docker-compose.quickstart.yml up -d --no-build
```

The API applies the SQL migrations on startup, including the `audit` and `development` plan types.

Create a user. The response contains the user's MCP URL once; copy it.

```bash
curl -s -X POST http://localhost:8080/admin/users \
  -H "Authorization: Bearer local-admin-token" \
  -H "Content-Type: application/json" \
  -d '{"githubUsername":"alice","displayName":"Alice","actorType":"human","isAdmin":true}'
# { "user": {...}, "url": "http://localhost:8080/<token>",
#   "mcp_endpoint": "http://localhost:8080/<token>/mcp", "warning": "..." }
```

`isAdmin` lets this user call the setup tools (`create_project`, `create_plan`, ...).
Check the URL:

```bash
curl http://localhost:8080/<token>
# {"ok":true,"actor":{"id":"...","github_username":"alice","is_admin":true},...}
```

Then connect an MCP client (next section) and ask it to create a project, a development plan
and a few tasks, activate the plan, and claim one.

Stop with `docker compose -f deploy/docker-compose.quickstart.yml down` (add `-v` to drop the data).

## Connecting an MCP client

The server speaks MCP over HTTP (JSON-RPC 2.0 POSTs) at `<base>/<token>/mcp`. There are no
extra headers; the token in the path identifies the user.

**Claude Code**

```bash
claude mcp add --transport http workstream http://localhost:8080/<token>/mcp
```

**Claude Desktop** (`claude_desktop_config.json`). Claude Desktop launches stdio servers from
this file, so use the `mcp-remote` bridge (needs Node.js):

```json
{
  "mcpServers": {
    "workstream": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8080/<token>/mcp"]
    }
  }
}
```

If the server is reachable from the internet over HTTPS, you can instead add the URL as a
custom connector in Claude Desktop's settings.

**stdio** (any client). The same binary speaks MCP over stdin/stdout with `--stdio`, acting as
the user whose token is in `WORKSTREAM_USER_TOKEN` against the database in
`WORKSTREAM_DB_CONNECTION` (an HTTP server must still be running somewhere to drain the GitHub
and Slack outboxes):

```json
{
  "mcpServers": {
    "workstream": {
      "command": "dotnet",
      "args": ["/path/to/Workstream.Api.dll", "--stdio"],
      "env": {
        "WORKSTREAM_DB_CONNECTION": "Host=localhost;Database=workstream;Username=workstream;Password=...",
        "WORKSTREAM_USER_TOKEN": "<token>"
      }
    }
  }
}
```

Without `WORKSTREAM_DB_CONNECTION`, `--stdio` starts in discovery mode: `in