@kammcs/buildit-mcp 0.2.0 → 0.7.0

package/dist/config.js

@@ -5,25 +5,45 @@
  * environment (a flag would be visible to other processes), and no message
  * produced here ever contains it.
  */
+import { basename, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { LOG_LEVELS, scrubString } from './log.js';
 import { DEFAULT_TOOLSETS, isToolsetName, TOOLSET_NAMES, } from './toolsets/toolsets.js';
 export const DEFAULT_API_URL = 'https://api.buildit.social/functions/v1/agent-api';
 export const DEFAULT_HTTP_HOST = '127.0.0.1';
 export const DEFAULT_HTTP_PORT = 8765;
+export const DEFAULT_ASK_TIMEOUT_MINUTES = 60;
+export const DEFAULT_APPROVAL_TIMEOUT_MINUTES = 60;
+export const DEFAULT_MAX_PARALLEL_ITEMS = 3;
 export class ConfigError extends Error {
     name = 'ConfigError';
 }
 export const USAGE = `Usage: buildit-mcp [options]
+       buildit-mcp connect --project <KEY> [--label <name>] [--folder <path>] [--api-url <url>]
+       buildit-mcp disconnect [--folder <path>] [--api-url <url>]
+       buildit-mcp status [--folder <path>] [--api-url <url>]
 
 An MCP server for buildIt.Social. By default it serves one person over stdio,
 with the personal access token in the BUILDIT_TOKEN environment variable.
+With --channel it is also a Claude Code channel: the messages its owner sends
+to the agent in buildIt.Social arrive in the Claude Code session, which
+answers with the reply tool. Its token is the session token that
+"buildit-mcp connect" saved for the folder (or BUILDIT_TOKEN).
+
+Commands (run them in a terminal, in the folder where Claude Code runs):
+  connect                   Connect this folder to buildIt.Social as an agent
+                            session: shows a code to approve in the app, then
+                            saves the session token in the OS keychain
+  disconnect                Forget this folder's saved session
+  status                    Show this folder's session
+  Run "buildit-mcp <command> --help" for a command's options.
 
 Options (each also has an environment variable):
   --api-url <url>           BUILDIT_API_URL           Agent API base URL
                                                       (default ${DEFAULT_API_URL})
   --toolsets <list>         BUILDIT_TOOLSETS          Comma-separated toolsets, or "all"
-                                                      (default ${DEFAULT_TOOLSETS.join(',')};
+                                                      (default ${DEFAULT_TOOLSETS.join(',')}, or all
+                                                      with --channel;
                                                       known: ${TOOLSET_NAMES.join(', ')})
   --read-only               BUILDIT_READ_ONLY=true    Only list tools that change nothing
   --exclude-tools <list>    BUILDIT_EXCLUDE_TOOLS     Comma-separated tool names to hide
@@ -33,6 +53,26 @@ Options (each also has an environment variable):
   --port <port>             BUILDIT_PORT              HTTP port (default ${DEFAULT_HTTP_PORT})
   --allowed-hosts <list>    BUILDIT_ALLOWED_HOSTS     Hostnames accepted in the Host header
   --allowed-origins <list>  BUILDIT_ALLOWED_ORIGINS   Hostnames accepted in the Origin header
+  --channel                 BUILDIT_CHANNEL=true      Claude Code channel mode (stdio only)
+  --folder <path>           BUILDIT_FOLDER            The folder whose saved session --channel uses
+                                                      (default: the working directory)
+  --from-plugin                                       --channel: started by the buildit plugin, which
+                                                      Claude Code registers as the channel (the
+                                                      plugin passes it)
+                            BUILDIT_QUESTIONS_IN_APP  --channel: the plugin's question hook asks in
+                                                      buildIt.Social (default true)
+                            BUILDIT_ASK_TIMEOUT_MINUTES
+                                                      --channel: how long a question card waits,
+                                                      1 to 60 (default 60)
+                            BUILDIT_MAX_PARALLEL_ITEMS
+                                                      --channel with the plugin: how many work items
+                                                      are worked on at once, 1 to 10 (default 3)
+                            BUILDIT_APPROVALS_IN_APP  --channel: the plugin's permission hook asks to
+                                                      approve tool calls in buildIt.Social too
+                                                      (default true)
+                            BUILDIT_APPROVAL_TIMEOUT_MINUTES
+                                                      --channel: how long a tool approval card waits,
+                                                      1 to 60 (default 60)
   --allow-any-host          BUILDIT_ALLOW_ANY_HOST=true
                                                       Off loopback, serve without checking the
                                                       Host header (otherwise BUILDIT_ALLOWED_HOSTS
@@ -43,6 +83,55 @@ Options (each also has an environment variable):
 The token is never accepted as a flag. In stdio mode set BUILDIT_TOKEN; in HTTP
 mode every request carries its own "Authorization: Bearer <token>" header.
 `;
+export const COMMAND_USAGE = {
+    connect: `Usage: buildit-mcp connect --project <KEY> [options]
+
+Connects this folder to buildIt.Social as a session of your personal agent,
+for Claude Code's channel mode (buildit-mcp --channel). It shows a code and a
+link: open the link, check the code, and approve in buildIt.Social. The
+session token is then saved in the OS keychain for this folder and API.
+
+Options:
+  --project <KEY>           A project the session may reach (repeat it, or
+                            separate keys with commas; 1 to 10)
+  --label <name>            The session's name in buildIt.Social, 1 to 40
+                            characters (default: the folder's name)
+  --folder <path>           The folder (default: the working directory)
+  --api-url <url>           BUILDIT_API_URL  Agent API base URL
+                            (default ${DEFAULT_API_URL})
+  --yes                     Save without asking "Is this you?" once it is
+                            approved. For scripts only: unsafe if anyone else
+                            could have seen the code, since whoever approves
+                            it gets the session
+  -h, --help                Show this help
+
+Once approved, it says who approved it (the agent, its owner, the org, the
+projects) and asks "Is this you?"; only "y" saves the token, and any other
+answer cancels the session.
+`,
+    disconnect: `Usage: buildit-mcp disconnect [options]
+
+Cancels this folder's session in buildIt.Social and forgets its saved token.
+If buildIt.Social can't be reached, the token is forgotten anyway: revoke
+the session in the app then.
+
+Options:
+  --folder <path>           The folder (default: the working directory)
+  --api-url <url>           BUILDIT_API_URL  Agent API base URL
+  -h, --help                Show this help
+`,
+    status: `Usage: buildit-mcp status [options]
+
+Shows the session saved for this folder: its agent, name, org and reach, and
+whether buildIt.Social still accepts it.
+
+Options:
+  --folder <path>           The folder (default: the working directory)
+  --api-url <url>           BUILDIT_API_URL  Agent API base URL
+  -h, --help                Show this help
+`,
+};
+const SESSION_COMMANDS = ['connect', 'disconnect', 'status'];
 const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
 const FALSE_VALUES = new Set(['0', 'false', 'no', 'off', '']);
 export function parseBoolean(name, raw, fallback) {
@@ -55,6 +144,73 @@ export function parseBoolean(name, raw, fallback) {
         return false;
     throw new ConfigError(`${name} must be true or false (got "${raw}").`);
 }
+/**
+ * The plugin's settings arrive as environment variables it fills in, so a
+ * value that is empty or doesn't parse keeps the default, with a warning,
+ * instead of stopping the server.
+ */
+function parseAsk(env, warnings) {
+    let questionsInApp = true;
+    const rawIn = env.BUILDIT_QUESTIONS_IN_APP?.trim() ?? '';
+    if (rawIn !== '') {
+        const value = rawIn.toLowerCase();
+        if (TRUE_VALUES.has(value))
+            questionsInApp = true;
+        else if (FALSE_VALUES.has(value))
+            questionsInApp = false;
+        else
+            warnings.push('BUILDIT_QUESTIONS_IN_APP is not true or false; questions go to buildIt.Social.');
+    }
+    let timeoutMinutes = DEFAULT_ASK_TIMEOUT_MINUTES;
+    const rawMinutes = env.BUILDIT_ASK_TIMEOUT_MINUTES?.trim() ?? '';
+    if (rawMinutes !== '') {
+        const n = Number(rawMinutes);
+        if (Number.isFinite(n) && n >= 1 && n <= 60) {
+            timeoutMinutes = Math.floor(n);
+        }
+        else {
+            warnings.push(`BUILDIT_ASK_TIMEOUT_MINUTES must be 1 to 60; using ${DEFAULT_ASK_TIMEOUT_MINUTES}.`);
+        }
+    }
+    let maxParallelItems = DEFAULT_MAX_PARALLEL_ITEMS;
+    const rawParallel = env.BUILDIT_MAX_PARALLEL_ITEMS?.trim() ?? '';
+    if (rawParallel !== '') {
+        const n = Number(rawParallel);
+        if (Number.isFinite(n) && n >= 1 && n <= 10) {
+            maxParallelItems = Math.floor(n);
+        }
+        else {
+            warnings.push(`BUILDIT_MAX_PARALLEL_ITEMS must be 1 to 10; using ${DEFAULT_MAX_PARALLEL_ITEMS}.`);
+        }
+    }
+    return { questionsInApp, timeoutMinutes, maxParallelItems };
+}
+/** The tool approval settings, read as the question settings are (a bad value keeps the default). */
+function parseApprovals(env, warnings) {
+    let inApp = true;
+    const rawIn = env.BUILDIT_APPROVALS_IN_APP?.trim() ?? '';
+    if (rawIn !== '') {
+        const value = rawIn.toLowerCase();
+        if (TRUE_VALUES.has(value))
+            inApp = true;
+        else if (FALSE_VALUES.has(value))
+            inApp = false;
+        else
+            warnings.push('BUILDIT_APPROVALS_IN_APP is not true or false; tool approvals go to buildIt.Social.');
+    }
+    let timeoutMinutes = DEFAULT_APPROVAL_TIMEOUT_MINUTES;
+    const rawMinutes = env.BUILDIT_APPROVAL_TIMEOUT_MINUTES?.trim() ?? '';
+    if (rawMinutes !== '') {
+        const n = Number(rawMinutes);
+        if (Number.isFinite(n) && n >= 1 && n <= 60) {
+            timeoutMinutes = Math.floor(n);
+        }
+        else {
+            warnings.push(`BUILDIT_APPROVAL_TIMEOUT_MINUTES must be 1 to 60; using ${DEFAULT_APPROVAL_TIMEOUT_MINUTES}.`);
+        }
+    }
+    return { inApp, timeoutMinutes };
+}
 function splitList(raw) {
     return [
         ...new Set(raw
@@ -90,6 +246,24 @@ const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
 export function isLoopbackHost(host) {
     return LOOPBACK_HOSTS.has(host.toLowerCase());
 }
+/** The agent API's path on a buildIt.Social host. */
+export const AGENT_API_PATH = '/functions/v1/agent-api';
+/**
+ * The note shown once when an API address is a bare host (no path), which
+ * parseApiUrl completes with the agent API's path; undefined otherwise.
+ */
+export function apiUrlNote(raw) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        if (new URL(raw.trim()).pathname !== '/')
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    return `The API address ${raw.trim()} has no path, so buildit-mcp uses ${parseApiUrl(raw)}, the agent API on that host.`;
+}
 export function parseApiUrl(raw) {
     let url;
     try {
@@ -108,6 +282,9 @@ export function parseApiUrl(raw) {
     if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
         throw new ConfigError('BUILDIT_API_URL must use https:// (plain http:// is only allowed for localhost).');
     }
+    // A bare host means its agent API.
+    if (url.pathname === '/')
+        url.pathname = AGENT_API_PATH;
     return url.toString().replace(/\/+$/, '');
 }
 const HOSTNAME = /^(\[[0-9a-f:.]+\]|[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*)$/;
@@ -166,15 +343,120 @@ function parseLogLevel(raw) {
 function nonEmpty(value) {
     return value === undefined || value.trim() === '' ? undefined : value;
 }
+const PROJECT_KEY = /^[A-Za-z][A-Za-z0-9]{1,5}$/;
+export const LABEL_MAX_CHARS = 40;
+/** Control, direction and zero-width characters (a RegExp character class), which a session label may not hold. */
+export const FORBIDDEN_CHARS = '[\\u0000-\\u001F\\u007F-\\u009F\\u200B-\\u200F\\u202A-\\u202E\\u2060-\\u2069\\uFEFF]';
+/** Project keys from --project flags (each may list several, comma-separated). */
+export function parseProjects(values) {
+    const keys = [...new Set(values.flatMap((v) => splitList(v)).map((k) => k.toUpperCase()))];
+    if (keys.length === 0) {
+        throw new ConfigError('Name the project the session may reach with --project <KEY>, for example --project DEMO.');
+    }
+    const bad = keys.filter((k) => !PROJECT_KEY.test(k));
+    if (bad.length > 0) {
+        throw new ConfigError(`Not a project key: ${bad.join(', ')}. Keys are 2 to 6 letters and digits, starting with a letter (for example DEMO).`);
+    }
+    if (keys.length > 10)
+        throw new ConfigError('A session may reach at most 10 projects.');
+    return keys;
+}
+/** The --label given, checked; or the folder's name, made to fit. */
+export function sessionLabel(raw, folder) {
+    if (raw !== undefined) {
+        const label = raw.trim();
+        if (label.length === 0 || Array.from(label).length > LABEL_MAX_CHARS) {
+            throw new ConfigError(`The label must be 1 to ${LABEL_MAX_CHARS} characters.`);
+        }
+        if (new RegExp(FORBIDDEN_CHARS, 'u').test(label)) {
+            throw new ConfigError('The label may not hold control, direction or invisible characters.');
+        }
+        return label;
+    }
+    const name = Array.from(basename(folder).replace(new RegExp(FORBIDDEN_CHARS, 'gu'), '').trim())
+        .slice(0, LABEL_MAX_CHARS)
+        .join('')
+        .trim();
+    return name.length > 0 ? name : 'session';
+}
+/** The folder a session belongs to: --folder, else BUILDIT_FOLDER, else the working directory. */
+function folderOf(flag, env, cwd) {
+    const raw = typeof flag === 'string' ? flag : nonEmpty(env.BUILDIT_FOLDER);
+    if (raw !== undefined && raw.trim() === '')
+        throw new ConfigError('--folder must not be empty.');
+    return resolve(cwd, raw?.trim() ?? '.');
+}
+function parseSessionCommand(command, argv, env, cwd, secrets) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: [...argv],
+            strict: true,
+            allowPositionals: false,
+            options: {
+                'api-url': { type: 'string' },
+                folder: { type: 'string' },
+                help: { type: 'boolean', short: 'h' },
+                ...(command === 'connect'
+                    ? {
+                        project: { type: 'string', multiple: true },
+                        label: { type: 'string' },
+                        yes: { type: 'boolean' },
+                    }
+                    : {}),
+            },
+        }));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ConfigError(`${scrubString(message, secrets)} Run "buildit-mcp ${command} --help" for the options.`);
+    }
+    if (values.help === true)
+        return { kind: 'help', command };
+    const apiFlag = values['api-url'];
+    const apiRaw = (typeof apiFlag === 'string' ? apiFlag : nonEmpty(env.BUILDIT_API_URL)) ?? DEFAULT_API_URL;
+    const apiUrl = parseApiUrl(apiRaw);
+    const note = apiUrlNote(apiRaw);
+    const folder = folderOf(values.folder, env, cwd);
+    if (command !== 'connect') {
+        return {
+            kind: command,
+            options: {
+                apiUrl,
+                folder,
+                apiUrlFlag: typeof apiFlag === 'string',
+                ...(note === undefined ? {} : { apiUrlNote: note }),
+            },
+        };
+    }
+    const projectFlags = values.project;
+    const projects = parseProjects(Array.isArray(projectFlags) ? projectFlags : []);
+    const label = sessionLabel(typeof values.label === 'string' ? values.label : undefined, folder);
+    return {
+        kind: 'connect',
+        options: {
+            apiUrl,
+            folder,
+            projects,
+            label,
+            yes: values.yes === true,
+            ...(note === undefined ? {} : { apiUrlNote: note }),
+        },
+    };
+}
 /**
  * Parses flags and environment variables. Throws ConfigError with a message
  * that is safe to print (it never contains the token).
  */
-export function parseCli(argv, env) {
+export function parseCli(argv, env, cwd = process.cwd()) {
     const secrets = env.BUILDIT_TOKEN ? [env.BUILDIT_TOKEN] : [];
     if (argv.some((a) => a === '--token' || a.startsWith('--token='))) {
         throw new ConfigError('The token is never accepted as a flag (other processes can read flags). Set the BUILDIT_TOKEN environment variable instead.');
     }
+    const command = SESSION_COMMANDS.find((c) => c === argv[0]);
+    if (command !== undefined) {
+        return parseSessionCommand(command, argv.slice(1), env, cwd, secrets);
+    }
     let values;
     try {
         ({ values } = parseArgs({
@@ -193,6 +475,9 @@ export function parseCli(argv, env) {
                 'allowed-hosts': { type: 'string' },
                 'allowed-origins': { type: 'string' },
                 'allow-any-host': { type: 'boolean' },
+                channel: { type: 'boolean' },
+                folder: { type: 'string' },
+                'from-plugin': { type: 'boolean' },
                 help: { type: 'boolean', short: 'h' },
                 version: { type: 'boolean', short: 'v' },
             },
@@ -213,9 +498,23 @@ export function parseCli(argv, env) {
     const warnings = [];
     const http = values.http === true || parseBoolean('BUILDIT_HTTP', env.BUILDIT_HTTP, false);
     const mode = http ? 'http' : 'stdio';
-    const apiUrl = parseApiUrl(str('api-url', 'BUILDIT_API_URL') ?? DEFAULT_API_URL);
+    const channelMode = values.channel === true || parseBoolean('BUILDIT_CHANNEL', env.BUILDIT_CHANNEL, false);
+    if (channelMode && mode === 'http') {
+        throw new ConfigError('Channel mode (--channel) runs over stdio only: Claude Code starts it as a local server.');
+    }
+    const apiRaw = str('api-url', 'BUILDIT_API_URL') ?? DEFAULT_API_URL;
+    const apiUrl = parseApiUrl(apiRaw);
+    const apiNote = apiUrlNote(apiRaw);
+    if (apiNote !== undefined)
+        warnings.push(apiNote);
     const toolsetsRaw = str('toolsets', 'BUILDIT_TOOLSETS');
-    const toolsets = toolsetsRaw === undefined ? [...DEFAULT_TOOLSETS] : parseToolsets(toolsetsRaw);
+    // Channel mode turns every toolset on by default: approvals need destructive and admin (the
+    // session's own scopes still limit what works).
+    const toolsets = toolsetsRaw === undefined
+        ? channelMode
+            ? [...TOOLSET_NAMES]
+            : [...DEFAULT_TOOLSETS]
+        : parseToolsets(toolsetsRaw);
     const readOnly = values['read-only'] === true || parseBoolean('BUILDIT_READ_ONLY', env.BUILDIT_READ_ONLY, false);
     const excludeRaw = str('exclude-tools', 'BUILDIT_EXCLUDE_TOOLS');
     const excludeTools = excludeRaw === undefined ? [] : parseToolNames(excludeRaw, 'BUILDIT_EXCLUDE_TOOLS');
@@ -236,8 +535,29 @@ export function parseCli(argv, env) {
         httpConfig.allowedOrigins = parseHostList(originsRaw, 'BUILDIT_ALLOWED_ORIGINS', true);
     }
     let token;
+    let channel;
     const rawToken = env.BUILDIT_TOKEN;
-    if (mode === 'stdio') {
+    if (channelMode) {
+        channel = {
+            folder: folderOf(values.folder, env, cwd),
+            tokenSource: 'store',
+            apiUrlFlag: typeof values['api-url'] === 'string',
+            fromPlugin: values['from-plugin'] === true || nonEmpty(env.CLAUDE_PLUGIN_ROOT) !== undefined,
+        };
+        const envToken = rawToken?.trim() ?? '';
+        if (envToken.startsWith('buildit_ags_')) {
+            if (/\s/.test(envToken)) {
+                throw new ConfigError('BUILDIT_TOKEN contains whitespace; check that it was copied whole.');
+            }
+            token = envToken;
+            channel.tokenSource = 'env';
+        }
+        else if (envToken !== '') {
+            // A user-level personal access token from the usual setup: the folder's session wins.
+            warnings.push('BUILDIT_TOKEN is not a session token, so channel mode ignores it and uses the session that "buildit-mcp connect" saved for the folder.');
+        }
+    }
+    else if (mode === 'stdio') {
         if (rawToken === undefined || rawToken.trim() === '') {
             throw new ConfigError('BUILDIT_TOKEN is not set. Create a personal access token in buildIt.Social and put it in the BUILDIT_TOKEN environment variable (never in a file you commit).');
         }
@@ -245,7 +565,7 @@ export function parseCli(argv, env) {
         if (/\s/.test(token)) {
             throw new ConfigError('BUILDIT_TOKEN contains whitespace; check that it was copied whole.');
         }
-        if (!token.startsWith('buildit_pat_')) {
+        if (!token.startsWith('buildit_pat_') && !token.startsWith('buildit_ags_')) {
             warnings.push('BUILDIT_TOKEN does not start with "buildit_pat_"; buildIt.Social personal access tokens do.');
         }
     }
@@ -269,6 +589,9 @@ export function parseCli(argv, env) {
             mode,
             apiUrl,
             ...(token === undefined ? {} : { token }),
+            ...(channel === undefined ? {} : { channel }),
+            ask: parseAsk(env, warnings),
+            approvals: parseApprovals(env, warnings),
             toolsets,
             readOnly,
             excludeTools,

package/dist/errors.js

@@ -83,6 +83,12 @@ const RATE_BUCKETS = {
     token_writes_per_day: 'writes per day for this token',
     org_requests_per_minute: 'requests per minute for the whole org, across all its tokens',
     user_requests_per_minute: 'requests per minute for your account, across all your tokens',
+    session_polls_per_minute: 'polls per minute for this session',
+    session_typing_per_minute: 'typing notices per minute for this session',
+    session_approvals_per_minute: 'tool approval calls per minute for this session',
+    connect_starts_per_hour: 'connections started per hour from this address',
+    connect_pending_grants: 'connections waiting for approval on this server',
+    connect_pending_per_address: 'connections waiting for approval from this network',
 };
 /** The release operations, as plan_release's actions. */
 const RELEASE_ACTIONS = {
@@ -316,6 +322,38 @@ export function describeApiError(err) {
     return lines.join('\n');
 }
 /** A tool result for any failure inside a tool handler. */
+/** The codes that mean an agent session is over: its token is no longer accepted. */
+export const SESSION_OVER_CODES = new Set([
+    'token_revoked',
+    'token_expired',
+    'token_invalid',
+]);
+const SESSION_OVER_WHY = {
+    token_revoked: 'it was revoked',
+    token_expired: 'it expired after 30 days unused',
+    token_invalid: 'buildIt.Social no longer recognises its token',
+};
+/**
+ * What to tell the agent once a session token is refused for good: a
+ * session is reconnected with `connect`, never with a new personal access
+ * token.
+ */
+export function sessionEndedText(code) {
+    const why = SESSION_OVER_WHY[code] ?? code;
+    return `This buildIt.Social session has ended (${why}). In this folder run \`buildit-mcp connect --project <KEY>\`, approve it, then restart Claude Code. Tell the person; retrying won't help.`;
+}
+/** A tool result for a call made after (or refused because) the session ended. */
+export function sessionEndedResult(code) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: `buildit-mcp error: session_ended (${code})\n${sessionEndedText(code)}`,
+            },
+        ],
+    };
+}
 export function toolErrorResult(err, requestId) {
     if (err instanceof ApiError) {
         return { isError: true, content: [{ type: 'text', text: describeApiError(err) }] };

package/dist/index.js

@@ -1,9 +1,16 @@
 #!/usr/bin/env node
 /**
- * The buildit-mcp command. stdio by default; Streamable HTTP with --http.
+ * The buildit-mcp command. stdio by default; Streamable HTTP with --http;
+ * a Claude Code channel with --channel; and the session commands
+ * (connect, disconnect, status), which run in a terminal.
  */
-import { ConfigError, parseCli, USAGE } from './config.js';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { acquireChannelLock, defaultLockDir } from './channel/lock.js';
+import { runConnect, runDisconnect, runStatus } from './cli/commands.js';
+import { COMMAND_USAGE, ConfigError, parseApiUrl, parseCli, USAGE } from './config.js';
 import { createLogger } from './log.js';
+import { forgetSession, openTokenStore, savedApiUrl, sessionKey } from './secrets/keychain.js';
 import { CATALOG } from './toolsets/catalog.js';
 import { unknownToolNames } from './toolsets/registry.js';
 import { startHttp } from './transports/http.js';
@@ -23,19 +30,89 @@ async function main() {
         throw err;
     }
     if (action.kind === 'help') {
-        process.stdout.write(USAGE);
+        process.stdout.write(action.command ? COMMAND_USAGE[action.command] : USAGE);
         return;
     }
     if (action.kind === 'version') {
         process.stdout.write(`${SERVER_VERSION}\n`);
         return;
     }
-    const { config } = action;
+    if (action.kind === 'connect' || action.kind === 'disconnect' || action.kind === 'status') {
+        if (action.options.apiUrlNote !== undefined) {
+            process.stdout.write(`${action.options.apiUrlNote}\n`);
+        }
+        // A terminal command says what happened in plain text; logs stay quiet.
+        const store = await openTokenStore({
+            warn: (message) => process.stderr.write(`${SERVER_NAME}: ${message}\n`),
+        });
+        const io = {
+            out: (text) => process.stdout.write(text),
+            err: (text) => process.stderr.write(`${SERVER_NAME}: ${text}`),
+            store,
+            logger: createLogger({ level: 'error' }),
+            ask: async (question) => {
+                const rl = createInterface({ input: process.stdin, output: process.stdout });
+                // Without a terminal or input (stdin closed), the answer is empty: not saved.
+                const closed = new Promise((resolve) => rl.once('close', () => {
+                    resolve('');
+                }));
+                try {
+                    return await Promise.race([rl.question(question), closed]);
+                }
+                finally {
+                    rl.close();
+                }
+            },
+        };
+        process.exitCode =
+            action.kind === 'connect'
+                ? await runConnect(action.options, io)
+                : action.kind === 'disconnect'
+                    ? await runDisconnect(action.options, io)
+                    : await runStatus(action.options, io);
+        return;
+    }
+    let { config } = action;
+    const early = [];
+    let clearSaved;
+    if (config.channel !== undefined) {
+        // Channel mode: the API connect saved for the folder, unless --api-url says otherwise.
+        const store = await openTokenStore({ warn: (message) => early.push(message) });
+        const saved = config.channel.apiUrlFlag
+            ? undefined
+            : await savedApiUrl(store, config.channel.folder);
+        if (saved !== undefined) {
+            try {
+                config = { ...config, apiUrl: parseApiUrl(saved) };
+            }
+            catch {
+                early.push('The API saved for this folder is not valid; using BUILDIT_API_URL or the default.');
+            }
+        }
+    }
+    if (config.channel !== undefined && config.token === undefined) {
+        // Channel mode without a session token in BUILDIT_TOKEN: the token connect saved for the folder.
+        const store = await openTokenStore({ warn: () => undefined });
+        const key = sessionKey(config.channel.folder, config.apiUrl);
+        const token = await store.get(key);
+        if (token === undefined) {
+            process.stderr.write(`${SERVER_NAME}: No buildIt.Social session is saved for ${config.channel.folder}. In a terminal in that folder, run: npx -y @kammcs/buildit-mcp@latest connect --project <KEY>\n`);
+            process.exitCode = 2;
+            return;
+        }
+        const folder = config.channel.folder;
+        const apiUrl = config.apiUrl;
+        config = { ...config, token };
+        clearSaved = async () => {
+            // The token, and the record of its deployment, as disconnect does.
+            await forgetSession(store, folder, apiUrl);
+        };
+    }
     const logger = createLogger({
         level: config.logLevel,
         ...(config.token ? { secrets: [config.token] } : {}),
     });
-    for (const warning of config.warnings)
+    for (const warning of [...config.warnings, ...early])
         logger.warn(warning);
     const unknown = unknownToolNames(CATALOG, config.excludeTools);
     if (unknown.length > 0) {
@@ -44,12 +121,51 @@ async function main() {
     logger.info('starting', {
         version: SERVER_VERSION,
         mode: config.mode,
+        channel: config.channel !== undefined,
         api_url: config.apiUrl,
         toolsets: config.toolsets,
         read_only: config.readOnly,
     });
     if (config.mode === 'stdio') {
-        const handle = startStdio(config, logger);
+        // One channel server per folder: the plugin's first, else the first to start.
+        let channelOwner = true;
+        let channelLock;
+        if (config.channel !== undefined) {
+            try {
+                channelLock = acquireChannelLock(config.channel.folder, config.apiUrl, {
+                    plugin: config.channel.fromPlugin,
+                });
+                channelOwner = channelLock !== undefined;
+                if (channelLock?.preempted !== undefined) {
+                    logger.warn("another buildit server without the plugin was receiving this folder's messages; the plugin's server takes them over, and that one stops polling. Remove it (claude mcp remove <name>)", { other_pid: channelLock.preempted });
+                }
+                else if (channelLock !== undefined && !channelLock.plugin) {
+                    logger.info("this server receives the folder's messages; Claude Code shows them only when it was started with --dangerously-load-development-channels server:<name> (or use the buildit plugin)");
+                }
+            }
+            catch (err) {
+                // Without a lock folder, serve as the channel (as before locks existed).
+                logger.warn('could not take the channel lock; serving as the channel', { error: err });
+            }
+        }
+        const handle = startStdio(config, logger, {
+            channelOwner,
+            ...(channelLock === undefined ? {} : { channelLock }),
+            // The folder's open tool approvals, next to its lock files.
+            ...(config.channel !== undefined && channelOwner
+                ? {
+                    approvalJournal: join(defaultLockDir(), `${sessionKey(config.channel.folder, config.apiUrl)}.approvals.json`),
+                }
+                : {}),
+            onSessionEnded: async (reason) => {
+                if (reason !== 'token_revoked' && reason !== 'token_expired')
+                    return;
+                if (clearSaved === undefined)
+                    return;
+                await clearSaved().catch(() => undefined);
+                logger.warn('the session was revoked or has expired, so its saved token is cleared; run "buildit-mcp connect" in the folder to connect again');
+            },
+        });
         const stop = () => {
             void handle.close().finally(() => process.exit(0));
         };

package/dist/log.js

@@ -14,13 +14,14 @@ const REDACTED = '[redacted]';
 /** Field names whose values are never logged. */
 const SECRET_KEY = /(authorization|token|secret|password|api[-_]?key|cookie)/i;
 /**
- * Bearer credentials and buildIt personal access tokens, wherever they appear
- * in a string. The token pattern has no word boundary in front, so a token
+ * Bearer credentials and buildIt personal access and session tokens, wherever
+ * they appear in a string. The token pattern has no word boundary in front, so a token
  * glued to other text (`MY_buildit_pat_...`, `x1buildit_pat_...`) is caught too.
  */
 const SECRET_PATTERNS = [
     /\bBearer\s+[^\s"',;]+/gi,
     /buildit_pat_[A-Za-z0-9_]+/g,
+    /buildit_ags_[A-Za-z0-9_]+/g,
 ];
 export function scrubString(value, secrets = []) {
     let out = value;