@bighub/bighub-mcp 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @bighub/bighub-mcp
+
+Official MCP server for BIGHUB governance APIs.
+
+This package exposes MCP tools that call `https://api.bighub.io` for governance operations:
+actions, rules, approvals, kill switch, events, API keys, webhooks, and auth.
+
+## Install
+
+```bash
+npm install @bighub/bighub-mcp
+```
+
+## Local development
+
+```bash
+npm install
+npm run test
+npm run check
+npm run build
+```
+
+Run in stdio mode:
+
+```bash
+npm run start
+```
+
+## Environment variables
+
+- `BIGHUB_API_KEY` - preferred auth method (`X-API-Key`)
+- `BIGHUB_BEARER_TOKEN` - optional auth method (`Authorization: Bearer ...`)
+- `BIGHUB_BASE_URL` - defaults to `https://api.bighub.io`
+- `BIGHUB_TIMEOUT_MS` - HTTP timeout (default: `15000`)
+- `BIGHUB_MAX_RETRIES` - retry count on transient failures (default: `2`)
+- `BIGHUB_ALLOW_INSECURE_HTTP` - only for localhost/private host testing
+
+## Tool coverage
+
+- **Actions:** submit, submit_v2, dry_run, status, verify, stats, dashboard summary
+- **Future Memory:** ingest, context, refresh aggregates, recommendations
+- **Rules:** create/list/get/update/delete/pause/resume/validate/dry-run/versions/domains/apply_patch/purge_idempotency
+- **Approvals:** list, resolve
+- **Kill switch:** status, activate, deactivate
+- **Events:** list, stats
+- **API keys:** create, list, delete, rotate, validate, scopes
+- **Webhooks:** create, list, get, update, delete, deliveries, test, list_events, verify_signature, replay
+- **Auth:** signup, login, refresh, logout
+- **Fallback:** generic `bighub_http_request` tool for endpoints not yet wrapped
+
+## Notes
+
+- Tools are one-to-one wrappers over BIGHUB HTTP endpoints.
+- Retries use exponential backoff with jitter for transient errors.
+- Errors preserve structured metadata when returned by the API.
+
+## Links
+
+- [Main README](../../README.md)

package/dist/httpClient.js

@@ -0,0 +1,174 @@
+export class BighubHttpError extends Error {
+    statusCode;
+    requestId;
+    code;
+    responseBody;
+    constructor(message, options) {
+        super(message);
+        this.name = "BighubHttpError";
+        this.statusCode = options?.statusCode;
+        this.requestId = options?.requestId;
+        this.code = options?.code;
+        this.responseBody = options?.responseBody;
+    }
+}
+const RETRYABLE_STATUS_CODES = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function shouldRetry(statusCode, err) {
+    if (err !== undefined) {
+        return true;
+    }
+    return statusCode !== undefined && RETRYABLE_STATUS_CODES.has(statusCode);
+}
+function buildRetryDelayMs(attempt) {
+    const base = 250;
+    const cap = 2500;
+    const delay = Math.min(cap, base * 2 ** Math.max(0, attempt - 1));
+    const jitter = Math.random() * Math.min(250, delay / 2);
+    return delay + jitter;
+}
+function ensureSecureBaseUrl(baseUrl) {
+    const url = new URL(baseUrl);
+    const scheme = url.protocol.replace(":", "").toLowerCase();
+    const host = (url.hostname || "").toLowerCase();
+    const allowInsecure = new Set(["1", "true", "yes", "on"]).has((process.env.BIGHUB_ALLOW_INSECURE_HTTP || "").trim().toLowerCase());
+    const localhost = host === "localhost" || host === "127.0.0.1";
+    const privateHost = host.endsWith(".local");
+    if (scheme !== "https" && !(localhost || (allowInsecure && privateHost))) {
+        throw new Error("Insecure base_url is not allowed. Use https:// or set BIGHUB_ALLOW_INSECURE_HTTP=true only for localhost/private hosts.");
+    }
+}
+function buildUrl(baseUrl, path, query) {
+    const url = new URL(`${baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`);
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value === undefined || value === null) {
+                continue;
+            }
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    if (item !== undefined && item !== null) {
+                        url.searchParams.append(key, String(item));
+                    }
+                }
+            }
+            else {
+                url.searchParams.set(key, String(value));
+            }
+        }
+    }
+    return url.toString();
+}
+function extractErrorMetadata(body) {
+    if (!body || typeof body !== "object") {
+        return {};
+    }
+    const value = body;
+    const detail = value.detail;
+    const requestId = (typeof value.request_id === "string" ? value.request_id : undefined) ||
+        (typeof value.validation_id === "string" ? value.validation_id : undefined) ||
+        (value.error && typeof value.error === "object" && typeof value.error.request_id === "string"
+            ? value.error.request_id
+            : undefined);
+    const code = detail && typeof detail === "object" && typeof detail.code === "string"
+        ? detail.code
+        : undefined;
+    return { requestId, code, detail };
+}
+async function parseResponseBody(response) {
+    const contentType = response.headers.get("content-type") || "";
+    if (contentType.includes("application/json")) {
+        try {
+            return await response.json();
+        }
+        catch {
+            return {};
+        }
+    }
+    const text = await response.text();
+    return text ? { text } : {};
+}
+export class BighubHttpClient {
+    config;
+    constructor(config) {
+        ensureSecureBaseUrl(config.baseUrl);
+        this.config = config;
+    }
+    async request(options) {
+        const url = buildUrl(this.config.baseUrl, options.path, options.query);
+        const headers = {
+            Accept: "application/json",
+            "User-Agent": this.config.userAgent,
+            ...(options.headers || {}),
+        };
+        if (this.config.apiKey) {
+            headers["X-API-Key"] = this.config.apiKey;
+        }
+        else if (this.config.bearerToken) {
+            headers.Authorization = `Bearer ${this.config.bearerToken}`;
+        }
+        if (options.idempotencyKey) {
+            headers["Idempotency-Key"] = options.idempotencyKey;
+        }
+        if (options.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        let lastError;
+        for (let attempt = 1; attempt <= this.config.maxRetries + 1; attempt += 1) {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+            try {
+                const response = await fetch(url, {
+                    method: options.method,
+                    headers,
+                    body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (shouldRetry(response.status) && attempt <= this.config.maxRetries) {
+                    await sleep(buildRetryDelayMs(attempt));
+                    continue;
+                }
+                const body = await parseResponseBody(response);
+                if (response.ok) {
+                    return body;
+                }
+                const { requestId, code, detail } = extractErrorMetadata(body);
+                const message = typeof detail === "string" ? detail : response.statusText || "API error";
+                throw new BighubHttpError(message, {
+                    statusCode: response.status,
+                    requestId,
+                    code,
+                    responseBody: body,
+                });
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                lastError = error;
+                const isAbort = error instanceof DOMException && error.name === "AbortError";
+                const retryable = shouldRetry(undefined, error);
+                if (isAbort) {
+                    if (attempt <= this.config.maxRetries) {
+                        await sleep(buildRetryDelayMs(attempt));
+                        continue;
+                    }
+                    throw new BighubHttpError(`Request timed out: ${options.method} ${options.path}`);
+                }
+                if (retryable && attempt <= this.config.maxRetries) {
+                    await sleep(buildRetryDelayMs(attempt));
+                    continue;
+                }
+                if (error instanceof BighubHttpError) {
+                    throw error;
+                }
+                throw new BighubHttpError(`Network error: ${options.method} ${options.path}`);
+            }
+        }
+        if (lastError instanceof BighubHttpError) {
+            throw lastError;
+        }
+        throw new BighubHttpError(`Request failed after retries: ${options.method} ${options.path}`);
+    }
+}

package/dist/index.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { BighubHttpClient } from "./httpClient.js";
+import { registerBighubTools } from "./registerTools.js";
+function parseNumberEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+async function main() {
+    const baseUrl = process.env.BIGHUB_BASE_URL || "https://api.bighub.io";
+    const apiKey = process.env.BIGHUB_API_KEY;
+    const bearerToken = process.env.BIGHUB_BEARER_TOKEN;
+    if (!apiKey && !bearerToken) {
+        console.error("BIGHUB_API_KEY or BIGHUB_BEARER_TOKEN must be set. " +
+            "Most tools require authentication against api.bighub.io.");
+    }
+    const client = new BighubHttpClient({
+        baseUrl,
+        apiKey,
+        bearerToken,
+        timeoutMs: parseNumberEnv("BIGHUB_TIMEOUT_MS", 15000),
+        maxRetries: parseNumberEnv("BIGHUB_MAX_RETRIES", 2),
+        userAgent: "bighub-mcp/0.1.0",
+    });
+    const server = new McpServer({
+        name: "bighub-mcp",
+        version: "0.1.0",
+    });
+    registerBighubTools(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("bighub-mcp server running on stdio");
+    const shutdown = async () => {
+        await server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((error) => {
+    console.error("bighub-mcp startup error:", error);
+    process.exit(1);
+});

package/dist/registerTools.js

@@ -0,0 +1,548 @@
+import { z } from "zod";
+const JsonObjectSchema = z.record(z.string(), z.unknown());
+const JsonPatchSchema = z.union([
+    z.array(JsonObjectSchema),
+    z.object({
+        ops: z.array(JsonObjectSchema),
+        format: z.string().optional(),
+    }),
+]);
+const AnyOutputSchema = z.object({}).passthrough();
+function toResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+function cleanObject(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+export function registerBighubTools(server, client) {
+    server.registerTool("bighub_http_request", {
+        description: "Low-level passthrough for any BIGHUB API endpoint.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            method: z.enum(["GET", "POST", "PATCH", "DELETE"]),
+            path: z.string().regex(/^\/.*/, "Path must start with '/'"),
+            query: JsonObjectSchema.optional(),
+            body: z.union([JsonObjectSchema, z.array(JsonObjectSchema)]).optional(),
+            headers: z.record(z.string(), z.string()).optional(),
+            idempotency_key: z.string().optional(),
+        },
+    }, async ({ method, path, query, body, headers, idempotency_key }) => toResult(await client.request({
+        method,
+        path,
+        query,
+        body,
+        headers,
+        idempotencyKey: idempotency_key,
+    })));
+    server.registerTool("bighub_actions_submit", {
+        description: "Validate an action via /actions/submit.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            action: z.string(),
+            actor: z.string().default("AI_AGENT"),
+            value: z.number().optional(),
+            target: z.string().optional(),
+            domain: z.string().optional(),
+            metadata: JsonObjectSchema.optional(),
+            idempotency_key: z.string().optional(),
+        },
+    }, async ({ action, actor, value, target, domain, metadata, idempotency_key }) => toResult(await client.request({
+        method: "POST",
+        path: "/actions/submit",
+        body: cleanObject({ action, actor, value, target, domain, metadata }),
+        idempotencyKey: idempotency_key,
+    })));
+    server.registerTool("bighub_actions_submit_v2", {
+        description: "Validate an action with pro decision intelligence via /actions/submit/v2.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            payload: JsonObjectSchema,
+            idempotency_key: z.string().optional(),
+        },
+    }, async ({ payload, idempotency_key }) => toResult(await client.request({
+        method: "POST",
+        path: "/actions/submit/v2",
+        body: payload,
+        idempotencyKey: idempotency_key,
+    })));
+    server.registerTool("bighub_actions_dry_run", {
+        description: "Run a non-persistent action validation via /actions/submit/dry-run.",
+        inputSchema: {
+            payload: JsonObjectSchema,
+            idempotency_key: z.string().optional(),
+        },
+    }, async ({ payload, idempotency_key }) => toResult(await client.request({
+        method: "POST",
+        path: "/actions/submit/dry-run",
+        body: payload,
+        idempotencyKey: idempotency_key,
+    })));
+    server.registerTool("bighub_actions_verify_validation", {
+        description: "Verify a previous validation by validation_id.",
+        inputSchema: { validation_id: z.string() },
+    }, async ({ validation_id }) => toResult(await client.request({
+        method: "GET",
+        path: `/actions/validations/${validation_id}/verify`,
+    })));
+    server.registerTool("bighub_actions_observer_stats", {
+        description: "Get action observer stats.",
+        inputSchema: {},
+    }, async () => toResult(await client.request({ method: "GET", path: "/actions/observer/stats" })));
+    server.registerTool("bighub_actions_dashboard_summary", {
+        description: "Get action dashboard summary.",
+        inputSchema: {},
+    }, async () => toResult(await client.request({ method: "GET", path: "/actions/dashboard/summary" })));
+    server.registerTool("bighub_actions_status", {
+        description: "Get action system status.",
+        inputSchema: {},
+    }, async () => toResult(await client.request({ method: "GET", path: "/actions/status" })));
+    server.registerTool("bighub_actions_memory_ingest", {
+        description: "Ingest governed execution events into Future Memory.",
+        inputSchema: {
+            events: z.array(JsonObjectSchema),
+            source: z.string().default("adapter"),
+            source_version: z.string().optional(),
+            actor: z.string().optional(),
+            domain: z.string().optional(),
+            model: z.string().optional(),
+            trace_id: z.string().optional(),
+            redact: z.boolean().default(true),
+            redaction_policy: z.string().default("default"),
+        },
+    }, async ({ events, source, source_version, actor, domain, model, trace_id, redact, redaction_policy }) => toResult(await client.request({
+        method: "POST",
+        path: "/actions/memory/ingest",
+        body: cleanObject({
+            source,
+            events,
+            source_version,
+            actor,
+            domain,
+            model,
+            trace_id,
+            redact,
+            redaction_policy,
+        }),
+    })));
+    server.registerTool("bighub_actions_memory_context", {
+        description: "Read Future Memory context window and rates.",
+        inputSchema: {
+            window_hours: z.number().int().default(24),
+            tool: z.string().optional(),
+            domain: z.string().optional(),
+            actor: z.string().optional(),
+            source: z.string().optional(),
+            limit_recent: z.number().int().default(25),
+        },
+    }, async ({ window_hours, tool, domain, actor, source, limit_recent }) => toResult(await client.request({
+        method: "GET",
+        path: "/actions/memory/context",
+        query: cleanObject({ window_hours, tool, domain, actor, source, limit_recent }),
+    })));
+    server.registerTool("bighub_actions_memory_refresh_aggregates", {
+        description: "Refresh Future Memory aggregates.",
+        inputSchema: {
+            concurrent: z.boolean().default(false),
+            window_hours: z.number().int().default(24),
+        },
+    }, async ({ concurrent, window_hours }) => toResult(await client.request({
+        method: "POST",
+        path: "/actions/memory/refresh-aggregates",
+        query: { concurrent, window_hours },
+    })));
+    server.registerTool("bighub_actions_memory_recommendations", {
+        description: "Compute Future Memory policy recommendations.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            window_hours: z.number().int().default(24),
+            scope: JsonObjectSchema.optional(),
+            tool: z.string().optional(),
+            domain: z.string().optional(),
+            actor: z.string().optional(),
+            source: z.string().optional(),
+            min_events: z.number().int().default(20),
+            min_blocked_rate: z.number().default(0.15),
+            min_approval_rate: z.number().default(0.1),
+            min_tool_error_rate: z.number().default(0.05),
+            limit_recommendations: z.number().int().default(10),
+            include_examples: z.boolean().default(true),
+            auto_apply: z.boolean().default(false),
+        },
+    }, async (args) => toResult(await client.request({
+        method: "POST",
+        path: "/actions/memory/recommendations",
+        body: cleanObject(args),
+    })));
+    server.registerTool("bighub_rules_create", {
+        description: "Create a governance rule.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            payload: JsonObjectSchema,
+            idempotency_key: z.string().optional(),
+        },
+    }, async ({ payload, idempotency_key }) => toResult(await client.request({
+        method: "POST",
+        path: "/rules",
+        body: payload,
+        idempotencyKey: idempotency_key,
+    })));
+    server.registerTool("bighub_rules_list", {
+        description: "List governance rules.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            status: z.string().optional(),
+            domain: z.string().optional(),
+            limit: z.number().int().optional(),
+            offset: z.number().int().optional(),
+        },
+    }, async ({ status, domain, limit, offset }) => toResult(await client.request({
+        method: "GET",
+        path: "/rules",
+        query: cleanObject({ status, domain, limit, offset }),
+    })));
+    server.registerTool("bighub_rules_get", {
+        description: "Fetch a single rule by rule_id.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: { rule_id: z.string() },
+    }, async ({ rule_id }) => toResult(await client.request({ method: "GET", path: `/rules/${rule_id}` })));
+    server.registerTool("bighub_rules_update", {
+        description: "Update a rule by rule_id.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            rule_id: z.string(),
+            payload: JsonObjectSchema,
+            idempotency_key: z.string().optional(),
+        },
+    }, async ({ rule_id, payload, idempotency_key }) => toResult(await client.request({
+        method: "PATCH",
+        path: `/rules/${rule_id}`,
+        body: payload,
+        idempotencyKey: idempotency_key,
+    })));
+    server.registerTool("bighub_rules_delete", {
+        description: "Delete a rule.",
+        inputSchema: {
+            rule_id: z.string(),
+            idempotency_key: z.string().optional(),
+        },
+    }, async ({ rule_id, idempotency_key }) => toResult(await client.request({
+        method: "DELETE",
+        path: `/rules/${rule_id}`,
+        idempotencyKey: idempotency_key,
+    })));
+    server.registerTool("bighub_rules_pause", {
+        description: "Pause rule enforcement for a rule_id.",
+        inputSchema: {
+            rule_id: z.string(),
+            idempotency_key: z.string().optional(),
+        },
+    }, async ({ rule_id, idempotency_key }) => toResult(await client.request({
+        method: "POST",
+        path: `/rules/${rule_id}/pause`,
+        idempotencyKey: idempotency_key,
+    })));
+    server.registerTool("bighub_rules_resume", {
+        description: "Resume a paused rule.",
+        inputSchema: {
+            rule_id: z.string(),
+            idempotency_key: z.string().optional(),
+        },
+    }, async ({ rule_id, idempotency_key }) => toResult(await client.request({
+        method: "POST",
+        path: `/rules/${rule_id}/resume`,
+        idempotencyKey: idempotency_key,
+    })));
+    server.registerTool("bighub_rules_dry_run", {
+        description: "Dry run a rule payload without persisting.",
+        inputSchema: {
+            payload: JsonObjectSchema,
+        },
+    }, async ({ payload }) => toResult(await client.request({
+        method: "POST",
+        path: "/rules/dry-run",
+        body: payload,
+    })));
+    server.registerTool("bighub_rules_validate", {
+        description: "Validate a rule payload.",
+        inputSchema: {
+            payload: JsonObjectSchema,
+        },
+    }, async ({ payload }) => toResult(await client.request({
+        method: "POST",
+        path: "/rules/validate",
+        body: payload,
+    })));
+    server.registerTool("bighub_rules_validate_dry_run", {
+        description: "Dry-run validate a rule payload.",
+        inputSchema: {
+            payload: JsonObjectSchema,
+        },
+    }, async ({ payload }) => toResult(await client.request({
+        method: "POST",
+        path: "/rules/validate/dry-run",
+        body: payload,
+    })));
+    server.registerTool("bighub_rules_domains", {
+        description: "List available rule domains.",
+        inputSchema: {},
+    }, async () => toResult(await client.request({ method: "GET", path: "/rules/domains" })));
+    server.registerTool("bighub_rules_versions", {
+        description: "List historical versions for a rule.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            rule_id: z.string(),
+            limit: z.number().int().optional(),
+        },
+    }, async ({ rule_id, limit }) => toResult(await client.request({
+        method: "GET",
+        path: `/rules/${rule_id}/versions`,
+        query: cleanObject({ limit }),
+    })));
+    server.registerTool("bighub_rules_purge_idempotency", {
+        description: "Purge rule idempotency records from the backend store.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            only_expired: z.boolean().default(true),
+            older_than_hours: z.number().int().optional(),
+            limit: z.number().int().optional(),
+        },
+    }, async ({ only_expired, older_than_hours, limit }) => toResult(await client.request({
+        method: "POST",
+        path: "/rules/admin/idempotency/purge",
+        query: cleanObject({ only_expired, older_than_hours, limit }),
+    })));
+    server.registerTool("bighub_rules_apply_patch", {
+        description: "Apply JSON Patch operations to a rule with preview/optimistic locking support.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            rule_id: z.string(),
+            patch: JsonPatchSchema,
+            preview: z.boolean().default(true),
+            reason: z.string().optional(),
+            if_match_version: z.number().int().optional(),
+            idempotency_key: z.string().optional(),
+            if_match: z.string().optional(),
+        },
+    }, async ({ rule_id, patch, preview, reason, if_match_version, idempotency_key, if_match }) => {
+        const patchOps = Array.isArray(patch) ? patch : patch.ops;
+        return toResult(await client.request({
+            method: "POST",
+            path: `/rules/${rule_id}/apply_patch`,
+            body: cleanObject({ patch: patchOps, preview, reason, if_match_version }),
+            idempotencyKey: idempotency_key,
+            headers: cleanObject({ "If-Match": if_match }),
+        }));
+    });
+    server.registerTool("bighub_approvals_list", {
+        description: "List approval queue items.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            status_filter: z.string().default("pending"),
+            limit: z.number().int().optional(),
+        },
+    }, async ({ status_filter, limit }) => toResult(await client.request({
+        method: "GET",
+        path: "/approvals",
+        query: cleanObject({ status: status_filter, limit }),
+    })));
+    server.registerTool("bighub_approvals_resolve", {
+        description: "Resolve an approval request.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            request_id: z.string(),
+            resolution: z.enum(["approved", "rejected"]),
+            comment: z.string().optional(),
+        },
+    }, async ({ request_id, resolution, comment }) => toResult(await client.request({
+        method: "POST",
+        path: `/approvals/${request_id}/resolve`,
+        body: cleanObject({ resolution, comment }),
+    })));
+    server.registerTool("bighub_kill_switch_status", {
+        description: "Read kill switch status.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {},
+    }, async () => toResult(await client.request({ method: "GET", path: "/kill-switch/status" })));
+    server.registerTool("bighub_kill_switch_activate", {
+        description: "Activate global/domain kill switch.",
+        inputSchema: {
+            payload: JsonObjectSchema.optional(),
+        },
+    }, async ({ payload }) => toResult(await client.request({ method: "POST", path: "/kill-switch/activate", body: payload || {} })));
+    server.registerTool("bighub_kill_switch_deactivate", {
+        description: "Deactivate kill switch by switch_id.",
+        inputSchema: {
+            switch_id: z.string(),
+            payload: JsonObjectSchema.optional(),
+        },
+    }, async ({ switch_id, payload }) => toResult(await client.request({
+        method: "POST",
+        path: `/kill-switch/deactivate/${switch_id}`,
+        body: payload || {},
+    })));
+    server.registerTool("bighub_events_list", {
+        description: "List event stream entries.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            event_type: z.string().optional(),
+            severity: z.string().optional(),
+            rule_id: z.string().optional(),
+            limit: z.number().int().optional(),
+            offset: z.number().int().optional(),
+        },
+    }, async ({ event_type, severity, rule_id, limit, offset }) => toResult(await client.request({
+        method: "GET",
+        path: "/events",
+        query: cleanObject({ event_type, severity, rule_id, limit, offset }),
+    })));
+    server.registerTool("bighub_events_stats", {
+        description: "Get aggregate event stats.",
+        inputSchema: {},
+    }, async () => toResult(await client.request({ method: "GET", path: "/events/stats" })));
+    server.registerTool("bighub_api_keys_create", {
+        description: "Create an API key.",
+        inputSchema: {
+            payload: JsonObjectSchema,
+        },
+    }, async ({ payload }) => toResult(await client.request({ method: "POST", path: "/api-keys", body: payload })));
+    server.registerTool("bighub_api_keys_list", {
+        description: "List API keys.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            include_revoked: z.boolean().default(false),
+        },
+    }, async ({ include_revoked }) => toResult(await client.request({ method: "GET", path: "/api-keys", query: { include_revoked } })));
+    server.registerTool("bighub_api_keys_delete", {
+        description: "Delete or revoke an API key.",
+        inputSchema: {
+            key_id: z.string(),
+            reason: z.string().optional(),
+        },
+    }, async ({ key_id, reason }) => toResult(await client.request({
+        method: "DELETE",
+        path: `/api-keys/${key_id}`,
+        body: reason ? { reason } : undefined,
+    })));
+    server.registerTool("bighub_api_keys_rotate", {
+        description: "Rotate an API key.",
+        inputSchema: {
+            key_id: z.string(),
+        },
+    }, async ({ key_id }) => toResult(await client.request({ method: "POST", path: `/api-keys/${key_id}/rotate` })));
+    server.registerTool("bighub_api_keys_validate", {
+        description: "Validate an API key (query + X-API-Key header).",
+        inputSchema: {
+            api_key: z.string(),
+        },
+    }, async ({ api_key }) => toResult(await client.request({
+        method: "GET",
+        path: "/api-keys/validate",
+        query: { api_key },
+        headers: { "X-API-Key": api_key },
+    })));
+    server.registerTool("bighub_api_keys_scopes", {
+        description: "List available API key scopes.",
+        inputSchema: {},
+    }, async () => toResult(await client.request({ method: "GET", path: "/api-keys/scopes" })));
+    server.registerTool("bighub_webhooks_create", {
+        description: "Create a webhook endpoint.",
+        inputSchema: {
+            payload: JsonObjectSchema,
+        },
+    }, async ({ payload }) => toResult(await client.request({ method: "POST", path: "/webhooks", body: payload })));
+    server.registerTool("bighub_webhooks_list", {
+        description: "List webhooks.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            include_inactive: z.boolean().default(false),
+        },
+    }, async ({ include_inactive }) => toResult(await client.request({ method: "GET", path: "/webhooks", query: { include_inactive } })));
+    server.registerTool("bighub_webhooks_get", {
+        description: "Get a webhook by webhook_id.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            webhook_id: z.string(),
+        },
+    }, async ({ webhook_id }) => toResult(await client.request({ method: "GET", path: `/webhooks/${webhook_id}` })));
+    server.registerTool("bighub_webhooks_update", {
+        description: "Update webhook by webhook_id.",
+        inputSchema: {
+            webhook_id: z.string(),
+            payload: JsonObjectSchema,
+        },
+    }, async ({ webhook_id, payload }) => toResult(await client.request({ method: "PATCH", path: `/webhooks/${webhook_id}`, body: payload })));
+    server.registerTool("bighub_webhooks_delete", {
+        description: "Delete a webhook.",
+        inputSchema: {
+            webhook_id: z.string(),
+        },
+    }, async ({ webhook_id }) => toResult(await client.request({ method: "DELETE", path: `/webhooks/${webhook_id}` })));
+    server.registerTool("bighub_webhooks_deliveries", {
+        description: "List webhook delivery logs.",
+        inputSchema: {
+            webhook_id: z.string(),
+            limit: z.number().int().optional(),
+        },
+    }, async ({ webhook_id, limit }) => toResult(await client.request({
+        method: "GET",
+        path: `/webhooks/${webhook_id}/deliveries`,
+        query: cleanObject({ limit }),
+    })));
+    server.registerTool("bighub_webhooks_test", {
+        description: "Send a test webhook delivery.",
+        inputSchema: {
+            webhook_id: z.string(),
+            event_type: z.string().default("signal.new"),
+        },
+    }, async ({ webhook_id, event_type }) => toResult(await client.request({
+        method: "POST",
+        path: `/webhooks/${webhook_id}/test`,
+        body: { event_type },
+    })));
+    server.registerTool("bighub_webhooks_list_events", {
+        description: "List supported webhook event types.",
+        inputSchema: {},
+    }, async () => toResult(await client.request({ method: "GET", path: "/webhooks/events/list" })));
+    server.registerTool("bighub_webhooks_verify_signature", {
+        description: "Verify webhook signature payload.",
+        inputSchema: {
+            payload: z.string(),
+            signature: z.string(),
+            secret: z.string(),
+            timestamp: z.number().int(),
+        },
+    }, async ({ payload, signature, secret, timestamp }) => toResult(await client.request({
+        method: "POST",
+        path: "/webhooks/verify-signature",
+        body: { payload, signature, secret, timestamp },
+    })));
+    server.registerTool("bighub_webhooks_replay_failed_delivery", {
+        description: "Replay a failed webhook delivery.",
+        inputSchema: {
+            webhook_id: z.string(),
+            delivery_id: z.number().int(),
+        },
+    }, async ({ webhook_id, delivery_id }) => toResult(await client.request({
+        method: "POST",
+        path: `/webhooks/${webhook_id}/deliveries/${delivery_id}/replay`,
+    })));
+    server.registerTool("bighub_auth_signup", {
+        description: "Sign up and return access/refresh tokens.",
+        inputSchema: { payload: JsonObjectSchema },
+    }, async ({ payload }) => toResult(await client.request({ method: "POST", path: "/auth/signup", body: payload })));
+    server.registerTool("bighub_auth_login", {
+        description: "Authenticate and return access/refresh tokens.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: { payload: JsonObjectSchema },
+    }, async ({ payload }) => toResult(await client.request({ method: "POST", path: "/auth/login", body: payload })));
+    server.registerTool("bighub_auth_refresh", {
+        description: "Rotate auth tokens with refresh token.",
+        inputSchema: { refresh_token: z.string() },
+    }, async ({ refresh_token }) => toResult(await client.request({ method: "POST", path: "/auth/refresh", body: { refresh_token } })));
+    server.registerTool("bighub_auth_logout", {
+        description: "Invalidate a refresh token.",
+        inputSchema: { refresh_token: z.string() },
+    }, async ({ refresh_token }) => toResult(await client.request({ method: "POST", path: "/auth/logout", body: { refresh_token } })));
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@bighub/bighub-mcp",
+  "version": "0.1.0",
+  "description": "Official MCP server for BIGHUB governance APIs.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "bighub-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "bighub",
+    "mcp",
+    "governance",
+    "ai-agents"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  }
+}