Capsid

Capsid is a Model Context Protocol (MCP) server and control plane for AI coding agents. It runs as a single Cloudflare Worker and provides four functions to the agents that connect to it:

• a versioned knowledge base of project documents, stored in D1 and searchable by keyword and by meaning;
• a work queue of signed task descriptions, from which agents claim and complete work;
• per-agent credentials with explicit scopes, enforced at a single authorization point;
• mediated access to GitHub repositories through a GitHub App, with a record of each agent's reported outcome alongside the outcome GitHub confirms.

The repository contains the source of one production deployment, operated by its owner and the co-owners listed in CO_OWNER_EMAILS. It is published under the MIT license for reference. It is not a hosted service and is not supported for third-party use; Installation describes how to run a separate instance.

The public system explorer at capsid.dustinedwards.info, generated daily from Capsid's public data.

Contents

• Architecture
• Components
• MCP tools
• HTTP interface
• Repository layout
• Installation
• Development
• Documentation
• License

Architecture

Runtime and storage

Capsid is written in TypeScript and deployed as one Cloudflare Worker. It uses the following bindings:

Binding	Type	Purpose
DB	D1	Documents, document versions, jobs, agents, namespaces, outcomes and the audit log. Full-text search uses SQLite FTS5.
APP_KV	KV	Cached GitHub installation tokens, switches and short-lived state.
OAUTH_KV	KV	OAuth grants and client registrations.
MEDIA	R2	Daily database exports and the Markdown mirror of every document.
AI_SEARCH	AI Search	A derived semantic index of the documents, used for hybrid search. D1 remains the source of record.
ASSETS	Static assets	The built Capsid Portal (dashboard/dist).

Hosts

The Worker answers on two hosts, each restricted to its own set of paths:

• MCP host (mcp.dustinedwards.info): the MCP endpoints, OAuth sign-in, agent and operator routes under /ops/, and the public read-only documents. The permitted paths are listed in src/mcp-host.ts.
• Portal host (portal.dustinedwards.info): the Capsid Portal, the administrative web application. See src/portal-host.ts.

The system explorer at capsid.dustinedwards.info is a separate, assets-only Worker built from explorer/. It is prerendered from Capsid's public documents and makes no requests to Capsid at read time.

Authentication

Caller	Mechanism
Owner and co-owners, through an MCP client or the Portal	Cloudflare Access for SaaS (OIDC), issued as an OAuth access token by @cloudflare/workers-oauth-provider.
Agents and scheduled clients	A per-agent bearer key on /ops/mcp. Only the key's SHA-256 hash is stored.
Capsid, towards GitHub	A GitHub App. The Worker signs an RS256 JWT and exchanges it for a short-lived installation token; no long-lived GitHub token is stored.

Every caller resolves to an agent record with a name, a set of scopes and an audit identity. Authorization is checked in one function, checkScope in src/scope.ts.

Scheduled work

Three Cron Triggers are declared, and their expressions are defined once in src/index.ts:

Schedule (UTC)	Task
*/5 * * * *	The tick: site watcher, auto-merge evaluation, merge-state sweep, search indexing, phone alerts, the daily email digest, and the daily build of the public model and statistics.
0 9 * * *	Database backup to R2, followed by pruning of old document versions and audit rows.
30 9 * * *	Weekly skills refresh, which runs on one configured day and posts a job when a model's prompting guide has changed.

Components

Knowledge base

A document is a row in D1 identified by namespace and path, with a title, a Markdown body, a type, a status and tags. A namespace corresponds to one project and maps to one or more GitHub repositories; that mapping is also the boundary for repository access. Document types include core, concept, decision, spec, protocol, procedural, task and reference (docs/schema.md).

Every overwrite or delete stores the previous body in document_versions and writes a row to audit_log. Search combines FTS5 keyword matching with semantic matching from an AI Search index. The index is filled from D1 by the five-minute tick, and every semantic result is re-checked against D1 before it is returned.

Authorization

An agent's scopes have five axes: namespaces, repos, tools, grants (read, or read and write) and flags. Flags control operations with a wide effect, such as merging (can_merge), committing directly to a default branch (can_direct_write), dispatching workflows (can_dispatch) and writing protected paths (can_touch_protected). A new agent receives read access to its named namespaces and no flags. Scopes that fail to parse resolve to no access. The required grant for each tool is declared in TOOL_GRANTS (src/scope.ts), and a tool absent from that table requires the write grant. See docs/auth.md.

Work queue

A job consists of a title and a body; the body is the complete prompt an agent executes. Bodies are signed when posted, and a claim verifies the signature first, so a body altered outside the queue's own edit action is rejected. The lifecycle is post, claim, then complete, fail, block or resume. A job that reaches an operation requiring a person (a push, a deploy, a secret, a live migration or a merge) is blocked with the exact command to run. Capsid assigns each job a kind and a recommended model and effort (src/model-routing.ts).

Capsid can start a Claude Code cloud session for a queued job by firing a saved Claude Code routine (docs/routines.md). When an agent completes a job, it names the pull request that carries the work. Capsid then reads that pull request from GitHub and stores the verified state beside the agent's claim, so the two can be compared (docs/work-queue.md).

GitHub integration and merge policy

Repository tools resolve the target repository from the namespace mapping and check the resolved repository against the caller's repos axis (docs/repo-access.md). Agents open pull requests; merging requires the can_merge flag.

Automatic merging is governed by a policy document that must be signed by the administrator before it has any effect; an unsigned policy, or one edited after signing, authorizes nothing. When enabled, the tick merges only pull requests that pass every check in the policy. Certain paths, including migrations, workflows, lockfiles and authentication code, are always refused automatic merging (docs/autonomy.md). Both automatic merging and the overnight run (docs/overnight.md) are disabled in a new installation.

Capsid Portal

The Portal is a single-page application in dashboard/, served by the Worker as static assets and restricted to the administrator's Cloudflare Access session. It presents items awaiting the owner, site health, the job queue, open pull requests, deploys, agents, activity and backups, and exposes the administrative controls defined in src/controls.ts (docs/portal.md).

Portal Health view, rendered from sample data.

Portal job queue with a job's detail drawer open, rendered from sample data.

Site monitoring

The watcher, which runs on the tick, reads each registered site's health route, CI status, deploys and live responses (docs/health-format.md, docs/live-checks.md). Search performance is read from Google Search Console and Bing Webmaster Tools (docs/search-console.md, docs/bing-webmaster.md).

Session telemetry

Claude Code sessions can send hook events to /ops/hooks and OpenTelemetry metrics to /ops/otlp/v1/*. Capsid keeps per-session summaries and per-job cost and token totals; it does not store prompts, responses or tool content (docs/hooks.md, docs/telemetry.md).

Public data

Once a day the Worker builds a public system model and a set of aggregate statistics, after a privacy filter, and serves them without authentication (docs/public-data.md). Current figures are available at mcp.dustinedwards.info/public/stats/v1.json. The system explorer is built from these documents (explorer/README.md).

Backups and recovery

D1 Time Travel provides 30-day point-in-time recovery. In addition, the daily backup writes one JSON export per table and a Markdown mirror of every document to R2, and the exports are mirrored to a private repository outside the Cloudflare account. A scheduled workflow rehearses a restore (docs/backups.md). Rolling back a faulty deploy is described in docs/rollback.md.

MCP tools

Capsid serves 22 tools over two MCP servers. The count is derived from TOOL_GRANTS by src/counts.ts, and the registrations are in src/tools/surface.ts. Most tools take an action argument that selects one operation.

Capsid (/mcp, /ops/mcp): 14 tools for project work.

Tool	Grant	Function
capsid_start_session	read	Session briefing for a namespace.
capsid_find_docs	read	List, glob or full-text search documents; list reachable namespaces.
capsid_read_doc	read	Read a document, its versions or its edges.
capsid_write_doc	write	Create, change, restore or move a document.
capsid_delete_doc	write	Delete a document, retaining its last version.
capsid_lint_namespace	per action	Gather, finalize and report on a namespace's documents (docs/consolidation.md).
capsid_read_repo	read	List directories, read files and search code in a mapped repository.
capsid_inspect_repo	read	Branches, tags, pull requests, history, CI runs, live site checks and search-console data.
capsid_change_repo	write	Write or delete a file, or create a branch.
capsid_open_pr	write	Open a pull request or comment on one.
capsid_close_pr	write	Merge or close a pull request, delete a branch, tag a commit or publish a release.
capsid_run_ci	write	Dispatch a workflow or rerun failed jobs.
capsid_work_jobs	per action	The work queue lifecycle.
capsid_run_improve	read	Capsid status per namespace: queue, breaker, maintenance and items awaiting the owner. The name is retained from a removed feature.

Capsid Admin (/mcp/admin, /ops/mcp/admin): 8 tools, available to the administrator identity only.

Tool	Grant	Function
capsid_admin_whats_next	admin read	Items awaiting the owner across every namespace.
capsid_admin_manage_namespaces	admin	Register, remap or delete a namespace.
capsid_admin_manage_agents	admin	Mint, revoke and re-scope agent credentials.
capsid_admin_read_claims	admin read	Agent claims beside verified outcomes.
capsid_admin_read_ops	admin read	Watcher state, Cloudflare Access and Email Routing configuration, Workers Builds.
capsid_admin_run_controls	admin	Preview and perform administrative controls with a single-use token.
capsid_admin_control_improve	admin	Operator keys, policy signing, the job breaker and the overnight switch.
capsid_admin_set_site_key	admin	Mint a site key and install it on the site Worker.

Adding a tool requires a recorded ruling (CLAUDE.md, rule 1).

HTTP interface

The router is defaultHandler in src/routes.ts. The principal routes are:

Route	Authentication	Purpose
POST /mcp, POST /mcp/admin	OAuth	MCP over Streamable HTTP for the owner and co-owners.
POST /ops/mcp, POST /ops/mcp/admin	Bearer key	MCP for agents and scheduled clients.
/authorize, /callback, /token, /register, /.well-known/*	None	OAuth sign-in and discovery.
POST /ops/hooks, POST /ops/otlp/v1/*	Bearer key	Claude Code hook events and telemetry.
GET /ops/inbox, POST /ops/inbox/report	Bearer key	Items awaiting the owner, per application.
GET /health	None	Deploy provenance and a store probe; returns 503 when D1 or FTS5 fails.
GET /public/model/v1.json, /public/stats/v1.json, /public/code/v1.json	None	Public system model, statistics and code maps.
/portal/*	Access session	The Capsid Portal and its API.

The complete list, including signed backup and benchmark routes, is in docs/auth.md.

Repository layout

Path	Contents
src/	Worker source. index.ts is the entry point; tools/ holds the MCP tool surface.
migrations/	D1 schema migrations, applied in order.
dashboard/	The Capsid Portal (Vite) and its Playwright tests.
explorer/	The public system explorer, a separate assets-only Worker.
system/	The hand-written public system model and its JSON Schema.
scripts/	Deploy, agent minting, backup and verification scripts.
test/	Unit tests and lint checks.
test-integration/	Integration tests run in workerd through @cloudflare/vitest-plugin.
docs/	Reference documentation. docs/policy/ holds the reviewable copies of the signed policies.
wrangler.jsonc.example	Template for the Worker configuration. The real wrangler.jsonc is not committed.

Installation

An installation requires a Cloudflare account and a GitHub App. The procedure is given in full in docs/bootstrap.md, section 10. In outline:

1. Install dependencies with npm install. Node.js 26.11.1 or later is required.
2. Create a D1 database, two KV namespaces and an R2 bucket with Wrangler.
3. Copy wrangler.jsonc.example to wrangler.jsonc and enter the resource identifiers. APP_KV and OAUTH_KV must be different namespaces.
4. Apply the migrations: npx wrangler d1 migrations apply capsid --remote.
5. Create a Cloudflare Access for SaaS (OIDC) application and a GitHub App, and set the required secrets.
6. Run npm run check and npm run deploy.
7. Add https://<worker-host>/mcp as a custom connector in the MCP client.

wrangler.jsonc, .dev.vars, .env, keys and real document content must never be committed. Optional features, including site monitoring, Cloudflare reads, phone alerts and automatic merging, remain inactive until configured.

Development

Command	Purpose
npm run check	Type-check the Worker.
npm test	Unit tests.
npm run test:integration	Integration tests in workerd.
npm run lint	Lint checks, including documentation drift.
npm run build:dashboard	Build the Portal and enforce its size budget.
npm run test:browser	Portal browser tests (Playwright).
npm --prefix dashboard run dev	Serve the Portal locally against sample data.
EXPECT_SHA=<sha> npm run verify:live	Verify the deployed Worker.

The full pre-push sequence is in docs/bootstrap.md. Continuous integration runs these checks on every pull request, and a merge to master deploys to production.

Documentation

Setup and access

• docs/bootstrap.md: installation, agent minting, switches and pre-push checks.
• docs/auth.md: authentication, scopes, roles, co-owners and endpoints.
• docs/repo-access.md: the GitHub App and repository resolution.
• docs/hooks.md: Claude Code hook events.
• docs/telemetry.md: session and job telemetry.

Jobs and agents

• docs/work-queue.md: the job lifecycle, signing and recorded evidence.
• docs/routines.md: starting cloud sessions through routines.
• docs/autonomy.md: automatic merging and pre-approved gates.
• docs/overnight.md: the overnight plan and morning digest.
• docs/bench.md: the paired comparison run in capsid-bench.

Sites and public data

• docs/portal.md: the Capsid Portal.
• docs/health-format.md: the health route format.
• docs/live-checks.md: checks against deployed sites.
• docs/search-console.md: Google Search Console data.
• docs/bing-webmaster.md: Bing Webmaster Tools data.
• docs/public-data.md: the public model, statistics and code maps.
• explorer/README.md: the system explorer.

Data and recovery

• docs/schema.md: document types and database tables.
• docs/consolidation.md: namespace maintenance and destructive writes.
• docs/backups.md: backup contents and restore procedure.
• docs/rollback.md: reverting a deploy.

License

MIT. See LICENSE. Citation metadata is in CITATION.cff.