@scp-dev/mcp 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _scp_dev_core from '@scp-dev/core';
-import { Claim } from '@scp-dev/core';
+import { Claim, Wake } from '@scp-dev/core';
 import { RelayClient } from '@scp-dev/broker';
 
 declare const MCP_PROTOCOLS: readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
@@ -25,6 +25,8 @@ interface RelayMcpOptions {
     channels?: boolean;
     /** the client was started with channels loaded (Claude Code does not declare the capability itself) */
     launchedWithChannels?: boolean;
+    /** the wake the endpoint advertises while this shim pushes by channel, over `pi` for a pi client and `channels` for any other */
+    wake?: Wake;
     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<{
@@ -289,7 +291,7 @@ declare const TOOLS: readonly [{
     };
 }, {
     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 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: {
@@ -297,6 +299,10 @@ declare const TOOLS: readonly [{
                 readonly type: "string";
                 readonly maxLength: 63;
             };
+            readonly under: {
+                readonly type: "string";
+                readonly maxLength: 128;
+            };
         };
         readonly additionalProperties: false;
     };

package/dist/index.js

@@ -7,6 +7,7 @@ import {
   deliveryText,
   LIMITS,
   PREAMBLE,
+  presenceText,
   reachLines,
   receiptLines,
   RelayError,
@@ -160,8 +161,12 @@ var TOOLS = [
   },
   {
     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 }
+    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",
@@ -274,7 +279,11 @@ function heldText(held) {
   return `held for review by your human: hold ${held.hold_id}; nothing was delivered`;
 }
 function sentContent(result) {
-  return { id: result.id, thread: result.thread, recipients: result.deliveries.map((d) => ({ address: d.address, ...d.state ? { state: d.state } : {} })) };
+  return {
+    id: result.id,
+    thread: result.thread,
+    recipients: result.deliveries.map((d) => ({ address: d.address, ...d.state ? { state: d.state } : {}, ...d.wake ? { wake: d.wake } : {} }))
+  };
 }
 function redactedText(redacted) {
   return redacted ? `; redacted ${redacted.n} span${redacted.n === 1 ? "" : "s"} (${redacted.kinds.join(", ")}) before delivery` : "";
@@ -400,6 +409,8 @@ async function runRelayMcp(options) {
   let stopped = false;
   const channelPushed = /* @__PURE__ */ new Set();
   let channelLoop;
+  let wake;
+  let advertised;
   const write = (message) => {
     if (!stopped) options.output(`${JSON.stringify(message)}
 `);
@@ -442,8 +453,17 @@ async function runRelayMcp(options) {
       throw new Error("the relay MCP shim is stopping");
     }
     client = next;
+    advertise();
     return next;
   }
+  function advertise() {
+    if (!client || wake === void 0) return;
+    const via = wake ?? "none";
+    if (advertised?.client === client && advertised.via === via || via === "none" && !advertised) return;
+    advertised = { client, via };
+    client.request("wake", { via }).catch(() => {
+    });
+  }
   function ensure() {
     if (client) return Promise.resolve(client);
     connecting ??= open().finally(() => connecting = void 0);
@@ -469,7 +489,7 @@ async function runRelayMcp(options) {
     return [
       `${e.address}${me && e.id === me.id ? " (you)" : ""}`,
       e.harness ?? e.kind,
-      e.presence,
+      presenceText(e),
       e.title ? `title ${quote(e.title)}` : "",
       status,
       cwd ? quote(cwd) : "",
@@ -634,17 +654,20 @@ async function runRelayMcp(options) {
       }
       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 } : {} });
+          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}: peers can message you, and new messages reach you after your tool calls`);
+        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");
@@ -808,6 +831,9 @@ ${wrapMessage(message)}`,
         const capabilities = params.capabilities;
         const channel = capabilities?.experimental?.["claude/channel"];
         channelClient = typeof channel === "object" && channel !== null || options.launchedWithChannels === true;
+        const clientInfo = params.clientInfo;
+        wake = options.channels && channelClient ? options.wake ?? (clientInfo?.name === "pi" ? "pi" : "channels") : null;
+        advertise();
         return respond({
           protocolVersion,
           capabilities: { tools: {}, ...options.channels ? { experimental: { "claude/channel": {} } } : {} },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/mcp",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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.3",
-    "@scp-dev/core": "0.1.2"
+    "@scp-dev/broker": "0.1.5",
+    "@scp-dev/core": "0.1.4"
   },
   "devDependencies": {
     "tsup": "^8.5.1"

package/src/server.ts

@@ -18,6 +18,7 @@ import {
   type SendResult,
   type PeerView,
   PREAMBLE,
+  presenceText,
   reachLines,
   receiptLines,
   RelayError,
@@ -26,6 +27,7 @@ import {
   shortId,
   STATUS_STATES,
   type ThreadMessage,
+  type Wake,
   type WhyResult,
   widenText,
   wrapMessage,
@@ -65,6 +67,8 @@ export interface RelayMcpOptions {
   channels?: boolean
   /** the client was started with channels loaded (Claude Code does not declare the capability itself) */
   launchedWithChannels?: boolean
+  /** the wake the endpoint advertises while this shim pushes by channel, over `pi` for a pi client and `channels` for any other */
+  wake?: Wake
   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 }>
@@ -232,8 +236,12 @@ export const TOOLS = [
   {
     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 },
+      "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",
@@ -362,7 +370,11 @@ function heldText(held: JudgeHeld): string {
 
 /** a send's id, thread and recipients with their states, for a result's structuredContent */
 function sentContent(result: SendResult): Record<string, unknown> {
-  return { id: result.id, thread: result.thread, recipients: result.deliveries.map((d) => ({ address: d.address, ...(d.state ? { state: d.state } : {}) })) }
+  return {
+    id: result.id,
+    thread: result.thread,
+    recipients: result.deliveries.map((d) => ({ address: d.address, ...(d.state ? { state: d.state } : {}), ...(d.wake ? { wake: d.wake } : {}) })),
+  }
 }
 
 function redactedText(redacted: JudgeRedacted | undefined): string {
@@ -526,6 +538,9 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
   /** seqs this shim pushed, so a push whose confirm was lost is not pushed again */
   const channelPushed = new Set<number>()
   let channelLoop: Promise<void> | undefined
+  /** what the endpoint advertises once initialize said whether the client takes channel pushes; null advertises nothing */
+  let wake: Wake | null | undefined
+  let advertised: { client: RelayClient; via: Wake } | undefined
 
   const write = (message: Json) => {
     if (!stopped) options.output(`${JSON.stringify(message)}\n`)
@@ -572,9 +587,19 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
       throw new Error("the relay MCP shim is stopping")
     }
     client = next
+    advertise()
     return next
   }
 
+  /** tells the broker how a message wakes this session, once per connection and value, when both it and the client's capabilities are known */
+  function advertise() {
+    if (!client || wake === undefined) return
+    const via = wake ?? "none"
+    if ((advertised?.client === client && advertised.via === via) || (via === "none" && !advertised)) return
+    advertised = { client, via }
+    client.request("wake", { via }).catch(() => {})
+  }
+
   function ensure(): Promise<RelayClient> {
     if (client) return Promise.resolve(client)
     connecting ??= open().finally(() => (connecting = undefined))
@@ -604,7 +629,7 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
     return [
       `${e.address}${me && e.id === me.id ? " (you)" : ""}`,
       e.harness ?? e.kind,
-      e.presence,
+      presenceText(e),
       e.title ? `title ${quote(e.title)}` : "",
       status,
       cwd ? quote(cwd) : "",
@@ -777,17 +802,20 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
       }
       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 } : {} })
+          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}: peers can message you, and new messages reach you after your tool calls`)
+        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")
@@ -953,6 +981,9 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
         const capabilities = params.capabilities as { experimental?: Record<string, unknown> } | undefined
         const channel = capabilities?.experimental?.["claude/channel"]
         channelClient = (typeof channel === "object" && channel !== null) || options.launchedWithChannels === true
+        const clientInfo = params.clientInfo as { name?: unknown } | undefined
+        wake = options.channels && channelClient ? (options.wake ?? (clientInfo?.name === "pi" ? "pi" : "channels")) : null
+        advertise()
         return respond({
           protocolVersion,
           capabilities: { tools: {}, ...(options.channels ? { experimental: { "claude/channel": {} } } : {}) },