@webbula/mcp 1.0.0

package/dist/api/webbula-client.d.ts

@@ -0,0 +1,116 @@
+import type { AccountInfoResponse, BatchRunResponse, BatchTaskResponse, ExpressCompoundResponse, ExpressEmailResponseV5, PersonaAppendResponse } from "./types.js";
+/** Batch submission parameters — exactly one of `inline` / `dataSource` is set. */
+export interface BatchRunParams {
+    profile: string;
+    /** Inline base64 submission (JSON `file_base64` mode). */
+    inline?: {
+        filename: string;
+        content_base64: string;
+    };
+    /** Remote data-source submission (form mode). */
+    dataSource?: {
+        data_source: "web" | "ftp" | "ssh";
+        url?: string;
+        host?: string;
+        port?: number;
+        username?: string;
+        password?: string;
+        path?: string;
+        secure?: boolean;
+        filename?: string;
+    };
+}
+/** Raw result-file body returned by `getResultFile` — bytes + the upstream content-type. */
+export interface ResultFileBytes {
+    bytes: Buffer;
+    contentType?: string;
+}
+/**
+ * Lead attributes accepted by v4 `task/lead`; only supplied fields are sent.
+ * The full street/city/state/ZIP goes in `full_address` (mapped to the upstream
+ * `address` form param).
+ */
+export interface LeadValidateParams {
+    profile: string;
+    first_name?: string;
+    last_name?: string;
+    full_address?: string;
+    phone?: string;
+    emails?: string[];
+}
+/** Which data point a persona append should resolve and return. */
+export type PersonaFilter = "Email" | "Telephone" | "Postal" | "Automotive";
+/** Identity-resolution scope for a persona append (CSV: default "both"). */
+export type PersonaScope = "individual" | "household" | "both";
+/**
+ * Input to the persona data-append endpoint (feature 006). `record` carries the
+ * known PII used as the match key; only supplied fields are sent. `filter`
+ * selects the data point to append; `scope` selects the identity-resolution
+ * level. The wrapper never invents PII — it forwards exactly what the caller
+ * provided (constitution principle I).
+ */
+export interface PersonaAppendParams {
+    filter: PersonaFilter;
+    scope: PersonaScope;
+    record: {
+        first_name?: string;
+        last_name?: string;
+        email?: string;
+        address?: string;
+        city?: string;
+        state?: string;
+        zip5?: string;
+        phone?: string;
+    };
+}
+/** Failure categories surfaced to tool handlers (data-model ToolError). */
+export type ErrorCategory = "missing_credential" | "validation" | "auth" | "upstream" | "network";
+/**
+ * A structured client error. The message is safe to surface to an agent and
+ * NEVER contains the API key (principle V). Tool handlers turn this into an MCP
+ * tool error (`isError: true`).
+ */
+export declare class WebbulaApiError extends Error {
+    readonly category: ErrorCategory;
+    constructor(category: ErrorCategory, message: string);
+}
+export interface WebbulaClientOptions {
+    /** Override the base URL (defaults to config). */
+    baseUrl?: string;
+    /** Override the persona-append base URL (defaults to config — feature 006). */
+    personaBaseUrl?: string;
+    /** Override key resolution (mainly for tests). Defaults to `resolveApiKey`. */
+    resolveKey?: () => string | undefined;
+}
+export interface WebbulaClient {
+    /** `POST /api.v4/task/express` (form) — single address (verify_email). */
+    expressHygiene(params: {
+        emails: string[];
+        profile: string;
+    }): Promise<ExpressEmailResponseV5>;
+    /**
+     * `POST /api/v5/task/express` (JSON) — multi-address hygiene (hygiene_check).
+     * v4 express is single-email only, so the synchronous list path uses v5, which
+     * accepts an `emails` array and returns one result per address.
+     */
+    expressHygieneV5(params: {
+        emails: string[];
+        profile: string;
+    }): Promise<ExpressEmailResponseV5>;
+    /** `POST /api.v4/account/info` (form, `mode=short`) — `key` never returned (principle V). */
+    accountInfo(): Promise<AccountInfoResponse>;
+    /** `POST /api.v4/task/lead` (form) — validate a lead record (feature 002). */
+    leadValidate(params: LeadValidateParams): Promise<ExpressCompoundResponse>;
+    /** `POST /api.v4/task/run` — submit a batch file task (multipart or form). */
+    runBatch(params: BatchRunParams): Promise<BatchRunResponse>;
+    /** `POST /api.v4/task/info` (form) — poll a batch task by `package_name`. */
+    taskInfo(packageName: string): Promise<BatchTaskResponse>;
+    /** `POST /api.v4/task/get_file` (form) — download a result file (raw bytes). */
+    getResultFile(params: {
+        package_name: string;
+        filename: string;
+    }): Promise<ResultFileBytes>;
+    /** `POST {persona}/v1/append` — append a data point via identity resolution (feature 006). */
+    personaAppend(params: PersonaAppendParams): Promise<PersonaAppendResponse>;
+}
+export declare function createWebbulaClient(options?: WebbulaClientOptions): WebbulaClient;

package/dist/api/webbula-client.js

@@ -0,0 +1,249 @@
+/**
+ * The single HTTP boundary to the Webbula Email Hygiene API (constitution
+ * principle I). Native `fetch`, `X-API-KEY` header auth (research D3), `/api/v5`
+ * base path (research D2). All error handling is centralized here so every tool
+ * handler surfaces a structured, secret-free failure (principle V, research D7).
+ */
+import { createHash } from "node:crypto";
+import { resolveApiKey, WEBBULA_API_BASE_URL, WEBBULA_API_PATH, WEBBULA_DEBUG, WEBBULA_PERSONA_BASE_URL, } from "../config.js";
+/** Webbula API version path segment (v4 — form-encoded endpoints). */
+const API_PATH = WEBBULA_API_PATH;
+/**
+ * v5 path, used ONLY by `hygiene_check` — v4 express is single-email, so the
+ * synchronous multi-address path stays on v5 (JSON array body).
+ */
+const API_PATH_V5 = "/api/v5";
+/** Persona data-append path on the persona host (feature 006). */
+const PERSONA_APPEND_PATH = "/v1/append";
+/** Build an `application/x-www-form-urlencoded` request init from string params. */
+function formInit(params) {
+    const form = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            form.set(key, value);
+    }
+    return {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: form.toString(),
+    };
+}
+/**
+ * A structured client error. The message is safe to surface to an agent and
+ * NEVER contains the API key (principle V). Tool handlers turn this into an MCP
+ * tool error (`isError: true`).
+ */
+export class WebbulaApiError extends Error {
+    category;
+    constructor(category, message) {
+        super(message);
+        this.name = "WebbulaApiError";
+        this.category = category;
+    }
+}
+/** Pull verbatim upstream message(s) out of a legacy error envelope. */
+function extractErrorMessages(body) {
+    const errors = body?.errors;
+    if (Array.isArray(errors))
+        return errors.filter((e) => typeof e === "string");
+    if (typeof errors === "string")
+        return [errors];
+    const message = errors?.message;
+    return typeof message === "string" ? [message] : [];
+}
+/** Describe a thrown transport error without leaking internals. */
+function networkReason(error) {
+    if (error instanceof Error && error.message)
+        return error.message;
+    return "connection failed";
+}
+/**
+ * Log the raw upstream response to stderr when `WEBBULA_DEBUG` is on. A `key`
+ * field is redacted before logging so the API token can never leak (principle
+ * V). Logging goes to stderr only — never stdout (stdio JSON-RPC channel).
+ */
+function debugLogResponse(method, url, status, body) {
+    if (!WEBBULA_DEBUG)
+        return;
+    let printable = body;
+    if (body !== null && typeof body === "object" && "key" in body) {
+        printable = { ...body, key: "[redacted]" };
+    }
+    console.error(`[webbula-debug] ${method.toUpperCase()} ${url} → HTTP ${status}\n` +
+        JSON.stringify(printable, null, 2));
+}
+export function createWebbulaClient(options = {}) {
+    const baseUrl = (options.baseUrl ?? WEBBULA_API_BASE_URL).replace(/\/+$/, "");
+    const personaBaseUrl = (options.personaBaseUrl ?? WEBBULA_PERSONA_BASE_URL).replace(/\/+$/, "");
+    const resolveKey = options.resolveKey ?? resolveApiKey;
+    /** Resolve the key or fail loud (pre-flight, principle V). */
+    function requireKey() {
+        const key = resolveKey();
+        if (!key) {
+            throw new WebbulaApiError("missing_credential", "Webbula API key required (set WEBBULA_API_KEY)");
+        }
+        return key;
+    }
+    /**
+     * Perform a request and map every failure path to a `WebbulaApiError`.
+     * `base` overrides the default API host (the persona append endpoint lives on
+     * its own host — feature 006).
+     */
+    async function request(path, init, base = baseUrl) {
+        const key = requireKey();
+        const headers = new Headers(init.headers);
+        headers.set("X-API-KEY", key);
+        headers.set("Accept", "application/json");
+        let response;
+        try {
+            response = await fetch(`${base}${path}`, { ...init, headers });
+        }
+        catch (error) {
+            throw new WebbulaApiError("network", `Webbula API unreachable: ${networkReason(error)}`);
+        }
+        if (response.status === 401) {
+            throw new WebbulaApiError("auth", "Authentication failed — check WEBBULA_API_KEY");
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = undefined;
+        }
+        debugLogResponse(init.method ?? "GET", `${base}${path}`, response.status, body);
+        // The legacy envelope uses `success: 0` even on HTTP 200 in some cases, so
+        // inspect the body, not just the status (research D7).
+        const legacyFailure = body !== undefined && body.success === 0;
+        if (!response.ok || legacyFailure) {
+            const messages = extractErrorMessages(body);
+            throw new WebbulaApiError("upstream", messages.length > 0
+                ? messages.join("; ")
+                : `Webbula API error (HTTP ${response.status})`);
+        }
+        return body;
+    }
+    return {
+        async expressHygiene({ emails, profile }) {
+            // v4 `task/express` is form-encoded and single-email (verify_email passes
+            // exactly one address). The response `emails` is still an array.
+            return request(`${API_PATH}/task/express`, formInit({ profile, emails: emails.join(",") }));
+        },
+        async expressHygieneV5({ emails, profile }) {
+            // hygiene_check stays on v5: JSON `emails` array, one result per address.
+            return request(`${API_PATH_V5}/task/express`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ profile, emails }),
+            });
+        },
+        async accountInfo() {
+            // v4 `account/info`: form POST with `mode=short` (never `full` — keeps the
+            // API key out of the response, principle V).
+            return request(`${API_PATH}/account/info`, formInit({ mode: "short" }));
+        },
+        async leadValidate(params) {
+            // Map our tool-facing fields to the v4 `task/lead` form params
+            // (firstname/lastname/address/phone/emails). Only supplied fields are sent
+            // (FR-003); `emails` is a single value, so a list is joined comma-separated.
+            return request(`${API_PATH}/task/lead`, formInit({
+                profile: params.profile,
+                firstname: params.first_name,
+                lastname: params.last_name,
+                address: params.full_address,
+                phone: params.phone,
+                emails: params.emails && params.emails.length > 0
+                    ? params.emails.join(",")
+                    : undefined,
+            }));
+        },
+        async runBatch(params) {
+            if (params.inline !== undefined) {
+                // v4 `task/run` raw-file mode: multipart/form-data with `data_file` and
+                // its `md5` checksum (required when `data_file` is present).
+                const bytes = Buffer.from(params.inline.content_base64, "base64");
+                const md5 = createHash("md5").update(bytes).digest("hex");
+                const form = new FormData();
+                form.set("profile", params.profile);
+                form.set("md5", md5);
+                form.set("data_file", new Blob([new Uint8Array(bytes)]), params.inline.filename);
+                // Do not set Content-Type — fetch adds the multipart boundary itself.
+                return request(`${API_PATH}/task/run`, {
+                    method: "POST",
+                    body: form,
+                });
+            }
+            // Remote data source → form-encoded mode.
+            const fields = { profile: params.profile };
+            if (params.dataSource !== undefined) {
+                for (const [key, value] of Object.entries(params.dataSource)) {
+                    if (value !== undefined)
+                        fields[key] = String(value);
+                }
+            }
+            return request(`${API_PATH}/task/run`, formInit(fields));
+        },
+        async taskInfo(packageName) {
+            // v4 `task/info`: form POST with `package_name`.
+            return request(`${API_PATH}/task/info`, formInit({ package_name: packageName }));
+        },
+        async getResultFile({ package_name, filename }) {
+            // The first non-JSON client path: the body is the file content (text or
+            // binary), but the API returns a JSON error envelope on failure. Read the
+            // bytes, then surface a JSON error as a structured error — never as content
+            // (FR-007).
+            const key = requireKey();
+            const form = new URLSearchParams({ package_name, filename });
+            const headers = new Headers();
+            headers.set("X-API-KEY", key);
+            headers.set("Content-Type", "application/x-www-form-urlencoded");
+            let response;
+            try {
+                response = await fetch(`${baseUrl}${API_PATH}/task/get_file`, {
+                    method: "POST",
+                    headers,
+                    body: form.toString(),
+                });
+            }
+            catch (error) {
+                throw new WebbulaApiError("network", `Webbula API unreachable: ${networkReason(error)}`);
+            }
+            if (response.status === 401) {
+                throw new WebbulaApiError("auth", "Authentication failed — check WEBBULA_API_KEY");
+            }
+            const contentType = response.headers.get("content-type") ?? undefined;
+            const bytes = Buffer.from(await response.arrayBuffer());
+            // A JSON body (or any non-2xx) is an error envelope, not file content.
+            const looksJson = contentType?.includes("json") ?? false;
+            if (!response.ok || looksJson) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(bytes.toString("utf8"));
+                }
+                catch {
+                    parsed = undefined;
+                }
+                const messages = extractErrorMessages(parsed);
+                throw new WebbulaApiError("upstream", messages.length > 0
+                    ? messages.join("; ")
+                    : `Webbula API error (HTTP ${response.status})`);
+            }
+            return { bytes, contentType };
+        },
+        async personaAppend({ filter, scope, record }) {
+            // Forward only the PII the caller supplied (omit undefined) plus the
+            // append filter + scope. The persona endpoint lives on its own host.
+            const body = { filter, scope };
+            for (const [key, value] of Object.entries(record)) {
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            return request(`${PERSONA_APPEND_PATH}`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+            }, personaBaseUrl);
+        },
+    };
+}
+//# sourceMappingURL=webbula-client.js.map

package/dist/api/webbula-client.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared, transport-agnostic configuration for the Webbula MCP server.
+ *
+ * All configuration is passed through the environment. The Webbula API key is
+ * read from the `WEBBULA_API_KEY` env var and held in memory only — never logged
+ * or persisted.
+ */
+export declare const SERVER_NAME = "webbula-mcp";
+export declare const SERVER_VERSION = "0.1.0";
+/** Default Webbula API base URL; override with WEBBULA_API_BASE_URL. */
+export declare const WEBBULA_API_BASE_URL: string;
+/**
+ * API version path segment. The current Webbula contract is **v4** (`/api.v4`,
+ * note the dot, not a slash); endpoints take `application/x-www-form-urlencoded`
+ * bodies. Override with `WEBBULA_API_PATH`.
+ */
+export declare const WEBBULA_API_PATH: string;
+/**
+ * Base URL for the persona data-append API (feature 006). The append product
+ * lives on a separate host from the hygiene API; override with
+ * `WEBBULA_PERSONA_BASE_URL`. The default is a placeholder — the real host must
+ * be supplied per deployment before `append_*` tools can succeed.
+ */
+export declare const WEBBULA_PERSONA_BASE_URL: string;
+/**
+ * Default identity-resolution scope for the `append_*` tools when a call omits
+ * one (CSV note: "Assume Both"). Override with `WEBBULA_PERSONA_SCOPE`; an
+ * unrecognized value falls back to `both`.
+ */
+export declare const WEBBULA_PERSONA_DEFAULT_SCOPE: string;
+/** HTTP transport listen port; override with PORT. */
+export declare const HTTP_PORT: number;
+/**
+ * When set (`WEBBULA_DEBUG=1`), the client logs each raw upstream response to
+ * **stderr** (stdout is reserved for the stdio JSON-RPC stream). A `key` field,
+ * if ever present, is redacted before logging (principle V). Off by default.
+ */
+export declare const WEBBULA_DEBUG: boolean;
+/** `verify_email` → `task/express` verification preset (CSV: `_Verification_Only`). */
+export declare const WEBBULA_VERIFICATION_PROFILE: string;
+/** `hygiene_check` → `task/express` email-hygiene preset (CSV: `_B2C_HVI`). */
+export declare const WEBBULA_HYGIENE_PROFILE: string;
+/** `validate_lead` → `task/lead` lead-hygiene preset (CSV: `_Default_LHVI`). */
+export declare const WEBBULA_LEAD_PROFILE: string;
+/**
+ * `upload_file` → `task/run` batch preset. The CSV lists three batch presets
+ * (verification / hygiene / lead) for the one batch endpoint; this defaults to
+ * the verification preset and is overridden per call (or via env) for hygiene or
+ * lead batches.
+ */
+export declare const WEBBULA_BATCH_PROFILE: string;
+/**
+ * Upper bound on addresses per `hygiene_check` call (research D8 / FR-010). The
+ * express endpoint is synchronous, so large lists belong in the batch flow.
+ * Falls back to 100; a non-positive or non-numeric override is ignored.
+ */
+export declare const WEBBULA_MAX_EMAILS: number;
+/**
+ * Maximum decoded size (bytes) of an inline base64 upload for `upload_file`
+ * (feature 003, FR-003). The JSON `file_base64` mode is documented at ~1 MiB;
+ * larger files must use a remote `data_source`. Override with
+ * `WEBBULA_MAX_INLINE_BYTES`; a non-positive/non-numeric override falls back.
+ */
+export declare const WEBBULA_MAX_INLINE_BYTES: number;
+/**
+ * Resolve the Webbula API key from the environment. Returns `undefined` when
+ * `WEBBULA_API_KEY` is unset — callers that require a key (tool handlers) surface
+ * a structured error per constitution principle V (Fail Loud, Fail Structured).
+ */
+export declare function resolveApiKey(): string | undefined;

package/dist/config.js

@@ -0,0 +1,90 @@
+/**
+ * Shared, transport-agnostic configuration for the Webbula MCP server.
+ *
+ * All configuration is passed through the environment. The Webbula API key is
+ * read from the `WEBBULA_API_KEY` env var and held in memory only — never logged
+ * or persisted.
+ */
+export const SERVER_NAME = "webbula-mcp";
+export const SERVER_VERSION = "0.1.0";
+/** Default Webbula API base URL; override with WEBBULA_API_BASE_URL. */
+export const WEBBULA_API_BASE_URL = process.env.WEBBULA_API_BASE_URL ?? "http://eh-api-dev3.us-east-1.elasticbeanstalk.com";
+/**
+ * API version path segment. The current Webbula contract is **v4** (`/api.v4`,
+ * note the dot, not a slash); endpoints take `application/x-www-form-urlencoded`
+ * bodies. Override with `WEBBULA_API_PATH`.
+ */
+export const WEBBULA_API_PATH = process.env.WEBBULA_API_PATH ?? "/api.v4";
+/**
+ * Base URL for the persona data-append API (feature 006). The append product
+ * lives on a separate host from the hygiene API; override with
+ * `WEBBULA_PERSONA_BASE_URL`. The default is a placeholder — the real host must
+ * be supplied per deployment before `append_*` tools can succeed.
+ */
+export const WEBBULA_PERSONA_BASE_URL = process.env.WEBBULA_PERSONA_BASE_URL ?? "https://persona.webbula.com";
+/**
+ * Default identity-resolution scope for the `append_*` tools when a call omits
+ * one (CSV note: "Assume Both"). Override with `WEBBULA_PERSONA_SCOPE`; an
+ * unrecognized value falls back to `both`.
+ */
+export const WEBBULA_PERSONA_DEFAULT_SCOPE = (() => {
+    const raw = process.env.WEBBULA_PERSONA_SCOPE;
+    return raw === "individual" || raw === "household" ? raw : "both";
+})();
+/** HTTP transport listen port; override with PORT. */
+export const HTTP_PORT = Number(process.env.PORT ?? 3000);
+/**
+ * When set (`WEBBULA_DEBUG=1`), the client logs each raw upstream response to
+ * **stderr** (stdout is reserved for the stdio JSON-RPC stream). A `key` field,
+ * if ever present, is redacted before logging (principle V). Off by default.
+ */
+export const WEBBULA_DEBUG = process.env.WEBBULA_DEBUG === "1" || process.env.WEBBULA_DEBUG === "true";
+/*
+ * Per-tool default profile presets, hardcoded to the values from the MCP tool
+ * list ("Filter Profile or Preset" column). The account owns the real set of
+ * profile names (they are typically prefixed with the company name upstream,
+ * e.g. `Webbula_B2C_HVI`); these bare presets are the out-of-the-box defaults a
+ * call uses when it omits `profile`. Each stays env-overridable (undocumented)
+ * for accounts whose preset names differ.
+ */
+/** `verify_email` → `task/express` verification preset (CSV: `_Verification_Only`). */
+export const WEBBULA_VERIFICATION_PROFILE = process.env.WEBBULA_VERIFICATION_PROFILE ?? "_Verification_Only";
+/** `hygiene_check` → `task/express` email-hygiene preset (CSV: `_B2C_HVI`). */
+export const WEBBULA_HYGIENE_PROFILE = process.env.WEBBULA_HYGIENE_PROFILE ?? "_B2C_HVI";
+/** `validate_lead` → `task/lead` lead-hygiene preset (CSV: `_Default_LHVI`). */
+export const WEBBULA_LEAD_PROFILE = process.env.WEBBULA_LEAD_PROFILE ?? "_Default_LHVI";
+/**
+ * `upload_file` → `task/run` batch preset. The CSV lists three batch presets
+ * (verification / hygiene / lead) for the one batch endpoint; this defaults to
+ * the verification preset and is overridden per call (or via env) for hygiene or
+ * lead batches.
+ */
+export const WEBBULA_BATCH_PROFILE = process.env.WEBBULA_BATCH_PROFILE ?? "_Verification_Only";
+/**
+ * Upper bound on addresses per `hygiene_check` call (research D8 / FR-010). The
+ * express endpoint is synchronous, so large lists belong in the batch flow.
+ * Falls back to 100; a non-positive or non-numeric override is ignored.
+ */
+export const WEBBULA_MAX_EMAILS = (() => {
+    const raw = Number(process.env.WEBBULA_MAX_EMAILS);
+    return Number.isInteger(raw) && raw > 0 ? raw : 100;
+})();
+/**
+ * Maximum decoded size (bytes) of an inline base64 upload for `upload_file`
+ * (feature 003, FR-003). The JSON `file_base64` mode is documented at ~1 MiB;
+ * larger files must use a remote `data_source`. Override with
+ * `WEBBULA_MAX_INLINE_BYTES`; a non-positive/non-numeric override falls back.
+ */
+export const WEBBULA_MAX_INLINE_BYTES = (() => {
+    const raw = Number(process.env.WEBBULA_MAX_INLINE_BYTES);
+    return Number.isInteger(raw) && raw > 0 ? raw : 1_048_576;
+})();
+/**
+ * Resolve the Webbula API key from the environment. Returns `undefined` when
+ * `WEBBULA_API_KEY` is unset — callers that require a key (tool handlers) surface
+ * a structured error per constitution principle V (Fail Loud, Fail Structured).
+ */
+export function resolveApiKey() {
+    return process.env.WEBBULA_API_KEY || undefined;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;AACzC,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAEtC,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAC/B,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,mDAAmD,CAAC;AAE1F;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,SAAS,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACnC,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,6BAA6B,CAAC;AAExE;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,GAAG,EAAE;IACjD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;IAC9C,OAAO,GAAG,KAAK,YAAY,IAAI,GAAG,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AACpE,CAAC,CAAC,EAAE,CAAC;AAEL,sDAAsD;AACtD,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;AAE1D;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,MAAM,CAAC;AAE5E;;;;;;;GAOG;AAEH,uFAAuF;AACvF,MAAM,CAAC,MAAM,4BAA4B,GACvC,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,oBAAoB,CAAC;AAEnE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,uBAAuB,GAClC,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,UAAU,CAAC;AAEpD,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAC/B,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,eAAe,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAChC,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,oBAAoB,CAAC;AAE5D;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE;IACtC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACnD,OAAO,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;AACtD,CAAC,CAAC,EAAE,CAAC;AAEL;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,GAAG,EAAE;IAC5C,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;IACzD,OAAO,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5D,CAAC,CAAC,EAAE,CAAC;AAEL;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,SAAS,CAAC;AAClD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * Webbula MCP server entry point.
+ *
+ * Dual-transport bootstrap (constitution principle IV):
+ *   - default            → local stdio transport (the `webbula-mcp` npm binary)
+ *   - `--http` / MCP_HTTP → remote HTTP transport (`/mcp`) plus `/health`
+ *
+ * Both transports expose the identical tool set via `registerTools()`.
+ */
+import { startHttpServer } from "./server/http.js";
+import { startStdioServer } from "./server/stdio.js";
+const useHttp = process.argv.includes("--http") || process.env.MCP_HTTP === "1";
+if (useHttp) {
+    startHttpServer();
+}
+else {
+    startStdioServer().catch((error) => {
+        console.error("webbula-mcp: failed to start stdio transport:", error);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,OAAO,GACX,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC;AAElE,IAAI,OAAO,EAAE,CAAC;IACZ,eAAe,EAAE,CAAC;AACpB,CAAC;KAAM,CAAC;IACN,gBAAgB,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACjC,OAAO,CAAC,KAAK,CAAC,+CAA+C,EAAE,KAAK,CAAC,CAAC;QACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/server/http.d.ts

@@ -0,0 +1,4 @@
+/** Build the Express app. Exported so it can be exercised in tests. */
+export declare function createHttpApp(): import("express-serve-static-core").Express;
+/** Start the HTTP server and resolve once it is listening. */
+export declare function startHttpServer(port?: number): import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;

package/dist/server/http.js

@@ -0,0 +1,76 @@
+/**
+ * Remote HTTP transport entry point for the Webbula MCP server.
+ *
+ * Hosts the operational `GET /health` liveness/readiness endpoint plus the MCP
+ * Streamable HTTP transport at `/mcp`. The MCP server is built per request in
+ * stateless mode (`sessionIdGenerator: undefined`) via the shared
+ * `buildMcpServer()`, so the tool set is identical to the stdio transport
+ * (constitution principle IV).
+ */
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+import { HTTP_PORT, SERVER_NAME, SERVER_VERSION } from "../config.js";
+import { buildMcpServer } from "./stdio.js";
+const startedAt = Date.now();
+/** Build the Express app. Exported so it can be exercised in tests. */
+export function createHttpApp() {
+    const app = express();
+    app.use(express.json());
+    // Unauthenticated health endpoint — operational contract for probes.
+    app.get("/health", (_req, res) => {
+        const uptimeSeconds = Math.floor((Date.now() - startedAt) / 1000);
+        res.status(200).json({
+            status: "ok",
+            service: SERVER_NAME,
+            version: SERVER_VERSION,
+            uptime_seconds: uptimeSeconds,
+            timestamp: new Date().toISOString(),
+        });
+    });
+    // MCP Streamable HTTP transport — stateless: a fresh server + transport per
+    // request, with no session persistence (suits the synchronous, short tool calls).
+    app.post("/mcp", async (req, res) => {
+        const server = buildMcpServer();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+        });
+        res.on("close", () => {
+            void transport.close();
+            void server.close();
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (error) {
+            console.error(`${SERVER_NAME}: /mcp request failed:`, error);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+        }
+    });
+    // Stateless transport: session-based GET/DELETE are not supported.
+    const methodNotAllowed = (_req, res) => {
+        res.status(405).json({
+            jsonrpc: "2.0",
+            error: { code: -32000, message: "Method not allowed (stateless transport)" },
+            id: null,
+        });
+    };
+    app.get("/mcp", methodNotAllowed);
+    app.delete("/mcp", methodNotAllowed);
+    return app;
+}
+/** Start the HTTP server and resolve once it is listening. */
+export function startHttpServer(port = HTTP_PORT) {
+    const app = createHttpApp();
+    return app.listen(port, () => {
+        console.error(`${SERVER_NAME} v${SERVER_VERSION} HTTP transport listening on port ${port} (GET /health)`);
+    });
+}
+//# sourceMappingURL=http.js.map