# MCP tools & hub API

> Reference for project-scoped MCP tools, browser routes, leases, and configuration.

Run `npx -y @wcgw/vibe-check-mcp@0.3.0 hub` once. MCP clients spawn
`npx -y @wcgw/vibe-check-mcp@0.3.0 connect` and expose the tools below.

## Project selection

Every project-scoped tool accepts optional `project_id: string`. It may be
omitted only when exactly one active project exists or the session already owns
a lease. Multiple active projects without a selection return
`project-ambiguous`; an unknown value returns `project-not-found`.

## Tools

| Tool | Parameters | Returns |
|---|---|---|
| `list_projects` | — | Active project summaries with URL, last seen, issue count, queue depth, and agent state. |
| `get_performance_snapshot` | `project_id?` | Latest `VibeSnapshot`, or `no-snapshot`. |
| `get_detected_issues` | `project_id?`, `severity?`, `detector?` | `{ count, issues }` for one project. |
| `get_fix_suggestions` | `project_id?`, `issue_id` | Markdown suggestion, or `issue-not-found`. |
| `watch_performance` | `project_id?`, `timeout_seconds?` (1–300, default 30) | Acquires the lease and returns the next project snapshot, or `watch-timeout`. |
| `watch_for_issue` | `project_id?`, `timeout_seconds?` (1–300, default 30) | Acquires the lease and returns one queued widget dispatch plus its suggestion, or `watch-timeout`. |
| `acknowledge_issue` | `project_id?`, `issue_id` | `{ acknowledged: true, projectId, issue_id }`. |
| `resolve_issue` | `project_id?`, `issue_id` | `{ resolved: true, projectId, issue_id }`. |
| `release_project` | — | Releases the current session's lease. |

One session cannot select a different project while it owns a lease; the result
is `session-already-watching`. A healthy owner blocks another session with
`lease-conflict`.

## Browser API

| Route | Method | Response |
|---|---|---|
| `/api/health` | GET | `{ status: "ok", service: "vibe-check-hub", version }`. |
| `/api/snapshot` | POST | Accepts `{ projectId, instanceId, pageUrl, snapshot }`; returns `{ received: true, projectId }`. |
| `/api/projects/:projectId/status` | GET | `{ projectId, state, queueDepth, leaseExpiresAt, conflictAt }`. |
| `/api/projects/:projectId/dispatch` | POST | Accepts `{ projectId, instanceId, issue }`; returns a `DispatchIssueResponse`. |

Browser routes allow CORS. `/internal/*` is reserved for the local bridge and
rejects requests carrying a browser `Origin` header.

Dispatch result codes are `dispatched`, `unconfigured`, `hub-offline`,
`agent-not-watching`, `queue-full`, `invalid-issue`, and `failed`. The per-project
queue holds at most 10 issues.

## Lease timing

| Event | Timing |
|---|---|
| Bridge heartbeat | every 5 seconds |
| Widget reports watcher stale | after 10 seconds |
| Lease expires and may be reclaimed | after 15 seconds |
| Conflict warning retained | 30 seconds |

## Environment

| Role | Variable | Default |
|---|---|---|
| `hub` | `VIBE_CHECK_HOST` | `127.0.0.1` |
| `hub` | `VIBE_CHECK_PORT` | `4200` |
| `connect` | `VIBE_CHECK_HUB_URL` | `http://127.0.0.1:4200` |

**Keep the hub local**

  It is an unauthenticated development service. The default loopback bind is
  intentional; do not expose it to a public interface.