# SwipeFlow MCP Server

Human-in-the-loop approvals for AI agents, over the [Model Context Protocol](https://modelcontextprotocol.io).

An agent asks a person to review something, gets a durable handle back, and resumes once a
decision has been made. Human review takes minutes or days, so the wait is asynchronous by
design — the agent is never required to hold a connection open.

> **Status:** early development. The tool surface is being built against MCP `2026-07-28`.
> Not yet ready for production use.

## Why this exists

Agents increasingly produce work that a human should approve before it ships — content,
code changes, outbound messages, spending decisions. The awkward part is never the approval
itself, it's the *waiting*: humans are slow and agents are not built to block.

This server makes that wait a first-class protocol concern.

## Design

Three properties shape everything else:

**Stateless.** The server holds no task store, no session store, no database. Task state
lives in SwipeFlow, because a review *is* a task. That is what gives resumability across
restarts, horizontal scaling with no coordination, and self-hosting with no infrastructure.

**Decisions are outcomes, not failures.** Approved, rejected, and changes-requested all
complete normally and carry an outcome. Failure is reserved for genuine errors, so an agent
can branch on a human's judgement without treating disagreement as a fault.

**Works with or without the Tasks extension.** Support varies across MCP clients, so every
asynchronous tool has a synchronous fallback with identical semantics and identical IDs.
Tasks is an upgrade in how a handle is delivered, never in what it means.

## Development

Requires Node.js 20 or newer.

```bash
npm install
npm run verify     # boundary checks, lint, typecheck, tests
npm run build
```

Individual steps:

```bash
npm run check:deps      # dependency allowlist
npm run check:boundary  # copied-code fingerprints
npm run lint
npm run typecheck
npm test
```

### The boundary checks

This repository is public; the SwipeFlow backend is not. The MCP server reaches SwipeFlow
**only through its public REST API** — never a database, never a shared private module.

Two guards enforce that mechanically rather than by review discipline:

- `check:deps` — every dependency must be declared in `allowed-dependencies.json`. Adding one
  is a deliberate act. Stale entries also fail, so the allowlist cannot quietly accumulate
  grants.
- `check:boundary` — scans source for the fingerprints of backend code having been copied
  across: database drivers, backend-only credential surfaces, relative imports that escape
  the repository.

Both run in CI ahead of lint and tests, and both are themselves covered by tests in
`test/boundary.test.ts` — a guard nobody exercises is a guard that silently stops working.

## Contributing

Issues and discussion: <https://github.com/swipeflow/swipeflow-mcp/issues>

## License

[Apache 2.0](./LICENSE)