Agent Q

Agent Q is a Model Context Protocol (MCP) review server for repository governance. It applies a deterministic policy to pull requests, commits and repositories, and returns findings by rule identifier.

1. Scope

Related MCP server: shipcheck-mcp

2. Conventions

The key words MUST, MUST NOT, SHALL, SHALL NOT, SHOULD and MAY are to be read as described in RFC 2119 and RFC 8174.

3. Requirements

4. Tools

The policy is also published as the MCP resource agentq://policy.

5. Policy

A verdict of CHANGES REQUESTED follows from any error finding, COMMENT from any warning, and APPROVE otherwise.

6. Integration

6.1 Copilot custom agent

Copy templates/.github/agents/agent-q.agent.md to .github/agents/ in the target repository. Agent Q then appears in the Copilot agents list for that repository.

6.2 GitHub Actions

Copy templates/.github/workflows/agent-q.yml to .github/workflows/. The workflow reviews each pull request with the job's own GITHUB_TOKEN, maintains one review comment and fails on CHANGES REQUESTED.

6.3 Other MCP clients

claude mcp add --transport http agent-q https://tcaefdirgffncwfwrlbe.supabase.co/functions/v1/agent-q/mcp --header "apikey: sb_publishable_KpeKmqmnbI9lTj_eu98nzA_tGUOMtBC"

6.4 Cloudflare Workers

The same application runs as a Worker (worker/index.ts, wrangler.jsonc), served at the Worker root: /, /health and /mcp.

Dashboard: Workers and Pages, Create, Import a repository, select this repository. Build command: none. Deploy command: npx wrangler deploy. Root directory: /.

CLI:

npm ci
npx wrangler deploy
npx wrangler secret put AGENT_Q_TOKEN

6.4.1 Single-step AI reviewer

POST /review on the Worker runs one pass per request: it fetches the pull request or commit from GitHub, reads the repository's data points from Supabase with @supabase/supabase-js, applies the Agent Q rules, makes one Workers AI call (@cf/meta/llama-3.1-8b-instruct-fast by default, override with AGENT_Q_MODEL) and saves the result to public.reviews. The rule verdict is authoritative; the model only explains and prioritises.

curl -X POST https://agent-q.itsdhruvsetty.workers.dev/review \
  -H "apikey: <publishable key>" -H "content-type: application/json" \
  -d '{"owner":"whatheheckisthis","repo":"agent-q","number":1}'

GET /reviews/<owner>/<repo> returns the saved history. The Worker needs the secret SUPABASE_SERVICE_ROLE_KEY (npx wrangler secret put SUPABASE_SERVICE_ROLE_KEY); without it the review still runs but is not saved. Tables are created by supabase/migrations/20261115000000_agent_q_reviews.sql, with RLS on and no public policies.

6.5 Web console

docs/index.html is a browser console for the server, served as static assets by the Cloudflare Worker at https://agent-q.itsdhruvsetty.workers.dev/. It reviews pasted code, pull requests, commits and repositories, and shows the policy. Settings hold the endpoint, the gateway key and an optional GitHub token, all kept in the browser.

6.6 Deployment

The Supabase GitHub integration deploys supabase/functions/agent-q to project tcaefdirgffncwfwrlbe on every push to main.

7. Configuration

8. Local verification

deno check supabase/functions/agent-q/index.ts
supabase functions serve agent-q
npm ci && npx wrangler dev

9. Limitations

1. The policy is lexical. It does not establish the truth of a claim, only the presence of its evidence reference.

2. Pull request review covers added lines only. Context outside the diff is not evaluated.

3. Without GITHUB_TOKEN, the server reads public repositories only, within the unauthenticated GitHub API rate limit.