@kammcs/buildit-mcp 0.2.0 → 0.8.0

package/dist/transports/stdio.js

@@ -1,10 +1,30 @@
-import { isJSONRPCRequest, } from '@modelcontextprotocol/server';
+import { isJSONRPCNotification, isJSONRPCRequest, PROTOCOL_VERSION_META_KEY, ProtocolErrorCode, SUPPORTED_PROTOCOL_VERSIONS, } from '@modelcontextprotocol/server';
 import { serveStdio, StdioServerTransport, } from '@modelcontextprotocol/server/stdio';
 import { ApiClient } from '../api/client.js';
+import { CHANNEL_NOTIFICATION, ChannelLoop, ChannelState, } from '../channel/loop.js';
 import { invalidatesIdentity } from '../identity.js';
 import { createSwitchableMcpServer, DEGRADED_LIST_TTL_MS, listedByPolicy, resolveListedTools, identityFromApi, } from '../server.js';
+import { PREEMPT_WAIT_MS } from '../channel/lock.js';
+import { TypingIndicator } from '../channel/typing.js';
+import { ToolApprovals } from '../channel/approvals.js';
+import { APPROVAL_HOOK_TOOLS, createApprovalHookTools, READ_ONLY_SAFE_HOOKS, createApproveTool, } from '../tools/approve.js';
+import { createAskTool } from '../tools/ask.js';
+import { createReplyTool, createTurnEndedTool } from '../tools/reply.js';
+import { createListThreadsTool } from '../tools/threads.js';
+import { createHandoffTools } from '../tools/handoff.js';
+import { suggestedCapabilities } from '../capabilities.js';
 import { CATALOG } from '../toolsets/catalog.js';
 import { compareVersions, SERVER_VERSION } from '../version.js';
+/**
+ * The plugin's AskUserQuestion and PermissionRequest hooks' timeout, in
+ * seconds (plugin/hooks/hooks.json). A card's wait ends a minute before it,
+ * so the answer arrives in time.
+ */
+export const HOOK_TIMEOUT_S = 3600;
+/** How long a hook's card waits: the configured minutes, a minute under the hook's timeout at most. */
+export function hookWaitSeconds(minutes) {
+    return Math.min(minutes * 60, HOOK_TIMEOUT_S - 60);
+}
 /** A known identity is read again at most this often. */
 export const IDENTITY_REFRESH_MS = 60_000;
 /** Methods whose answer depends on the token's scopes: they wait for a due refresh. */
@@ -111,13 +131,17 @@ export class StdioIdentity {
 class GatedTransport {
     inner;
     before;
+    closed;
     onclose;
     onerror;
     onmessage;
     queue = Promise.resolve();
-    constructor(inner, before) {
+    constructor(inner, before, 
+    /** Told when the connection closes (stdin ended, or close()). */
+    closed = () => undefined) {
         this.inner = inner;
         this.before = before;
+        this.closed = closed;
     }
     start() {
         this.inner.onmessage = (message, extra) => {
@@ -129,6 +153,71 @@ class GatedTransport {
             });
         };
         this.inner.onerror = (error) => this.onerror?.(error);
+        this.inner.onclose = () => {
+            this.closed();
+            this.onclose?.();
+        };
+        return this.inner.start();
+    }
+    send(message, options) {
+        return this.inner.send(message, options);
+    }
+    close() {
+        return this.inner.close();
+    }
+}
+/** Whether a message claims a protocol revision in its _meta (the 2026-07-28 way of opening). */
+function claimsRevision(message) {
+    if (!isJSONRPCRequest(message) && !isJSONRPCNotification(message))
+        return false;
+    const params = message.params;
+    return params?._meta?.[PROTOCOL_VERSION_META_KEY] !== undefined;
+}
+/**
+ * Keeps a connection on the 2025 handshake (channel mode): until
+ * `initialize`, a request that claims a revision is answered with the
+ * unsupported-version error naming only the 2025-era revisions, which makes
+ * a client fall back to `initialize`; such a notification is dropped.
+ */
+export class LegacyOnlyTransport {
+    inner;
+    onclose;
+    onerror;
+    onmessage;
+    initialized = false;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    start() {
+        this.inner.onmessage = (message, extra) => {
+            if (!this.initialized && claimsRevision(message)) {
+                if (isJSONRPCRequest(message)) {
+                    const meta = message.params._meta ?? {};
+                    const requested = meta[PROTOCOL_VERSION_META_KEY];
+                    void this.inner
+                        .send({
+                        jsonrpc: '2.0',
+                        id: message.id,
+                        error: {
+                            code: ProtocolErrorCode.UnsupportedProtocolVersion,
+                            message: 'Unsupported protocol version: this channel server speaks the 2025 handshake.',
+                            data: {
+                                supported: [...SUPPORTED_PROTOCOL_VERSIONS],
+                                requested: typeof requested === 'string' ? requested : 'unknown',
+                            },
+                        },
+                    })
+                        .catch((error) => {
+                        this.onerror?.(error instanceof Error ? error : new Error(String(error)));
+                    });
+                }
+                return;
+            }
+            if (isJSONRPCRequest(message) && message.method === 'initialize')
+                this.initialized = true;
+            this.onmessage?.(message, extra);
+        };
+        this.inner.onerror = (error) => this.onerror?.(error);
         this.inner.onclose = () => this.onclose?.();
         return this.inner.start();
     }
@@ -139,6 +228,68 @@ class GatedTransport {
         return this.inner.close();
     }
 }
+/** The tools that post in a thread and stop its "is writing" themselves. */
+const POSTING_TOOLS = new Set(['reply', 'ask', 'turn_ended', 'list_threads']);
+/**
+ * A tool call is activity for "is writing": for the thread it names (its
+ * thread_id or card_thread, or an item's key that the session works on),
+ * else for the only working thread. A call that works on an active item's
+ * thread (a worker reading or changing its item) shows "is writing" there
+ * again; the posting tools stop it themselves.
+ */
+function noteActivity(state, tool, args) {
+    const typing = state.typing;
+    if (typing === undefined)
+        return;
+    // The plugin's approval hooks: tool_seen counts the activity itself.
+    if (APPROVAL_HOOK_TOOLS.has(tool))
+        return;
+    const a = (args !== null && typeof args === 'object' ? args : {});
+    const str = (v) => typeof v === 'string' && v !== '' ? v : undefined;
+    const ref = str(a.thread_id) ?? str(a.card_thread) ?? str(a.item);
+    const key = ref?.startsWith('#') ? ref.slice(1) : ref;
+    const thread = key === undefined
+        ? undefined
+        : state.activeItems.has(key)
+            ? key
+            : state.items.get(key.toUpperCase());
+    if (thread === undefined || !state.activeItems.has(thread)) {
+        typing.activity(key !== undefined && thread === undefined ? key : undefined);
+        return;
+    }
+    if (POSTING_TOOLS.has(tool))
+        typing.activity(thread);
+    else
+        typing.work(thread);
+}
+/**
+ * The tools only channel mode has (reply, ask, list_threads, and the
+ * plugin's hooks: turn_ended, approve and the hooks that end approvals),
+ * under the operator's read-only and exclude rules.
+ */
+function channelTools(policy, state, ask, approve) {
+    return [
+        createReplyTool(state),
+        createAskTool(state, ask),
+        createListThreadsTool(state),
+        createTurnEndedTool(state),
+        createApproveTool(state, approve),
+        ...createApprovalHookTools(state),
+        ...createHandoffTools(state),
+    ].filter((tool) => (!policy.readOnly || tool.annotations.readOnlyHint || READ_ONLY_SAFE_HOOKS.has(tool.name)) &&
+        !policy.excludeTools.includes(tool.name));
+}
+/**
+ * The channel tools this server's API serves: a tool that needs operations
+ * the API's /v1/meta leaves out is not listed (when the API doesn't say,
+ * every tool is, and an older one says so when called).
+ */
+function servedTools(api, tools) {
+    const served = api.served?.operations;
+    if (served === undefined)
+        return [...tools];
+    return tools.filter((t) => (t.requiresOperations ?? []).every((op) => served.has(op)));
+}
 export function startStdio(config, logger, options = {}) {
     if (config.token === undefined)
         throw new Error('stdio mode needs a token');
@@ -159,14 +310,49 @@ export function startStdio(config, logger, options = {}) {
                 invalidations.listener();
         },
     });
-    const identity = new StdioIdentity(() => resolveListedTools(identityFromApi(api), catalog, policy, logger), logger, options.now);
-    invalidations.listener = () => {
-        identity.invalidate();
+    const channel = config.channel !== undefined;
+    const state = new ChannelState();
+    state.isChannel = options.channelOwner ?? true;
+    state.folder = config.channel?.folder;
+    if (channel && state.isChannel) {
+        state.typing = new TypingIndicator({
+            api,
+            logger: logger.child({ component: 'typing' }),
+            ...options.typing,
+        });
+        state.approvals = new ToolApprovals({
+            logger: logger.child({ component: 'approvals' }),
+            journal: options.approvalJournal,
+        });
+    }
+    const extraTools = channel
+        ? channelTools(policy, state, {
+            questionsInApp: config.ask.questionsInApp,
+            hookWaitS: hookWaitSeconds(config.ask.timeoutMinutes),
+            ...options.ask,
+        }, {
+            approvalsInApp: config.approvals.inApp,
+            hookWaitS: hookWaitSeconds(config.approvals.timeoutMinutes),
+            ...options.approve,
+        })
+        : [];
+    // Once a channel's session has ended, the listing stays as it last was
+    // (without reply), so Claude keeps its tools, which then say why.
+    let lastKnown;
+    const isEnded = () => state.ended !== undefined;
+    const frozen = () => {
+        const base = lastKnown ?? {
+            ...listedByPolicy(catalog, policy),
+            identity: 'unverified',
+        };
+        return {
+            ...base,
+            tools: base.tools.filter((t) => !extraTools.includes(t) || t.runsAfterSessionEnd === true),
+        };
     };
-    // Read the identity at startup.
-    void identity.refresh();
-    // Warn early when the API needs a newer server.
-    void api
+    // Read what the API serves at startup: it warns when the API needs a newer server, and
+    // channel tools newer than the server (the handoffs) are left out of the listing.
+    const metaRead = api
         .getMeta()
         .then((meta) => {
         if (meta.min_mcp_version && compareVersions(SERVER_VERSION, meta.min_mcp_version) < 0) {
@@ -177,27 +363,117 @@ export function startStdio(config, logger, options = {}) {
         }
     })
         .catch(() => undefined);
+    const identity = new StdioIdentity(async () => {
+        if (isEnded())
+            return frozen();
+        const listed = await resolveListedTools(identityFromApi(api), catalog, policy, logger);
+        if (extraTools.length > 0)
+            await metaRead;
+        const served = servedTools(api, extraTools);
+        const shown = served.length > 0 ? { ...listed, tools: [...listed.tools, ...served] } : listed;
+        if (shown.identity === 'known')
+            lastKnown = shown;
+        // The session may have ended while the identity was read.
+        return isEnded() ? frozen() : shown;
+    }, logger, options.now);
+    invalidations.listener = () => {
+        identity.invalidate();
+    };
+    // Read the identity at startup.
+    void identity.refresh();
     // Everything the configuration allows is registered; the identity decides what is shown.
     const allowed = listedByPolicy(catalog, policy);
     const wire = options.stdin && options.stdout
         ? new StdioServerTransport(options.stdin, options.stdout)
         : new StdioServerTransport();
-    return serveStdio(async () => {
+    let loop;
+    const stopLoop = () => loop?.stop() ?? Promise.resolve();
+    const handle = serveStdio(async () => {
         const listed = await identity.refresh();
         const switchable = createSwitchableMcpServer({
-            tools: allowed.tools,
+            // What /v1/meta said is known by now (refresh waited for it): the instructions leave out
+            // the channel tools this API doesn't serve.
+            tools: [...allowed.tools, ...servedTools(api, extraTools)],
             resources: allowed.resources,
             prompts: allowed.prompts,
             api,
             logger,
+            channel,
+            ...(channel
+                ? {
+                    channelState: state,
+                    ...(config.channel?.fromPlugin === true
+                        ? { lead: { maxParallelItems: config.ask.maxParallelItems } }
+                        : {}),
+                    onToolCall: (tool, args) => {
+                        noteActivity(state, tool, args);
+                    },
+                    sessionEnded: () => state.ended,
+                    onSessionOver: (code) => {
+                        void loop?.end(code);
+                    },
+                }
+                : {}),
             ...(listed.identity === 'known' ? {} : { toolsListTtlMs: DEGRADED_LIST_TTL_MS }),
         });
         identity.attach(switchable);
+        if (channel) {
+            const mcp = switchable.server.server;
+            // Notifications sent before the client has initialized would be lost.
+            mcp.oninitialized = () => {
+                if (loop !== undefined)
+                    return;
+                if (!state.isChannel) {
+                    logger.warn('another buildit server in this folder receives the messages from buildIt.Social (it holds the channel lock); this one serves its tools without the channel. Remove the extra server (claude mcp remove <name>; "buildit-mcp status" names them)');
+                    return;
+                }
+                loop = new ChannelLoop({
+                    api,
+                    logger: logger.child({ component: 'channel' }),
+                    state,
+                    notify: (params) => mcp.notification({ method: CHANNEL_NOTIFICATION, params }),
+                    // What this computer can do, as tag names only (BUILDIT_CAPABILITIES replaces it).
+                    capabilities: () => suggestedCapabilities(config.channel?.capabilities),
+                    ...(options.channelLock === undefined
+                        ? {}
+                        : {
+                            owns: () => options.channelLock?.owns() ?? true,
+                            ...(options.channelLock.preempted === undefined
+                                ? {}
+                                : { firstPollDelayMs: options.preemptWaitMs ?? PREEMPT_WAIT_MS }),
+                        }),
+                    onEnded: async (reason) => {
+                        if (state.ended !== undefined) {
+                            // The server stays up: Claude keeps its tools (which now say the session
+                            // ended), without reply.
+                            switchable.show(frozen());
+                            try {
+                                switchable.server.sendToolListChanged();
+                            }
+                            catch {
+                                // A client that is gone can't be told.
+                            }
+                        }
+                        await options.onSessionEnded?.(reason);
+                    },
+                    ...options.channelLoop,
+                });
+                void loop.start();
+            };
+        }
         return switchable.server;
     }, {
         onerror: (error) => {
             logger.error('stdio transport error', { error });
         },
-        transport: new GatedTransport(wire, (message) => identity.beforeMessage(message)),
+        transport: new GatedTransport(channel ? new LegacyOnlyTransport(wire) : wire, (message) => identity.beforeMessage(message), () => {
+            void stopLoop();
+        }),
     });
+    return {
+        async close() {
+            await stopLoop();
+            await handle.close();
+        },
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kammcs/buildit-mcp",
-  "version": "0.2.0",
+  "version": "0.8.0",
   "description": "MCP server for buildIt.Social: lets AI agents work with an org's projects, pages and channels through the buildIt.Social agent API, with a personal access token.",
   "license": "MIT",
   "author": "Kamm Creative Solutions",
@@ -46,6 +46,7 @@
     "inspect:docker": "npm run build && docker build -t buildit-mcp:inspect . && tsx scripts/inspect.ts --image buildit-mcp:inspect",
     "image:publish": "tsx scripts/publish-image.ts",
     "bundle": "npm run build && tsx scripts/bundle.ts",
+    "dev-marketplace": "tsx scripts/dev-marketplace.ts",
     "conformance": "npm run build && tsx scripts/conformance.ts",
     "generate": "tsx scripts/generate.ts",
     "privacy": "tsx scripts/privacy.ts",
@@ -73,5 +74,8 @@
     "typescript": "6.0.3",
     "typescript-eslint": "8.71.1",
     "vitest": "5.0.3"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "2.1.1"
   }
 }