@klarefi/mcp 0.2.0

package/README.md

@@ -0,0 +1,56 @@
+# @klarefi/mcp
+
+MCP stdio server for agent access to Klarefi. It wraps the
+[`@klarefi/node`](../klarefi-node) SDK for customer-plane API calls and the
+applicant-plane intake driver.
+
+Applicant-plane tools work from a signed intake URL or from
+`session_id`/`access_token`; they do not require `KLAREFI_API_KEY`.
+Customer-plane tools require `KLAREFI_API_KEY`.
+
+## Client config
+
+```json
+{
+  "mcpServers": {
+    "klarefi": {
+      "command": "npx",
+      "args": ["-y", "@klarefi/mcp"],
+      "env": {
+        "KLAREFI_API_KEY": "sk_test_...",
+        "KLAREFI_API_BASE_URL": "https://api.klarefi.com"
+      }
+    }
+  }
+}
+```
+
+Omit `KLAREFI_API_KEY` when you only need applicant-plane intake tools.
+`KLAREFI_API_BASE_URL` is optional and defaults to `https://api.klarefi.com`.
+
+## Applicant-plane tools
+
+- `open_intake` - open an intake from `url` or from `session_id` plus
+  `access_token`; returns the current intake state.
+- `get_intake_state` - return the selected or most recently opened intake
+  state.
+- `answer_question` - answer an active applicant question with free text.
+- `answer_fields` - answer structured requested facts by `fact_id`; `yes_no`
+  values are `"yes"` or `"no"`, and dates use `YYYY-MM-DD`.
+- `upload_document` - upload by `file_path` or inline `content_base64`.
+  Inline uploads are limited to 5MB decoded; use `file_path` for documents up
+  to 25MB.
+- `submit_intake` - submit the intake and return `{ submitted, blockers,
+  state }`.
+- `save_intake_draft` - save draft form fields without submitting.
+- `wait_for_next_action` - poll for the next applicant action. If `timed_out`
+  is true, call it again.
+
+## Customer-plane tools
+
+- `create_connector_from_openapi` - import a public OpenAPI JSON URL as a
+  verification connector.
+- `create_connector`
+- `delete_connector`
+- `create_intake_session`
+- `get_case`

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { IntakeSessionRegistry } from "./sessions.js";
+import { createToolDispatcher, requiredString, } from "./tools.js";
+function readPackageVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    if (typeof packageJson.version !== "string" || !packageJson.version) {
+        throw new Error("Package version is missing.");
+    }
+    return packageJson.version;
+}
+const SERVER_VERSION = readPackageVersion();
+const intakeRegistry = new IntakeSessionRegistry();
+const dispatcher = createToolDispatcher({ intakeRegistry });
+function asJsonObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function writeMessage(message) {
+    process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+function result(id, value) {
+    writeMessage({ jsonrpc: "2.0", id, result: value });
+}
+function errorResult(id, error) {
+    writeMessage({
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: -32000,
+            message: error instanceof Error ? error.message : String(error),
+        },
+    });
+}
+async function handleRequest(request) {
+    if (request.id === undefined || request.id === null) {
+        return;
+    }
+    try {
+        if (request.method === "initialize") {
+            result(request.id, {
+                protocolVersion: "2024-11-05",
+                capabilities: { tools: {} },
+                serverInfo: { name: "klarefi-mcp", version: SERVER_VERSION },
+            });
+            return;
+        }
+        if (request.method === "tools/list") {
+            result(request.id, { tools: [...dispatcher.tools] });
+            return;
+        }
+        if (request.method === "tools/call") {
+            const params = request.params ?? {};
+            const name = requiredString(params, "name");
+            const args = asJsonObject(params.arguments);
+            result(request.id, await dispatcher.callTool(name, args));
+            return;
+        }
+        throw new Error(`Unsupported MCP method: ${request.method ?? "(missing)"}`);
+    }
+    catch (error) {
+        errorResult(request.id, error);
+    }
+}
+let buffer = Buffer.alloc(0);
+let draining = false;
+let drainAgain = false;
+process.stdin.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    void drainMessages();
+});
+function headerBoundary(source) {
+    const crlf = source.indexOf("\r\n\r\n");
+    const lf = source.indexOf("\n\n");
+    if (crlf === -1 && lf === -1) {
+        return null;
+    }
+    if (crlf !== -1 && (lf === -1 || crlf < lf)) {
+        return { index: crlf, length: 4 };
+    }
+    return { index: lf, length: 2 };
+}
+function looksLikeContentLengthFrame(source) {
+    const prefix = source
+        .slice(0, Math.min(source.length, "Content-Length:".length))
+        .toString("utf8")
+        .toLowerCase();
+    return "content-length:".startsWith(prefix) || prefix === "content-length:";
+}
+function readContentLengthFrame() {
+    if (!looksLikeContentLengthFrame(buffer)) {
+        return undefined;
+    }
+    const boundary = headerBoundary(buffer);
+    if (!boundary) {
+        return null;
+    }
+    const header = buffer.slice(0, boundary.index).toString("utf8");
+    const match = /content-length:\s*(\d+)/i.exec(header);
+    if (!match) {
+        throw new Error("Malformed Content-Length frame.");
+    }
+    const length = Number(match[1]);
+    const messageStart = boundary.index + boundary.length;
+    const messageEnd = messageStart + length;
+    if (buffer.length < messageEnd) {
+        return null;
+    }
+    const raw = buffer.slice(messageStart, messageEnd).toString("utf8");
+    buffer = buffer.slice(messageEnd);
+    return raw;
+}
+function readNewlineFrame() {
+    const newline = buffer.indexOf("\n");
+    if (newline === -1) {
+        return null;
+    }
+    const raw = buffer.slice(0, newline).toString("utf8").trim();
+    buffer = buffer.slice(newline + 1);
+    return raw;
+}
+async function drainMessages() {
+    if (draining) {
+        drainAgain = true;
+        return;
+    }
+    draining = true;
+    try {
+        while (true) {
+            drainAgain = false;
+            const contentLengthFrame = readContentLengthFrame();
+            if (contentLengthFrame === null) {
+                return;
+            }
+            if (contentLengthFrame !== undefined) {
+                await handleRequest(JSON.parse(contentLengthFrame));
+                continue;
+            }
+            const newlineFrame = readNewlineFrame();
+            if (newlineFrame === null) {
+                return;
+            }
+            if (!newlineFrame) {
+                continue;
+            }
+            await handleRequest(JSON.parse(newlineFrame));
+        }
+    }
+    finally {
+        draining = false;
+        if (drainAgain) {
+            void drainMessages();
+        }
+    }
+}

package/dist/sessions.d.ts

@@ -0,0 +1,50 @@
+import type { AgentIntakeState, IntakeSubmitResult, UploadDocumentParams } from "@klarefi/node/intake";
+export interface IntakeSessionLike {
+    getState(): Promise<AgentIntakeState>;
+    answer(text: string, opts?: {
+        taskId?: string;
+    }): Promise<AgentIntakeState>;
+    answerFields(fields: Record<string, string>, opts?: {
+        taskId?: string;
+    }): Promise<AgentIntakeState>;
+    saveDraft(fields: Record<string, string | null>): Promise<AgentIntakeState>;
+    submit(opts?: {
+        fieldValues?: Record<string, string | null>;
+    }): Promise<IntakeSubmitResult>;
+    uploadDocument(params: UploadDocumentParams): Promise<AgentIntakeState>;
+    nextAction(opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<{
+        state: AgentIntakeState;
+        timed_out: boolean;
+    }>;
+}
+export interface OpenIntakeOptions {
+    url?: string;
+    session_id?: string;
+    access_token?: string;
+    api_base_url?: string;
+}
+export type IntakeSessionFactoryInput = {
+    kind: "signed_url";
+    url: string;
+    baseUrl: string;
+    clientName: string;
+} | {
+    kind: "credentials";
+    sessionId: string;
+    accessToken: string;
+    baseUrl: string;
+    clientName: string;
+};
+export type IntakeSessionFactory = (input: IntakeSessionFactoryInput) => IntakeSessionLike;
+export interface IntakeSessionRegistryOptions {
+    createSession?: IntakeSessionFactory;
+}
+export declare class IntakeSessionRegistry {
+    #private;
+    constructor(options?: IntakeSessionRegistryOptions);
+    open(opts: OpenIntakeOptions): IntakeSessionLike;
+    get(sessionId?: string): IntakeSessionLike;
+}

package/dist/sessions.js

@@ -0,0 +1,92 @@
+import { IntakeSession } from "@klarefi/node/intake";
+const DEFAULT_API_BASE_URL = "https://api.klarefi.com";
+function envApiBaseUrl() {
+    const value = process.env.KLAREFI_API_BASE_URL?.trim();
+    return value || undefined;
+}
+function resolveApiBaseUrl(value) {
+    if (typeof value === "string" && value.trim()) {
+        return value.trim();
+    }
+    return envApiBaseUrl() ?? DEFAULT_API_BASE_URL;
+}
+function parseSessionIdFromSignedUrl(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new Error("Signed intake URL is malformed.");
+    }
+    const segments = url.pathname.split("/").filter(Boolean);
+    if (segments.length !== 2 || segments[0] !== "s" || !segments[1]) {
+        throw new Error("Signed intake URL must have the path /s/{session_id}.");
+    }
+    return decodeURIComponent(segments[1]);
+}
+function createDefaultSession(input) {
+    if (input.kind === "signed_url") {
+        return IntakeSession.fromSignedUrl(input.url, {
+            baseUrl: input.baseUrl,
+            clientName: input.clientName,
+        });
+    }
+    return new IntakeSession({
+        sessionId: input.sessionId,
+        accessToken: input.accessToken,
+        baseUrl: input.baseUrl,
+        clientName: input.clientName,
+    });
+}
+export class IntakeSessionRegistry {
+    #sessions = new Map();
+    #createSession;
+    #latestSessionId = null;
+    constructor(options = {}) {
+        this.#createSession = options.createSession ?? createDefaultSession;
+    }
+    open(opts) {
+        const apiBaseUrl = resolveApiBaseUrl(opts.api_base_url);
+        const clientName = "klarefi-mcp";
+        let sessionId;
+        let session;
+        if (opts.url) {
+            sessionId = parseSessionIdFromSignedUrl(opts.url);
+            session = this.#createSession({
+                kind: "signed_url",
+                url: opts.url,
+                baseUrl: apiBaseUrl,
+                clientName,
+            });
+        }
+        else {
+            const rawSessionId = opts.session_id?.trim();
+            const rawAccessToken = opts.access_token?.trim();
+            if (!rawSessionId || !rawAccessToken) {
+                throw new Error("open_intake requires either url or both session_id and access_token.");
+            }
+            sessionId = rawSessionId;
+            session = this.#createSession({
+                kind: "credentials",
+                sessionId,
+                accessToken: rawAccessToken,
+                baseUrl: apiBaseUrl,
+                clientName,
+            });
+        }
+        this.#sessions.set(sessionId, session);
+        this.#latestSessionId = sessionId;
+        return session;
+    }
+    get(sessionId) {
+        const requestedSessionId = sessionId?.trim() || this.#latestSessionId;
+        if (!requestedSessionId) {
+            throw new Error("No open intake session. Call open_intake first.");
+        }
+        const session = this.#sessions.get(requestedSessionId);
+        if (!session) {
+            throw new Error(`No open intake session for session_id "${requestedSessionId}". Call open_intake first.`);
+        }
+        return session;
+    }
+}