@actalumen/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# @actalumen/mcp-server
+
+MCP server for [ActaLumen](https://actalumen.com) — verify documents for compliance from Claude Desktop, Cursor, and Claude Code.
+
+## What it does
+
+Exposes ActaLumen's verification, chat, and document tooling to any MCP-compatible AI agent. Your agent can upload a contract, run it against a compliance template (SOC2, GDPR, custom), and chat with the document — all grounded in citations.
+
+**PII is redacted server-side before storage.** Agents never see un-redacted content, even when explicitly asked.
+
+## Install
+
+### Prerequisites
+
+1. An ActaLumen API key with `read`, `write`, and `verify` scopes. Create one at **app.actalumen.com → Settings → API Keys**.
+2. Node.js 18.17 or newer.
+3. A directory the agent is allowed to upload from. Default: `~/actalumen-inbox` (create it: `mkdir ~/actalumen-inbox`).
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "actalumen": {
+      "command": "npx",
+      "args": ["-y", "@actalumen/mcp-server"],
+      "env": {
+        "ACTALUMEN_API_KEY": "ak_live_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see the ActaLumen tools in the tools menu.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "actalumen": {
+      "command": "npx",
+      "args": ["-y", "@actalumen/mcp-server"],
+      "env": { "ACTALUMEN_API_KEY": "ak_live_..." }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add actalumen -- npx -y @actalumen/mcp-server
+# then set the key in your shell or settings:
+export ACTALUMEN_API_KEY=ak_live_...
+```
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `ACTALUMEN_API_KEY` | (required) | Org-scoped API key. |
+| `ACTALUMEN_BASE_URL` | `https://api.actalumen.com` | Override for self-hosted or staging. |
+| `ACTALUMEN_UPLOAD_DIR` | `~/actalumen-inbox` | Path allowlist — agents can only upload files from inside this directory. |
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `upload_document` | Upload a PDF (must be inside `ACTALUMEN_UPLOAD_DIR`). Returns a document ID; PII is redacted on the server before storage. |
+| `get_document` | Poll a document's status — wait for `READY` before verifying or chatting. |
+| `list_documents` | Find existing documents by name without re-uploading. |
+| `list_templates` | Discover available compliance templates (e.g., SOC2 Vendor). |
+| `start_verification` | Run a document against a template. Returns a `jobId`. |
+| `get_verification` | Fetch report status and findings. |
+| `chat_with_document` | Ask grounded questions about one or more documents. |
+| `get_usage` | Check plan quota before batch operations. |
+
+## Example agent flow
+
+> "Check whether `~/actalumen-inbox/acme-msa.pdf` meets our SOC2 vendor requirements and summarize the gaps."
+
+The agent will:
+
+1. `list_templates` → find the SOC2 template.
+2. `upload_document` → get a document ID, wait for `READY` via `get_document`.
+3. `start_verification` → get a `jobId`.
+4. `get_verification` (polling) → receive the full report.
+5. Summarize the failed criteria back to you with page citations.
+
+## Verify your install
+
+```bash
+ACTALUMEN_API_KEY=ak_live_... npx -y @actalumen/mcp-server --health
+# → ok — https://api.actalumen.com — org Acme Inc — upload dir /Users/.../actalumen-inbox
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+import type { Config } from "./config.js";
+export declare class ApiError extends Error {
+    status: number;
+    body: unknown;
+    constructor(status: number, body: unknown, message: string);
+}
+export declare class ActalumenClient {
+    private readonly cfg;
+    constructor(cfg: Config);
+    private headers;
+    private parse;
+    private request;
+    get<T>(path: string, query?: Record<string, string | number | undefined>): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+    postMultipart<T>(path: string, form: FormData): Promise<T>;
+}

package/dist/client.js

@@ -0,0 +1,66 @@
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "ApiError";
+    }
+}
+export class ActalumenClient {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    headers(extra = {}) {
+        return {
+            "X-API-Key": this.cfg.apiKey,
+            "User-Agent": "actalumen-mcp/0.1.0",
+            ...extra,
+        };
+    }
+    async parse(res) {
+        const text = await res.text();
+        if (!text)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    async request(method, path, init = {}) {
+        const url = new URL(this.cfg.baseUrl + path);
+        if (init.query) {
+            for (const [k, v] of Object.entries(init.query)) {
+                if (v !== undefined)
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const res = await fetch(url, {
+            method,
+            headers: this.headers(init.headers),
+            body: init.body,
+        });
+        const body = await this.parse(res);
+        if (!res.ok) {
+            const detail = typeof body === "object" && body && "error" in body ? String(body.error) : res.statusText;
+            throw new ApiError(res.status, body, `${method} ${path} → ${res.status}: ${detail}`);
+        }
+        return body;
+    }
+    get(path, query) {
+        return this.request("GET", path, { query });
+    }
+    post(path, body) {
+        return this.request("POST", path, {
+            body: JSON.stringify(body),
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+    postMultipart(path, form) {
+        return this.request("POST", path, { body: form });
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+export interface Config {
+    apiKey: string;
+    baseUrl: string;
+    uploadDir: string;
+}
+export declare function loadConfig(): Config;

package/dist/config.js

@@ -0,0 +1,11 @@
+import path from "node:path";
+import os from "node:os";
+export function loadConfig() {
+    const apiKey = process.env.ACTALUMEN_API_KEY;
+    if (!apiKey) {
+        throw new Error("ACTALUMEN_API_KEY is not set. Create a key at https://app.actalumen.com/settings/api-keys");
+    }
+    const baseUrl = (process.env.ACTALUMEN_BASE_URL ?? "https://api.actalumen.com").replace(/\/+$/, "");
+    const uploadDir = path.resolve(process.env.ACTALUMEN_UPLOAD_DIR ?? path.join(os.homedir(), "actalumen-inbox"));
+    return { apiKey, baseUrl, uploadDir };
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { loadConfig } from "./config.js";
+import { ActalumenClient, ApiError } from "./client.js";
+import { tools } from "./tools/index.js";
+async function runHealthCheck() {
+    try {
+        const cfg = loadConfig();
+        const client = new ActalumenClient(cfg);
+        const me = await client.get("/v1/me");
+        process.stdout.write(`ok — ${cfg.baseUrl} — org ${me.orgName ?? me.orgId ?? "(unknown)"} — upload dir ${cfg.uploadDir}\n`);
+        return 0;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`health check failed: ${msg}\n`);
+        return 1;
+    }
+}
+async function main() {
+    if (process.argv.includes("--health")) {
+        process.exit(await runHealthCheck());
+    }
+    const config = loadConfig();
+    const client = new ActalumenClient(config);
+    const ctx = { client, config };
+    const server = new Server({ name: "actalumen", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: zodToJsonSchema(t.inputSchema),
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const tool = tools.find((t) => t.name === req.params.name);
+        if (!tool) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }],
+            };
+        }
+        const parsed = tool.inputSchema.safeParse(req.params.arguments ?? {});
+        if (!parsed.success) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Invalid arguments: ${parsed.error.message}` }],
+            };
+        }
+        try {
+            const result = await tool.handler(parsed.data, ctx);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            const text = err instanceof ApiError
+                ? `ActaLumen API error (${err.status}): ${JSON.stringify(err.body)}`
+                : err instanceof Error
+                    ? err.message
+                    : String(err);
+            return { isError: true, content: [{ type: "text", text }] };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write(`ActaLumen MCP ready — ${config.baseUrl} — upload dir ${config.uploadDir}\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/tools/chat_with_document.d.ts

@@ -0,0 +1 @@
+export declare const chatWithDocument: import("./types.js").ToolDef;

package/dist/tools/chat_with_document.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { defineTool } from "./types.js";
+const Input = z.object({
+    documentIds: z
+        .array(z.string())
+        .min(1)
+        .describe("One or more document IDs to ground the answer in. All must be READY."),
+    message: z.string().min(1).describe("The user's question. Answers are grounded in retrieved chunks with page citations."),
+    sessionId: z
+        .string()
+        .optional()
+        .describe("Optional existing chat session ID to continue a multi-turn conversation."),
+});
+export const chatWithDocument = defineTool({
+    name: "chat_with_document",
+    description: "Ask a grounded question about one or more documents. Returns an answer with citations into the document. PII in source documents has already been redacted server-side, so answers cannot leak redacted data.",
+    inputSchema: Input,
+    handler: async (input, { client }) => client.post("/v1/chat", input),
+});

package/dist/tools/get_document.d.ts

@@ -0,0 +1 @@
+export declare const getDocument: import("./types.js").ToolDef;

package/dist/tools/get_document.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { defineTool } from "./types.js";
+const Input = z.object({
+    documentId: z.string().describe("Document ID returned by upload_document."),
+});
+export const getDocument = defineTool({
+    name: "get_document",
+    description: "Get a document's status and metadata. Use this to poll after upload — call start_verification or chat_with_document only when status is READY. Status values: PROCESSING (embeddings running), READY (queryable), FAILED.",
+    inputSchema: Input,
+    handler: async ({ documentId }, { client }) => client.get(`/v1/documents/${encodeURIComponent(documentId)}`),
+});

package/dist/tools/get_usage.d.ts

@@ -0,0 +1 @@
+export declare const getUsage: import("./types.js").ToolDef;

package/dist/tools/get_usage.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+import { defineTool } from "./types.js";
+const Input = z.object({}).describe("No arguments.");
+export const getUsage = defineTool({
+    name: "get_usage",
+    description: "Check the organization's current plan, quota, and remaining allowance for documents, verifications, chat messages, and generated media. Call before kicking off expensive batch operations.",
+    inputSchema: Input,
+    handler: async (_input, { client }) => client.get("/v1/usage"),
+});

package/dist/tools/get_verification.d.ts

@@ -0,0 +1 @@
+export declare const getVerification: import("./types.js").ToolDef;

package/dist/tools/get_verification.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { defineTool } from "./types.js";
+const Input = z.object({
+    jobId: z.string().describe("Job ID returned by start_verification."),
+});
+export const getVerification = defineTool({
+    name: "get_verification",
+    description: "Fetch verification job status and (when complete) the full report with per-criterion findings, citations, and pass/fail summary. Poll roughly every 5–10s after start_verification.",
+    inputSchema: Input,
+    handler: async ({ jobId }, { client }) => client.get(`/v1/reports/${encodeURIComponent(jobId)}`),
+});

package/dist/tools/index.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDef } from "./types.js";
+export declare const tools: ToolDef[];

package/dist/tools/index.js

@@ -0,0 +1,18 @@
+import { uploadDocument } from "./upload_document.js";
+import { getDocument } from "./get_document.js";
+import { listDocuments } from "./list_documents.js";
+import { listTemplates } from "./list_templates.js";
+import { startVerification } from "./start_verification.js";
+import { getVerification } from "./get_verification.js";
+import { chatWithDocument } from "./chat_with_document.js";
+import { getUsage } from "./get_usage.js";
+export const tools = [
+    uploadDocument,
+    getDocument,
+    listDocuments,
+    listTemplates,
+    startVerification,
+    getVerification,
+    chatWithDocument,
+    getUsage,
+];

package/dist/tools/list_documents.d.ts

@@ -0,0 +1 @@
+export declare const listDocuments: import("./types.js").ToolDef;

package/dist/tools/list_documents.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { defineTool } from "./types.js";
+const Input = z.object({
+    limit: z.number().int().min(1).max(100).optional().describe("Max documents to return (default 25)."),
+    offset: z.number().int().min(0).optional(),
+});
+export const listDocuments = defineTool({
+    name: "list_documents",
+    description: "List documents in the organization. Use this to find an existing document ID by name instead of re-uploading.",
+    inputSchema: Input,
+    handler: async (input, { client }) => client.get("/v1/documents", input),
+});

package/dist/tools/list_templates.d.ts

@@ -0,0 +1 @@
+export declare const listTemplates: import("./types.js").ToolDef;

package/dist/tools/list_templates.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+import { defineTool } from "./types.js";
+const Input = z.object({}).describe("No arguments.");
+export const listTemplates = defineTool({
+    name: "list_templates",
+    description: "List compliance criteria templates available to the organization (e.g., 'SOC2 Vendor', 'GDPR DPA'). Call this before start_verification to find the right templateId. Each template encodes a checklist of criteria a document is verified against.",
+    inputSchema: Input,
+    handler: async (_input, { client }) => client.get("/v1/templates"),
+});

package/dist/tools/start_verification.d.ts

@@ -0,0 +1 @@
+export declare const startVerification: import("./types.js").ToolDef;

package/dist/tools/start_verification.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { defineTool } from "./types.js";
+const Input = z
+    .object({
+    documentId: z.string().describe("Document to verify. Must be READY (see get_document)."),
+    templateId: z
+        .number()
+        .int()
+        .optional()
+        .describe("Template ID from list_templates. Either templateId or criteria is required."),
+    criteria: z
+        .array(z.object({ id: z.string(), text: z.string() }))
+        .optional()
+        .describe("Ad-hoc criteria list, used when no template fits. Either templateId or criteria is required."),
+})
+    .refine((v) => v.templateId !== undefined || (v.criteria && v.criteria.length > 0), {
+    message: "Provide either templateId or a non-empty criteria array.",
+});
+export const startVerification = defineTool({
+    name: "start_verification",
+    description: "Run compliance verification on a document against a template (or ad-hoc criteria). Returns a jobId; the job runs async — poll get_verification until status is 'completed'. Requires the API key to have the 'verify' scope.",
+    inputSchema: Input,
+    handler: async (input, { client }) => client.post("/v1/reports", input),
+});

package/dist/tools/types.d.ts

@@ -0,0 +1,19 @@
+import type { z } from "zod";
+import type { ActalumenClient } from "../client.js";
+import type { Config } from "../config.js";
+export interface ToolContext {
+    client: ActalumenClient;
+    config: Config;
+}
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: z.ZodType<unknown>;
+    handler: (input: unknown, ctx: ToolContext) => Promise<unknown>;
+}
+export declare function defineTool<Input extends z.ZodTypeAny>(t: {
+    name: string;
+    description: string;
+    inputSchema: Input;
+    handler: (input: z.infer<Input>, ctx: ToolContext) => Promise<unknown>;
+}): ToolDef;

package/dist/tools/types.js

@@ -0,0 +1,3 @@
+export function defineTool(t) {
+    return t;
+}

package/dist/tools/upload_document.d.ts

@@ -0,0 +1 @@
+export declare const uploadDocument: import("./types.js").ToolDef;

package/dist/tools/upload_document.js

@@ -0,0 +1,45 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { defineTool } from "./types.js";
+const Input = z.object({
+    path: z
+        .string()
+        .describe("Absolute or ~/-relative path to a PDF. Must be inside ACTALUMEN_UPLOAD_DIR (default ~/actalumen-inbox) — the user controls which files agents can upload."),
+    id: z
+        .string()
+        .regex(/^[a-zA-Z0-9_-]{1,128}$/)
+        .optional()
+        .describe("Optional custom document ID (letters, digits, -, _, max 128). Useful for idempotent re-runs."),
+});
+function expandHome(p) {
+    if (p.startsWith("~/"))
+        return path.join(process.env.HOME ?? "", p.slice(2));
+    return p;
+}
+export const uploadDocument = defineTool({
+    name: "upload_document",
+    description: "Upload a PDF to ActaLumen for compliance verification. The server applies organization-configured PII redaction before storage — the agent will only ever see redacted content in subsequent calls. Returns a document ID; the document is PROCESSING until embeddings finish (poll get_document for status=READY).",
+    inputSchema: Input,
+    handler: async (input, { client, config }) => {
+        const resolved = path.resolve(expandHome(input.path));
+        const allowed = config.uploadDir;
+        const rel = path.relative(allowed, resolved);
+        if (rel.startsWith("..") || path.isAbsolute(rel)) {
+            throw new Error(`Upload denied: ${resolved} is outside the allowed upload directory (${allowed}). ` +
+                `Move the file there, or set ACTALUMEN_UPLOAD_DIR to a directory containing it.`);
+        }
+        const stat = await fs.stat(resolved);
+        if (!stat.isFile())
+            throw new Error(`Not a file: ${resolved}`);
+        if (!resolved.toLowerCase().endsWith(".pdf")) {
+            throw new Error("Only PDF files are supported.");
+        }
+        const bytes = await fs.readFile(resolved);
+        const form = new FormData();
+        form.append("file", new Blob([bytes], { type: "application/pdf" }), path.basename(resolved));
+        if (input.id)
+            form.append("id", input.id);
+        return client.postMultipart("/v1/documents", form);
+    },
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@actalumen/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for ActaLumen — verify documents for compliance from Claude Desktop, Cursor, and Claude Code.",
+  "type": "module",
+  "bin": {
+    "actalumen-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "health": "node dist/index.js --health",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}