botmancers 0.0.0-stage → 0.1.0

package/dist/redact.js

@@ -0,0 +1,16 @@
+// Secrets never reach logs or error messages: every line the bridge writes
+// passes through a redactor that knows the configured tokens.
+export const REDACTED = '[REDACTED]';
+export function createRedactor(secrets) {
+    const known = [...new Set(secrets.filter((secret) => !!secret && secret.length >= 4))]
+        .sort((a, b) => b.length - a.length);
+    return text => {
+        let out = text;
+        for (const secret of known)
+            out = out.split(secret).join(REDACTED);
+        // Belt and braces: any bearer credential or URL userinfo that slipped in.
+        return out
+            .replace(/(Bearer[ \t]+)[A-Za-z0-9._~+/=-]{12,}/gi, `$1${REDACTED}`)
+            .replace(/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi, `$1${REDACTED}@`);
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,33 @@
+import { type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import type { BridgeConfig } from './config.js';
+import { type Redactor } from './redact.js';
+import { type Upstream } from './upstream.js';
+export declare const MCP_PATH = "/mcp";
+export declare const HEALTH_PATH = "/healthz";
+export declare const MAX_BODY_BYTES: number;
+export declare const JSON_RPC: {
+    parseError: number;
+    invalidRequest: number;
+    methodNotFound: number;
+    invalidParams: number;
+    internalError: number;
+};
+export interface Logger {
+    info(message: string): void;
+    error(message: string): void;
+}
+export interface BridgeOptions {
+    config: BridgeConfig;
+    logger?: Logger;
+    upstream?: Upstream;
+}
+export interface Bridge {
+    server: Server;
+    redact: Redactor;
+    upstream: Upstream;
+    listen(): Promise<AddressInfo>;
+    close(): Promise<void>;
+}
+export declare const defaultLogger: Logger;
+export declare function createBridge(options: BridgeOptions): Bridge;

package/dist/server.js

@@ -0,0 +1,240 @@
+// The standalone bridge: MCP Streamable HTTP at POST /mcp, stateless, with
+// application/json responses (no session id, no server-initiated SSE
+// stream, so GET and DELETE are 405), and an unauthenticated GET /healthz.
+//
+// initialize, ping, and tools/list are answered locally from the bundled
+// botmancers.mcp.v1 schema; tools/call for a contract tool is forwarded
+// unchanged to Botmancers' /api/v0/mcp with the service token. MCP clients
+// authenticate to the bridge with their own bearer token and never see the
+// service token.
+//
+// DNS-rebinding guard: when bound to a loopback address, Host must be a
+// loopback host; an Origin header, when present, must be exactly
+// http://<loopback Host>. The endpoint has no CORS support.
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { isLoopbackHost } from './config.js';
+import { MCP_CONTRACT, MCP_INSTRUCTIONS, MCP_PROTOCOL_VERSIONS, loadToolContract, negotiateProtocolVersion, packageVersion } from './contract.js';
+import { createRedactor } from './redact.js';
+import { UpstreamError, createUpstream } from './upstream.js';
+export const MCP_PATH = '/mcp';
+export const HEALTH_PATH = '/healthz';
+export const MAX_BODY_BYTES = 256 * 1024;
+export const JSON_RPC = { parseError: -32700, invalidRequest: -32600, methodNotFound: -32601, invalidParams: -32602, internalError: -32603 };
+function rpcError(id, code, message, data) {
+    return { jsonrpc: '2.0', id, error: { code, message, ...(data === undefined ? {} : { data }) } };
+}
+function sendJson(res, status, body, headers = {}) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', ...headers });
+    res.end(text);
+}
+function envelope(res, status, code, message, headers = {}) {
+    sendJson(res, status, { error: { code, message } }, headers);
+}
+class BodyTooLarge extends Error {
+}
+function readBody(req) {
+    const declared = req.headers['content-length'];
+    if (declared !== undefined && !(/^\d+$/.test(declared.trim()) && Number(declared) <= MAX_BODY_BYTES)) {
+        return Promise.reject(new BodyTooLarge());
+    }
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.byteLength;
+            if (size > MAX_BODY_BYTES) {
+                req.pause();
+                reject(new BodyTooLarge());
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+function digest(value) {
+    return createHash('sha256').update(value, 'utf8').digest();
+}
+export const defaultLogger = {
+    info: message => process.stderr.write(`${message}\n`),
+    error: message => process.stderr.write(`${message}\n`),
+};
+export function createBridge(options) {
+    const { config } = options;
+    const redact = createRedactor([config.serviceToken, config.mcpToken]);
+    const base = options.logger ?? defaultLogger;
+    const logger = { info: m => base.info(redact(m)), error: m => base.error(redact(m)) };
+    const upstream = options.upstream ?? createUpstream({ botmancersUrl: config.botmancersUrl, serviceToken: config.serviceToken });
+    const contract = loadToolContract();
+    const toolNames = new Set(contract.tools.map(tool => tool.name));
+    const version = packageVersion();
+    const expectedToken = digest(config.mcpToken);
+    const loopbackOnly = isLoopbackHost(config.host);
+    function authorized(req) {
+        const match = /^Bearer[ \t]+(\S+)[ \t]*$/i.exec(req.headers.authorization ?? '');
+        if (!match || match[1].length > 4096)
+            return false;
+        return timingSafeEqual(digest(match[1]), expectedToken);
+    }
+    // Null when Host and Origin are trusted, else [code, message].
+    function rebindingRefusal(req) {
+        const host = (req.headers.host ?? '').trim().toLowerCase();
+        if (loopbackOnly && !isLoopbackHost(host.replace(/:\d+$/, ''))) {
+            return ['host_not_allowed', 'The request did not arrive on a loopback host.'];
+        }
+        const origin = req.headers.origin;
+        if (origin === undefined)
+            return null;
+        if (isLoopbackHost(host.replace(/:\d+$/, '')) && origin.trim().toLowerCase() === `http://${host}`)
+            return null;
+        return ['origin_not_allowed', 'Cross-origin requests are not accepted.'];
+    }
+    async function handleMessage(message) {
+        if (!message || typeof message !== 'object' || Array.isArray(message)) {
+            return { status: 400, body: rpcError(null, JSON_RPC.invalidRequest, 'Invalid Request') };
+        }
+        const { jsonrpc, id, method, params } = message;
+        const hasId = typeof id === 'string' || (typeof id === 'number' && Number.isFinite(id));
+        if (jsonrpc !== '2.0' || (id !== undefined && !hasId))
+            return { status: 400, body: rpcError(null, JSON_RPC.invalidRequest, 'Invalid Request') };
+        if (typeof method !== 'string') {
+            // A response to a server request; this server sends none.
+            return hasId ? { status: 202 } : { status: 400, body: rpcError(null, JSON_RPC.invalidRequest, 'Invalid Request') };
+        }
+        if (!hasId)
+            return { status: 202 };
+        const requestId = id;
+        const p = (params && typeof params === 'object' && !Array.isArray(params) ? params : {});
+        switch (method) {
+            case 'initialize':
+                return {
+                    status: 200,
+                    body: {
+                        jsonrpc: '2.0',
+                        id: requestId,
+                        result: {
+                            protocolVersion: negotiateProtocolVersion(p.protocolVersion),
+                            capabilities: { tools: { listChanged: false } },
+                            serverInfo: { name: 'botmancers', title: 'Botmancers', version },
+                            instructions: MCP_INSTRUCTIONS,
+                        },
+                    },
+                };
+            case 'ping':
+                return { status: 200, body: { jsonrpc: '2.0', id: requestId, result: {} } };
+            case 'tools/list':
+                return { status: 200, body: { jsonrpc: '2.0', id: requestId, result: { tools: contract.tools } } };
+            case 'tools/call': {
+                const name = p.name;
+                if (typeof name !== 'string' || !toolNames.has(name)) {
+                    return { status: 200, body: rpcError(requestId, JSON_RPC.invalidParams, `Unknown tool: ${typeof name === 'string' ? name.slice(0, 100) : String(name)}`) };
+                }
+                try {
+                    const answer = await upstream.send({ jsonrpc: '2.0', id: requestId, method, params: p });
+                    return { status: 200, body: answer };
+                }
+                catch (error) {
+                    if (!(error instanceof UpstreamError))
+                        throw error;
+                    logger.error(`botmancers: tools/call ${name} failed: ${error.message}`);
+                    if (error.kind === 'rate_limited') {
+                        return {
+                            status: 429,
+                            body: { error: { code: 'rate_limited', message: 'Too many tool calls; retry later.' } },
+                            headers: error.retryAfter ? { 'retry-after': error.retryAfter } : {},
+                        };
+                    }
+                    return { status: 200, body: rpcError(requestId, JSON_RPC.internalError, redact(error.message), { code: `botmancers_${error.kind}` }) };
+                }
+            }
+            default:
+                return { status: 200, body: rpcError(requestId, JSON_RPC.methodNotFound, 'Method not found') };
+        }
+    }
+    async function handleMcpPost(req, res) {
+        const refusal = rebindingRefusal(req);
+        if (refusal)
+            return envelope(res, 403, refusal[0], refusal[1]);
+        if (!authorized(req)) {
+            return envelope(res, 401, 'unauthenticated', 'Send Authorization: Bearer <BOTMANCERS_MCP_TOKEN>.', { 'www-authenticate': 'Bearer realm="botmancers"' });
+        }
+        const protocol = req.headers['mcp-protocol-version'];
+        if (typeof protocol === 'string' && !MCP_PROTOCOL_VERSIONS.includes(protocol)) {
+            return envelope(res, 400, 'unsupported_protocol_version', `Supported MCP protocol versions: ${MCP_PROTOCOL_VERSIONS.join(', ')}.`);
+        }
+        const accept = req.headers.accept;
+        if (accept && !/application\/json|application\/\*|\*\/\*/i.test(accept)) {
+            return envelope(res, 406, 'not_acceptable', 'This server answers with application/json.');
+        }
+        let text;
+        try {
+            text = await readBody(req);
+        }
+        catch (error) {
+            if (error instanceof BodyTooLarge) {
+                res.setHeader('connection', 'close');
+                return envelope(res, 413, 'payload_too_large', 'The message is too large.');
+            }
+            throw error;
+        }
+        let message;
+        try {
+            message = JSON.parse(text);
+        }
+        catch {
+            return sendJson(res, 400, rpcError(null, JSON_RPC.parseError, 'Parse error'));
+        }
+        if (Array.isArray(message))
+            return sendJson(res, 400, rpcError(null, JSON_RPC.invalidRequest, 'Batched messages are not supported.'));
+        const answer = await handleMessage(message);
+        if (answer.body === undefined) {
+            res.writeHead(answer.status);
+            res.end();
+            return;
+        }
+        sendJson(res, answer.status, answer.body, answer.headers);
+    }
+    const server = createServer((req, res) => {
+        const path = (req.url ?? '/').split('?')[0];
+        const route = async () => {
+            if (path === HEALTH_PATH) {
+                if (req.method !== 'GET' && req.method !== 'HEAD')
+                    return envelope(res, 405, 'method_not_allowed', 'Use GET.', { allow: 'GET, HEAD' });
+                return sendJson(res, 200, { status: 'ok', contract: MCP_CONTRACT, version });
+            }
+            if (path === MCP_PATH) {
+                if (req.method === 'POST')
+                    return handleMcpPost(req, res);
+                return envelope(res, 405, 'method_not_allowed', 'This MCP endpoint accepts POST only (no server-initiated stream or session).', { allow: 'POST' });
+            }
+            return envelope(res, 404, 'not_found', `Not found. The MCP endpoint is POST ${MCP_PATH}.`);
+        };
+        route().catch(error => {
+            logger.error(`botmancers: internal error: ${error.message}`);
+            if (!res.headersSent)
+                envelope(res, 500, 'internal_error', 'The request could not be processed.');
+            else
+                res.end();
+        });
+    });
+    return {
+        server,
+        redact,
+        upstream,
+        listen: () => new Promise((resolve, reject) => {
+            const onError = (error) => reject(error);
+            server.once('error', onError);
+            server.listen(config.port, config.host, () => {
+                server.off('error', onError);
+                resolve(server.address());
+            });
+        }),
+        close: () => new Promise(resolve => {
+            server.close(() => resolve());
+            server.closeAllConnections();
+        }),
+    };
+}

package/dist/upstream.d.ts

@@ -0,0 +1,24 @@
+export declare const MCP_SERVER_NAME = "botmancers";
+export declare const UPSTREAM_PATH = "/api/v0/mcp";
+export declare const UPSTREAM_TIMEOUT_MS = 30000;
+export type UpstreamFailureKind = 'unreachable' | 'unauthorized' | 'unconfigured' | 'incompatible' | 'rate_limited' | 'error';
+export declare class UpstreamError extends Error {
+    readonly kind: UpstreamFailureKind;
+    readonly status: number | null;
+    readonly retryAfter: string | null;
+    constructor(kind: UpstreamFailureKind, message: string, status?: number | null, retryAfter?: string | null);
+}
+export interface UpstreamOptions {
+    botmancersUrl: string;
+    serviceToken: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare function createUpstream(options: UpstreamOptions): {
+    endpoint: string;
+    send: (message: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    preflight: () => Promise<{
+        serverVersion: string | null;
+    }>;
+};
+export type Upstream = ReturnType<typeof createUpstream>;

package/dist/upstream.js

@@ -0,0 +1,106 @@
+// The Botmancers side of the bridge: JSON-RPC messages POSTed to the app's
+// /api/v0/mcp endpoint with the service token. Failures are classified so
+// the CLI and the MCP surface can say what to fix, without echoing secrets.
+import { MCP_CONTRACT, MCP_PROTOCOL_VERSIONS, loadToolContract } from './contract.js';
+// The serverInfo.name the Botmancers app reports from initialize.
+export const MCP_SERVER_NAME = 'botmancers';
+export const UPSTREAM_PATH = '/api/v0/mcp';
+export const UPSTREAM_TIMEOUT_MS = 30_000;
+export class UpstreamError extends Error {
+    kind;
+    status;
+    retryAfter;
+    constructor(kind, message, status = null, retryAfter = null) {
+        super(message);
+        this.name = 'UpstreamError';
+        this.kind = kind;
+        this.status = status;
+        this.retryAfter = retryAfter;
+    }
+}
+function errorCodeOf(body) {
+    const code = body?.error?.code;
+    return typeof code === 'string' ? code.slice(0, 60) : null;
+}
+export function createUpstream(options) {
+    const endpoint = `${options.botmancersUrl}${UPSTREAM_PATH}`;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const timeoutMs = options.timeoutMs ?? UPSTREAM_TIMEOUT_MS;
+    async function send(message) {
+        let response;
+        try {
+            response = await fetchImpl(endpoint, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/json',
+                    authorization: `Bearer ${options.serviceToken}`,
+                    'mcp-protocol-version': MCP_PROTOCOL_VERSIONS[0],
+                },
+                body: JSON.stringify(message),
+                signal: AbortSignal.timeout(timeoutMs),
+                redirect: 'error',
+            });
+        }
+        catch (error) {
+            const cause = error.cause?.code ?? error.name;
+            throw new UpstreamError('unreachable', `Cannot reach Botmancers at ${options.botmancersUrl} (${cause}). Is the Botmancers app running, and is BOTMANCERS_URL correct?`);
+        }
+        const text = await response.text().catch(() => '');
+        let body = null;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            body = null;
+        }
+        const code = errorCodeOf(body);
+        if (response.status === 401 || response.status === 403) {
+            throw new UpstreamError('unauthorized', `Botmancers rejected the service token (HTTP ${response.status}${code ? ` ${code}` : ''}). Check that BOTMANCERS_SERVICE_TOKEN matches an entry of BOTMANCERS_SERVICE_TOKENS on the Botmancers server.`, response.status);
+        }
+        if (response.status === 503 && code === 'authentication_unavailable') {
+            throw new UpstreamError('unconfigured', 'Botmancers has no valid service tokens configured. Set BOTMANCERS_SERVICE_TOKENS on the Botmancers server (see the README).', response.status);
+        }
+        if (response.status === 429) {
+            throw new UpstreamError('rate_limited', 'Botmancers rate-limited this bridge; retry later.', 429, response.headers.get('retry-after'));
+        }
+        if (response.status === 404 || response.status === 405 || (response.status === 400 && code === 'unsupported_protocol_version')) {
+            throw new UpstreamError('incompatible', `Botmancers at ${options.botmancersUrl} does not serve a compatible MCP endpoint at ${UPSTREAM_PATH} (HTTP ${response.status}). Check BOTMANCERS_URL and upgrade Botmancers.`, response.status);
+        }
+        const isRpc = body && typeof body === 'object' && body.jsonrpc === '2.0';
+        if (!isRpc) {
+            throw new UpstreamError('error', `Botmancers answered HTTP ${response.status}${code ? ` ${code}` : ''} without a JSON-RPC response.`, response.status);
+        }
+        return body;
+    }
+    // initialize and tools/list round trips: authenticate, then confirm the
+    // endpoint is Botmancers and offers every botmancers.mcp.v1 tool. No tool
+    // is called, so preflight writes nothing and is not rate-limited.
+    async function preflight() {
+        const incompatible = (why) => new UpstreamError('incompatible', `${options.botmancersUrl}${UPSTREAM_PATH} is an MCP endpoint but not a compatible Botmancers (${why}). Check BOTMANCERS_URL and upgrade Botmancers.`);
+        const init = await send({
+            jsonrpc: '2.0',
+            id: 'botmancers-bridge-preflight',
+            method: 'initialize',
+            params: { protocolVersion: MCP_PROTOCOL_VERSIONS[0], capabilities: {}, clientInfo: { name: 'botmancers-bridge', version: '0' } },
+        });
+        const result = init.result;
+        if (!result)
+            throw new UpstreamError('incompatible', `Botmancers at ${options.botmancersUrl} refused MCP initialize.`);
+        if (result.serverInfo?.name !== MCP_SERVER_NAME)
+            throw incompatible(`serverInfo.name is not "${MCP_SERVER_NAME}"`);
+        if (!result.capabilities?.tools || typeof result.capabilities.tools !== 'object')
+            throw incompatible('no tools capability');
+        const list = await send({ jsonrpc: '2.0', id: 'botmancers-bridge-preflight-tools', method: 'tools/list', params: {} });
+        const offered = list.result?.tools;
+        if (!Array.isArray(offered))
+            throw incompatible('tools/list returned no tools');
+        const names = new Set(offered.map(tool => tool?.name));
+        const missing = loadToolContract().tools.map(tool => tool.name).filter(name => !names.has(name));
+        if (missing.length)
+            throw incompatible(`missing ${MCP_CONTRACT} tools: ${missing.join(', ')}`);
+        const version = result.serverInfo.version;
+        return { serverVersion: typeof version === 'string' ? version : null };
+    }
+    return { endpoint, send, preflight };
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "botmancers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Botmancers MCP bridge: a Streamable HTTP MCP server that hands tasks to a Botmancers coordinator (contract botmancers.mcp.v1).",
+  "keywords": [
+    "botmancers",
+    "mcp",
+    "model-context-protocol",
+    "streamable-http",
+    "agents"
+  ],
+  "license": "MIT",
+  "author": "Yusuke Muraoka",
+  "homepage": "https://github.com/not-so-fat/botmancers/tree/main/packages/mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/not-so-fat/botmancers/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/not-so-fat/botmancers.git",
+    "directory": "packages/mcp-server"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./schemas/botmancers.mcp.v1.tools.json": "./schemas/botmancers.mcp.v1.tools.json",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "botmancers": "dist/cli.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "schemas/*.json",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "canary"
+  },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/",
+    "check:pack": "node scripts/check-pack.mjs",
+    "smoke:install": "node scripts/smoke-install.mjs",
+    "release:check": "node scripts/release.mjs",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.43",
+    "typescript": "5.9.3"
+  }
+}