@scp-dev/mcp 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -13,6 +13,12 @@ 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` to a client that declares `claude/channel` or was launched with channels */
@@ -98,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;
@@ -277,6 +287,31 @@ 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); under links you below that agent, as if it had spawned you: you show as its child and reach only what a worker of it reaches.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly name: {
+                readonly type: "string";
+                readonly maxLength: 63;
+            };
+            readonly under: {
+                readonly type: "string";
+                readonly maxLength: 128;
+            };
+        };
+        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,20 @@ 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); under links you below that agent, as if it had spawned you: you show as its child and reach only what a worker of it reaches.",
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string", maxLength: 63 }, under: { type: "string", maxLength: 128 } },
+      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.`,
@@ -398,7 +413,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;
@@ -409,7 +430,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) {
@@ -516,10 +537,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 {
@@ -614,6 +636,30 @@ 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 under = str(args, "under");
+        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 } : {}, ...under ? { under } : {} } });
+          me = hello.endpoint;
+        } finally {
+          next.close();
+        }
+        await ensure();
+        return text(
+          `joined the relay as ${me?.address}${me?.parent ? ` under ${me.parent}` : ""}: 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 });
@@ -807,7 +853,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.2",
+  "version": "0.1.4",
   "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.2",
-    "@scp-dev/core": "0.1.1"
+    "@scp-dev/broker": "0.1.4",
+    "@scp-dev/core": "0.1.3"
   },
   "devDependencies": {
     "tsup": "^8.5.1"

package/src/server.ts

@@ -57,6 +57,8 @@ 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` to a client that declares `claude/channel` or was launched with channels */
@@ -137,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,
@@ -226,6 +229,21 @@ 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); under links you below that agent, as if it had spawned you: you show as its child and reach only what a worker of it reaches.",
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string", maxLength: 63 }, under: { type: "string", maxLength: 128 } },
+      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.`,
@@ -523,7 +541,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
@@ -534,7 +560,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) {
@@ -653,10 +679,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`]
@@ -752,6 +779,30 @@ 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 under = str(args, "under")
+        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 } : {}), ...(under ? { under } : {}) } })
+          me = hello.endpoint
+        } finally {
+          next.close()
+        }
+        await ensure()
+        return text(
+          `joined the relay as ${me?.address}${me?.parent ? ` under ${me.parent}` : ""}: 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 })
@@ -949,7 +1000,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)