@rackbops/plugin-mcp 0.0.0 → 0.3.1

package/README.md

@@ -1,3 +1,159 @@
-# @rackbops/plugin-mcp (placeholder)
+# @rackbops/plugin-mcp
 
-This 0.0.0 release only bootstraps npm trusted publishing. Install a real version (0.3.0 or later), published by CI from Rackbops/rackbops-bot-plugins.
+The bridge plugin for the Discord delivery MCP ([`Rackbops/discord-mcp`](https://github.com/Rackbops/discord-mcp),
+[Rackbops/Tooling#742](https://github.com/Rackbops/Tooling/issues/742)). It implements the service
+side of that repo's `docs/bridge-protocol.md` under `/mcp/` on the bot's own HTTP listener
+(rackbops-discord-bot's host-owned router, ADR-0007) -- `GET /capabilities`,
+`POST /deliveries`, `GET /deliveries/{request_id}` and `GET /recipients` -- so the MCP service can
+hand it a message and get exactly one Discord post, DM or edit out of it, however many times it
+retries. It also owns Discord-side agent identity ([Rackbops/Tooling#743](https://github.com/Rackbops/Tooling/issues/743)):
+the `/agent` slash command, and `POST /pair/redeem` + `GET /registration/{user_id}` under the same
+`/mcp/` path.
+
+The host prefixes every plugin command with the instance's `COMMAND_PREFIX` (`/pipagent` on a bot
+with `COMMAND_PREFIX=pip`), so `/agent` below reads literally only on an unprefixed bot; the
+command's own replies name whichever form the user invoked.
+
+## What it does
+
+- Accepts a delivery request, answers `202` immediately, and delivers to Discord in the background.
+- Keeps one state file per `request_id` (`pending` -> `delivered`/`failed`, or `unknown` after a bot
+  restart mid-delivery) so a retry with the same `request_id` never delivers twice.
+- A tick re-drives any delivery a restart left `unknown`, and prunes records older than 8 days.
+- `kind: "post"` goes through `host.post` (or `host.announce` when the host predates it); `kind: "dm"`
+  goes through `host.dm`, to a registered user only; `kind: "edit"` goes through `host.edit`, applied
+  against the stored delivery `message_ref` names. `GET /capabilities` reports `dm`/`edit` as `true`
+  exactly when the host provides `host.dm`/`host.edit` -- a host without either still gets a clean
+  `failed{CAPABILITY_UNAVAILABLE}` for that kind, the same shape a missing `host.post` has always
+  gotten.
+- `/agent register` mints a Discord user a `generation` id; `/agent pair` issues a single-use,
+  10-minute pairing code (at least 128 bits, 27 characters; at most 5 live at once -- issuing a 6th
+  drops the oldest); a connector exchanges that code for the user's id and generation via
+  `POST /pair/redeem`; `/agent unregister` deletes the registration and every outstanding code in
+  one write.
+
+## DM, edit and recipients
+
+Example ids used throughout: user `123456789012345678`, guild `234567890123456789`, channel
+`345678901234567890`, message `456789012345678901`; an original send's `request_id` is 64 x `a`, an
+edit's is 64 x `b`.
+
+`POST /deliveries`, `kind: "dm"` -- `target.user_id` must match `^[1-9][0-9]{16,19}$`; `body` is
+validated as for a post:
+
+```
+request:  {"request_id":"<64 hex>","kind":"dm","target":{"user_id":"123456789012345678"},"body":{"content":"hi"}}
+202:      {"state":{"state":"pending","kind":"dm","target":{"user_id":"123456789012345678"},"body":{"content":"hi"},"created_at":"2026-09-25T00:00:00.000Z"},"existing":false}
+GET once delivered:
+          {"state":"delivered","kind":"dm","target":{"user_id":"123456789012345678"},"body":{"content":"hi"},"created_at":"2026-09-25T00:00:00.000Z","message_ref":"<the dm's own request_id>","url":"https://discord.com/channels/@me/345678901234567890/456789012345678901"}
+GET when the recipient isn't registered, or has closed DMs:
+          {"state":"failed","kind":"dm","target":{"user_id":"123456789012345678"},"body":{"content":"hi"},"created_at":"2026-09-25T00:00:00.000Z","code":"RECIPIENT_UNREACHABLE"}
+```
+
+`POST /deliveries`, `kind: "edit"` -- `target.message_ref` is the original post's or dm's own
+`request_id` and must match `^[0-9a-f]{64}$`; `target.seq` is the service's own per-message edit
+counter, an integer from 1 to 2147483647; `body` is partial -- at least one of `content` (1-2000
+characters when present), `card` or `links`:
+
+```
+request:  {"request_id":"bbbb...(64)","kind":"edit","target":{"message_ref":"aaaa...(64)","seq":2},"body":{"content":"v2"}}
+GET once applied:
+          {"state":"delivered","kind":"edit","target":{"message_ref":"aaaa...(64)","seq":2},"body":{"content":"v2"},"created_at":"2026-09-25T00:00:00.000Z","message_ref":"aaaa...(64)","url":"https://discord.com/channels/234567890123456789/345678901234567890/456789012345678901","applied":true}
+GET once superseded by a higher seq already applied (reported as unchanged, not an error):
+          { ...same..., "applied":false }
+```
+
+`failed` codes for an edit:
+
+| Code | When |
+| --- | --- |
+| `NOT_FOUND` | No record for `message_ref`, the record isn't `delivered`, or it is itself an edit. |
+| `CAPABILITY_UNAVAILABLE` | `host.edit` is absent, or the original was delivered by `announce` (`delivery: null`). |
+| `RECIPIENT_UNREACHABLE` | The original was a dm and its recipient is no longer registered. |
+| `UPSTREAM_UNAVAILABLE` | `host.edit` rejected. |
+
+`applied` appears only on `kind: "edit"` records that are `delivered`. `state` stays
+`pending|delivered|failed|unknown` -- there is no new state.
+
+`GET /recipients` -- every registered user, ordered by registration time ascending then `user_id`, at
+most 100, each `display_name` truncated to 100 characters (same bearer auth; any other method is
+`405`):
+
+```
+200: {"items":[{"user_id":"123456789012345678","display_name":"Roshne"}]}
+200: {"items":[]}
+```
+
+`GET /capabilities` now reflects the host's real `dm`/`edit` support:
+
+```
+{"dm":<typeof host.dm === "function">,"targeted_post":<has post>,"cards":<has post>,"edit":<typeof host.edit === "function">,"destinations":[...unchanged...]}
+```
+
+A dm/edit's `target` 400s use the existing `{"error":"<reason>"}` shape (`target.user_id`/
+`target.message_ref` must be a snowflake/64-hex-string; `target.seq` must be an integer in range;
+the edit body must include at least one of `content`, `card` or `links`).
+
+A record created before this version (`kind: "dm"`/`"edit"` with the old coerced target) is never
+delivered -- a dm gets `failed{RECIPIENT_UNREACHABLE}`, an edit gets `failed{NOT_FOUND}`, both with
+no Discord call. No migration runs; the mismatch between the record's `kind` and its actual target
+shape is what a redrive recognizes.
+
+## Registration and pairing
+
+`POST /pair/redeem` -- exchanges a code from `/agent pair` for the Discord user id and generation:
+
+```
+request:  {"code":"ABCDEFGHJKMNPQRSTVWXYZ23456"}
+200:      {"discord_user_id":"123456789012345678","generation":"q1w2e3r4t5y6u7i8o9p0aZ"}
+404:      {"error":"invalid or expired code"}     (unknown, expired, already used, or issued before an unregister -- one answer for all)
+400:      {"error":"malformed request"}           (not JSON, no string `code`, or `code` not matching ^[A-Z2-9]{27}$)
+```
+
+`GET /registration/{user_id}` -- `{user_id}` must match `^[1-9][0-9]{16,19}$`, else `404`:
+
+```
+200:      {"generation":"q1w2e3r4t5y6u7i8o9p0aZ"}
+404:      {"error":"not registered"}
+```
+
+A `generation` changes only across a full unregister-then-register-again -- a connector holding a
+stale `generation` for a user has been revoked and re-paired since, not merely re-issued a code.
+
+## Env
+
+| Key | Required | Secret | What it does |
+|---|---|---|---|
+| `MCP_BRIDGE_TOKEN` | No | Yes | The bearer token the MCP service must present. Unset = every request gets `503 {"error":"bridge not configured"}`. At least 256 bits, base64url -- generate one with e.g. `openssl rand -base64 32 \| tr -d '=' \| tr '/+' '_-'`. |
+
+## Destinations
+
+Declared so the operator can map each to a channel per server in the admin panel (the same
+`destinations` mechanism every plugin's `HostApi.announce` uses):
+
+| Name | What it's for |
+|---|---|
+| `alerts` | Time-sensitive findings and warnings |
+| `deals` | Notable deals or opportunities |
+| `digest` | Periodic summaries |
+| `ops` | Operational status and infrastructure notices |
+
+## Operator steps (not done by this plugin)
+
+1. Set `PLUGINS=...,mcp` and `MCP_BRIDGE_TOKEN` on the bot instance.
+2. Map at least one destination to a channel, in exactly one server, from the admin panel.
+3. Confirm how the bot's HTTP listener is exposed; if `/mcp/` is not already behind Cloudflare
+   Access, front it with an Access application using the existing machine-access service-token
+   policy -- the bridge secret above is the second factor, not a substitute for Access.
+4. Configure the MCP service (`Rackbops/discord-mcp`) with this bridge's URL and the same token.
+
+None of this runs the plugin's first live end-to-end check by itself -- see
+[Rackbops/Tooling#742](https://github.com/Rackbops/Tooling/issues/742)'s acceptance bullets for what
+that verifies.
+
+## Design
+
+`docs/bridge-protocol.md` in [`Rackbops/discord-mcp`](https://github.com/Rackbops/discord-mcp) is the
+protocol this plugin implements; where this README and that document ever disagree, the protocol
+document wins (this plugin is the implementation, not the source of truth). See `CONTEXT.md` in this
+repo for the file-by-file breakdown and the state-machine gotchas.

package/dist/plugin.js

@@ -0,0 +1,839 @@
+// @bun
+// plugins/mcp/src/auth.ts
+import { createHash, timingSafeEqual } from "crypto";
+var WINDOW_MS = 60000;
+var MAX_FAILURES = 10;
+function createRateLimiter() {
+  const windows = new Map;
+  return {
+    isLocked(clientIp, now) {
+      const entry = windows.get(clientIp);
+      if (entry === undefined)
+        return false;
+      if (now.getTime() - entry.windowStart >= WINDOW_MS)
+        return false;
+      return entry.count > MAX_FAILURES;
+    },
+    recordFailure(clientIp, now) {
+      const entry = windows.get(clientIp);
+      if (entry === undefined || now.getTime() - entry.windowStart >= WINDOW_MS) {
+        windows.set(clientIp, { windowStart: now.getTime(), count: 1 });
+      } else {
+        entry.count += 1;
+      }
+    }
+  };
+}
+function constantTimeEqual(given, expected) {
+  const a = createHash("sha256").update(given).digest();
+  const b = createHash("sha256").update(expected).digest();
+  return timingSafeEqual(a, b);
+}
+function checkAuth(request, clientIp, expectedToken, limiter, now, log) {
+  const at = now();
+  if (limiter.isLocked(clientIp, at))
+    return { ok: false, status: 429 };
+  const header = request.headers.get("authorization") ?? "";
+  const given = header.startsWith("Bearer ") ? header.slice("Bearer ".length) : undefined;
+  if (given === undefined || given.length === 0 || !constantTimeEqual(given, expectedToken)) {
+    limiter.recordFailure(clientIp, at);
+    log.warn(`auth failed from ${clientIp}`);
+    return { ok: false, status: 401 };
+  }
+  return { ok: true };
+}
+
+// plugins/mcp/src/commands.ts
+import { MessageFlags } from "discord.js";
+async function replyEphemeral(interaction, content) {
+  await interaction.reply({ content, flags: MessageFlags.Ephemeral });
+}
+function subcommandRef(interaction, sub) {
+  return `\`/${interaction.commandName} ${sub}\``;
+}
+function displayNameOf(interaction) {
+  return interaction.user.globalName ?? interaction.user.username;
+}
+async function handleRegister(interaction, store) {
+  const outcome = await store.register(interaction.user.id, displayNameOf(interaction), () => new Date);
+  if (!outcome.changed) {
+    await replyEphemeral(interaction, "Already registered \u2014 nothing changed.");
+    return;
+  }
+  await replyEphemeral(interaction, `Registered. Run ${subcommandRef(interaction, "pair")} to generate a pairing code for your agent.`);
+}
+async function handlePair(interaction, store) {
+  const outcome = await store.pair(interaction.user.id, displayNameOf(interaction), () => new Date);
+  if (!outcome.ok) {
+    await replyEphemeral(interaction, `Run ${subcommandRef(interaction, "register")} first.`);
+    return;
+  }
+  await replyEphemeral(interaction, `Your pairing code: **${outcome.code}**
+
+` + "Valid 10 minutes, single use. Enter it only in `discord-mcp pair` or your connector's authorization page \u2014 never paste it anywhere else.");
+}
+async function handleUnregister(interaction, store) {
+  const { changed } = await store.unregister(interaction.user.id, () => new Date);
+  await replyEphemeral(interaction, changed ? "Unregistered: your agents' tokens and DMs are revoked." : "You weren't registered.");
+}
+function agentCommand(store) {
+  return {
+    name: "agent",
+    build: (builder) => builder.setDescription("Manage your Discord MCP agent access").addSubcommand((s) => s.setName("register").setDescription("Register this Discord account for agent access")).addSubcommand((s) => s.setName("pair").setDescription("Generate a one-time pairing code for your agent")).addSubcommand((s) => s.setName("unregister").setDescription("Revoke your agent access")),
+    async handle(interaction) {
+      const subcommand = interaction.options.getSubcommand();
+      if (subcommand === "register")
+        return handleRegister(interaction, store);
+      if (subcommand === "pair")
+        return handlePair(interaction, store);
+      if (subcommand === "unregister")
+        return handleUnregister(interaction, store);
+    }
+  };
+}
+
+// plugins/mcp/src/protocol.ts
+var REQUEST_ID_RE = /^[0-9a-f]{64}$/;
+var SNOWFLAKE_RE = /^[0-9]{5,25}$/;
+var DISCORD_USER_ID_RE = /^[1-9][0-9]{16,19}$/;
+var MAX_BODY_BYTES = 64 * 1024;
+var CONTENT_MIN = 1;
+var CONTENT_MAX = 2000;
+var SEQ_MIN = 1;
+var SEQ_MAX = 2147483647;
+var RECIPIENTS_MAX = 100;
+var DISPLAY_NAME_MAX = 100;
+var PAIR_CODE_RE = /^[A-Z2-9]{27}$/;
+var DESTINATIONS = [
+  { name: "alerts", description: "Time-sensitive findings and warnings" },
+  { name: "deals", description: "Notable deals or opportunities" },
+  { name: "digest", description: "Periodic summaries" },
+  { name: "ops", description: "Operational status and infrastructure notices" }
+];
+var DESTINATION_NAMES = DESTINATIONS.map((d) => d.name);
+function isPostTarget(target) {
+  return "guildId" in target && "destination" in target;
+}
+function isDmTarget(target) {
+  return "userId" in target;
+}
+function isEditTarget(target) {
+  return "messageRef" in target && "seq" in target;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateBody(raw, opts) {
+  if (!isRecord(raw))
+    return { ok: false, reason: "body must be an object" };
+  const value = {};
+  if (raw.content !== undefined) {
+    if (typeof raw.content !== "string" || raw.content.length < CONTENT_MIN || raw.content.length > CONTENT_MAX) {
+      return { ok: false, reason: `body.content must be ${CONTENT_MIN}..${CONTENT_MAX} characters` };
+    }
+    value.content = raw.content;
+  } else if (opts.requireContent) {
+    return { ok: false, reason: `body.content must be ${CONTENT_MIN}..${CONTENT_MAX} characters` };
+  }
+  if (raw.card !== undefined) {
+    if (!isRecord(raw.card))
+      return { ok: false, reason: "body.card must be an object" };
+    value.card = raw.card;
+  }
+  if (raw.links !== undefined) {
+    if (!Array.isArray(raw.links))
+      return { ok: false, reason: "body.links must be an array" };
+    value.links = raw.links;
+  }
+  if (!opts.requireContent && value.content === undefined && value.card === undefined && value.links === undefined) {
+    return { ok: false, reason: "body must include at least one of content, card or links" };
+  }
+  return { ok: true, value };
+}
+function validateCreateRequest(raw) {
+  if (!isRecord(raw))
+    return { ok: false, reason: "request body must be an object" };
+  const requestId = raw.request_id;
+  if (typeof requestId !== "string" || !REQUEST_ID_RE.test(requestId)) {
+    return { ok: false, reason: "request_id must be a lowercase 64-character hex string" };
+  }
+  const kind = raw.kind;
+  if (kind !== "post" && kind !== "dm" && kind !== "edit") {
+    return { ok: false, reason: 'kind must be "post", "dm" or "edit"' };
+  }
+  if (kind === "post") {
+    const bodyResult = validateBody(raw.body, { requireContent: true });
+    if (!bodyResult.ok)
+      return bodyResult;
+    if (!isRecord(raw.target))
+      return { ok: false, reason: "target must be an object" };
+    const guildId = raw.target.guild_id;
+    if (typeof guildId !== "string" || !SNOWFLAKE_RE.test(guildId)) {
+      return { ok: false, reason: "target.guild_id must be a snowflake" };
+    }
+    const destination = raw.target.destination;
+    if (typeof destination !== "string" || !DESTINATION_NAMES.includes(destination)) {
+      return { ok: false, reason: `target.destination must be one of ${DESTINATION_NAMES.join(", ")}` };
+    }
+    return { ok: true, requestId, kind, target: { guildId, destination }, body: bodyResult.value };
+  }
+  if (kind === "dm") {
+    const bodyResult = validateBody(raw.body, { requireContent: true });
+    if (!bodyResult.ok)
+      return bodyResult;
+    if (!isRecord(raw.target))
+      return { ok: false, reason: "target must be an object" };
+    const userId = raw.target.user_id;
+    if (typeof userId !== "string" || !DISCORD_USER_ID_RE.test(userId)) {
+      return { ok: false, reason: "target.user_id must be a snowflake" };
+    }
+    return { ok: true, requestId, kind, target: { userId }, body: bodyResult.value };
+  }
+  const bodyResult = validateBody(raw.body, { requireContent: false });
+  if (!bodyResult.ok)
+    return bodyResult;
+  if (!isRecord(raw.target))
+    return { ok: false, reason: "target must be an object" };
+  const messageRef = raw.target.message_ref;
+  if (typeof messageRef !== "string" || !REQUEST_ID_RE.test(messageRef)) {
+    return { ok: false, reason: "target.message_ref must be a lowercase 64-character hex string" };
+  }
+  const seq = raw.target.seq;
+  if (typeof seq !== "number" || !Number.isInteger(seq) || seq < SEQ_MIN || seq > SEQ_MAX) {
+    return { ok: false, reason: `target.seq must be an integer from ${SEQ_MIN} to ${SEQ_MAX}` };
+  }
+  return { ok: true, requestId, kind, target: { messageRef, seq }, body: bodyResult.value };
+}
+function validateRedeemRequest(raw) {
+  if (!isRecord(raw))
+    return { ok: false };
+  const code = raw.code;
+  if (typeof code !== "string" || !PAIR_CODE_RE.test(code))
+    return { ok: false };
+  return { ok: true, code };
+}
+function capabilitiesResponse(flags) {
+  return {
+    dm: flags.dm,
+    targeted_post: flags.post,
+    cards: flags.post,
+    edit: flags.edit,
+    destinations: DESTINATIONS.map((d) => ({ destination: d.name, description: d.description }))
+  };
+}
+function wireTarget(target) {
+  if (isDmTarget(target))
+    return { user_id: target.userId };
+  if (isEditTarget(target))
+    return { message_ref: target.messageRef, seq: target.seq };
+  return { guild_id: target.guildId, destination: target.destination };
+}
+function toWireState(stored) {
+  const base = {
+    kind: stored.kind,
+    target: wireTarget(stored.target),
+    body: {
+      ...stored.body.content !== undefined ? { content: stored.body.content } : {},
+      ...stored.body.card !== undefined ? { card: stored.body.card } : {},
+      ...stored.body.links !== undefined ? { links: stored.body.links } : {}
+    },
+    created_at: stored.createdAt
+  };
+  switch (stored.state) {
+    case "pending":
+    case "unknown":
+      return { state: stored.state, ...base };
+    case "delivered":
+      return {
+        state: "delivered",
+        ...base,
+        message_ref: stored.messageRef,
+        url: stored.url,
+        ...stored.applied !== undefined ? { applied: stored.applied } : {}
+      };
+    case "failed":
+      return { state: "failed", ...base, code: stored.code };
+  }
+}
+function recipientsResponse(entries) {
+  const sorted = [...entries].sort((a, b) => a.registeredAt.localeCompare(b.registeredAt) || a.userId.localeCompare(b.userId));
+  return {
+    items: sorted.slice(0, RECIPIENTS_MAX).map((e) => ({ user_id: e.userId, display_name: e.displayName.slice(0, DISPLAY_NAME_MAX) }))
+  };
+}
+
+// plugins/mcp/src/drain.ts
+var RECIPIENT_UNREACHABLE_MESSAGE = "recipient cannot be messaged";
+function createEditQueue() {
+  const chains = new Map;
+  return {
+    run(key, fn) {
+      const prior = chains.get(key) ?? Promise.resolve();
+      const next = prior.then(fn, fn);
+      chains.set(key, next.catch(() => {}));
+      return next;
+    }
+  };
+}
+async function attemptEdit(deps, requestId, target, body) {
+  if (!isEditTarget(target)) {
+    return { state: "failed", code: "NOT_FOUND" };
+  }
+  const { messageRef, seq } = target;
+  return deps.editQueue.run(messageRef, async () => {
+    const original = await deps.store.get(messageRef);
+    if (original === undefined || original.state !== "delivered" || original.kind === "edit") {
+      return { state: "failed", code: "NOT_FOUND" };
+    }
+    const delivered = original;
+    if (typeof deps.host.edit !== "function" || delivered.delivery === null) {
+      return { state: "failed", code: "CAPABILITY_UNAVAILABLE" };
+    }
+    if (delivered.kind === "dm") {
+      const userId = isDmTarget(delivered.target) ? delivered.target.userId : undefined;
+      const generation = userId !== undefined ? await deps.registry.generationOf(userId) : undefined;
+      if (generation === undefined) {
+        return { state: "failed", code: "RECIPIENT_UNREACHABLE" };
+      }
+    }
+    if (seq < (delivered.lastEditSeq ?? 0)) {
+      return { state: "delivered", messageRef: delivered.messageRef, url: delivered.url, delivery: delivered.delivery, applied: false };
+    }
+    try {
+      await deps.host.edit(delivered.delivery, body);
+    } catch (err) {
+      deps.log.error(`edit ${requestId} (of ${messageRef}) failed`, err);
+      return { state: "failed", code: "UPSTREAM_UNAVAILABLE" };
+    }
+    await deps.store.recordEditSeq(messageRef, seq);
+    return { state: "delivered", messageRef: delivered.messageRef, url: delivered.url, delivery: delivered.delivery, applied: true };
+  });
+}
+async function attemptDm(deps, requestId, target, body) {
+  if (!isDmTarget(target)) {
+    return { state: "failed", code: "RECIPIENT_UNREACHABLE" };
+  }
+  const generation = await deps.registry.generationOf(target.userId);
+  if (generation === undefined) {
+    return { state: "failed", code: "RECIPIENT_UNREACHABLE" };
+  }
+  try {
+    const delivery = await deps.host.dm(target.userId, {
+      content: body.content ?? "",
+      ...body.card !== undefined ? { card: body.card } : {},
+      ...body.links !== undefined ? { links: body.links } : {}
+    });
+    const url = `https://discord.com/channels/@me/${delivery.channelId}/${delivery.messageId}`;
+    return { state: "delivered", messageRef: requestId, url, delivery };
+  } catch (err) {
+    if (err instanceof Error && err.message === RECIPIENT_UNREACHABLE_MESSAGE) {
+      return { state: "failed", code: "RECIPIENT_UNREACHABLE" };
+    }
+    deps.log.error(`delivery ${requestId} failed`, err);
+    return { state: "failed", code: "UPSTREAM_UNAVAILABLE" };
+  }
+}
+async function attemptDelivery(deps, requestId, entry) {
+  const { kind, target, body } = entry;
+  if (kind === "dm")
+    return attemptDm(deps, requestId, target, body);
+  if (kind === "edit")
+    return attemptEdit(deps, requestId, target, body);
+  if (!isPostTarget(target)) {
+    return { state: "failed", code: "CAPABILITY_UNAVAILABLE" };
+  }
+  const { host, log } = deps;
+  if (typeof host.post === "function") {
+    try {
+      const delivery = await host.post(target.guildId, target.destination, {
+        content: body.content ?? "",
+        ...body.card !== undefined ? { card: body.card } : {},
+        ...body.links !== undefined ? { links: body.links } : {}
+      });
+      const url = `https://discord.com/channels/${delivery.guildId ?? "@me"}/${delivery.channelId}/${delivery.messageId}`;
+      return { state: "delivered", messageRef: requestId, url, delivery };
+    } catch (err) {
+      log.error(`delivery ${requestId} failed`, err);
+      return { state: "failed", code: "UPSTREAM_UNAVAILABLE" };
+    }
+  }
+  if (body.card !== undefined || body.links !== undefined && body.links.length > 0) {
+    return { state: "failed", code: "CAPABILITY_UNAVAILABLE" };
+  }
+  try {
+    await host.announce(body.content ?? "", target.destination);
+    return { state: "delivered", messageRef: null, url: null, delivery: null };
+  } catch (err) {
+    log.error(`delivery ${requestId} failed`, err);
+    return { state: "failed", code: "UPSTREAM_UNAVAILABLE" };
+  }
+}
+function createDrainLock() {
+  const inFlight = new Map;
+  return {
+    tryStart(requestId) {
+      if (inFlight.has(requestId))
+        return false;
+      let resolve;
+      const promise = new Promise((res) => {
+        resolve = res;
+      });
+      inFlight.set(requestId, { promise, resolve });
+      return true;
+    },
+    finish(requestId) {
+      const entry = inFlight.get(requestId);
+      inFlight.delete(requestId);
+      entry?.resolve();
+    },
+    settled(requestId) {
+      return inFlight.get(requestId)?.promise ?? Promise.resolve();
+    }
+  };
+}
+async function drainAndPersist(deps, requestId, entry) {
+  const outcome = await attemptDelivery(deps, requestId, entry);
+  const next = outcome.state === "delivered" ? {
+    ...entry,
+    state: "delivered",
+    messageRef: outcome.messageRef,
+    url: outcome.url,
+    delivery: outcome.delivery,
+    ...outcome.applied !== undefined ? { applied: outcome.applied } : {}
+  } : { ...entry, state: "failed", code: outcome.code };
+  await deps.store.set(requestId, next);
+}
+
+// plugins/mcp/src/http.ts
+function json(status, body) {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+}
+async function startDrain(deps, requestId, entry) {
+  if (!deps.drainLock.tryStart(requestId))
+    return false;
+  try {
+    await deps.store.set(requestId, entry);
+  } catch (err) {
+    deps.log.error(`writing the initial state for delivery ${requestId} failed -- attempting delivery anyway`, err);
+  }
+  drainAndPersist(deps, requestId, entry).catch((err) => deps.log.error(`delivery ${requestId} failed to persist`, err)).finally(() => deps.drainLock.finish(requestId));
+  return true;
+}
+function hasCapability(deps, kind) {
+  if (kind === "post")
+    return true;
+  if (kind === "dm")
+    return typeof deps.host.dm === "function";
+  return typeof deps.host.edit === "function";
+}
+async function handleCreateDelivery(request, deps) {
+  const text = await request.text();
+  if (new TextEncoder().encode(text).length > MAX_BODY_BYTES)
+    return json(413, { error: "request body too large" });
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return json(400, { error: "request body must be valid JSON" });
+  }
+  const validated = validateCreateRequest(raw);
+  if (!validated.ok)
+    return json(400, { error: validated.reason });
+  const { requestId, kind, target, body } = validated;
+  if (!hasCapability(deps, kind)) {
+    const { value, existing } = await deps.store.reserve(requestId, kind, target, body, deps.now);
+    if (value.state === "pending" || value.state === "unknown") {
+      const failed = { state: "failed", kind, target, body, createdAt: value.createdAt, code: "CAPABILITY_UNAVAILABLE" };
+      await deps.store.set(requestId, failed);
+      return json(202, { state: toWireState(failed), existing });
+    }
+    return json(202, { state: toWireState(value), existing });
+  }
+  const { value, existing } = await deps.store.reserve(requestId, kind, target, body, deps.now);
+  if (!existing) {
+    await startDrain(deps, requestId, value);
+    return json(202, { state: toWireState(value), existing });
+  }
+  if (value.state === "delivered" || value.state === "pending") {
+    return json(202, { state: toWireState(value), existing });
+  }
+  const reset = {
+    state: "pending",
+    kind: value.kind,
+    target: value.target,
+    body: value.body,
+    createdAt: value.createdAt
+  };
+  const started = await startDrain(deps, requestId, reset);
+  return json(202, { state: toWireState(started ? reset : value), existing });
+}
+async function handleGetDelivery(requestId, deps) {
+  const value = await deps.store.get(requestId);
+  if (value === undefined)
+    return json(404, { error: "unknown request_id" });
+  return json(200, toWireState(value));
+}
+async function handleRedeemPair(request, deps) {
+  const text = await request.text();
+  if (new TextEncoder().encode(text).length > MAX_BODY_BYTES)
+    return json(413, { error: "request body too large" });
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return json(400, { error: "malformed request" });
+  }
+  const validated = validateRedeemRequest(raw);
+  if (!validated.ok)
+    return json(400, { error: "malformed request" });
+  const outcome = await deps.registry.redeem(validated.code, deps.now);
+  if (!outcome.ok) {
+    deps.log.warn("pair redeem: no matching unexpired code");
+    return json(404, { error: "invalid or expired code" });
+  }
+  deps.log.info(`pair redeem: succeeded for discord user ${outcome.discordUserId}`);
+  return json(200, { discord_user_id: outcome.discordUserId, generation: outcome.generation });
+}
+async function handleGetRegistration(userId, deps) {
+  const generation = await deps.registry.generationOf(userId);
+  if (generation === undefined)
+    return json(404, { error: "not registered" });
+  return json(200, { generation });
+}
+async function handleGetRecipients(deps) {
+  const entries = await deps.registry.listRecipients();
+  return json(200, recipientsResponse(entries));
+}
+var DELIVERY_ID_RE = /^\/deliveries\/([0-9a-f]{64})$/;
+var REGISTRATION_ID_RE = /^\/registration\/([1-9][0-9]{16,19})$/;
+async function handleMcpHttp(request, info, deps) {
+  if (deps.token === undefined)
+    return json(503, { error: "bridge not configured" });
+  const auth = checkAuth(request, info.clientIp, deps.token, deps.limiter, deps.now, deps.log);
+  if (!auth.ok)
+    return json(auth.status, { error: auth.status === 429 ? "too many failed attempts" : "unauthorized" });
+  if (info.path === "/capabilities") {
+    if (request.method !== "GET")
+      return json(405, { error: "method not allowed" });
+    return json(200, capabilitiesResponse({
+      post: typeof deps.host.post === "function",
+      dm: typeof deps.host.dm === "function",
+      edit: typeof deps.host.edit === "function"
+    }));
+  }
+  if (info.path === "/deliveries") {
+    if (request.method !== "POST")
+      return json(405, { error: "method not allowed" });
+    return handleCreateDelivery(request, deps);
+  }
+  const deliveryMatch = DELIVERY_ID_RE.exec(info.path);
+  if (deliveryMatch) {
+    if (request.method !== "GET")
+      return json(405, { error: "method not allowed" });
+    return handleGetDelivery(deliveryMatch[1], deps);
+  }
+  if (info.path === "/pair/redeem") {
+    if (request.method !== "POST")
+      return json(405, { error: "method not allowed" });
+    return handleRedeemPair(request, deps);
+  }
+  const registrationMatch = REGISTRATION_ID_RE.exec(info.path);
+  if (registrationMatch) {
+    if (request.method !== "GET")
+      return json(405, { error: "method not allowed" });
+    return handleGetRegistration(registrationMatch[1], deps);
+  }
+  if (info.path === "/recipients") {
+    if (request.method !== "GET")
+      return json(405, { error: "method not allowed" });
+    return handleGetRecipients(deps);
+  }
+  return json(404, { error: "not found" });
+}
+
+// plugins/mcp/src/registry.ts
+import { createHash as createHash2, randomBytes, randomInt } from "crypto";
+import { join } from "path";
+function freshRegistry() {
+  return { users: {} };
+}
+var MAX_CODES = 5;
+var CODE_TTL_MS = 10 * 60 * 1000;
+function generateGeneration() {
+  return randomBytes(16).toString("base64url");
+}
+var CODE_ALPHABET = "ABCDEFGHJKMNPQRSTVWXYZ23456789";
+var CODE_LENGTH = 27;
+function generateCode() {
+  let code = "";
+  for (let i = 0;i < CODE_LENGTH; i++)
+    code += CODE_ALPHABET[randomInt(CODE_ALPHABET.length)];
+  return code;
+}
+function hashCode(code) {
+  return createHash2("sha256").update(code).digest("hex");
+}
+function entryOf(registry, userId) {
+  return Object.hasOwn(registry.users, userId) ? registry.users[userId] : undefined;
+}
+function pruneRegistry(registry, now) {
+  let changed = false;
+  const users = {};
+  for (const userId of Object.keys(registry.users)) {
+    const entry = registry.users[userId];
+    const live = entry.codes.filter((c) => new Date(c.expiresAt).getTime() > now.getTime());
+    if (live.length !== entry.codes.length) {
+      changed = true;
+      users[userId] = { ...entry, codes: live };
+    } else {
+      users[userId] = entry;
+    }
+  }
+  return changed ? { ...registry, users } : registry;
+}
+function registerUser(registry, userId, displayName, now) {
+  const existing = entryOf(registry, userId);
+  if (existing !== undefined)
+    return { registry, outcome: { changed: false, generation: existing.generation } };
+  const entry = { generation: generateGeneration(), displayName, registeredAt: now.toISOString(), codes: [] };
+  return { registry: { ...registry, users: { ...registry.users, [userId]: entry } }, outcome: { changed: true, generation: entry.generation } };
+}
+function issueCode(registry, userId, displayName, now) {
+  const existing = entryOf(registry, userId);
+  if (existing === undefined)
+    return { registry, outcome: { ok: false } };
+  const code = generateCode();
+  const withNew = [...existing.codes, { hash: hashCode(code), expiresAt: new Date(now.getTime() + CODE_TTL_MS).toISOString() }];
+  const capped = withNew.length > MAX_CODES ? withNew.slice(withNew.length - MAX_CODES) : withNew;
+  const entry = { ...existing, displayName, codes: capped };
+  return { registry: { ...registry, users: { ...registry.users, [userId]: entry } }, outcome: { ok: true, code } };
+}
+function unregisterUser(registry, userId) {
+  if (!Object.hasOwn(registry.users, userId))
+    return { registry, changed: false };
+  const users = { ...registry.users };
+  delete users[userId];
+  return { registry: { ...registry, users }, changed: true };
+}
+function redeemCode(registry, code, now) {
+  const hash = hashCode(code);
+  for (const userId of Object.keys(registry.users)) {
+    const entry = registry.users[userId];
+    const idx = entry.codes.findIndex((c) => c.hash === hash);
+    if (idx === -1)
+      continue;
+    const codes = entry.codes.filter((_, i) => i !== idx);
+    const updated = { ...entry, codes };
+    return { registry: { ...registry, users: { ...registry.users, [userId]: updated } }, outcome: { ok: true, discordUserId: userId, generation: entry.generation } };
+  }
+  return { registry, outcome: { ok: false } };
+}
+function generationOf(registry, userId) {
+  return entryOf(registry, userId)?.generation;
+}
+function registryPath(dataDir) {
+  return join(dataDir, "mcp", "registry.json");
+}
+function createRegistryStore(dataDir, storage) {
+  const mutator = storage.createKeyedJsonMutator();
+  const path = registryPath(dataDir);
+  async function mutate(now, op) {
+    let result;
+    await mutator.update(path, freshRegistry, (current) => {
+      const pruned = pruneRegistry(current, now());
+      const outcome = op(pruned);
+      result = outcome.result;
+      return outcome.registry;
+    }, "mcp-registry");
+    return result;
+  }
+  return {
+    register: (userId, displayName, now) => mutate(now, (pruned) => {
+      const { registry, outcome } = registerUser(pruned, userId, displayName, now());
+      return { registry, result: outcome };
+    }),
+    pair: (userId, displayName, now) => mutate(now, (pruned) => {
+      const { registry, outcome } = issueCode(pruned, userId, displayName, now());
+      return { registry, result: outcome };
+    }),
+    unregister: (userId, now) => mutate(now, (pruned) => {
+      const { registry, changed } = unregisterUser(pruned, userId);
+      return { registry, result: { changed } };
+    }),
+    redeem: (code, now) => mutate(now, (pruned) => {
+      const { registry, outcome } = redeemCode(pruned, code, now());
+      return { registry, result: outcome };
+    }),
+    async generationOf(userId) {
+      const current = await storage.readJsonOrFresh(path, freshRegistry, "mcp-registry");
+      return generationOf(current, userId);
+    },
+    async listRecipients() {
+      const current = await storage.readJsonOrFresh(path, freshRegistry, "mcp-registry");
+      return Object.keys(current.users).map((userId) => {
+        const entry = current.users[userId];
+        return { userId, displayName: entry.displayName, registeredAt: entry.registeredAt };
+      });
+    }
+  };
+}
+
+// plugins/mcp/src/store.ts
+import { readdir, unlink } from "fs/promises";
+import { join as join2 } from "path";
+var NOOP_LOG = { info() {}, warn() {}, error() {} };
+
+class NoRecordForEditSeq extends Error {
+}
+var PRUNE_AFTER_MS = 8 * 24 * 60 * 60 * 1000;
+function deliveriesDir(dataDir) {
+  return join2(dataDir, "mcp", "deliveries");
+}
+function deliveryPath(dataDir, requestId) {
+  return join2(deliveriesDir(dataDir), `${requestId}.json`);
+}
+function createDeliveryStore(dataDir, storage, log = NOOP_LOG) {
+  const mutator = storage.createKeyedJsonMutator();
+  async function get(requestId) {
+    return storage.readJsonOrFresh(deliveryPath(dataDir, requestId), () => {
+      return;
+    }, "mcp-delivery");
+  }
+  async function set(requestId, value) {
+    await storage.writeJsonAtomic(deliveryPath(dataDir, requestId), value);
+  }
+  async function list() {
+    let names;
+    try {
+      names = await readdir(deliveriesDir(dataDir));
+    } catch (err) {
+      if (err.code === "ENOENT")
+        return [];
+      throw err;
+    }
+    return names.filter((n) => n.endsWith(".json")).map((n) => n.slice(0, -".json".length));
+  }
+  return {
+    async reserve(requestId, kind, target, body, now) {
+      let existing = false;
+      let result;
+      await mutator.update(deliveryPath(dataDir, requestId), () => null, (current) => {
+        if (current !== null) {
+          existing = true;
+          result = current;
+          return current;
+        }
+        existing = false;
+        result = { state: "pending", kind, target, body, createdAt: now().toISOString() };
+        return result;
+      }, "mcp-delivery");
+      return { value: result, existing };
+    },
+    set,
+    get,
+    list,
+    async markPendingUnknown() {
+      for (const requestId of await list()) {
+        try {
+          const current = await get(requestId);
+          if (current?.state === "pending")
+            await set(requestId, { ...current, state: "unknown" });
+        } catch (err) {
+          log.error(`marking delivery ${requestId} unknown after restart failed`, err);
+        }
+      }
+    },
+    async recordEditSeq(requestId, seq) {
+      try {
+        await mutator.update(deliveryPath(dataDir, requestId), () => {
+          throw new NoRecordForEditSeq;
+        }, (current) => current !== null && current.state === "delivered" ? { ...current, lastEditSeq: seq } : current, "mcp-delivery");
+      } catch (err) {
+        if (!(err instanceof NoRecordForEditSeq))
+          throw err;
+      }
+    },
+    async prune(now) {
+      const cutoff = now().getTime() - PRUNE_AFTER_MS;
+      const pruned = [];
+      for (const requestId of await list()) {
+        try {
+          const current = await get(requestId);
+          if (current !== undefined && new Date(current.createdAt).getTime() <= cutoff) {
+            await unlink(deliveryPath(dataDir, requestId));
+            pruned.push(requestId);
+          }
+        } catch (err) {
+          log.error(`pruning delivery ${requestId} failed`, err);
+        }
+      }
+      return pruned;
+    }
+  };
+}
+
+// plugins/mcp/src/index.ts
+function createPlugin(host) {
+  const store = createDeliveryStore(host.dataDir, host.storage, host.log);
+  const registry = createRegistryStore(host.dataDir, host.storage);
+  const limiter = createRateLimiter();
+  const drainLock = createDrainLock();
+  const editQueue = createEditQueue();
+  let disposed = false;
+  const httpDeps = {
+    host,
+    store,
+    registry,
+    editQueue,
+    token: host.env.MCP_BRIDGE_TOKEN,
+    limiter,
+    drainLock,
+    now: () => new Date,
+    log: host.log
+  };
+  return {
+    commands: [agentCommand(registry)],
+    async http(request, info) {
+      return handleMcpHttp(request, info, httpDeps);
+    },
+    ticks: [
+      {
+        name: "redrive",
+        async run(signal) {
+          for (const requestId of await store.list()) {
+            if (disposed || signal?.aborted === true)
+              return;
+            try {
+              const current = await store.get(requestId);
+              if (current === undefined || current.state !== "unknown")
+                continue;
+              if (!drainLock.tryStart(requestId))
+                continue;
+              try {
+                await drainAndPersist(httpDeps, requestId, current);
+              } finally {
+                drainLock.finish(requestId);
+              }
+            } catch (err) {
+              host.log.error(`redrive of delivery ${requestId} failed`, err);
+            }
+          }
+          if (disposed || signal?.aborted === true)
+            return;
+          const pruned = await store.prune(() => new Date);
+          if (pruned.length > 0)
+            host.log.info(`pruned ${pruned.length} deliveries older than 8 days`);
+        }
+      }
+    ],
+    async activate() {
+      await store.markPendingUnknown();
+    },
+    async dispose() {
+      disposed = true;
+    }
+  };
+}
+export {
+  createPlugin
+};

package/package.json

@@ -1,12 +1,36 @@
 {
   "name": "@rackbops/plugin-mcp",
-  "version": "0.0.0",
-  "description": "Placeholder that bootstraps npm trusted publishing. Real versions are published by CI from Rackbops/rackbops-bot-plugins.",
-  "license": "MIT",
+  "version": "0.3.1",
+  "description": "Bridge plugin for the Discord delivery MCP (Rackbops/discord-mcp): the service side of docs/bridge-protocol.md, plus /agent registration and pairing",
+  "type": "module",
+  "main": "dist/plugin.js",
+  "files": ["dist"],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Rackbops/rackbops-bot-plugins.git",
     "directory": "plugins/mcp"
   },
-  "files": ["README.md"]
+  "peerDependencies": {
+    "discord.js": "^14.27.0"
+  },
+  "botPlugin": {
+    "hostApiVersion": 1,
+    "intents": [],
+    "commands": ["agent"],
+    "env": [
+      {
+        "key": "MCP_BRIDGE_TOKEN",
+        "format": "^\\S{43,}$",
+        "required": false,
+        "secret": true,
+        "description": "Shared secret the Discord MCP service presents (>= 256 bits, base64url). Unset = the bridge answers 503."
+      }
+    ],
+    "destinations": [
+      { "name": "alerts", "description": "Time-sensitive findings and warnings" },
+      { "name": "deals", "description": "Notable deals or opportunities" },
+      { "name": "digest", "description": "Periodic summaries" },
+      { "name": "ops", "description": "Operational status and infrastructure notices" }
+    ]
+  }
 }