@webbula/mcp 1.0.0

package/dist/server/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/server/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACnG,OAAO,OAAwC,MAAM,SAAS,CAAC;AAE/D,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AAE7B,uEAAuE;AACvE,MAAM,UAAU,aAAa;IAC3B,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAExB,qEAAqE;IACrE,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,IAAa,EAAE,GAAa,EAAE,EAAE;QAClD,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC;QAClE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;YACnB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,WAAW;YACpB,OAAO,EAAE,cAAc;YACvB,cAAc,EAAE,aAAa;YAC7B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,4EAA4E;IAC5E,kFAAkF;IAClF,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;QACrD,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;QAChC,MAAM,SAAS,GAAG,IAAI,6BAA6B,CAAC;YAClD,kBAAkB,EAAE,SAAS;YAC7B,kBAAkB,EAAE,IAAI;SACzB,CAAC,CAAC;QACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACnB,KAAK,SAAS,CAAC,KAAK,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;QACtB,CAAC,CAAC,CAAC;QACH,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAChC,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,GAAG,WAAW,wBAAwB,EAAE,KAAK,CAAC,CAAC;YAC7D,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;gBACrB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;oBACnB,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,uBAAuB,EAAE;oBACzD,EAAE,EAAE,IAAI;iBACT,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,mEAAmE;IACnE,MAAM,gBAAgB,GAAG,CAAC,IAAa,EAAE,GAAa,EAAE,EAAE;QACxD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;YACnB,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,0CAA0C,EAAE;YAC5E,EAAE,EAAE,IAAI;SACT,CAAC,CAAC;IACL,CAAC,CAAC;IACF,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAClC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAErC,OAAO,GAAG,CAAC;AACb,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,eAAe,CAAC,OAAe,SAAS;IACtD,MAAM,GAAG,GAAG,aAAa,EAAE,CAAC;IAC5B,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE;QAC3B,OAAO,CAAC,KAAK,CACX,GAAG,WAAW,KAAK,cAAc,qCAAqC,IAAI,gBAAgB,CAC3F,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/server/stdio.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Local stdio transport bootstrap — the `webbula-mcp` npm binary (constitution
+ * principle IV). Builds an `McpServer`, registers the shared tool set via
+ * `registerTools()`, and connects it over stdio. The tool definitions and the
+ * Webbula client are transport-agnostic, so the same `registerTools()` also
+ * serves the HTTP transport.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Build a fully-registered MCP server instance (shared shape across transports). */
+export declare function buildMcpServer(): McpServer;
+/** Connect the MCP server over stdio and start listening. */
+export declare function startStdioServer(): Promise<void>;

package/dist/server/stdio.js

@@ -0,0 +1,30 @@
+/**
+ * Local stdio transport bootstrap — the `webbula-mcp` npm binary (constitution
+ * principle IV). Builds an `McpServer`, registers the shared tool set via
+ * `registerTools()`, and connects it over stdio. The tool definitions and the
+ * Webbula client are transport-agnostic, so the same `registerTools()` also
+ * serves the HTTP transport.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createWebbulaClient } from "../api/webbula-client.js";
+import { SERVER_NAME, SERVER_VERSION } from "../config.js";
+import { registerTools } from "../tools/register.js";
+/** Build a fully-registered MCP server instance (shared shape across transports). */
+export function buildMcpServer() {
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    registerTools(server, createWebbulaClient());
+    return server;
+}
+/** Connect the MCP server over stdio and start listening. */
+export async function startStdioServer() {
+    const server = buildMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Logs go to stderr so they never corrupt the stdio JSON-RPC stream on stdout.
+    console.error(`${SERVER_NAME} v${SERVER_VERSION} stdio transport ready`);
+}
+//# sourceMappingURL=stdio.js.map

package/dist/server/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/server/stdio.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,qFAAqF;AACrF,MAAM,UAAU,cAAc;IAC5B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IACH,aAAa,CAAC,MAAM,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAC7C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,6DAA6D;AAC7D,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;IAChC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,+EAA+E;IAC/E,OAAO,CAAC,KAAK,CAAC,GAAG,WAAW,KAAK,cAAc,wBAAwB,CAAC,CAAC;AAC3E,CAAC"}

package/dist/tools/download-results.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `download_results` — download a result file from a completed batch task
+ * (spec 003 US3). Maps to `GET /api/v5/task/get_file` and returns the file
+ * content unchanged (contracts/download_results.md).
+ *
+ * The bytes are passed through unmodified — text files (`.csv`/`.txt`) as text,
+ * binary files (`.xls`/`.xlsx`) base64-encoded so they survive the text channel.
+ * The wrapper never parses rows or decodes verdict flags (principle I, SC-003).
+ * A JSON error body from the upstream is mapped to a structured error by the
+ * client, never returned as content (FR-007).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { type WebbulaClient } from "../api/webbula-client.js";
+export declare const DOWNLOAD_RESULTS_NAME = "download_results";
+export declare const DOWNLOAD_RESULTS_DESCRIPTION: string;
+/**
+ * Documented result filenames (OpenAPI `get_file` enum + the v4.2.22 guide's
+ * `parse_errors.csv`). Used for a friendly pre-flight error; the canonical set
+ * for a given task is what `file_status.files` reports.
+ */
+export declare const ALLOWED_RESULT_FILES: readonly ["insert.csv", "_report.xls", "parse_errors.csv"];
+export declare const downloadResultsInputShape: {
+    readonly package_name: z.ZodString;
+    readonly filename: z.ZodString;
+};
+export interface ResultFile {
+    filename: string;
+    encoding: "text" | "base64";
+    content: string;
+}
+/** Validate the requested filename against the documented set (FR-006). */
+export declare function assertAllowedFilename(filename: string): void;
+/** Register `download_results` against the MCP server. */
+export declare function registerDownloadResults(server: McpServer, client: WebbulaClient): void;

package/dist/tools/download-results.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { WebbulaApiError } from "../api/webbula-client.js";
+import { toToolError } from "./errors.js";
+export const DOWNLOAD_RESULTS_NAME = "download_results";
+export const DOWNLOAD_RESULTS_DESCRIPTION = "Download a result file from a completed batch task. Provide the package_name " +
+    "and a filename reported by file_status (e.g. insert.csv for cleaned records, " +
+    "_report.xls for the summary). Returns the file content unchanged — text files " +
+    "as text, binary files base64-encoded.";
+/**
+ * Documented result filenames (OpenAPI `get_file` enum + the v4.2.22 guide's
+ * `parse_errors.csv`). Used for a friendly pre-flight error; the canonical set
+ * for a given task is what `file_status.files` reports.
+ */
+export const ALLOWED_RESULT_FILES = [
+    "insert.csv",
+    "_report.xls",
+    "parse_errors.csv",
+];
+export const downloadResultsInputShape = {
+    package_name: z.string().describe("The task handle from upload_file."),
+    filename: z
+        .string()
+        .describe("A result filename reported by file_status (e.g. insert.csv, _report.xls)."),
+};
+/** Text result extensions are returned as-is; everything else is base64. */
+function encodingFor(filename) {
+    const lower = filename.toLowerCase();
+    return lower.endsWith(".csv") || lower.endsWith(".txt") ? "text" : "base64";
+}
+/** Validate the requested filename against the documented set (FR-006). */
+export function assertAllowedFilename(filename) {
+    if (!ALLOWED_RESULT_FILES.includes(filename)) {
+        throw new WebbulaApiError("validation", `Unknown result file — request one listed by file_status (${ALLOWED_RESULT_FILES.join(", ")})`);
+    }
+}
+/** Register `download_results` against the MCP server. */
+export function registerDownloadResults(server, client) {
+    server.registerTool(DOWNLOAD_RESULTS_NAME, {
+        title: "Download a batch result file",
+        description: DOWNLOAD_RESULTS_DESCRIPTION,
+        inputSchema: downloadResultsInputShape,
+    }, async ({ package_name, filename }) => {
+        try {
+            assertAllowedFilename(filename);
+            const { bytes } = await client.getResultFile({ package_name, filename });
+            const encoding = encodingFor(filename);
+            const result = {
+                filename,
+                encoding,
+                content: encoding === "text" ? bytes.toString("utf8") : bytes.toString("base64"),
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+}
+//# sourceMappingURL=download-results.js.map

package/dist/tools/download-results.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download-results.js","sourceRoot":"","sources":["../../src/tools/download-results.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,eAAe,EAAsB,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC;AAExD,MAAM,CAAC,MAAM,4BAA4B,GACvC,+EAA+E;IAC/E,+EAA+E;IAC/E,gFAAgF;IAChF,uCAAuC,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,YAAY;IACZ,aAAa;IACb,kBAAkB;CACV,CAAC;AAEX,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;IACtE,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,CAAC,2EAA2E,CAAC;CAChF,CAAC;AAQX,4EAA4E;AAC5E,SAAS,WAAW,CAAC,QAAgB;IACnC,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IACrC,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC9E,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,QAAiD,CAAC,EAAE,CAAC;QACtF,MAAM,IAAI,eAAe,CACvB,YAAY,EACZ,4DAA4D,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC/F,CAAC;IACJ,CAAC;AACH,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,uBAAuB,CAAC,MAAiB,EAAE,MAAqB;IAC9E,MAAM,CAAC,YAAY,CACjB,qBAAqB,EACrB;QACE,KAAK,EAAE,8BAA8B;QACrC,WAAW,EAAE,4BAA4B;QACzC,WAAW,EAAE,yBAAyB;KACvC,EACD,KAAK,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,EAAE,EAAE;QACnC,IAAI,CAAC;YACH,qBAAqB,CAAC,QAAQ,CAAC,CAAC;YAChC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,CAAC;YACzE,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;YACvC,MAAM,MAAM,GAAe;gBACzB,QAAQ;gBACR,QAAQ;gBACR,OAAO,EAAE,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;aACjF,CAAC;YACF,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;gBAClE,iBAAiB,EAAE,MAA4C;aAChE,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/errors.d.ts

@@ -0,0 +1,10 @@
+export interface ToolErrorResult {
+    isError: true;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    /** Matches the SDK's `CallToolResult` open shape. */
+    [key: string]: unknown;
+}
+export declare function toToolError(error: unknown): ToolErrorResult;

package/dist/tools/errors.js

@@ -0,0 +1,16 @@
+/**
+ * Turn any thrown error into a structured MCP tool error (`isError: true`),
+ * never a fabricated success and never leaking the API key (constitution
+ * principle V). `WebbulaApiError` messages are already safe to surface verbatim;
+ * unknown errors are reported generically.
+ */
+import { WebbulaApiError } from "../api/webbula-client.js";
+export function toToolError(error) {
+    const message = error instanceof WebbulaApiError
+        ? error.message
+        : error instanceof Error
+            ? `Unexpected error: ${error.message}`
+            : "Unexpected error";
+    return { isError: true, content: [{ type: "text", text: message }] };
+}
+//# sourceMappingURL=errors.js.map

package/dist/tools/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/tools/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAS3D,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,MAAM,OAAO,GACX,KAAK,YAAY,eAAe;QAC9B,CAAC,CAAC,KAAK,CAAC,OAAO;QACf,CAAC,CAAC,KAAK,YAAY,KAAK;YACtB,CAAC,CAAC,qBAAqB,KAAK,CAAC,OAAO,EAAE;YACtC,CAAC,CAAC,kBAAkB,CAAC;IAC3B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AACvE,CAAC"}

package/dist/tools/file-status.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `file_status` — check a batch task's status (spec 003 US2). Maps to
+ * `GET /api/v5/task/info` and reshapes `BatchTaskResponse` into a
+ * `BatchTaskStatus` (contracts/file_status.md).
+ *
+ * `status` is the upstream value verbatim; `status_label` + `terminal` are a
+ * STATIC `TASK_STATUS` lookup (`api/enums.ts`), omitted for an undocumented
+ * status (FR-005, principle I). `files` is surfaced whenever the upstream
+ * returns it.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { BatchTaskResponse } from "../api/types.js";
+import type { WebbulaClient } from "../api/webbula-client.js";
+export declare const FILE_STATUS_NAME = "file_status";
+export declare const FILE_STATUS_DESCRIPTION: string;
+export declare const fileStatusInputShape: {
+    readonly package_name: z.ZodString;
+};
+export interface BatchTaskStatus {
+    package_name?: string;
+    /** Upstream status token, verbatim. */
+    status?: string;
+    /** Human-readable label for `status`; omitted for an undocumented status. */
+    status_label?: string;
+    /** Whether the status is terminal; omitted for an undocumented status. */
+    terminal?: boolean;
+    /** Result files available for download (when the upstream reports them). */
+    files?: string[];
+    transaction?: string;
+}
+/** Reshape the upstream `BatchTaskResponse`, enriching the status (FR-005). */
+export declare function toBatchTaskStatus(response: BatchTaskResponse): BatchTaskStatus;
+/** Register `file_status` against the MCP server. */
+export declare function registerFileStatus(server: McpServer, client: WebbulaClient): void;

package/dist/tools/file-status.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { TASK_STATUS } from "../api/enums.js";
+import { toToolError } from "./errors.js";
+export const FILE_STATUS_NAME = "file_status";
+export const FILE_STATUS_DESCRIPTION = "Check the status of a batch task by its package_name. Returns the current " +
+    "stage (preparing → prepared → running → finished → completed, or canceled) " +
+    "with a human-readable label and whether it is terminal, plus — once completed " +
+    "— the list of result files ready to download. Poll this after upload_file " +
+    "until the task is terminal.";
+export const fileStatusInputShape = {
+    package_name: z
+        .string()
+        .describe("The task handle returned by upload_file."),
+};
+/** Reshape the upstream `BatchTaskResponse`, enriching the status (FR-005). */
+export function toBatchTaskStatus(response) {
+    const out = {};
+    if (typeof response.package_name === "string")
+        out.package_name = response.package_name;
+    if (typeof response.status === "string") {
+        out.status = response.status;
+        if (Object.prototype.hasOwnProperty.call(TASK_STATUS, response.status)) {
+            const info = TASK_STATUS[response.status];
+            out.status_label = info.label;
+            out.terminal = info.terminal;
+        }
+    }
+    if (Array.isArray(response.files))
+        out.files = response.files;
+    if (typeof response.transaction === "string")
+        out.transaction = response.transaction;
+    return out;
+}
+/** Register `file_status` against the MCP server. */
+export function registerFileStatus(server, client) {
+    server.registerTool(FILE_STATUS_NAME, {
+        title: "Check a batch task's status",
+        description: FILE_STATUS_DESCRIPTION,
+        inputSchema: fileStatusInputShape,
+    }, async ({ package_name }) => {
+        try {
+            const response = await client.taskInfo(package_name);
+            const result = toBatchTaskStatus(response);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+}
+//# sourceMappingURL=file-status.js.map

package/dist/tools/file-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-status.js","sourceRoot":"","sources":["../../src/tools/file-status.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAE9C,MAAM,CAAC,MAAM,uBAAuB,GAClC,4EAA4E;IAC5E,6EAA6E;IAC7E,gFAAgF;IAChF,4EAA4E;IAC5E,6BAA6B,CAAC;AAEhC,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,QAAQ,CAAC,0CAA0C,CAAC;CAC/C,CAAC;AAeX,+EAA+E;AAC/E,MAAM,UAAU,iBAAiB,CAAC,QAA2B;IAC3D,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,IAAI,OAAO,QAAQ,CAAC,YAAY,KAAK,QAAQ;QAC3C,GAAG,CAAC,YAAY,GAAG,QAAQ,CAAC,YAAY,CAAC;IAC3C,IAAI,OAAO,QAAQ,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxC,GAAG,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC7B,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACvE,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC1C,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC;YAC9B,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,GAAG,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;IAC9D,IAAI,OAAO,QAAQ,CAAC,WAAW,KAAK,QAAQ;QAAE,GAAG,CAAC,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAC;IACrF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,kBAAkB,CAAC,MAAiB,EAAE,MAAqB;IACzE,MAAM,CAAC,YAAY,CACjB,gBAAgB,EAChB;QACE,KAAK,EAAE,6BAA6B;QACpC,WAAW,EAAE,uBAAuB;QACpC,WAAW,EAAE,oBAAoB;KAClC,EACD,KAAK,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE;QACzB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;YACrD,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YAC3C,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;gBAClE,iBAAiB,EAAE,MAA4C;aAChE,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/get-credits.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `get_credits` — read the account's remaining credit balance (spec US3). Maps
+ * to `GET /api/v5/account/info?mode=short` and reshapes `CreditsRemaining[]`
+ * into a `CreditBalance` (contracts/get_credits.md).
+ *
+ * `unlimited` is `true` when the upstream scenario reports `limited === false`
+ * (FR-003). `mode=short` keeps the API token out of the response; the wrapper
+ * also drops `key` defensively (constitution principle V).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AccountInfoResponse } from "../api/types.js";
+import type { WebbulaClient } from "../api/webbula-client.js";
+export declare const GET_CREDITS_NAME = "get_credits";
+export declare const GET_CREDITS_DESCRIPTION: string;
+/** This tool takes no parameters. */
+export declare const getCreditsInputShape: {};
+export interface CreditScenario {
+    service?: string;
+    scenario?: string;
+    records?: number;
+    /** `true` when the upstream scenario is not metered (`limited === false`). */
+    unlimited: boolean;
+}
+export interface CreditBalance {
+    login?: string;
+    scenarios: CreditScenario[];
+}
+/** Reshape the upstream account info into the agent-facing balance. */
+export declare function toCreditBalance(response: AccountInfoResponse): CreditBalance;
+/** Register `get_credits` against the MCP server. */
+export declare function registerGetCredits(server: McpServer, client: WebbulaClient): void;

package/dist/tools/get-credits.js

@@ -0,0 +1,47 @@
+import { toToolError } from "./errors.js";
+export const GET_CREDITS_NAME = "get_credits";
+export const GET_CREDITS_DESCRIPTION = "Check the Webbula account's remaining credit balance before running a larger " +
+    "job. Returns remaining credits per billing scenario, with an explicit " +
+    '"unlimited" flag for accounts that are not metered. Does not consume ' +
+    "verification credits.";
+/** This tool takes no parameters. */
+export const getCreditsInputShape = {};
+/** Reshape the upstream account info into the agent-facing balance. */
+export function toCreditBalance(response) {
+    const scenarios = (response.credits_remaining ?? []).map((entry) => {
+        const scenario = { unlimited: entry.limited === false };
+        if (entry.service !== undefined)
+            scenario.service = entry.service;
+        if (entry.scenario !== undefined)
+            scenario.scenario = entry.scenario;
+        if (entry.records !== undefined)
+            scenario.records = entry.records;
+        return scenario;
+    });
+    const out = { scenarios };
+    if (response.login !== undefined)
+        out.login = response.login;
+    // `key` is intentionally never copied across (principle V).
+    return out;
+}
+/** Register `get_credits` against the MCP server. */
+export function registerGetCredits(server, client) {
+    server.registerTool(GET_CREDITS_NAME, {
+        title: "Check remaining credits",
+        description: GET_CREDITS_DESCRIPTION,
+        inputSchema: getCreditsInputShape,
+    }, async () => {
+        try {
+            const response = await client.accountInfo();
+            const result = toCreditBalance(response);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+}
+//# sourceMappingURL=get-credits.js.map

package/dist/tools/get-credits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-credits.js","sourceRoot":"","sources":["../../src/tools/get-credits.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAE9C,MAAM,CAAC,MAAM,uBAAuB,GAClC,+EAA+E;IAC/E,wEAAwE;IACxE,uEAAuE;IACvE,uBAAuB,CAAC;AAE1B,qCAAqC;AACrC,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAW,CAAC;AAehD,uEAAuE;AACvE,MAAM,UAAU,eAAe,CAAC,QAA6B;IAC3D,MAAM,SAAS,GAAqB,CAAC,QAAQ,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,GAAG,CACxE,CAAC,KAAK,EAAE,EAAE;QACR,MAAM,QAAQ,GAAmB,EAAE,SAAS,EAAE,KAAK,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;QACxE,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;YAAE,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAClE,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;YAAE,QAAQ,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QACrE,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;YAAE,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAClE,OAAO,QAAQ,CAAC;IAClB,CAAC,CACF,CAAC;IACF,MAAM,GAAG,GAAkB,EAAE,SAAS,EAAE,CAAC;IACzC,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS;QAAE,GAAG,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;IAC7D,4DAA4D;IAC5D,OAAO,GAAG,CAAC;AACb,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,kBAAkB,CAAC,MAAiB,EAAE,MAAqB;IACzE,MAAM,CAAC,YAAY,CACjB,gBAAgB,EAChB;QACE,KAAK,EAAE,yBAAyB;QAChC,WAAW,EAAE,uBAAuB;QACpC,WAAW,EAAE,oBAAoB;KAClC,EACD,KAAK,IAAI,EAAE;QACT,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC;YAC5C,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;YACzC,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;gBAClE,iBAAiB,EAAE,MAA4C;aAChE,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/hygiene-check.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `hygiene_check` — full hygiene on a list of addresses (spec US2). Maps to
+ * `POST /api/v5/task/express` with `emails[]` and reshapes each `EmailResult`
+ * into a `HygieneResult` (contracts/hygiene_check.md), passing through the
+ * top-level `profile`, `transaction`, and `credits_remaining`.
+ *
+ * Like `verify_email`, every classification is upstream-verbatim and the `trust`
+ * block is assembled only from present upstream fields (principles I and II).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { EmailResult, ExpressEmailResponseV5 } from "../api/types.js";
+import type { WebbulaClient } from "../api/webbula-client.js";
+import { type TrustMetadata } from "../trust.js";
+export declare const HYGIENE_CHECK_NAME = "hygiene_check";
+export declare const HYGIENE_CHECK_DESCRIPTION: string;
+/** Zod raw shape for the tool input (validated before any upstream call). */
+export declare const hygieneCheckInputShape: {
+    readonly emails: z.ZodArray<z.ZodString, "many">;
+    readonly profile: z.ZodOptional<z.ZodString>;
+};
+export interface HygieneResult {
+    email: string;
+    corrected?: string;
+    /** Upstream classification token, verbatim. */
+    result: string;
+    /** Human-readable label for `result`; omitted for unknown tokens. */
+    label?: string;
+    /** Documented risk level for `result`; omitted for unknown tokens. */
+    risk?: string;
+    /** Documented description for `result`; omitted for unknown tokens. */
+    description?: string;
+    activity_first_seen?: string;
+    activity_most_recent_seen?: string;
+    activity_trajectory?: string;
+    trust?: TrustMetadata;
+}
+export interface HygieneCheckResult {
+    profile?: string;
+    transaction?: string;
+    credits_remaining?: number;
+    results: HygieneResult[];
+}
+/** Reshape one upstream `EmailResult` into a `HygieneResult`. */
+export declare function toHygieneResult(result: EmailResult): HygieneResult;
+/** Reshape the full express response into the tool's output. */
+export declare function toHygieneCheckResult(response: ExpressEmailResponseV5): HygieneCheckResult;
+/** Register `hygiene_check` against the MCP server. */
+export declare function registerHygieneCheck(server: McpServer, client: WebbulaClient): void;

package/dist/tools/hygiene-check.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { lookupEmailVerdict } from "../api/enums.js";
+import { WEBBULA_HYGIENE_PROFILE, WEBBULA_MAX_EMAILS } from "../config.js";
+import { assembleTrust } from "../trust.js";
+import { toToolError } from "./errors.js";
+export const HYGIENE_CHECK_NAME = "hygiene_check";
+export const HYGIENE_CHECK_DESCRIPTION = "Run Webbula's full email hygiene analysis on one or more addresses. For each " +
+    "email you get its classification, activity history (first/last seen, " +
+    "trajectory), a corrected form when a typo is detected, and a trust block. Use " +
+    "this when you need the full picture — threats, spam-trap/complainer risk, and " +
+    `provenance — not just a yes/no. Accepts 1..${WEBBULA_MAX_EMAILS} addresses per call.`;
+/** Zod raw shape for the tool input (validated before any upstream call). */
+export const hygieneCheckInputShape = {
+    emails: z
+        .array(z.string().email())
+        .min(1)
+        .max(WEBBULA_MAX_EMAILS)
+        .describe(`The email addresses to check (1..${WEBBULA_MAX_EMAILS}). Larger lists belong in the batch flow.`),
+    profile: z
+        .string()
+        .optional()
+        .describe("Optional Webbula hygiene profile name. Defaults to the server's configured profile."),
+};
+/** Reshape one upstream `EmailResult` into a `HygieneResult`. */
+export function toHygieneResult(result) {
+    const out = { email: result.email, result: result.result };
+    if (result.corrected !== undefined)
+        out.corrected = result.corrected;
+    // Static lookup of the documented label/risk/description (api/enums.ts);
+    // unknown tokens leave them omitted (principle I — no guessing).
+    const verdict = lookupEmailVerdict(result.result);
+    if (verdict !== undefined) {
+        out.label = verdict.label;
+        out.risk = verdict.risk;
+        out.description = verdict.description;
+    }
+    if (result.activity_first_seen !== undefined)
+        out.activity_first_seen = result.activity_first_seen;
+    if (result.activity_most_recent_seen !== undefined)
+        out.activity_most_recent_seen = result.activity_most_recent_seen;
+    if (result.activity_trajectory !== undefined)
+        out.activity_trajectory = result.activity_trajectory;
+    const trust = assembleTrust(result);
+    if (trust !== undefined)
+        out.trust = trust;
+    return out;
+}
+/** Reshape the full express response into the tool's output. */
+export function toHygieneCheckResult(response) {
+    const out = {
+        results: (response.emails ?? []).map(toHygieneResult),
+    };
+    if (response.profile !== undefined)
+        out.profile = response.profile;
+    if (response.transaction !== undefined)
+        out.transaction = response.transaction;
+    if (response.credits_remaining !== undefined)
+        out.credits_remaining = response.credits_remaining;
+    return out;
+}
+/** Register `hygiene_check` against the MCP server. */
+export function registerHygieneCheck(server, client) {
+    server.registerTool(HYGIENE_CHECK_NAME, {
+        title: "Hygiene check a list of emails",
+        description: HYGIENE_CHECK_DESCRIPTION,
+        inputSchema: hygieneCheckInputShape,
+    }, async ({ emails, profile }) => {
+        try {
+            const response = await client.expressHygieneV5({
+                emails,
+                profile: profile ?? WEBBULA_HYGIENE_PROFILE,
+            });
+            const result = toHygieneCheckResult(response);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+}
+//# sourceMappingURL=hygiene-check.js.map

package/dist/tools/hygiene-check.js.map

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

package/dist/tools/persona-append.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Persona data-append tools (feature 006): `append_email`, `append_telephone`,
+ * `append_postal`, `append_automotive`. Each maps to `POST {persona}/v1/append`
+ * with a fixed `filter` selecting the data point to resolve, and reshapes the
+ * persona response into one agent-facing `AppendResult`.
+ *
+ * The four tools share one PII input shape and differ only by their `filter`.
+ * The wrapper forwards exactly the PII the caller supplied and passes the
+ * appended `data` through verbatim — it never invents PII or infers a match
+ * (constitution principle I). A no-match is reported as `matched: false`, not a
+ * fabricated value; transport/auth/upstream failures surface as structured
+ * errors (principle V).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { PersonaAppendResponse } from "../api/types.js";
+import { type PersonaFilter, type PersonaScope, type WebbulaClient } from "../api/webbula-client.js";
+/** The PII attributes that can serve as a match key (at least one required). */
+export declare const APPEND_MATCH_KEYS: readonly ["first_name", "last_name", "email", "address", "city", "state", "zip5", "phone"];
+/** Zod raw shape shared by all four append tools (validated before any call). */
+export declare const appendInputShape: {
+    readonly first_name: z.ZodOptional<z.ZodString>;
+    readonly last_name: z.ZodOptional<z.ZodString>;
+    readonly email: z.ZodOptional<z.ZodString>;
+    readonly address: z.ZodOptional<z.ZodString>;
+    readonly city: z.ZodOptional<z.ZodString>;
+    readonly state: z.ZodOptional<z.ZodString>;
+    readonly zip5: z.ZodOptional<z.ZodString>;
+    readonly phone: z.ZodOptional<z.ZodString>;
+    readonly scope: z.ZodOptional<z.ZodEnum<["individual", "household", "both"]>>;
+};
+/** Parsed, validated append input (one optional field per match key + scope). */
+export type AppendInput = {
+    [K in (typeof APPEND_MATCH_KEYS)[number]]?: string;
+} & {
+    scope?: PersonaScope;
+};
+/** Agent-facing append result — the appended data passed through verbatim. */
+export interface AppendResult {
+    /** Which data point was requested. */
+    filter: PersonaFilter;
+    /** The identity-resolution scope used for the lookup. */
+    scope: PersonaScope;
+    /** True when the persona endpoint resolved a match with data. */
+    matched: boolean;
+    /** The appended field(s), verbatim from the upstream `data` block. */
+    data?: Record<string, unknown>;
+}
+/** Reshape a persona response into the agent-facing result (no fabrication). */
+export declare function toAppendResult(filter: PersonaFilter, scope: PersonaScope, response: PersonaAppendResponse): AppendResult;
+/** Definition of one append tool — its name, filter, and human-facing text. */
+interface AppendToolSpec {
+    name: string;
+    title: string;
+    filter: PersonaFilter;
+    description: string;
+}
+/** The four append tools (CSV rows 22–25). */
+export declare const APPEND_TOOLS: readonly AppendToolSpec[];
+/** Register all four persona append tools against the MCP server. */
+export declare function registerPersonaAppend(server: McpServer, client: WebbulaClient): void;
+export {};