docs(mcp): note signal-cli + Google Voice dependency for signal-mcp

1 files changed, 12 insertions, 0 deletions

diff --git a/mcp/README.org b/mcp/README.org
index c8cb49a..30dc082 100644
--- a/mcp/README.org
+++ b/mcp/README.org
@@ -79,3 +79,15 @@ A Google refresh token dies when scopes are re-granted, the Connected App is rem
 
 - *HTTP/SSE servers* (=linear=, =notion=) carry their own hosted OAuth — the first tool call in a session triggers an in-client auth flow; nothing local to cache. If a connection fails, it is usually an expired in-client grant, re-authorized from the client, not from this pipeline.
 - *stdio servers needing OAuth* (=google-docs-*=, =google-calendar=) cannot run an interactive browser flow under Claude Code's stdio loader. They depend on a *pre-seeded* token/keys file on disk — which is exactly why the installer materializes them from the bundle. A "Failed to connect" on one of these almost always means the on-disk token cache is missing or stale; rotate it (above) rather than re-running the server by hand.
+
+* Signal MCP — local signal-cli dependency
+
+The =signal-mcp= server (rymurr/signal-mcp, cloned to =~/.local/share/signal-mcp= with a =uv=-built =.venv=) wraps a locally-installed =signal-cli=. Unlike the OAuth servers, it carries no secret in the bundle — its only config is the =--user-id= it runs as, which is set in =servers.json=.
+
+Prerequisites on a fresh machine, in order:
+
+1. Install =signal-cli= (AUR: =signal-cli=; needs a JRE 21+).
+2. Register the dedicated pager account. Signal requires a captcha for registration: run =signal-cli -a +<number> register=, follow the printed =signalcaptchas.org= link, solve it, and pass the resulting token to =signal-cli -a +<number> register --captcha <token>= within a minute or two before it expires. Signal then texts a code to the number; verify with =signal-cli -a +<number> verify <code>=.
+3. =make install-mcp= registers =signal-mcp= pointed at that =--user-id=.
+
+The =--user-id= is a *dedicated* number (a Google Voice number registered to =signal-cli=), not Craig's primary. Signal mobile won't push-notify a message an account sends to itself, so paging from the primary to itself is silent; a distinct sender account reaching Craig's account notifies normally. Craig's account hides its phone number under phone-number privacy, so the destination is its stable account UUID rather than a number. The same account and recipient back the =page-signal= CLI wrapper (=PAGE_SIGNAL_ACCOUNT= / =PAGE_SIGNAL_TO=). The MCP server is the two-way path (=receive_message= to listen for replies); =page-signal= is the fast send-only path.