Skip to main content
Glama
signal-mcpl

signal-mcpl

by jimmielin
README.md
# connectome-signal-mcpl

A [Signal](https://signal.org) surface for Connectome agents. It is an MCPL
server that wraps [signal-cli](https://github.com/AsamK/signal-cli)'s JSON-RPC
interface, so an agent can hold end-to-end-encrypted 1:1 conversations from
any Signal client (Signal, Molly, …).

```
phone (Signal/Molly) ⇄ Signal service ⇄ signal-cli ⇄ signal-mcpl ⇄ connectome-host ⇄ agent
                     └──────── end-to-end encrypted ────────┘
```

Messages are encrypted between the phone and the host running signal-cli; the
Signal service never sees plaintext. (The agent's inference provider and the
host's disk necessarily do.)

## What it does

- **Inbound:** DMs from allowlisted contacts are delivered to the agent as
  `push/event`s carrying `origin.mcplChannelId` (`signal:dm:<ACI>`), so the
  host registers the conversation and routes the agent's prose reply straight
  back. Edits, deletes, and reactions are relayed too (not tagged
  `chat:addressed`, so wake policies can treat them as ambient). Images are
  inlined; small text files are inlined; voice notes and other files are
  described.
- **Outbound:** the agent's prose (`channels/publish`) is sent as a Signal
  message, with markdown converted to Signal's native formatting (bold,
  italic, strikethrough, monospace, spoiler). Long messages are handled by
  signal-cli.
- **Presence:** a typing indicator while the agent is responding, and read
  receipts once the agent actually engages (types, replies, or reacts), not
  merely when the host queues the message.
- **Tools:** `send_message` (incl. quoting), `react`, `edit_message`,
  `delete_message`, `fetch_history`, `list_conversations`, and — if enabled —
  `send_file`. With multiple known contacts, specify `to`; ambiguous names
  are refused, so use the channel ID when names overlap.
- **History:** Signal has no server-side history, so every relayed message is
  appended to `$SIGNAL_STATE_DIR/messages.jsonl`; `fetch_history` and
  `channels/open` read from it.

Not yet: group chats (ignored), voice-note transcription, MCPL rollback.

## Safety properties

- **Allowlist, fail-closed.** Only senders in `SIGNAL_ALLOWED_SENDERS` are
  relayed, and the agent can only message allowlisted contacts. An empty list
  relays nothing. Dropped senders are logged by id only, never by content.
- **Nothing is lost before the host is ready.** signal-cli runs with
  `--receive-mode=manual` and is only subscribed once the host has granted
  push delivery (MCPL §5.3), so the Signal service holds messages until then.
- **Safety-number changes are not auto-trusted** (signal-cli's default
  `on-first-use`). A send to a contact whose key changed fails with an
  explanatory error until an operator verifies and runs `signal-cli trust`.
- **`send_file` is confined** to `SIGNAL_SEND_FILE_ROOTS` (symlinks resolved);
  without that variable the tool is not offered at all.

## Setup

### 1. Install signal-cli

macOS: `brew install signal-cli`. Linux: download a release from
<https://github.com/AsamK/signal-cli/releases> (the native build needs no
JVM; the JVM build needs the Java version named in the release notes).
Keep it updated — Signal stops accepting old clients after a few months.
The JSON-RPC integration was reviewed against signal-cli 0.14.9.

### 2. Register the bot's number

Run these as the user that will run the agent (signal-cli keeps its keys in
`~/.local/share/signal-cli` unless `--config` says otherwise):

```sh
# Solve https://signalcaptchas.org/registration/generate.html and copy the
# "Open Signal" link (signalcaptcha://…).
signal-cli -a +1BOTNUMBER register --captcha 'signalcaptcha://…'
#   landline? after one SMS attempt: add --voice
signal-cli -a +1BOTNUMBER verify 123456

signal-cli -a +1BOTNUMBER updateProfile --given-name SignalBot   # optional: --avatar pic.png
signal-cli -a +1BOTNUMBER setPin 'a-long-registration-lock-pin'   # blocks re-registration hijacks
```

### 3. Find your own id

From your phone, send the bot a message. Then run the server (or the agent)
with your number in `SIGNAL_ALLOWED_SENDERS`. If your number is hidden by
Signal's phone-number privacy, the message is dropped and the log prints your
ACI instead:

```
[signal-mcpl] dropped message from non-allowlisted sender uuid=… number=-
```

Put that UUID in `SIGNAL_ALLOWED_SENDERS`.

### 4. Build and add to the recipe

Requires Node.js 22.12 or newer.

```sh
git clone https://github.com/jimmielin/connectome-signal-mcpl.git
cd connectome-signal-mcpl
npm install && npm run build
```

```jsonc
"mcpServers": {
  "signal": {
    "command": "node",
    "args": ["/path/to/connectome-signal-mcpl/dist/src/index.js", "--stdio"],
    "env": {
      "SIGNAL_ACCOUNT": "${SIGNAL_ACCOUNT}",
      "SIGNAL_ALLOWED_SENDERS": "${SIGNAL_ALLOWED_SENDERS}",
      "SIGNAL_CONTACT_NAMES": "${SIGNAL_CONTACT_NAMES}",
      "SIGNAL_STATE_DIR": "./data/signal",
      "SIGNAL_CLI_BIN": "/path/to/signal-cli"
    }
  }
}
```

and, if the recipe has explicit wake policies, wake on addressed Signal
messages while letting reactions/edits wait for the next turn:

```jsonc
"wake": { "policies": [
  { "name": "signal-dm", "match": { "source": "signal", "tagsAny": ["chat:addressed"] }, "behavior": "always" },
  { "name": "signal-ambient", "match": { "source": "signal" }, "behavior": "defer" }
] }
```

(`source` is the `mcpServers` key.)

Set `SIGNAL_ACCOUNT` and `SIGNAL_ALLOWED_SENDERS` in the host's environment
before loading this recipe. Set `SIGNAL_CONTACT_NAMES` too, or remove its
optional line: Connectome rejects substitutions for unset variables. Other
`SIGNAL_*` settings must also be passed explicitly in the server's `env` map;
the host does not inherit arbitrary environment variables into MCPL children.

### Running signal-cli as a separate daemon (optional)

By default signal-mcpl spawns signal-cli as a child process. To keep
signal-cli running across agent restarts instead, run it as a service and
point the server at its socket:

```sh
signal-cli -a +1BOTNUMBER daemon --socket /run/user/$UID/signal-cli.sock --receive-mode=manual
```

```jsonc
"SIGNAL_CLI_SOCKET": "/run/user/1000/signal-cli.sock"
```

Socket requests explicitly select `SIGNAL_ACCOUNT`, and notifications for
other accounts are ignored. In socket mode, use the phone number for a
numbered account, or the ACI for a numberless account, matching signal-cli's
notification `account` field.

## Configuration

| Variable | Default | |
|---|---|---|
| `SIGNAL_ACCOUNT` | — (required) | The bot's registered number (or ACI). |
| `SIGNAL_ALLOWED_SENDERS` | empty ⇒ relay nothing | Comma-separated numbers and/or ACIs. |
| `SIGNAL_CONTACT_NAMES` | — | `id=Name,…` display names shown to the agent. |
| `SIGNAL_CLI_BIN` | `signal-cli` | Executable for spawn mode. |
| `SIGNAL_CLI_CONFIG` | signal-cli default | signal-cli data dir (`--config`). |
| `SIGNAL_CLI_SOCKET` | — | Use a running daemon instead of spawning. |
| `SIGNAL_STATE_DIR` | `./signal-state` | Message log and contact book. |
| `SIGNAL_MARKDOWN` | on | `off` sends agent text verbatim. |
| `SIGNAL_READ_RECEIPTS` | on | `off` never sends read receipts. |
| `SIGNAL_SEND_FILE_ROOTS` | — (tool hidden) | Colon-separated dirs `send_file` may read. |
| `SIGNAL_IMAGE_INLINE_MAX_BYTES` | 3500000 | Larger images are described, not inlined. |
| `SIGNAL_TEXT_INLINE_MAX_BYTES` | 65536 | Larger text files are described, not inlined. |
| `AGENT_TIMEZONE` | system | Injected by connectome-host; used in `fetch_history`. |

### Local data and privacy

The state directory contains **plaintext** message content and contact IDs.
New state directories are owner-only and state files are readable/writable
only by their owner. Keep this directory and signal-cli's key/attachment
directory out of Git, backups you do not trust, and public release artifacts.
The npm package includes only the runtime, source, README, and license.

The append-only log retains original text even after a message is edited or
deleted, and it does not implement Signal disappearing-message expiration.
Only the most recent 5,000 log entries are loaded for history; the on-disk log
is not automatically pruned. Delivery failures are logged, but are not
automatically replayed after a server restart. Dropped-sender diagnostics
contain contact IDs, and signal-cli's own diagnostics may also contain
operational metadata. Treat stderr logs as private.

## MCPL surface

- Capabilities: `pushEvents`, `channels.{register,lifecycle,publish,incoming,acknowledge,typing}`.
- Feature sets: `signal.messaging` (`tools`, `pushEvents`, `channels.register`,
  `channels.publish`) — the core; `signal.channels` (`channels.lifecycle`,
  `channels.incoming`, `channels.acknowledge`, `channels.typing`) — optional,
  so a host that withholds these degrades to "DMs in, replies out".
- Event tags: messages carry `chat:dm`, `chat:addressed`, `chat:private`,
  `chat:from-human`, plus `chat:reply` (quoting the agent) and
  `chat:has-image|audio|file`. Edits, deletes, and reactions carry only
  `chat:private`, `chat:from-human`, and `chat:edited` / `chat:deleted` /
  `chat:reaction` / `chat:reaction-remove` — never `chat:dm`, because the
  host expands `chat:dm` to `chat:addressed` (MCPL §16.3).

## Development

```sh
npm test    # unit tests + an end-to-end run against a fake signal-cli
```

`src/mcpl05.ts` and `src/timezone.ts` are vendored from
connectome-heartbeat-mcpl; keep them in sync.

This MCPL was developed in collaboration with Claude Opus 5.5.