@behavior-os/mcp-server 0.0.0-stage → 2.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Ilvan Joaquim
+
+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/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/rate-limit.d.ts

@@ -0,0 +1,64 @@
+/** Default ceiling: 300 calls per tool per minute (5/s average). */ export declare const DEFAULT_RATE_LIMIT_MAX_CALLS = 300;
+export declare const DEFAULT_RATE_LIMIT_WINDOW_MS = 60000;
+export interface RateLimitConfig {
+    /** Bucket capacity and number of calls allowed per `windowMs`. */
+    maxCalls: number;
+    /** Refill window in milliseconds. */
+    windowMs: number;
+    /** When true, `check()` always allows the call. */
+    disabled: boolean;
+}
+export interface RateLimitDecision {
+    allowed: boolean;
+    /** Configured bucket capacity. */
+    limit: number;
+    /** Whole calls left in the bucket after this decision. */
+    remaining: number;
+    /** Milliseconds until one token is available; 0 when allowed. */
+    retryAfterMs: number;
+}
+/**
+ * Per-tool token bucket.
+ *
+ * MCP runs over stdio in a single process, so the bucket is intentionally
+ * in-process: it throttles a runaway or looping agent, it is not a distributed
+ * quota and does not replace authentication or authorization. Each tool has its
+ * own bucket, so one noisy read-only tool cannot starve a governance call.
+ */
+export declare class ToolRateLimiter {
+    private readonly buckets;
+    private readonly maxCalls;
+    private readonly windowMs;
+    private readonly disabled;
+    constructor(config: RateLimitConfig);
+    get limit(): number;
+    get window(): number;
+    /**
+     * Consume one token for `toolName`. `now` is injectable so tests can prove
+     * refill behavior without sleeping.
+     */
+    check(toolName: string, now?: number): RateLimitDecision;
+    /** Forget one tool's history, or every tool when called with no argument. */
+    reset(toolName?: string): void;
+    private refillPerMs;
+}
+export interface ParsedRateLimitConfig {
+    config: RateLimitConfig;
+    warnings: string[];
+}
+/**
+ * Read the optional environment overrides. Missing variables keep the secure
+ * defaults; malformed values are reported and replaced by the default instead
+ * of silently disabling the limiter.
+ */
+export declare function rateLimitConfigFromEnv(env?: NodeJS.ProcessEnv): ParsedRateLimitConfig;
+/**
+ * Wrap a registered tool callback with the shared limiter. The check runs
+ * before the handler, so a throttled call does no engine work and returns a
+ * normal MCP error result (the client sees `isError: true`, not a crash).
+ *
+ * The wrapper is generic over the callback's function type, so the MCP SDK's
+ * per-tool argument inference is preserved.
+ */
+export declare function withRateLimit<F extends (...args: never[]) => unknown>(toolName: string, callback: F, limiter: ToolRateLimiter): F;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAAA,oEAAoE,CAAC,eAAO,MAAM,4BAA4B,MAAM,CAAC;AACrH,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;CACtB;AAOD;;;;;;;GAOG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;gBAEvB,MAAM,EAAE,eAAe;IAYnC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,iBAAiB;IAiCpE,6EAA6E;IAC7E,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ9B,OAAO,CAAC,WAAW;CAGpB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,eAAe,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAiBD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,qBAAqB,CAiBvB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,EACnE,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,eAAe,GACvB,CAAC,CAgBH"}

package/dist/rate-limit.js

@@ -0,0 +1,127 @@
+/** Default ceiling: 300 calls per tool per minute (5/s average). */ export const DEFAULT_RATE_LIMIT_MAX_CALLS = 300;
+export const DEFAULT_RATE_LIMIT_WINDOW_MS = 60_000;
+/**
+ * Per-tool token bucket.
+ *
+ * MCP runs over stdio in a single process, so the bucket is intentionally
+ * in-process: it throttles a runaway or looping agent, it is not a distributed
+ * quota and does not replace authentication or authorization. Each tool has its
+ * own bucket, so one noisy read-only tool cannot starve a governance call.
+ */
+export class ToolRateLimiter {
+    buckets = new Map();
+    maxCalls;
+    windowMs;
+    disabled;
+    constructor(config) {
+        if (!Number.isFinite(config.maxCalls) || config.maxCalls < 1) {
+            throw new RangeError('rate limit maxCalls must be >= 1');
+        }
+        if (!Number.isFinite(config.windowMs) || config.windowMs < 1) {
+            throw new RangeError('rate limit windowMs must be >= 1');
+        }
+        this.maxCalls = Math.floor(config.maxCalls);
+        this.windowMs = Math.floor(config.windowMs);
+        this.disabled = config.disabled;
+    }
+    get limit() {
+        return this.maxCalls;
+    }
+    get window() {
+        return this.windowMs;
+    }
+    /**
+     * Consume one token for `toolName`. `now` is injectable so tests can prove
+     * refill behavior without sleeping.
+     */
+    check(toolName, now = Date.now()) {
+        if (this.disabled) {
+            return { allowed: true, limit: this.maxCalls, remaining: this.maxCalls, retryAfterMs: 0 };
+        }
+        let bucket = this.buckets.get(toolName);
+        if (!bucket) {
+            bucket = { tokens: this.maxCalls, updatedAt: now };
+            this.buckets.set(toolName, bucket);
+        }
+        else {
+            const elapsed = Math.max(0, now - bucket.updatedAt);
+            bucket.tokens = Math.min(this.maxCalls, bucket.tokens + elapsed * this.refillPerMs());
+            bucket.updatedAt = now;
+        }
+        if (bucket.tokens >= 1) {
+            bucket.tokens -= 1;
+            return {
+                allowed: true,
+                limit: this.maxCalls,
+                remaining: Math.floor(bucket.tokens),
+                retryAfterMs: 0,
+            };
+        }
+        return {
+            allowed: false,
+            limit: this.maxCalls,
+            remaining: 0,
+            retryAfterMs: Math.max(1, Math.ceil((1 - bucket.tokens) / this.refillPerMs())),
+        };
+    }
+    /** Forget one tool's history, or every tool when called with no argument. */
+    reset(toolName) {
+        if (toolName === undefined) {
+            this.buckets.clear();
+        }
+        else {
+            this.buckets.delete(toolName);
+        }
+    }
+    refillPerMs() {
+        return this.maxCalls / this.windowMs;
+    }
+}
+function positiveInteger(raw, fallback, name, warnings) {
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        warnings.push(`${name}="${raw}" is invalid; using ${fallback}`);
+        return fallback;
+    }
+    return parsed;
+}
+/**
+ * Read the optional environment overrides. Missing variables keep the secure
+ * defaults; malformed values are reported and replaced by the default instead
+ * of silently disabling the limiter.
+ */
+export function rateLimitConfigFromEnv(env = process.env) {
+    const warnings = [];
+    const maxCalls = positiveInteger(env.BEHAVIOROS_MCP_RATE_LIMIT_MAX, DEFAULT_RATE_LIMIT_MAX_CALLS, 'BEHAVIOROS_MCP_RATE_LIMIT_MAX', warnings);
+    const windowMs = positiveInteger(env.BEHAVIOROS_MCP_RATE_LIMIT_WINDOW_MS, DEFAULT_RATE_LIMIT_WINDOW_MS, 'BEHAVIOROS_MCP_RATE_LIMIT_WINDOW_MS', warnings);
+    const disabled = env.BEHAVIOROS_MCP_RATE_LIMIT_DISABLED === 'true';
+    return { config: { maxCalls, windowMs, disabled }, warnings };
+}
+/**
+ * Wrap a registered tool callback with the shared limiter. The check runs
+ * before the handler, so a throttled call does no engine work and returns a
+ * normal MCP error result (the client sees `isError: true`, not a crash).
+ *
+ * The wrapper is generic over the callback's function type, so the MCP SDK's
+ * per-tool argument inference is preserved.
+ */
+export function withRateLimit(toolName, callback, limiter) {
+    return (async (...args) => {
+        const decision = limiter.check(toolName);
+        if (!decision.allowed) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Rate limit exceeded for ${toolName}: retry after ${decision.retryAfterMs} ms (limit ${decision.limit} calls per ${limiter.window} ms).`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return callback(...args);
+    });
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { ToolRateLimiter } from './rate-limit.js';
+export declare const server: McpServer;
+export declare const toolRateLimiter: ToolRateLimiter;
+/**
+ * Exported for tests that need a fresh server instance (e.g. InMemoryTransport
+ * contracts). Each call creates a new McpServer so the singleton does not get
+ * re-connected across tests.
+ */
+export declare function createServer(): McpServer;
+/**
+ * Canonical structural shape of a vote, shared by every tool that accepts one
+ * (`bos_decide`, `bos_evolution`, `bos_apply_code_fixes`, `bos_code_edit`).
+ * Kept in one place so a malformed vote is rejected at the tool boundary
+ * instead of reaching the decision engine.
+ */
+export declare const voteSchema: z.ZodObject<{
+    voterId: z.ZodString;
+    choice: z.ZodEnum<{
+        approve: "approve";
+        reject: "reject";
+        abstain: "abstain";
+    }>;
+    weight: z.ZodOptional<z.ZodNumber>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AAiBA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAA0B,eAAe,EAAiB,MAAM,iBAAiB,CAAC;AAkCzF,eAAO,MAAM,MAAM,WAGjB,CAAC;AAYH,eAAO,MAAM,eAAe,iBAA8C,CAAC;AAS3E;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAExC;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU;;;;;;;;;iBAKrB,CAAC"}