@kammcs/buildit-mcp 0.2.0 → 0.7.0

package/dist/tools/whoami.js

@@ -2,6 +2,7 @@
  * whoami: who the token acts as, where, and with what reach.
  */
 import { z } from 'zod';
+import { NOT_THE_CHANNEL } from '../channel/lock.js';
 import { OPERATIONS } from '../api/generated/operations.js';
 import { defineTool } from '../toolsets/registry.js';
 import { expandScopes } from '../toolsets/toolsets.js';
@@ -24,7 +25,14 @@ const OutputSchema = z.object({
             .describe('A test org (true); null when the API is older than 1.2.0.'),
     }),
     token: z.object({
-        name: z.string().nullable(),
+        name: z
+            .string()
+            .nullable()
+            .describe("The token's name; for an agent session, the session's label."),
+        kind: z
+            .string()
+            .nullable()
+            .describe('pat: a personal access token; session: an agent session (channel mode); null when the API is older.'),
         expires_at: z.string().nullable(),
     }),
     scopes: z.array(z.string()).describe('As granted; a write scope also allows reading.'),
@@ -137,6 +145,7 @@ export const whoamiTool = defineTool({
             },
             token: {
                 name: nullableLabel(me.token.name, NAME_CHARS),
+                kind: me.token.kind === undefined ? null : sanitizeLabel(me.token.kind, 20),
                 expires_at: me.token.expires_at,
             },
             scopes: [...me.token.scopes].sort(),
@@ -176,7 +185,9 @@ export const whoamiTool = defineTool({
         const names = [
             `User: ${s.user.name ?? s.user.id}${s.user.email ? ` (${s.user.email})` : ''}`,
             `Org: ${s.org.name ?? s.org.id}`,
-            ...(s.token.name ? [`Token: ${s.token.name}`] : []),
+            ...(s.token.name
+                ? [`${s.token.kind === 'session' ? 'Session' : 'Token'}: ${s.token.name}`]
+                : []),
         ];
         if (s.projects.length > 0) {
             const shown = s.projects
@@ -188,7 +199,7 @@ export const whoamiTool = defineTool({
             names.push(`Channels the token is limited to: ${s.limits.channels.join(', ')}`);
         }
         const lines = [
-            `Signed in to buildIt.Social with a personal access token${s.token.expires_at ? ` (expires ${s.token.expires_at})` : ''}. Who and where, as people named them:`,
+            `Signed in to buildIt.Social with ${s.token.kind === 'session' ? "an agent session's token (it acts as the session's owner)" : 'a personal access token'}${s.token.expires_at ? ` (expires ${s.token.expires_at})` : ''}. Who and where, as people named them:`,
             wrapLines(names, 'names'),
             `Scopes: ${s.scopes.length > 0 ? s.scopes.join(', ') : 'none'}.`,
             `Limits: ${s.limits.projects === null
@@ -222,6 +233,9 @@ export const whoamiTool = defineTool({
         if (s.server.not_served !== null && s.server.not_served.length > 0) {
             lines.push(`This buildIt.Social server (API ${s.server.api_version ?? 'unknown'}) doesn't serve these operations yet, so calls that need them are refused until it is updated: ${s.server.not_served.join(', ')}.`);
         }
+        if (ctx.channel !== undefined && !ctx.channel.isChannel) {
+            lines.push(NOT_THE_CHANNEL);
+        }
         if (updateRequired) {
             lines.push(`This buildit-mcp (${SERVER_VERSION}) is older than the API supports (${minVersion} or newer). Ask the person to update it.`);
         }

package/dist/toolsets/catalog.js

@@ -5,7 +5,7 @@
  */
 import { PROMPTS } from '../prompts.js';
 import { RESOURCES } from '../resources.js';
-import { listChannelsTool, readChannelTool, readThreadTool } from '../tools/chat.js';
+import { listChannelsTool, listEmojiTool, listPinsTool, readChannelTool, readThreadTool, } from '../tools/chat.js';
 import { addCommentTool, listCommentsTool } from '../tools/comments.js';
 import { getItemTool, searchItemsTool } from '../tools/items-read.js';
 import { assignItemTool, createItemTool, linkItemsTool, rankItemTool, transitionItemTool, unlinkItemsTool, updateItemTool, } from '../tools/items-write.js';
@@ -49,6 +49,8 @@ export const CATALOG = [
     listChannelsTool,
     readChannelTool,
     readThreadTool,
+    listPinsTool,
+    listEmojiTool,
     // admin
     createChannelTool,
     createProjectTool,

package/dist/toolsets/registry.js

@@ -13,6 +13,8 @@ export function createToolContext(init) {
         ...(init.signal ? { signal: init.signal } : {}),
         apiOptions,
         call: (id, args = {}) => callOperation(init.api, id, args, apiOptions),
+        ...(init.channel ? { channel: init.channel } : {}),
+        ...(init.progress ? { progress: init.progress } : {}),
     };
 }
 /** Identity helper that keeps the argument and output types tied to the schemas. */

package/dist/transports/stdio.js

@@ -1,10 +1,28 @@
-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 { 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 +129,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 +151,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 +226,56 @@ 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),
+    ].filter((tool) => (!policy.readOnly || tool.annotations.readOnlyHint || READ_ONLY_SAFE_HOOKS.has(tool.name)) &&
+        !policy.excludeTools.includes(tool.name));
+}
 export function startStdio(config, logger, options = {}) {
     if (config.token === undefined)
         throw new Error('stdio mode needs a token');
@@ -159,7 +296,56 @@ export function startStdio(config, logger, options = {}) {
                 invalidations.listener();
         },
     });
-    const identity = new StdioIdentity(() => resolveListedTools(identityFromApi(api), catalog, policy, logger), logger, options.now);
+    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),
+        };
+    };
+    const identity = new StdioIdentity(async () => {
+        if (isEnded())
+            return frozen();
+        const listed = await resolveListedTools(identityFromApi(api), catalog, policy, logger);
+        const shown = extraTools.length > 0 ? { ...listed, tools: [...listed.tools, ...extraTools] } : 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();
     };
@@ -182,22 +368,90 @@ export function startStdio(config, logger, options = {}) {
     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,
+            tools: [...allowed.tools, ...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 }),
+                    ...(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.7.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"
   }
 }