# Signal MCP

Signal is a lightweight MCP work queue for AI agents.

It provides a small set of tools for creating, claiming, starting, handing off, failing, completing, and reviewing durable work items through MCP.

Signal is intentionally simple.

## v0.1.0

The first release provides a basic agent work lifecycle:

```text
created
  ↓
claimed
  ↓
in_progress
  ↓
completed
```

With additional paths for:

```text
handoff
failed
```

## MCP Tools

| Tool              | Description                                |
| ----------------- | ------------------------------------------ |
| `signal.ping`     | Check that Signal and SQLite are available |
| `signal.create`   | Create a new Signal work item              |
| `signal.get`      | Retrieve a Signal by ID                    |
| `signal.list`     | List recent Signals                        |
| `signal.claim`    | Assign a Signal to an agent                |
| `signal.start`    | Mark a claimed Signal as in progress       |
| `signal.handoff`  | Transfer a Signal to another agent         |
| `signal.fail`     | Mark a Signal as failed                    |
| `signal.complete` | Mark a Signal as completed                 |

## Stack

* TypeScript
* Model Context Protocol
* Streamable HTTP
* SQLite
* Docker
* Docker Compose

## Connect

Signal exposes an MCP endpoint at:

http://localhost:3002/mcp

## Run

```bash
cp .env.example .env
docker compose up -d
```

By default, Signal is exposed at:

```text
http://localhost:3002/mcp
```

The container listens internally on port `3000`.

## Persistence

Signal stores work state in SQLite.

The Docker Compose setup mounts the database outside the container so work survives container replacement and restarts.

## Status

`v0.1.0` is intentionally small.

The goal of this release is to establish a simple, durable MCP work queue before adding more advanced features such as milestones, dependencies, events, artifacts, reviews, or workflow policies.

Those features will be shaped by actual agent usage rather than added in advance.