botmancers 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to the `botmancers` npm package. It uses
+[Semantic Versioning](https://semver.org): while the package is `0.x`, a
+minor version may change the CLI or configuration. The MCP tool contract is
+versioned separately, as `botmancers.mcp.v1`.
+
+## [0.1.0] - 2026-10-15
+
+### Added
+
+- `botmancers` CLI (`npx botmancers`), a standalone Streamable HTTP MCP bridge
+  that forwards the `botmancers.mcp.v1` tools to a Botmancers app's
+  `/api/v0/mcp` endpoint.
+- Configuration through `BOTMANCERS_URL`, `BOTMANCERS_SERVICE_TOKEN`,
+  `BOTMANCERS_MCP_TOKEN`, `BOTMANCERS_MCP_HOST`, and `BOTMANCERS_MCP_PORT`,
+  with `--botmancers-url`, `--host`, and `--port` flags. The bridge binds
+  loopback by default.
+- A startup preflight against Botmancers. Configuration, listen,
+  reachability, and credential failures each have their own exit code, and
+  their messages are redacted.
+- `GET /healthz` liveness endpoint.
+- The versioned tool schema at `schemas/botmancers.mcp.v1.tools.json`, and a
+  library export (`createBridge`, `parseCli`, and related functions).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuke Muraoka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# botmancers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Botmancers MCP bridge. It is a standalone [MCP](https://modelcontextprotocol.io)
+server, using Streamable HTTP, that lets an external agent hand a task to a
+Botmancers coordinator Agent and poll the result. Examples of such agents are
+Cursor's Grok Bot or any other MCP client.
+
+The bridge runs on your machine next to the Botmancers app. MCP clients
+authenticate to the bridge with their own token. The bridge forwards their
+tool calls to Botmancers with a service token, and clients never see that
+token. The tool contract is `botmancers.mcp.v1`, and its JSON schema ships in
+this package at `schemas/botmancers.mcp.v1.tools.json`.
+
+| Tool | What it does |
+| --- | --- |
+| `botmancers_start_task` | Sends one objective to an allowlisted coordinator. Returns `request_id` and `conversation_id`. |
+| `botmancers_get_request` | Polls a request until `terminal`. Returns its `result` or `failure`. |
+| `botmancers_get_conversation` | Reads the conversation the task opened. |
+| `botmancers_health` | Shows the caller's identity and the available coordinators. |
+
+Requirements: Node.js 20 or newer and a running Botmancers app.
+
+## Quick start
+
+1. **Create two tokens.** The service token authenticates the bridge to
+   Botmancers. The MCP token authenticates MCP clients to the bridge.
+
+   ```sh
+   export BOTMANCERS_SERVICE_TOKEN=$(openssl rand -hex 32)
+   export BOTMANCERS_MCP_TOKEN=$(openssl rand -hex 32)
+   printf %s "$BOTMANCERS_SERVICE_TOKEN" | shasum -a 256   # -> <hex>, for the next step
+   ```
+
+2. **Configure the Botmancers app**, in the environment of its `npm start`.
+   Store only the token's digest there, and allowlist the coordinators the
+   bridge may use:
+
+   ```sh
+   BOTMANCERS_SERVICE_TOKENS="mcp-bridge=sha256:<hex>"
+   BOTMANCERS_MCP_COORDINATORS="Tank"
+   ```
+
+3. **Start the bridge:**
+
+   ```sh
+   BOTMANCERS_URL=http://127.0.0.1:43123 npx botmancers
+   ```
+
+   It prints
+   `botmancers <version>: MCP bridge listening on http://127.0.0.1:43124/mcp ...`
+   and keeps running until you press Ctrl-C.
+
+4. **Connect an MCP client** to `http://127.0.0.1:43124/mcp` with the header
+   `Authorization: Bearer <BOTMANCERS_MCP_TOKEN>`. Then call
+   `botmancers_health`. It should return `status: "ok"` and each coordinator
+   with `available: true`.
+
+To pin an exact release, which is recommended for anything long-running:
+
+```sh
+BOTMANCERS_URL=http://127.0.0.1:43123 npx botmancers@0.1.0
+```
+
+## Configuration
+
+| Variable | Flag | Required | Default | Meaning |
+| --- | --- | --- | --- | --- |
+| `BOTMANCERS_URL` | `--botmancers-url` | yes | none | Base URL of the Botmancers app, for example `http://127.0.0.1:43123`. Must be `http://` or `https://`, with no credentials, query, or fragment. The bridge calls `<url>/api/v0/mcp`. |
+| `BOTMANCERS_SERVICE_TOKEN` | none (environment only) | yes | none | Bearer token the bridge sends to Botmancers. Its SHA-256 digest must be listed in the app's `BOTMANCERS_SERVICE_TOKENS`. |
+| `BOTMANCERS_MCP_TOKEN` | none (environment only) | yes | none | Bearer token MCP clients must send to the bridge. At least 16 characters, and must differ from the service token. |
+| `BOTMANCERS_MCP_HOST` | `--host` | no | `127.0.0.1` | Address to bind. |
+| `BOTMANCERS_MCP_PORT` | `--port` | no | `43124` | Port to bind. `0` picks a free port. |
+
+Flags override environment variables. Secrets are accepted only from the
+environment, because command-line flags are visible to every local user in
+the process list. `--service-token` and `--mcp-token` are refused.
+
+`botmancers --help` lists the options. `botmancers --version` prints the
+installed version.
+
+### Endpoints
+
+- `POST /mcp` is MCP Streamable HTTP. It is stateless and answers with
+  `application/json`, using protocol versions `2025-11-25`, `2025-06-18`, and
+  `2025-03-26`. Every request needs `Authorization: Bearer <BOTMANCERS_MCP_TOKEN>`.
+  `GET` and `DELETE` return 405 because the bridge opens no SSE stream and
+  issues no session. Bodies over 256 KiB are refused with 413.
+- `GET /healthz` returns `{"status":"ok","contract":"botmancers.mcp.v1","version":"<version>"}`.
+  It needs no authentication and does not call Botmancers. Use the
+  `botmancers_health` tool to check the end-to-end path.
+
+### Startup checks and exit codes
+
+Before listening, the bridge validates its configuration. It then sends
+Botmancers an MCP `initialize` with the service token. That call writes
+nothing and does not count against the rate limit. No error message contains
+a token.
+
+| Exit | Meaning | What to do |
+| --- | --- | --- |
+| `0` | Stopped by SIGINT or SIGTERM. | Nothing. |
+| `2` | Configuration error: a missing or invalid variable or flag. Every problem is listed. | Fix the listed settings. |
+| `3` | Cannot listen, for example because the port is already in use. | Stop the other process, or choose another `--port`. |
+| `4` | Botmancers is unreachable, or `BOTMANCERS_URL` is not a Botmancers MCP endpoint (the server is not named `botmancers` or lacks a `botmancers.mcp.v1` tool). | Start the app, or fix the URL. |
+| `5` | Botmancers rejected the service token, or the app has no service tokens configured. | Check `BOTMANCERS_SERVICE_TOKEN` against the app's `BOTMANCERS_SERVICE_TOKENS`. |
+
+If Botmancers becomes unavailable after startup, tool calls return a JSON-RPC
+error (`-32603`) whose `data.code` is `botmancers_unreachable`,
+`botmancers_unauthorized`, or a similar code. The bridge keeps running. When
+Botmancers rate-limits a tool call, the bridge answers 429 and passes on
+`Retry-After`.
+
+## Network exposure
+
+- **Loopback by default.** The bridge binds `127.0.0.1`. While it is bound to
+  loopback, it refuses any request whose `Host` is not a loopback name, and
+  any `Origin` other than its own. This guards against DNS rebinding. The
+  bridge does not support CORS, so browser pages cannot call it.
+- **Remote MCP consumers.** A hosted agent such as Grok Bot cannot reach your
+  loopback address. Put the bridge behind an HTTPS endpoint that you control,
+  such as a TLS-terminating reverse proxy or tunnel, or reach it over a
+  private network such as a VPN or tailnet. Do not expose it as plain HTTP on
+  the public internet: the MCP token would travel in cleartext. If you bind a
+  non-loopback address (`--host 0.0.0.0`), the bridge prints a warning. Keep
+  the proxy or network in front of it.
+- **Botmancers itself** should stay on loopback, with the bridge on the same
+  machine. If `BOTMANCERS_URL` points to another host over plain `http://`,
+  the bridge warns that the service token is sent unencrypted. Use `https://`
+  in that case.
+- Rotate a token by changing it and restarting the bridge. For the service
+  token, also update its digest in the app's `BOTMANCERS_SERVICE_TOKENS`.
+
+## Upgrade
+
+`npx botmancers` resolves the newest release on the `latest` tag the first
+time. After that, npx may reuse its cached copy. To move deliberately, name
+the version:
+
+```sh
+npx botmancers@0.1.0 --version
+```
+
+To upgrade a project-local or global install:
+
+```sh
+npm install botmancers@latest       # project-local
+npm install -g botmancers@latest    # global
+```
+
+Check the [changelog](CHANGELOG.md) before upgrading across a minor version
+while the package is `0.x`. The tool contract version, `botmancers.mcp.v1`,
+changes only with a major contract revision.
+
+## Uninstall
+
+Stop the bridge with Ctrl-C or SIGTERM, then remove the package:
+
+```sh
+npm uninstall botmancers        # project-local
+npm uninstall -g botmancers     # global
+npm cache clean --force         # optional: drops npx's cached copy
+```
+
+Finally, remove the bridge's entry from the app's `BOTMANCERS_SERVICE_TOKENS`
+so its token stops working. The bridge stores no files of its own.
+
+## Library use
+
+The package also exports the bridge for embedding:
+
+```js
+import { createBridge, parseCli } from 'botmancers';
+
+const command = parseCli([], process.env);
+if (command.kind === 'serve') {
+  const bridge = createBridge({ config: command.config });
+  await bridge.upstream.preflight();
+  const address = await bridge.listen();
+}
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly config: 2;
+    readonly listen: 3;
+    readonly unavailable: 4;
+    readonly credentials: 5;
+};
+export interface CliIo {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+export declare function main(argv: string[], env: NodeJS.ProcessEnv, io?: CliIo): Promise<number | 'serving'>;

package/dist/cli.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// `npx botmancers`: validate configuration, check that Botmancers is reachable
+// and accepts the service token, then serve the MCP bridge until a signal.
+import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { ConfigError, ENV, HELP, isLoopbackHost, parseCli } from './config.js';
+import { packageVersion } from './contract.js';
+import { createRedactor } from './redact.js';
+import { HEALTH_PATH, MCP_PATH, createBridge } from './server.js';
+import { UpstreamError } from './upstream.js';
+export const EXIT = { ok: 0, config: 2, listen: 3, unavailable: 4, credentials: 5 };
+const processIo = {
+    stdout: text => process.stdout.write(text),
+    stderr: text => process.stderr.write(text),
+};
+function urlHost(url) {
+    return new URL(url).hostname;
+}
+export async function main(argv, env, io = processIo) {
+    // Redact whatever secrets the environment holds before anything is printed.
+    const redact = createRedactor([env[ENV.serviceToken]?.trim(), env[ENV.mcpToken]?.trim()]);
+    const err = (line) => io.stderr(`${redact(line)}\n`);
+    let command;
+    try {
+        command = parseCli(argv, env);
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError))
+            throw error;
+        err('botmancers: configuration error:');
+        for (const problem of error.problems)
+            err(`  - ${problem}`);
+        err('Run botmancers --help for all options.');
+        return EXIT.config;
+    }
+    if (command.kind === 'help') {
+        io.stdout(HELP);
+        return EXIT.ok;
+    }
+    if (command.kind === 'version') {
+        io.stdout(`${packageVersion()}\n`);
+        return EXIT.ok;
+    }
+    const { config } = command;
+    const bridge = createBridge({ config, logger: { info: err, error: err } });
+    if (!isLoopbackHost(config.host)) {
+        err(`botmancers: warning: binding ${config.host}, not loopback. Expose the bridge only on a private network or behind an HTTPS (TLS-terminating) proxy.`);
+    }
+    if (config.botmancersUrl.startsWith('http://') && !isLoopbackHost(urlHost(config.botmancersUrl))) {
+        err(`botmancers: warning: ${ENV.url} uses plain http:// to a non-loopback host; the service token is sent unencrypted. Use https://.`);
+    }
+    try {
+        await bridge.upstream.preflight();
+    }
+    catch (error) {
+        if (!(error instanceof UpstreamError))
+            throw error;
+        err(`botmancers: ${error.message}`);
+        return error.kind === 'unauthorized' || error.kind === 'unconfigured' ? EXIT.credentials : EXIT.unavailable;
+    }
+    let address;
+    try {
+        address = await bridge.listen();
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'EADDRINUSE') {
+            err(`botmancers: port ${config.port} on ${config.host} is already in use. Stop the other process or choose another port with --port or ${ENV.port}.`);
+        }
+        else if (code === 'EADDRNOTAVAIL') {
+            err(`botmancers: cannot bind ${config.host}: no such local address. Check --host or ${ENV.host}.`);
+        }
+        else if (code === 'EACCES') {
+            err(`botmancers: permission denied binding ${config.host}:${config.port}. Use a port above 1023.`);
+        }
+        else {
+            err(`botmancers: cannot listen on ${config.host}:${config.port} (${code ?? error.message}).`);
+        }
+        return EXIT.listen;
+    }
+    const shown = address.family === 'IPv6' ? `[${address.address}]` : address.address;
+    err(`botmancers ${packageVersion()}: MCP bridge listening on http://${shown}:${address.port}${MCP_PATH} (health: ${HEALTH_PATH}) -> ${config.botmancersUrl}`);
+    const stop = (signal) => {
+        err(`botmancers: ${signal} received, shutting down.`);
+        bridge.close().then(() => process.exit(EXIT.ok));
+    };
+    process.once('SIGINT', () => stop('SIGINT'));
+    process.once('SIGTERM', () => stop('SIGTERM'));
+    return 'serving';
+}
+function invokedDirectly() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    main(process.argv.slice(2), process.env).then(outcome => {
+        if (outcome !== 'serving')
+            process.exitCode = outcome;
+    }, error => {
+        const redact = createRedactor([process.env[ENV.serviceToken]?.trim(), process.env[ENV.mcpToken]?.trim()]);
+        process.stderr.write(`botmancers: unexpected error: ${redact(error?.message ?? String(error))}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+export declare const ENV: {
+    readonly url: "BOTMANCERS_URL";
+    readonly serviceToken: "BOTMANCERS_SERVICE_TOKEN";
+    readonly mcpToken: "BOTMANCERS_MCP_TOKEN";
+    readonly host: "BOTMANCERS_MCP_HOST";
+    readonly port: "BOTMANCERS_MCP_PORT";
+};
+export declare const DEFAULT_HOST = "127.0.0.1";
+export declare const DEFAULT_PORT = 43124;
+export declare const MIN_MCP_TOKEN_LENGTH = 16;
+export interface BridgeConfig {
+    botmancersUrl: string;
+    serviceToken: string;
+    mcpToken: string;
+    host: string;
+    port: number;
+}
+export type CliCommand = {
+    kind: 'help';
+} | {
+    kind: 'version';
+} | {
+    kind: 'serve';
+    config: BridgeConfig;
+};
+export declare class ConfigError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+export declare function isLoopbackHost(host: string): boolean;
+export declare function parseBotmancersUrl(raw: string): {
+    url?: string;
+    problem?: string;
+};
+export declare function parseCli(argv: string[], env: NodeJS.ProcessEnv): CliCommand;
+export declare const HELP: string;

package/dist/config.js

@@ -0,0 +1,188 @@
+// Bridge configuration: environment variables, with command-line flags for
+// the non-secret settings. Secrets are accepted only from the environment
+// (flags are visible to every local user through the process list).
+import { isIP } from 'node:net';
+export const ENV = {
+    url: 'BOTMANCERS_URL',
+    serviceToken: 'BOTMANCERS_SERVICE_TOKEN',
+    mcpToken: 'BOTMANCERS_MCP_TOKEN',
+    host: 'BOTMANCERS_MCP_HOST',
+    port: 'BOTMANCERS_MCP_PORT',
+};
+export const DEFAULT_HOST = '127.0.0.1';
+export const DEFAULT_PORT = 43124;
+export const MIN_MCP_TOKEN_LENGTH = 16;
+export class ConfigError extends Error {
+    problems;
+    constructor(problems) {
+        super(problems.join('\n'));
+        this.name = 'ConfigError';
+        this.problems = problems;
+    }
+}
+const FLAGS = {
+    '--botmancers-url': 'url',
+    '--host': 'host',
+    '--port': 'port',
+};
+const SECRET_FLAGS = ['--service-token', '--mcp-token', '--token'];
+export function isLoopbackHost(host) {
+    const bare = host.replace(/^\[|\]$/g, '').toLowerCase();
+    return bare === 'localhost' || bare === '::1' || /^127(?:\.\d{1,3}){3}$/.test(bare);
+}
+function validToken(value) {
+    return /^[\x21-\x7e]+$/.test(value) && value.length <= 4096;
+}
+export function parseBotmancersUrl(raw) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        // Never echo the value: an operator may have pasted a token into it.
+        return { problem: `${ENV.url} is not a valid absolute URL. Expected something like http://127.0.0.1:43123.` };
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return { problem: `${ENV.url} must use http:// or https:// (got ${parsed.protocol}//).` };
+    }
+    if (parsed.username || parsed.password) {
+        return { problem: `${ENV.url} must not contain credentials; put the service token in ${ENV.serviceToken} instead.` };
+    }
+    if (parsed.search || parsed.hash) {
+        return { problem: `${ENV.url} must not contain a query string or fragment.` };
+    }
+    return { url: `${parsed.origin}${parsed.pathname.replace(/\/+$/, '')}` };
+}
+function parsePort(raw, source) {
+    const trimmed = raw.trim();
+    const port = /^\d+$/.test(trimmed) ? Number(trimmed) : NaN;
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        // Never echo the value: a token pasted into the wrong setting must not be printed.
+        return { problem: `${source} must be an integer port between 0 and 65535 (default ${DEFAULT_PORT}, 0 for any free port).` };
+    }
+    return { port };
+}
+function parseHost(raw, source) {
+    const host = raw.trim();
+    if (isIP(host.replace(/^\[|\]$/g, '')) || /^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?$/.test(host)) {
+        return { host: host.replace(/^\[|\]$/g, '') };
+    }
+    return { problem: `${source} must be an IP address or hostname to bind (default ${DEFAULT_HOST}).` };
+}
+// Parses argv (without node and script) and env into a command. Throws
+// ConfigError listing every problem, none of which contains a secret.
+export function parseCli(argv, env) {
+    const fromFlags = {};
+    const problems = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h' || arg === '--help')
+            return { kind: 'help' };
+        if (arg === '-v' || arg === '--version')
+            return { kind: 'version' };
+        const eq = arg.indexOf('=');
+        const name = eq > 0 ? arg.slice(0, eq) : arg;
+        if (SECRET_FLAGS.includes(name)) {
+            problems.push(`${name} is not accepted: pass secrets only through ${ENV.serviceToken} and ${ENV.mcpToken} environment variables.`);
+            if (eq < 0)
+                i++;
+            continue;
+        }
+        const key = FLAGS[name];
+        if (!key) {
+            // Echo only flag-shaped names; a stray positional value may be a pasted token.
+            problems.push(/^--?[a-z][a-z0-9-]{0,38}$/.test(name)
+                ? `Unknown argument ${JSON.stringify(name)}. Run botmancers --help for usage.`
+                : 'Unexpected positional argument (value not shown). Run botmancers --help for usage.');
+            continue;
+        }
+        const value = eq > 0 ? arg.slice(eq + 1) : argv[++i];
+        if (value === undefined || value === '') {
+            problems.push(`${name} needs a value.`);
+            continue;
+        }
+        fromFlags[key] = value;
+    }
+    const pick = (key) => {
+        const value = fromFlags[key] ?? env[ENV[key]];
+        return value === undefined || value.trim() === '' ? undefined : value.trim();
+    };
+    const rawUrl = pick('url');
+    let botmancersUrl = '';
+    if (!rawUrl) {
+        problems.push(`${ENV.url} is required: the Botmancers base URL, for example http://127.0.0.1:43123 (or pass --botmancers-url).`);
+    }
+    else {
+        const { url, problem } = parseBotmancersUrl(rawUrl);
+        if (problem)
+            problems.push(problem);
+        else
+            botmancersUrl = url;
+    }
+    const serviceToken = env[ENV.serviceToken]?.trim() ?? '';
+    if (!serviceToken) {
+        problems.push(`${ENV.serviceToken} is required: the bearer token whose SHA-256 digest Botmancers lists in BOTMANCERS_SERVICE_TOKENS.`);
+    }
+    else if (!validToken(serviceToken)) {
+        problems.push(`${ENV.serviceToken} must be a single printable token without spaces.`);
+    }
+    const mcpToken = env[ENV.mcpToken]?.trim() ?? '';
+    if (!mcpToken) {
+        problems.push(`${ENV.mcpToken} is required: the bearer token MCP clients must send to this bridge (generate one with: openssl rand -hex 32).`);
+    }
+    else if (!validToken(mcpToken) || mcpToken.length < MIN_MCP_TOKEN_LENGTH) {
+        problems.push(`${ENV.mcpToken} must be a single printable token of at least ${MIN_MCP_TOKEN_LENGTH} characters without spaces.`);
+    }
+    else if (mcpToken === serviceToken) {
+        problems.push(`${ENV.mcpToken} must differ from ${ENV.serviceToken}: MCP clients must not hold the Botmancers service token.`);
+    }
+    let host = DEFAULT_HOST;
+    const rawHost = pick('host');
+    if (rawHost) {
+        const parsed = parseHost(rawHost, fromFlags.host ? '--host' : ENV.host);
+        if (parsed.problem)
+            problems.push(parsed.problem);
+        else
+            host = parsed.host;
+    }
+    let port = DEFAULT_PORT;
+    const rawPort = pick('port');
+    if (rawPort) {
+        const parsed = parsePort(rawPort, fromFlags.port ? '--port' : ENV.port);
+        if (parsed.problem)
+            problems.push(parsed.problem);
+        else
+            port = parsed.port;
+    }
+    if (problems.length)
+        throw new ConfigError(problems);
+    return { kind: 'serve', config: { botmancersUrl, serviceToken, mcpToken, host, port } };
+}
+export const HELP = `Usage: botmancers [options]
+
+Run the Botmancers MCP bridge: a Streamable HTTP MCP server (contract
+botmancers.mcp.v1) that forwards tool calls to a running Botmancers app.
+
+Options:
+  --botmancers-url <url>  Botmancers base URL            (env ${ENV.url}, required)
+  --host <host>           Address to bind                (env ${ENV.host}, default ${DEFAULT_HOST})
+  --port <port>           Port to bind, 0 for any free   (env ${ENV.port}, default ${DEFAULT_PORT})
+  -h, --help              Show this help
+  -v, --version           Show the package version
+
+Secrets (environment only, never flags):
+  ${ENV.serviceToken}   Bearer token this bridge sends to Botmancers (required)
+  ${ENV.mcpToken}       Bearer token MCP clients must send to this bridge (required, >= ${MIN_MCP_TOKEN_LENGTH} chars)
+
+Endpoints:
+  POST /mcp       MCP Streamable HTTP (Authorization: Bearer $${ENV.mcpToken})
+  GET  /healthz   Liveness (no authentication, no upstream call)
+
+Example:
+  ${ENV.url}=http://127.0.0.1:43123 \\
+  ${ENV.serviceToken}=... ${ENV.mcpToken}=$(openssl rand -hex 32) \\
+  npx botmancers
+
+Exit codes: 0 stopped by signal, 2 configuration, 3 cannot listen,
+4 Botmancers unreachable or incompatible, 5 credentials rejected.
+`;

package/dist/contract.d.ts

@@ -0,0 +1,21 @@
+export declare const MCP_CONTRACT = "botmancers.mcp.v1";
+export declare const MCP_PROTOCOL_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26"];
+export declare const MCP_INSTRUCTIONS: string;
+export interface McpTool {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+}
+export interface ToolContract {
+    contract: string;
+    tools: McpTool[];
+}
+export declare const TOOL_SCHEMA_URL: import("url").URL;
+export declare function loadToolContract(): ToolContract;
+export declare function negotiateProtocolVersion(requested: unknown): string;
+export declare const PACKAGE_JSON_URL: import("url").URL;
+export declare function packageVersion(): string;

package/dist/contract.js

@@ -0,0 +1,28 @@
+// The botmancers.mcp.v1 tool contract, as captured by the Botmancers app in
+// docs/contracts/mcp-bridge-v1.tools.json and shipped here as a versioned
+// schema file. The bridge serves tools/list from it and forwards only these
+// tool names to Botmancers; it never alters the contract.
+import { readFileSync } from 'node:fs';
+export const MCP_CONTRACT = 'botmancers.mcp.v1';
+// Newest first; an unknown client version is answered with the newest.
+// Same list as the Botmancers app's /api/v0/mcp endpoint.
+export const MCP_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26'];
+export const MCP_INSTRUCTIONS = 'Botmancers bridge (botmancers.mcp.v1). Start a task with botmancers_start_task, then poll botmancers_get_request '
+    + 'until terminal and read botmancers_get_conversation; it stays active while the coordinator\'s follow-up work is open.';
+export const TOOL_SCHEMA_URL = new URL('../schemas/botmancers.mcp.v1.tools.json', import.meta.url);
+export function loadToolContract() {
+    const parsed = JSON.parse(readFileSync(TOOL_SCHEMA_URL, 'utf8'));
+    if (parsed.contract !== MCP_CONTRACT || !Array.isArray(parsed.tools)) {
+        throw new Error(`The bundled tool schema is not ${MCP_CONTRACT}; reinstall the botmancers package.`);
+    }
+    return parsed;
+}
+export function negotiateProtocolVersion(requested) {
+    return typeof requested === 'string' && MCP_PROTOCOL_VERSIONS.includes(requested)
+        ? requested
+        : MCP_PROTOCOL_VERSIONS[0];
+}
+export const PACKAGE_JSON_URL = new URL('../package.json', import.meta.url);
+export function packageVersion() {
+    return JSON.parse(readFileSync(PACKAGE_JSON_URL, 'utf8')).version;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { MCP_CONTRACT, MCP_PROTOCOL_VERSIONS, TOOL_SCHEMA_URL, loadToolContract, negotiateProtocolVersion, packageVersion, type McpTool, type ToolContract, } from './contract.js';
+export { DEFAULT_HOST, DEFAULT_PORT, ENV, ConfigError, isLoopbackHost, parseBotmancersUrl, parseCli, type BridgeConfig, type CliCommand, } from './config.js';
+export { createRedactor, REDACTED, type Redactor } from './redact.js';
+export { UPSTREAM_PATH, UpstreamError, createUpstream, type Upstream, type UpstreamFailureKind } from './upstream.js';
+export { HEALTH_PATH, MAX_BODY_BYTES, MCP_PATH, createBridge, type Bridge, type BridgeOptions, type Logger } from './server.js';
+export { EXIT, main } from './cli.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+// Library surface of the `botmancers` package: the botmancers.mcp.v1 MCP
+// bridge. The `botmancers` binary (./cli) is the supported entry point; these
+// exports let a Node program embed the same bridge.
+export { MCP_CONTRACT, MCP_PROTOCOL_VERSIONS, TOOL_SCHEMA_URL, loadToolContract, negotiateProtocolVersion, packageVersion, } from './contract.js';
+export { DEFAULT_HOST, DEFAULT_PORT, ENV, ConfigError, isLoopbackHost, parseBotmancersUrl, parseCli, } from './config.js';
+export { createRedactor, REDACTED } from './redact.js';
+export { UPSTREAM_PATH, UpstreamError, createUpstream } from './upstream.js';
+export { HEALTH_PATH, MAX_BODY_BYTES, MCP_PATH, createBridge } from './server.js';
+export { EXIT, main } from './cli.js';

package/dist/redact.d.ts

@@ -0,0 +1,3 @@
+export declare const REDACTED = "[REDACTED]";
+export type Redactor = (text: string) => string;
+export declare function createRedactor(secrets: Array<string | undefined>): Redactor;