workstream-mcp
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.
Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
docker run -i --rm ghcr.io/ahmad-codex/workstream-mcp:0.3.1Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
WORKSTREAM_DB_CONNECTION=<secret> WORKSTREAM_ADMIN_TOKEN=<secret> WORKSTREAM_PUBLIC_BASE_URL=<value> WORKSTREAM_USER_TOKEN=<secret> claude mcp add io.github.ahmad-codex-workstream-mcp -- docker run -i --rm ghcr.io/ahmad-codex/workstream-mcp:0.3.1รันในเทอร์มินัล
{ "mcpServers": { "io.github.ahmad-codex-workstream-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/ahmad-codex/workstream-mcp:0.3.1" ], "env": { "WORKSTREAM_DB_CONNECTION": "<secret>", "WORKSTREAM_ADMIN_TOKEN": "<secret>", "WORKSTREAM_PUBLIC_BASE_URL": "<value>", "WORKSTREAM_USER_TOKEN": "<secret>" } } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดจากผู้เผยแพร่
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.
Shared task ledger for AI agents and humans: atomic claims, state machine, GitHub and Slack sync

One container with Postgres and the server in demo mode, seeded with a project, an active plan and three tasks:
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.
Open http://localhost:8080/demo-insecure-token/ui/ to watch the plan on the dashboard.
To see agents race for tasks, start the container with -e WORKSTREAM_ADMIN_TOKEN=local-admin and
run WORKSTREAM_ADMIN_TOKEN=local-admin node scripts/simulate-agents.mjs.
Clone the repo, open Claude Code in it, and paste:
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.
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:
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.
What the code does today:
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.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.events row. Triggers block UPDATE
and DELETE on events and verdicts.board_sync_log and slack_notify_log
inside the request transaction and drained by background workers with retries./<token>/ui/: tasks by status, claim holders
with a TTL countdown, dependencies, stuck work and the event timeline of every task. See
docs/dashboard.md.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.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/* 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_reports.flowchart LR
subgraph Clients
CC[Claude Code / Desktop / Cursor]
ORCH[Orchestrator agents]
end
CC -- "POST /<token>/mcp<br/>JSON-RPC 2.0" --> API
ORCH -- "POST /<token>/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]
More in docs/architecture.md and docs/state-machine.md.
Needs Docker. This starts Postgres and the API only; GitHub, Slack and the dispatcher stay off.
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:
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.
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:
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).
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
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):
{
"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):
{
"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: initialize and
tools/list work and every tool call returns a not_configured error. Directory scanners such
as Glama use this mode.
Cursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project):
{
"mcpServers": {
"workstream": {
"url": "http://localhost:8080/<token>/mcp"
}
}
}
The URL is a credential. Do not commit it; keep it in user-level config. See docs/onboarding.md for the full onboarding flow.
36 tools. Every response is { ok, data, error }; errors carry a stable code
(stale_claim, illegal_transition, retry_cap_exceeded, ...). Full details in
docs/mcp-tools.md. Any call may pass as_agent to set the role
persona used for Slack posts.
Environment variables read by the API. Each _FILE variant reads the value from a file
(Docker secrets).
Per-project Slack bot tokens are files under the secrets directory, referenced by
set_project_slack. See docs/slack-setup.md and
docs/github-setup.md.
dotnet build
dotnet test tests/Workstream.UnitTests # no Docker
dotnet test tests/Workstream.IntegrationTests # Docker (Testcontainers, Postgres 16)
dotnet test tests/Workstream.ConcurrencyTests # Docker
Run the API against your own Postgres:
export WORKSTREAM_DB_CONNECTION="Host=localhost;Database=workstream;Username=workstream;Password=devpass"
export WORKSTREAM_ADMIN_TOKEN="dev-admin-token"
dotnet run --project src/Workstream.Api
as_agentEarly, version 0.3.0. Known gaps:
claim_next_attempt_for_review is a stub.workstream-admin apply (declarative bootstrap) only prints the file.master is supported; there are no release branches.See CHANGELOG.md and the roadmap.
Start with CONTRIBUTING.md and the good first issues. Planned work is in ROADMAP.md. The repository opens in a dev container or GitHub Codespaces with the .NET 10 SDK and Postgres ready.
MIT. Copyright 2026 Ahmad Shawar.
Shared task ledger for AI agents and humans: atomic claims, state machine, GitHub and Slack sync
{ "mcpServers": { "io.github.ahmad-codex-workstream-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/ahmad-codex/workstream-mcp:0.3.1" ], "env": { "WORKSTREAM_DB_CONNECTION": "<secret>", "WORKSTREAM_ADMIN_TOKEN": "<secret>", "WORKSTREAM_PUBLIC_BASE_URL": "<value>", "WORKSTREAM_USER_TOKEN": "<secret>" } } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ผู้เผยแพร่ระบุตัวแปรสภาพแวดล้อมเหล่านี้: WORKSTREAM_DB_CONNECTION, WORKSTREAM_ADMIN_TOKEN, WORKSTREAM_PUBLIC_BASE_URL, WORKSTREAM_USER_TOKEN
Workstream ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-09 Shared task ledger for AI agents and humans: atomic claims, state machine, GitHub and Slack sync