@klarefi/mcp 0.2.0

package/dist/tools.js

@@ -0,0 +1,450 @@
+import { stat } from "node:fs/promises";
+import { basename } from "node:path";
+import { Klarefi } from "@klarefi/node";
+import { IntakeSessionRegistry } from "./sessions.js";
+const MAX_INLINE_UPLOAD_BYTES = 5 * 1024 * 1024;
+const MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+export const tools = [
+    {
+        name: "create_connector_from_openapi",
+        description: "Import a public OpenAPI JSON URL as a Klarefi verification connector. " +
+            "JSON specs only (convert YAML first). The connector goes live " +
+            "immediately — review its functions before routing live traffic.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                connector_key: { type: "string" },
+                openapi_url: { type: "string" },
+                label: { type: "string" },
+                base_url: { type: "string" },
+            },
+            required: ["connector_key", "openapi_url"],
+        },
+    },
+    {
+        name: "create_connector",
+        description: "Create or update a Klarefi verification connector manifest. The " +
+            "connector is active as soon as this returns — there is no draft/review " +
+            "step, so review its functions before routing live traffic.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: true,
+            required: [
+                "connector_key",
+                "label",
+                "connector_type",
+                "transport",
+                "functions",
+            ],
+        },
+    },
+    {
+        name: "delete_connector",
+        description: "Delete a configured Klarefi connector by key.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                connector_key: { type: "string" },
+            },
+            required: ["connector_key"],
+        },
+    },
+    {
+        name: "create_intake_session",
+        description: "Create a hosted Klarefi intake session.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                case_type_id: { type: "string" },
+                external_case_id: { type: "string" },
+                external_applicant_id: { type: "string" },
+                external_customer_id: { type: "string" },
+                return_url: { type: "string" },
+                ttl_hours: { type: "number" },
+                locale: { type: "string" },
+                prefill: {
+                    type: "object",
+                    additionalProperties: true,
+                    description: "Prefill payload passed through to the session; schema owned by the prefill feature",
+                },
+            },
+            required: ["case_type_id"],
+        },
+    },
+    {
+        name: "get_case",
+        description: "Retrieve a Klarefi case and resolved facts.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                case_id: { type: "string" },
+            },
+            required: ["case_id"],
+        },
+    },
+    {
+        name: "open_intake",
+        description: "Open an applicant-plane intake session from a signed URL or from session_id plus access_token. No KLAREFI_API_KEY is required.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                url: {
+                    type: "string",
+                    description: "Signed hosted intake URL.",
+                },
+                session_id: { type: "string" },
+                access_token: { type: "string" },
+                api_base_url: {
+                    type: "string",
+                    description: "Klarefi API base URL. Defaults to KLAREFI_API_BASE_URL or https://api.klarefi.com.",
+                },
+            },
+        },
+    },
+    {
+        name: "get_intake_state",
+        description: "Get the current applicant-plane intake state for the selected or most recently opened session.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string" },
+            },
+        },
+    },
+    {
+        name: "answer_question",
+        description: "Answer the active applicant question with free text, optionally targeting a task_id.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                text: { type: "string" },
+                session_id: { type: "string" },
+                task_id: { type: "string" },
+            },
+            required: ["text"],
+        },
+    },
+    {
+        name: "answer_fields",
+        description: 'Answer structured requested facts by fact_id. Values must be strings; yes_no fields take "yes" or "no", and date fields use YYYY-MM-DD.',
+        inputSchema: {
+            type: "object",
+            properties: {
+                fields: {
+                    type: "object",
+                    additionalProperties: { type: "string" },
+                    description: "String values keyed by fact_id.",
+                },
+                session_id: { type: "string" },
+                task_id: { type: "string" },
+            },
+            required: ["fields"],
+        },
+    },
+    {
+        name: "upload_document",
+        description: "Upload a requested applicant document. Provide exactly one of file_path or content_base64. Inline content_base64 is limited to 5MB decoded; use file_path for larger files up to 25MB.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file_path: { type: "string" },
+                content_base64: { type: "string" },
+                filename: {
+                    type: "string",
+                    description: "Required with content_base64. Defaults to the basename of file_path.",
+                },
+                mime_type: { type: "string" },
+                session_id: { type: "string" },
+                task_id: { type: "string" },
+            },
+        },
+    },
+    {
+        name: "submit_intake",
+        description: "Submit the applicant intake. Returns submitted, blockers, and the fresh intake state.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string" },
+                field_values: {
+                    type: "object",
+                    additionalProperties: true,
+                    description: "Optional final field values; each value must be string or null.",
+                },
+            },
+        },
+    },
+    {
+        name: "save_intake_draft",
+        description: "Save applicant form draft fields without submitting. Field values must be strings or null.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fields: {
+                    type: "object",
+                    additionalProperties: true,
+                    description: "Draft field values keyed by field_id.",
+                },
+                session_id: { type: "string" },
+            },
+            required: ["fields"],
+        },
+    },
+    {
+        name: "wait_for_next_action",
+        description: "Poll until the intake leaves processing or the timeout expires. If timed_out is true, call wait_for_next_action again.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string" },
+                timeout_seconds: {
+                    type: "number",
+                    default: 60,
+                    maximum: 120,
+                },
+            },
+        },
+    },
+];
+const defaultIntakeRegistry = new IntakeSessionRegistry();
+function createClient() {
+    const apiKey = process.env.KLAREFI_API_KEY?.trim();
+    if (!apiKey) {
+        throw new Error("KLAREFI_API_KEY is required.");
+    }
+    const baseUrl = process.env.KLAREFI_API_BASE_URL?.trim();
+    return new Klarefi({ apiKey, ...(baseUrl ? { baseUrl } : {}) });
+}
+export function requiredString(args, key) {
+    const value = args[key];
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${key} is required.`);
+    }
+    return value.trim();
+}
+function optionalString(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`${key} must be a string.`);
+    }
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requiredRecord(args, key) {
+    const value = args[key];
+    if (!isRecord(value)) {
+        throw new Error(`${key} is required and must be an object.`);
+    }
+    return value;
+}
+function requiredStringRecord(args, key) {
+    const record = requiredRecord(args, key);
+    const fields = {};
+    for (const [fieldKey, value] of Object.entries(record)) {
+        if (typeof value !== "string") {
+            throw new Error(`${key}.${fieldKey} must be a string.`);
+        }
+        fields[fieldKey] = value;
+    }
+    return fields;
+}
+function nullableStringRecord(value, key) {
+    if (!isRecord(value)) {
+        throw new Error(`${key} must be an object.`);
+    }
+    const fields = {};
+    for (const [fieldKey, fieldValue] of Object.entries(value)) {
+        if (fieldValue !== null && typeof fieldValue !== "string") {
+            throw new Error(`${key}.${fieldKey} must be a string or null.`);
+        }
+        fields[fieldKey] = fieldValue;
+    }
+    return fields;
+}
+function optionalNullableStringRecord(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    return nullableStringRecord(value, key);
+}
+function textResult(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}
+function decodedBase64Size(value) {
+    const normalized = value.replace(/\s+/g, "");
+    const padding = normalized.endsWith("==")
+        ? 2
+        : normalized.endsWith("=")
+            ? 1
+            : 0;
+    return Math.max(0, Math.floor((normalized.length * 3) / 4) - padding);
+}
+function validateOpenIntakeArgs(args) {
+    const url = optionalString(args, "url");
+    const sessionId = optionalString(args, "session_id");
+    const accessToken = optionalString(args, "access_token");
+    if (url && (sessionId || accessToken)) {
+        throw new Error("Provide either url or session_id with access_token, not both.");
+    }
+    if (!url && (!sessionId || !accessToken)) {
+        throw new Error("open_intake requires either url or both session_id and access_token.");
+    }
+    return {
+        url,
+        session_id: sessionId,
+        access_token: accessToken,
+        api_base_url: optionalString(args, "api_base_url"),
+    };
+}
+async function uploadDocumentArgs(args) {
+    const filePath = optionalString(args, "file_path");
+    const contentBase64 = optionalString(args, "content_base64");
+    if (Boolean(filePath) === Boolean(contentBase64)) {
+        throw new Error("Provide exactly one of file_path or content_base64 for upload_document.");
+    }
+    const filename = optionalString(args, "filename");
+    const mimeType = optionalString(args, "mime_type");
+    const taskId = optionalString(args, "task_id");
+    if (contentBase64) {
+        if (!filename) {
+            throw new Error("filename is required when content_base64 is provided.");
+        }
+        const expectedBytes = decodedBase64Size(contentBase64);
+        if (expectedBytes > MAX_INLINE_UPLOAD_BYTES) {
+            throw new Error("content_base64 uploads are limited to 5MB decoded. Use file_path for larger documents up to 25MB.");
+        }
+        const bytes = Buffer.from(contentBase64, "base64");
+        if (bytes.byteLength > MAX_INLINE_UPLOAD_BYTES) {
+            throw new Error("content_base64 uploads are limited to 5MB decoded. Use file_path for larger documents up to 25MB.");
+        }
+        return {
+            file: bytes,
+            filename,
+            ...(mimeType ? { mimeType } : {}),
+            ...(taskId ? { taskId } : {}),
+        };
+    }
+    const requiredFilePath = filePath ?? "";
+    const file = await stat(requiredFilePath);
+    if (file.size > MAX_UPLOAD_BYTES) {
+        throw new Error("Document uploads are limited to 25MB.");
+    }
+    return {
+        file: requiredFilePath,
+        filename: filename ?? basename(requiredFilePath),
+        ...(mimeType ? { mimeType } : {}),
+        ...(taskId ? { taskId } : {}),
+    };
+}
+async function callToolValue(name, args, deps) {
+    if (name === "create_connector_from_openapi") {
+        return await deps
+            .createClient()
+            .connectors.importOpenApi(args);
+    }
+    if (name === "create_connector") {
+        return await deps
+            .createClient()
+            .connectors.create(args);
+    }
+    if (name === "delete_connector") {
+        return await deps
+            .createClient()
+            .connectors.delete(requiredString(args, "connector_key"));
+    }
+    if (name === "create_intake_session") {
+        return await deps
+            .createClient()
+            .sessions.create(args);
+    }
+    if (name === "get_case") {
+        return await deps
+            .createClient()
+            .cases.retrieve(requiredString(args, "case_id"));
+    }
+    if (name === "open_intake") {
+        const session = deps.intakeRegistry.open(validateOpenIntakeArgs(args));
+        return await session.getState();
+    }
+    if (name === "get_intake_state") {
+        return await deps.intakeRegistry
+            .get(optionalString(args, "session_id"))
+            .getState();
+    }
+    if (name === "answer_question") {
+        const taskId = optionalString(args, "task_id");
+        return await deps.intakeRegistry
+            .get(optionalString(args, "session_id"))
+            .answer(requiredString(args, "text"), {
+            ...(taskId ? { taskId } : {}),
+        });
+    }
+    if (name === "answer_fields") {
+        const taskId = optionalString(args, "task_id");
+        return await deps.intakeRegistry
+            .get(optionalString(args, "session_id"))
+            .answerFields(requiredStringRecord(args, "fields"), {
+            ...(taskId ? { taskId } : {}),
+        });
+    }
+    if (name === "upload_document") {
+        const params = await uploadDocumentArgs(args);
+        return await deps.intakeRegistry
+            .get(optionalString(args, "session_id"))
+            .uploadDocument(params);
+    }
+    if (name === "submit_intake") {
+        const fieldValues = optionalNullableStringRecord(args, "field_values");
+        return await deps.intakeRegistry
+            .get(optionalString(args, "session_id"))
+            .submit({
+            ...(fieldValues ? { fieldValues } : {}),
+        });
+    }
+    if (name === "save_intake_draft") {
+        return await deps.intakeRegistry
+            .get(optionalString(args, "session_id"))
+            .saveDraft(nullableStringRecord(args.fields, "fields"));
+    }
+    if (name === "wait_for_next_action") {
+        const timeoutSecondsValue = args.timeout_seconds ?? 60;
+        if (typeof timeoutSecondsValue !== "number" ||
+            !Number.isFinite(timeoutSecondsValue) ||
+            timeoutSecondsValue < 0 ||
+            timeoutSecondsValue > 120) {
+            throw new Error("timeout_seconds must be a number between 0 and 120.");
+        }
+        return await deps.intakeRegistry
+            .get(optionalString(args, "session_id"))
+            .nextAction({ timeoutMs: timeoutSecondsValue * 1000 });
+    }
+    throw new Error(`Unknown tool: ${name}`);
+}
+export function createToolDispatcher(deps = {}) {
+    const resolvedDeps = {
+        intakeRegistry: deps.intakeRegistry ?? defaultIntakeRegistry,
+        createClient: deps.createClient ?? createClient,
+    };
+    return {
+        tools,
+        callTool: async (name, args = {}) => textResult(await callToolValue(name, args, resolvedDeps)),
+    };
+}
+const defaultDispatcher = createToolDispatcher();
+export async function callTool(name, args = {}) {
+    return defaultDispatcher.callTool(name, args);
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@klarefi/mcp",
+  "version": "0.2.0",
+  "description": "MCP server for Klarefi connector installation, intake sessions, and case retrieval.",
+  "type": "module",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jmqcooper1/Klarefi.git",
+    "directory": "packages/klarefi-mcp"
+  },
+  "bin": {
+    "klarefi-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "bun run build",
+    "test": "node --test test/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@klarefi/node": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}