@intangle/mcp-server 2.6.18 → 2.6.20

package/README.md

@@ -51,6 +51,42 @@ Standard MCP (Claude desktop, Cursor): by adding to your `claude_desktop_config.
 
 3. **Restart Claude Desktop** to load the MCP server
 
+## Claude Code live Tan channel (opt-in preview)
+
+The MCP server can forward new Tan-addressed messages from one explicitly bound
+Intangle Room into an already-running Claude Code session and send replies back
+through `intangle_channel_reply`. It does not attach to a session that was
+started before the channel was enabled, and it does not replay older messages.
+
+This custom channel requires Node.js 21 or later. The standard Intangle MCP
+tools continue to support Node.js 18. Claude Code currently treats custom
+channels as development channels; its channels feature is a research preview.
+
+Configure the Intangle MCP server with the exact Space, conversation, and
+participant IDs to receive Tan's addressed messages:
+
+```bash
+claude mcp add intangle -s user \
+  --env MCP_API_KEY=<your-intangle-api-key> \
+  --env NEXT_APP_URL=https://renvoi.co/intangle \
+  --env INTANGLE_CLAUDE_CHANNEL_ENABLED=1 \
+  --env INTANGLE_CLAUDE_CHANNEL_SPACE_ID=<space-id> \
+  --env INTANGLE_CLAUDE_CHANNEL_CONVERSATION_ID=<conversation-id> \
+  --env INTANGLE_CLAUDE_CHANNEL_PARTICIPANT_ID=<agent-participant-id> \
+  -- npx -y @intangle/mcp-server
+```
+
+Then start a new Claude Code session with the custom channel explicitly enabled:
+
+```bash
+claude --dangerously-load-development-channels server:intangle
+```
+
+Claude Code shows a development-channel warning and may ask you to trust the
+MCP server. Messages arrive only while that session is open. Remove the three
+`INTANGLE_CLAUDE_CHANNEL_*` scope values or omit the enabled flag to return to
+ordinary MCP-only behavior.
+
 ## Usage
 
 Once configured, Claude will automatically have access to your Intangle context. You can:

package/dist/claude-channel.js

@@ -0,0 +1,359 @@
+export const CLAUDE_CHANNEL_REPLY_TOOL = "intangle_channel_reply";
+export const CLAUDE_CHANNEL_ENABLED_ENV = "INTANGLE_CLAUDE_CHANNEL_ENABLED";
+export const CLAUDE_CHANNEL_RUNTIME_ERROR = "Intangle Claude channels require Node.js 21 or later for the built-in WebSocket API; standard MCP tools still support Node.js 18.";
+const CHANNEL_RECONNECT_SECONDS = 25;
+const REPLAY_OVERLAP_MS = 5_000;
+export function claudeChannelConfigFromEnv(env) {
+    if (env[CLAUDE_CHANNEL_ENABLED_ENV] !== "1")
+        return null;
+    const spaceId = nonblank(env.INTANGLE_CLAUDE_CHANNEL_SPACE_ID);
+    const conversationId = nonblank(env.INTANGLE_CLAUDE_CHANNEL_CONVERSATION_ID);
+    const participantId = nonblank(env.INTANGLE_CLAUDE_CHANNEL_PARTICIPANT_ID);
+    if (!spaceId || !conversationId || !participantId) {
+        throw new Error(`${CLAUDE_CHANNEL_ENABLED_ENV}=1 requires explicit Space, conversation, and participant IDs`);
+    }
+    return {
+        spaceId,
+        conversationId,
+        participantId,
+        participantLabel: nonblank(env.INTANGLE_CLAUDE_CHANNEL_PARTICIPANT_LABEL) || "Claude Code",
+        participantType: nonblank(env.INTANGLE_CLAUDE_CHANNEL_PARTICIPANT_TYPE) || "agent",
+        organizationId: nonblank(env.INTANGLE_CLAUDE_CHANNEL_ORGANIZATION_ID),
+    };
+}
+export function claudeChannelToolDefinition() {
+    return {
+        name: CLAUDE_CHANNEL_REPLY_TOOL,
+        title: "Reply to Tan in this Intangle Room",
+        description: "Send a reply to Tan in the explicitly configured Intangle conversation. The Space and conversation are fixed by the channel configuration.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                content: { type: "string", minLength: 1 },
+            },
+            required: ["content"],
+        },
+        annotations: { openWorldHint: true },
+    };
+}
+export async function sendClaudeChannelReply(config, content, sendReply, createTurnId) {
+    const normalized = nonblank(content);
+    if (!normalized)
+        throw new Error("content is required");
+    return sendReply({
+        space_id: config.spaceId,
+        conversation_id: config.conversationId,
+        content: normalized,
+        participant_id: config.participantId,
+        participant_type: config.participantType,
+        participant_label: config.participantLabel,
+        ...(config.organizationId
+            ? { organization_id: config.organizationId }
+            : {}),
+        client_turn_id: createTurnId(),
+    });
+}
+export class ClaudeChannelBridge {
+    options;
+    cursor = null;
+    initialCursor = null;
+    baselineLoaded = false;
+    socket = null;
+    reconnectTimer = null;
+    stopped = false;
+    connecting = false;
+    messageQueue = Promise.resolve();
+    delivered = new Map();
+    createSocket;
+    schedule;
+    report;
+    constructor(options) {
+        this.options = options;
+        this.createSocket =
+            options.createSocket ||
+                ((url) => new WebSocket(url));
+        this.schedule =
+            options.schedule || ((callback, delayMs) => setTimeout(callback, delayMs));
+        this.report =
+            options.report ||
+                ((status, detail) => {
+                    const suffix = detail ? `: ${detail}` : "";
+                    console.error(`[Intangle Claude channel] ${status}${suffix}`);
+                });
+    }
+    async start() {
+        if (!this.options.createSocket &&
+            typeof globalThis.WebSocket !== "function") {
+            throw new Error(CLAUDE_CHANNEL_RUNTIME_ERROR);
+        }
+        await this.connect();
+    }
+    stop() {
+        this.stopped = true;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+        this.socket?.close();
+        this.socket = null;
+    }
+    async connect() {
+        if (this.stopped || this.connecting)
+            return;
+        this.connecting = true;
+        try {
+            if (!this.baselineLoaded)
+                await this.loadBaseline();
+            if (this.stopped)
+                return;
+            const bootstrap = await this.fetchBootstrap();
+            if (this.stopped)
+                return;
+            const socketUrl = new URL(bootstrap.watch_url);
+            if (this.cursor !== null) {
+                socketUrl.searchParams.set("since", String(Math.max(0, this.cursor - REPLAY_OVERLAP_MS)));
+            }
+            const socket = this.createSocket(socketUrl.toString());
+            this.socket = socket;
+            socket.addEventListener("open", () => {
+                if (this.socket === socket) {
+                    this.report("watch_connected", this.options.config.conversationId);
+                }
+            });
+            socket.addEventListener("message", (event) => {
+                this.messageQueue = this.messageQueue
+                    .then(() => this.handleFrame(event.data))
+                    .catch((error) => {
+                    this.report("channel_notification_failed", errorText(error));
+                    socket.close();
+                });
+            });
+            socket.addEventListener("error", (event) => {
+                this.report("watch_connection_error", errorText(event));
+            });
+            socket.addEventListener("close", () => {
+                if (this.socket === socket)
+                    this.socket = null;
+                if (!this.stopped) {
+                    this.report("watch_disconnected", "reconnecting");
+                    this.scheduleReconnect(bootstrap.watch_keepalive_seconds);
+                }
+            });
+        }
+        catch (error) {
+            this.report("watch_start_failed", errorText(error));
+            this.scheduleReconnect(CHANNEL_RECONNECT_SECONDS);
+        }
+        finally {
+            this.connecting = false;
+        }
+    }
+    async loadBaseline() {
+        const result = asRecord(await this.options.api.fetchMessages({
+            space_id: this.options.config.spaceId,
+            conversation_id: this.options.config.conversationId,
+            ...(this.options.config.organizationId
+                ? { organization_id: this.options.config.organizationId }
+                : {}),
+            limit: 1,
+        }));
+        if (result?.success !== true ||
+            result.conversation_id !== this.options.config.conversationId ||
+            !Array.isArray(result.messages)) {
+            throw new Error("Conversation baseline fetch failed");
+        }
+        this.cursor = result.messages.reduce((latest, value) => {
+            const message = asRecord(value);
+            const durableTimestamp = message?.durable_timestamp;
+            if (typeof durableTimestamp !== "number" ||
+                !Number.isFinite(durableTimestamp)) {
+                return latest;
+            }
+            return latest === null
+                ? durableTimestamp
+                : Math.max(latest, durableTimestamp);
+        }, null);
+        this.initialCursor = this.cursor;
+        this.baselineLoaded = true;
+    }
+    async fetchBootstrap() {
+        const result = asRecord(await this.options.api.subscribe({
+            space_id: this.options.config.spaceId,
+            conversation_id: this.options.config.conversationId,
+            participant_id: this.options.config.participantId,
+            participant_type: this.options.config.participantType,
+            participant_label: this.options.config.participantLabel,
+            ...(this.options.config.organizationId
+                ? { organization_id: this.options.config.organizationId }
+                : {}),
+            mark_read: false,
+            include_watch: true,
+        }));
+        if (result?.success !== true ||
+            result.conversation_id !== this.options.config.conversationId ||
+            typeof result.watch_url !== "string" ||
+            typeof result.watch_expires_in_seconds !== "number" ||
+            typeof result.watch_keepalive_seconds !== "number" ||
+            typeof result.watch_max_lifetime_seconds !== "number" ||
+            !isWatchCursor(result.watch_cursor)) {
+            throw new Error("Conversation subscription omitted its watch bootstrap");
+        }
+        return result;
+    }
+    async handleFrame(raw) {
+        const text = typeof raw === "string" ? raw : String(raw);
+        let frame;
+        try {
+            frame = JSON.parse(text);
+        }
+        catch {
+            this.report("watch_frame_invalid", "ignored non-JSON frame");
+            return;
+        }
+        if (frame.type !== "message" ||
+            frame.space_id !== this.options.config.spaceId ||
+            frame.conversation_id !== this.options.config.conversationId ||
+            typeof frame.message_id !== "string" ||
+            typeof frame.durable_timestamp !== "number" ||
+            frame.transient === true ||
+            frame.role !== "assistant" ||
+            frame.source !== "tan_agent_message" ||
+            frame.recipient_id !== this.options.config.participantId ||
+            typeof frame.content !== "string") {
+            return;
+        }
+        if (this.initialCursor !== null &&
+            frame.durable_timestamp <= this.initialCursor) {
+            return;
+        }
+        const messageId = frame.message_id;
+        const content = frame.content;
+        const notificationContent = await this.resolveNotificationContent({
+            message_id: messageId,
+            content,
+            content_truncated: frame.content_truncated,
+        });
+        const fingerprint = notificationContent.content;
+        const previous = this.delivered.get(frame.message_id);
+        if (previous?.cursor === frame.durable_timestamp &&
+            previous.fingerprint === fingerprint)
+            return;
+        await this.options.sink.notification({
+            method: "notifications/claude/channel",
+            params: {
+                content: notificationContent.content,
+                meta: {
+                    conversation_id: this.options.config.conversationId,
+                    message_id: frame.message_id,
+                    sender: "Tan",
+                    recipient_id: this.options.config.participantId,
+                    ...(notificationContent.truncated
+                        ? {
+                            content_truncated: "true",
+                            delivery: "full_message_unavailable",
+                        }
+                        : {}),
+                },
+            },
+        });
+        this.delivered.set(frame.message_id, {
+            cursor: frame.durable_timestamp,
+            fingerprint,
+        });
+        this.cursor =
+            this.cursor === null
+                ? frame.durable_timestamp
+                : Math.max(this.cursor, frame.durable_timestamp);
+        const cutoff = Math.max(0, this.cursor - REPLAY_OVERLAP_MS);
+        for (const [messageId, projection] of this.delivered) {
+            if (projection.cursor < cutoff)
+                this.delivered.delete(messageId);
+        }
+        // MCP notifications have no consumer acknowledgement. This is transport
+        // write evidence only, never a claim that Claude processed the event.
+        this.report("notification_write_completed_unacknowledged", frame.message_id);
+    }
+    async resolveNotificationContent(frame) {
+        if (frame.content_truncated !== true) {
+            return { content: frame.content, truncated: false };
+        }
+        let result;
+        try {
+            result = asRecord(await this.options.api.fetchMessages({
+                space_id: this.options.config.spaceId,
+                conversation_id: this.options.config.conversationId,
+                ...(this.options.config.organizationId
+                    ? { organization_id: this.options.config.organizationId }
+                    : {}),
+                limit: 200,
+            }));
+        }
+        catch (error) {
+            this.report("message_content_fetch_failed", errorText(error));
+            return this.truncatedMessageWarning(frame.message_id);
+        }
+        const fullMessage = result?.success === true &&
+            result.conversation_id === this.options.config.conversationId &&
+            Array.isArray(result.messages)
+            ? result.messages.find((message) => asRecord(message)?.id === frame.message_id)
+            : undefined;
+        const fullRecord = asRecord(fullMessage);
+        const fullContent = fullRecord ? messageText(fullRecord) : undefined;
+        if (typeof fullContent === "string" &&
+            fullContent.length > frame.content.length) {
+            return { content: fullContent, truncated: false };
+        }
+        return this.truncatedMessageWarning(frame.message_id);
+    }
+    truncatedMessageWarning(messageId) {
+        this.report("message_content_unavailable", messageId);
+        return {
+            content: `Tan's message ${messageId} exceeded the live channel limit, and its full text could not be retrieved. Do not act on partial text. Ask Tan to resend the message in a shorter form.`,
+            truncated: true,
+        };
+    }
+    scheduleReconnect(seconds) {
+        if (this.stopped || this.reconnectTimer)
+            return;
+        const delaySeconds = Number.isFinite(seconds) && seconds > 0
+            ? seconds
+            : CHANNEL_RECONNECT_SECONDS;
+        this.reconnectTimer = this.schedule(() => {
+            this.reconnectTimer = null;
+            void this.connect();
+        }, delaySeconds * 1_000);
+    }
+}
+function isWatchCursor(value) {
+    const cursor = asRecord(value);
+    return (cursor?.parameter === "since" &&
+        cursor.semantics === "exclusive durable replay cursor");
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function nonblank(value) {
+    return typeof value === "string" && value.trim() !== ""
+        ? value.trim()
+        : undefined;
+}
+function messageText(message) {
+    if (typeof message.content === "string" && message.content !== "") {
+        return message.content;
+    }
+    if (!Array.isArray(message.parts))
+        return undefined;
+    const text = message.parts
+        .filter((part) => {
+        const record = asRecord(part);
+        return record?.type === "text" && typeof record.text === "string";
+    })
+        .map((part) => String(asRecord(part)?.text))
+        .join("");
+    return text || undefined;
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/index.js

@@ -2,6 +2,7 @@
 /**
  * Intangle MCP Server - Exposes Intangle context functionality through MCP
  */
+import { randomUUID } from "node:crypto";
 import { appendFileSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -10,6 +11,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { config } from "dotenv";
 import fetch from "node-fetch";
+import { CLAUDE_CHANNEL_ENABLED_ENV, CLAUDE_CHANNEL_REPLY_TOOL, CLAUDE_CHANNEL_RUNTIME_ERROR, ClaudeChannelBridge, claudeChannelConfigFromEnv, claudeChannelToolDefinition, sendClaudeChannelReply, } from "./claude-channel.js";
 import { HIGHQ_DIRECT_TOOL_NAMES } from "./highq-tool-definitions.js";
 const HIGHQ_DIRECT_TOOL_NAME_SET = new Set(HIGHQ_DIRECT_TOOL_NAMES);
 // ... imports ...
@@ -33,6 +35,7 @@ try {
     const API_BASE_URL = process.env.NEXT_APP_URL || "https://renvoi.co/intangle";
     const MCP_API_KEY = process.env.MCP_API_KEY;
     const VERCEL_BYPASS_TOKEN = process.env.VERCEL_BYPASS_TOKEN || process.env.VERCEL_PROTECTION_BYPASS;
+    const claudeChannelConfig = claudeChannelConfigFromEnv(process.env);
     log(`CWD: ${process.cwd()}`);
     log(`Has API Key: ${!!MCP_API_KEY}`);
     log(`Has Vercel Bypass Token: ${!!VERCEL_BYPASS_TOKEN}`);
@@ -250,14 +253,26 @@ try {
         capabilities: {
             resources: {},
             tools: {},
+            ...(claudeChannelConfig
+                ? { experimental: { "claude/channel": {} } }
+                : {}),
         },
+        ...(claudeChannelConfig
+            ? {
+                instructions: "Messages arrive from Tan in the explicitly configured Intangle conversation as a <channel> notification. Treat them as live requests in this session. Reply to Tan in this same Room only by calling intangle_channel_reply with the reply content. This channel delivers new messages only; it does not replay prior conversation history.",
+            }
+            : {}),
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         const result = await makeRemoteRpcCall("tools/list", {});
         if (!Array.isArray(result?.tools)) {
             throw new McpError(ErrorCode.InternalError, "Remote tool catalog unavailable");
         }
-        return { tools: result.tools };
+        return {
+            tools: claudeChannelConfig
+                ? [...result.tools, claudeChannelToolDefinition()]
+                : result.tools,
+        };
     });
     server.setRequestHandler(ListResourcesRequestSchema, async () => {
         const result = await makeRemoteRpcCall("resources/list", {});
@@ -470,6 +485,12 @@ try {
         try {
             let result;
             switch (name) {
+                case CLAUDE_CHANNEL_REPLY_TOOL:
+                    if (!claudeChannelConfig) {
+                        throw new McpError(ErrorCode.InvalidRequest, `${CLAUDE_CHANNEL_ENABLED_ENV} is not enabled for this server process`);
+                    }
+                    result = await sendClaudeChannelReply(claudeChannelConfig, args?.content, handleMessage, randomUUID);
+                    break;
                 case "search":
                     result = await handleSearchContext(args);
                     break;
@@ -599,9 +620,27 @@ try {
         }
     });
     async function main() {
+        if (claudeChannelConfig && typeof globalThis.WebSocket !== "function") {
+            console.error(CLAUDE_CHANNEL_RUNTIME_ERROR);
+            process.exit(1);
+        }
         const transport = new StdioServerTransport();
         await server.connect(transport);
         log("Server connected to transport");
+        if (claudeChannelConfig) {
+            const channel = new ClaudeChannelBridge({
+                config: claudeChannelConfig,
+                api: {
+                    fetchMessages: handleFetchConversationMessages,
+                    subscribe: handleSubscribeConversation,
+                    sendReply: handleMessage,
+                },
+                sink: server,
+            });
+            await channel.start();
+            process.once("SIGINT", () => channel.stop());
+            process.once("SIGTERM", () => channel.stop());
+        }
         // Client info is captured on-demand in ensureClientInfo() before first API call
     }
     main().catch((err) => {

package/dist/tool-definitions.js

@@ -159,11 +159,20 @@ const BASE_TOOLS = [
     {
         name: "get_items",
         title: "Get Items",
-        description: "Read complete Items by exact IDs or browse below one Space/Item using authoritative parent_id hierarchy. Every Item is a Room; Spaces remain typed scopes. Legacy IDs are accepted with alias provenance preserved. Use include=comments for canonical Item-owned comments and body revision. Use include=assignees for typed User/Agent principals.",
+        description: "For whole-Space organisation, use mode=structure. It returns complete authorised structural aggregates plus compact paged Item details; aggregates cover the full scope. Omit ids and depth, and omit under to inspect the whole authorised Space. Use coverage.snapshot, a structural SHA-256 checksum over authoritative inventory, to compare pages; it does not make page hydration transactional. Read complete Items by exact IDs or browse below one Space/Item using authoritative parent_id hierarchy. Every Item is a Room; Spaces remain typed scopes. Legacy IDs are accepted with alias provenance preserved. Use include=comments for canonical Item-owned comments and body revision. Use include=assignees for typed User/Agent principals.",
         inputSchema: {
             type: "object",
             additionalProperties: false,
             properties: {
+                mode: {
+                    type: "string",
+                    enum: [
+                        "items",
+                        "structure"
+                    ],
+                    default: "items",
+                    description: "items (default) returns bounded Item reads. structure returns complete authorised structural aggregates plus compact paged Item details; omit ids and depth. Omit under to inspect the whole authorised Space."
+                },
                 space_id: {
                     type: "string",
                     description: "REQUIRED: Exact Space containing the Items."
@@ -188,17 +197,20 @@ const BASE_TOOLS = [
                 depth: {
                     type: "integer",
                     minimum: 0,
-                    maximum: 20
+                    maximum: 20,
+                    description: "Maximum hierarchy depth. Defaults to 0 for current Space roots and 1 for explicit selectors. Omit in structure mode, which inspects all depths."
                 },
                 limit: {
                     type: "integer",
                     minimum: 1,
-                    maximum: 200
+                    maximum: 200,
+                    default: 50,
+                    description: "Maximum Items in this page."
                 },
                 offset: {
                     type: "integer",
                     minimum: 0,
-                    maximum: 5000
+                    description: "Items to skip in stable breadth-first order. items mode supports up to 5000; structure has no offset cap."
                 },
                 include: {
                     type: "array",
@@ -216,7 +228,8 @@ const BASE_TOOLS = [
                             "metadata",
                             "all"
                         ]
-                    }
+                    },
+                    description: "Optional payload fields for the returned page. structure defaults to []; items defaults to content, attributes, assignee, artifact, and metadata. Explicit include hydrates only selected page details, never aggregate content coverage."
                 }
             },
             required: [

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@intangle/mcp-server",
-  "version": "2.6.18",
+  "version": "2.6.20",
   "description": "Model Context Protocol server for Intangle - AI context that persists across conversations",
   "main": "dist/index.js",
   "type": "module",
   "scripts": {
     "start": "node dist/index.js",
     "dev": "tsx watch index.ts",
+    "test": "tsx --test tests/*.test.ts",
     "prebuild": "node scripts/sync-tool-definitions.mjs",
     "build": "tsc",
     "lint": "biome check .",
@@ -55,5 +56,5 @@
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
   },
-  "intangleSourceHash": "b0f174c2303048a64be3fb5fcfa162856d98b5f34a05ddbcf7813263f6820fbe"
+  "intangleSourceHash": "8cbc22fac71d3139119b38680db7337458c57e1a36d23033969618c3b8458dcb"
 }