@scp-dev/mcp 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -13,10 +13,18 @@ interface RelayMcpOptions {
     input: AsyncIterable<Uint8Array | string> | ReadableStream<Uint8Array>;
     /** one JSON-RPC line, newline included */
     output: (line: string) => void;
+    /** whether the session is on the relay now: `dark` (why not) keeps the shim from claiming, `handle` is the name it joined under */
+    membership?: () => {
+        dark: string;
+    } | {
+        handle?: string;
+    };
     /** HOME shortens cwds in relay_list */
     env?: Record<string, string | undefined>;
-    /** push deliveries as `notifications/claude/channel` */
+    /** push deliveries as `notifications/claude/channel` to a client that declares `claude/channel` or was launched with channels */
     channels?: boolean;
+    /** the client was started with channels loaded (Claude Code does not declare the capability itself) */
+    launchedWithChannels?: boolean;
     version?: string;
     /** starts a worker for relay_spawn, resolving with its name and its runner's pid once its harness started; without it there is no relay_spawn */
     spawn?: (request: SpawnRequest) => Promise<{
@@ -96,6 +104,10 @@ declare const TOOLS: readonly [{
                 readonly type: "boolean";
                 readonly description: "only for recipients allowed private data";
             };
+            readonly live: {
+                readonly type: "boolean";
+                readonly description: "refuse (not_live) instead of queueing when a recipient has no live session";
+            };
         };
         readonly required: readonly ["to", "body"];
         readonly additionalProperties: false;
@@ -275,6 +287,27 @@ declare const TOOLS: readonly [{
         readonly required: readonly ["now"];
         readonly additionalProperties: false;
     };
+}, {
+    readonly name: "relay_join";
+    readonly description: "Put this session on the relay, so peers can message it and new messages reach you after your tool calls; name sets your handle once (renaming you in place when you already joined).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly name: {
+                readonly type: "string";
+                readonly maxLength: 63;
+            };
+        };
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "relay_leave";
+    readonly description: "Take this session off the relay: it goes offline and gets no new messages pushed; its mail is kept until relay_join.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
 }, {
     readonly name: "relay_set_title";
     readonly description: "Set your title, a short line on what you work on that every agent and your user see in relay_list and swarm list; an empty title clears it.";

package/dist/index.js

@@ -70,7 +70,8 @@ var TOOLS = [
         to: { oneOf: [{ type: "string" }, { type: "array", items: { type: "string" }, minItems: 1, maxItems: LIMITS.recipients }] },
         body: { type: "string" },
         thread: { type: "string", description: "continue this thread: its id, or the id or short id of a message in it" },
-        private: { type: "boolean", description: "only for recipients allowed private data" }
+        private: { type: "boolean", description: "only for recipients allowed private data" },
+        live: { type: "boolean", description: "refuse (not_live) instead of queueing when a recipient has no live session" }
       },
       required: ["to", "body"],
       additionalProperties: false
@@ -157,6 +158,16 @@ var TOOLS = [
     description: "Set your now, a one-line note on what you are doing right now, shown with your title in relay_list and relay_peers; your status state stays (working when unset).",
     inputSchema: { type: "object", properties: { now: { type: "string", maxLength: LIMITS.noteChars } }, required: ["now"], additionalProperties: false }
   },
+  {
+    name: "relay_join",
+    description: "Put this session on the relay, so peers can message it and new messages reach you after your tool calls; name sets your handle once (renaming you in place when you already joined).",
+    inputSchema: { type: "object", properties: { name: { type: "string", maxLength: 63 } }, additionalProperties: false }
+  },
+  {
+    name: "relay_leave",
+    description: "Take this session off the relay: it goes offline and gets no new messages pushed; its mail is kept until relay_join.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
   {
     name: "relay_set_title",
     description: `Set your title, a short line on what you work on that every agent and your user see in relay_list and ${CLI_NAME} list; an empty title clears it.`,
@@ -336,6 +347,7 @@ function isDirectory(path) {
     return false;
   }
 }
+var capped = (wait) => typeof wait === "number" && wait > LIMITS.waitMaxS;
 function seconds(args, fallback) {
   const value = args.wait_s;
   if (value === void 0) return fallback;
@@ -397,7 +409,13 @@ async function runRelayMcp(options) {
     sent.set(message.id, { from: message.from.address, thread: message.thread });
     while (sent.size > DELIVERED_KEEP) sent.delete(sent.keys().next().value);
   };
+  function sessionClaim() {
+    const joined = options.membership?.() ?? {};
+    if ("dark" in joined) throw new RelayError("unavailable", joined.dark);
+    return joined.handle ? { ...options.claim, handle: joined.handle } : options.claim;
+  }
   async function open() {
+    const claim = sessionClaim();
     const next = await options.connect();
     try {
       let hello;
@@ -408,7 +426,7 @@ async function runRelayMcp(options) {
           if (!(error instanceof RelayError)) throw error;
         }
       }
-      hello ??= await next.hello({ claim: options.claim, ...options.claim.cwd === void 0 ? {} : { cwd: options.claim.cwd } });
+      hello ??= await next.hello({ claim, ...claim.cwd === void 0 ? {} : { cwd: claim.cwd } });
       if (hello.token) token = hello.token;
       me = hello.endpoint;
       if (!announced) {
@@ -515,10 +533,11 @@ async function runRelayMcp(options) {
           body: str(args, "body", true),
           ...args.thread !== void 0 ? { thread: str(args, "thread") } : {},
           ...bool(args, "private") ? { data_class: "private" } : {},
+          ...bool(args, "live") ? { live: true } : {},
           client_id: clientId()
         });
         if (result.held) return text(heldText(result.held));
-        const lines = reachLines(result.deliveries);
+        const lines = [...reachLines(result.deliveries), ...result.warnings ?? []];
         const to = result.deliveries.map((d) => lines.length ? d.address : deliveryText(d)).join(", ");
         const receipt = result.deliveries.some((d) => d.state === "running" || d.state === "starting") ? [`relay_status with id ${shortId(result.id)} shows when it is read`] : [];
         return {
@@ -581,7 +600,7 @@ async function runRelayMcp(options) {
       case "relay_inbox": {
         const ack = bool(args, "ack") ?? true;
         const { messages } = await call("inbox", { wait_s: seconds(args, 0) });
-        if (!messages.length) return text("no unread messages");
+        if (!messages.length) return text(`no unread messages${capped(args.wait_s) ? `; waited ${LIMITS.waitMaxS} s (cap)` : ""}`);
         for (const message of messages) remember(message);
         if (ack) await call("ack", { seqs: messages.map((m) => m.seq) });
         return text(delivered(messages));
@@ -613,6 +632,27 @@ async function runRelayMcp(options) {
         const view = await call("status", { note: args.now });
         return text(`${view.address}: ${view.status?.state}${view.status?.note ? `: ${quote(view.status.note)}` : ""}`);
       }
+      case "relay_join": {
+        const name2 = str(args, "name");
+        const joined = options.membership?.() ?? {};
+        const claim = "handle" in joined && joined.handle ? { ...options.claim, handle: joined.handle } : options.claim;
+        const next = await options.connect();
+        try {
+          const hello = await next.hello({ transient: true, claim, join: name2 ? { handle: name2 } : {} });
+          me = hello.endpoint;
+        } finally {
+          next.close();
+        }
+        await ensure();
+        return text(`joined the relay as ${me?.address}: peers can message you, and new messages reach you after your tool calls`);
+      }
+      case "relay_leave": {
+        const view = await call("leave");
+        client?.close();
+        client = void 0;
+        token = void 0;
+        return text(`${view.address} left the relay: it shows offline and gets no new messages pushed; its mail is kept until relay_join`);
+      }
       case "relay_set_title": {
         if (typeof args.title !== "string") throw new ToolInputError("title must be a string");
         const view = await call("title", { text: args.title });
@@ -766,9 +806,8 @@ ${wrapMessage(message)}`,
         const protocolVersion = typeof asked === "string" && MCP_PROTOCOLS.includes(asked) ? asked : MCP_PROTOCOLS[0];
         initialized = true;
         const capabilities = params.capabilities;
-        const client2 = params.clientInfo;
         const channel = capabilities?.experimental?.["claude/channel"];
-        channelClient = typeof channel === "object" && channel !== null || client2?.name === "claude-code";
+        channelClient = typeof channel === "object" && channel !== null || options.launchedWithChannels === true;
         return respond({
           protocolVersion,
           capabilities: { tools: {}, ...options.channels ? { experimental: { "claude/channel": {} } } : {} },
@@ -807,7 +846,16 @@ ${wrapMessage(message)}`,
     inFlight.add(running);
     void running.finally(() => inFlight.delete(running));
   }
-  ensure().catch((error) => log(`${CLI_NAME} mcp: could not reach the relay broker yet: ${error instanceof Error ? error.message : String(error)}`));
+  const dark = (() => {
+    try {
+      sessionClaim();
+      return false;
+    } catch {
+      return true;
+    }
+  })();
+  if (!dark)
+    ensure().catch((error) => log(`${CLI_NAME} mcp: could not reach the relay broker yet: ${error instanceof Error ? error.message : String(error)}`));
   const heartbeat = setInterval(() => {
     call("whoami").catch(() => {
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "The SCP stdio MCP server: gives an agent session the relay's tools.",
   "license": "Apache-2.0",
   "homepage": "https://scp.dev",
@@ -29,8 +29,8 @@
     "typecheck": "tsc -p ."
   },
   "dependencies": {
-    "@scp-dev/broker": "0.1.1",
-    "@scp-dev/core": "0.1.1"
+    "@scp-dev/broker": "0.1.3",
+    "@scp-dev/core": "0.1.2"
   },
   "devDependencies": {
     "tsup": "^8.5.1"

package/src/server.ts

@@ -57,10 +57,14 @@ export interface RelayMcpOptions {
   input: AsyncIterable<Uint8Array | string> | ReadableStream<Uint8Array>
   /** one JSON-RPC line, newline included */
   output: (line: string) => void
+  /** whether the session is on the relay now: `dark` (why not) keeps the shim from claiming, `handle` is the name it joined under */
+  membership?: () => { dark: string } | { handle?: string }
   /** HOME shortens cwds in relay_list */
   env?: Record<string, string | undefined>
-  /** push deliveries as `notifications/claude/channel` */
+  /** push deliveries as `notifications/claude/channel` to a client that declares `claude/channel` or was launched with channels */
   channels?: boolean
+  /** the client was started with channels loaded (Claude Code does not declare the capability itself) */
+  launchedWithChannels?: boolean
   version?: string
   /** starts a worker for relay_spawn, resolving with its name and its runner's pid once its harness started; without it there is no relay_spawn */
   spawn?: (request: SpawnRequest) => Promise<{ name: string; pid: number }>
@@ -135,6 +139,7 @@ export const TOOLS = [
         body: { type: "string" },
         thread: { type: "string", description: "continue this thread: its id, or the id or short id of a message in it" },
         private: { type: "boolean", description: "only for recipients allowed private data" },
+        live: { type: "boolean", description: "refuse (not_live) instead of queueing when a recipient has no live session" },
       },
       required: ["to", "body"],
       additionalProperties: false,
@@ -224,6 +229,17 @@ export const TOOLS = [
       "Set your now, a one-line note on what you are doing right now, shown with your title in relay_list and relay_peers; your status state stays (working when unset).",
     inputSchema: { type: "object", properties: { now: { type: "string", maxLength: LIMITS.noteChars } }, required: ["now"], additionalProperties: false },
   },
+  {
+    name: "relay_join",
+    description:
+      "Put this session on the relay, so peers can message it and new messages reach you after your tool calls; name sets your handle once (renaming you in place when you already joined).",
+    inputSchema: { type: "object", properties: { name: { type: "string", maxLength: 63 } }, additionalProperties: false },
+  },
+  {
+    name: "relay_leave",
+    description: "Take this session off the relay: it goes offline and gets no new messages pushed; its mail is kept until relay_join.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
   {
     name: "relay_set_title",
     description: `Set your title, a short line on what you work on that every agent and your user see in relay_list and ${CLI_NAME} list; an empty title clears it.`,
@@ -443,6 +459,8 @@ function isDirectory(path: string): boolean {
   }
 }
 
+const capped = (wait: unknown): boolean => typeof wait === "number" && wait > LIMITS.waitMaxS
+
 function seconds(args: Json, fallback: number): number {
   const value = args.wait_s
   if (value === undefined) return fallback
@@ -502,7 +520,7 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
   let me: EndpointView | null = null
   let announced = false
   let initialized = false
-  /** whether the client takes channel notifications: it says so, or it is Claude Code, which takes them without saying so when started with channels */
+  /** whether the client takes channel notifications: it says so, or it was launched with channels (Claude Code does not say so itself) */
   let channelClient = false
   let stopped = false
   /** seqs this shim pushed, so a push whose confirm was lost is not pushed again */
@@ -519,7 +537,15 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
     while (sent.size > DELIVERED_KEEP) sent.delete(sent.keys().next().value!)
   }
 
+  /** the claim for the session as it stands; a session off the relay is refused `unavailable` */
+  function sessionClaim(): Claim {
+    const joined = options.membership?.() ?? {}
+    if ("dark" in joined) throw new RelayError("unavailable", joined.dark)
+    return joined.handle ? { ...options.claim, handle: joined.handle } : options.claim
+  }
+
   async function open(): Promise<RelayClient> {
+    const claim = sessionClaim()
     const next = await options.connect()
     try {
       let hello: HelloResult | undefined
@@ -530,7 +556,7 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
           if (!(error instanceof RelayError)) throw error
         }
       }
-      hello ??= await next.hello({ claim: options.claim, ...(options.claim.cwd === undefined ? {} : { cwd: options.claim.cwd }) })
+      hello ??= await next.hello({ claim, ...(claim.cwd === undefined ? {} : { cwd: claim.cwd }) })
       if (hello.token) token = hello.token
       me = hello.endpoint
       if (!announced) {
@@ -649,10 +675,11 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
           body: str(args, "body", true),
           ...(args.thread !== undefined ? { thread: str(args, "thread") } : {}),
           ...(bool(args, "private") ? { data_class: "private" } : {}),
+          ...(bool(args, "live") ? { live: true } : {}),
           client_id: clientId(),
         })
         if (result.held) return text(heldText(result.held))
-        const lines = reachLines(result.deliveries)
+        const lines = [...reachLines(result.deliveries), ...(result.warnings ?? [])]
         const to = result.deliveries.map((d) => (lines.length ? d.address : deliveryText(d))).join(", ")
         const receipt = result.deliveries.some((d) => d.state === "running" || d.state === "starting")
           ? [`relay_status with id ${shortId(result.id)} shows when it is read`]
@@ -717,7 +744,7 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
       case "relay_inbox": {
         const ack = bool(args, "ack") ?? true
         const { messages } = await call<{ messages: Envelope[] }>("inbox", { wait_s: seconds(args, 0) })
-        if (!messages.length) return text("no unread messages")
+        if (!messages.length) return text(`no unread messages${capped(args.wait_s) ? `; waited ${LIMITS.waitMaxS} s (cap)` : ""}`)
         for (const message of messages) remember(message)
         if (ack) await call("ack", { seqs: messages.map((m) => m.seq) })
         return text(delivered(messages))
@@ -748,6 +775,27 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
         const view = await call<EndpointView>("status", { note: args.now })
         return text(`${view.address}: ${view.status?.state}${view.status?.note ? `: ${quote(view.status.note)}` : ""}`)
       }
+      case "relay_join": {
+        const name = str(args, "name")
+        const joined = options.membership?.() ?? {}
+        const claim = "handle" in joined && joined.handle ? { ...options.claim, handle: joined.handle } : options.claim
+        const next = await options.connect()
+        try {
+          const hello = await next.hello({ transient: true, claim, join: name ? { handle: name } : {} })
+          me = hello.endpoint
+        } finally {
+          next.close()
+        }
+        await ensure()
+        return text(`joined the relay as ${me?.address}: peers can message you, and new messages reach you after your tool calls`)
+      }
+      case "relay_leave": {
+        const view = await call<EndpointView>("leave")
+        client?.close()
+        client = undefined
+        token = undefined
+        return text(`${view.address} left the relay: it shows offline and gets no new messages pushed; its mail is kept until relay_join`)
+      }
       case "relay_set_title": {
         if (typeof args.title !== "string") throw new ToolInputError("title must be a string")
         const view = await call<EndpointView>("title", { text: args.title })
@@ -903,9 +951,8 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
         const protocolVersion = typeof asked === "string" && (MCP_PROTOCOLS as readonly string[]).includes(asked) ? asked : MCP_PROTOCOLS[0]
         initialized = true
         const capabilities = params.capabilities as { experimental?: Record<string, unknown> } | undefined
-        const client = params.clientInfo as { name?: unknown } | undefined
         const channel = capabilities?.experimental?.["claude/channel"]
-        channelClient = (typeof channel === "object" && channel !== null) || client?.name === "claude-code"
+        channelClient = (typeof channel === "object" && channel !== null) || options.launchedWithChannels === true
         return respond({
           protocolVersion,
           capabilities: { tools: {}, ...(options.channels ? { experimental: { "claude/channel": {} } } : {}) },
@@ -946,7 +993,16 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
     void running.finally(() => inFlight.delete(running))
   }
 
-  ensure().catch((error: unknown) => log(`${CLI_NAME} mcp: could not reach the relay broker yet: ${error instanceof Error ? error.message : String(error)}`))
+  const dark = (() => {
+    try {
+      sessionClaim()
+      return false
+    } catch {
+      return true
+    }
+  })()
+  if (!dark)
+    ensure().catch((error: unknown) => log(`${CLI_NAME} mcp: could not reach the relay broker yet: ${error instanceof Error ? error.message : String(error)}`))
   const heartbeat = setInterval(() => {
     call("whoami").catch(() => {})
   }, options.heartbeatMs ?? 30_000)