aidocx-mcp-server 0.1.2 → 0.3.0

package/README.md

@@ -34,11 +34,12 @@ Add to your `claude_desktop_config.json`:
 #### Claude Code
 
 ```bash
-claude mcp add aidocx -- npx aidocx-mcp-server
+claude mcp add aidocx \
+  -e AIDOCX_API_KEY=ak_xxxxxxxx \
+  -e AIDOCX_API_SECRET=your_secret_here \
+  -- npx aidocx-mcp-server
 ```
 
-Then set environment variables `AIDOCX_API_KEY` and `AIDOCX_API_SECRET`.
-
 ### 3. Start Using
 
 Ask your AI assistant:
@@ -46,21 +47,27 @@ Ask your AI assistant:
 - "계약서 양식 만들어서 AiDocX에 올려줘" (Create a contract and upload to AiDocX)
 - "NDA 계약서 작성해줘" (Draft an NDA)
 - "내 문서 목록 보여줘" (Show my documents)
+- "이 계약서 AI로 분석해줘" (Analyze this contract with AI)
+- "계약서 검색해줘" (Search my contracts)
 
 ## Available Tools
 
 | Tool | Description |
 |------|-------------|
-| `create_contract_from_html` | Create a contract from HTML content → auto-converted to PDF |
+| `create_contract` | Create a new contract — auto-generates a professionally formatted PDF |
 | `upload_contract` | Upload a PDF or Office file (DOC, DOCX, HWP, XLS, XLSX, PPT, PPTX) |
-| `list_contracts` | List contracts in document management |
-| `get_contract` | Get contract details |
+| `list_contracts` | List contracts with optional pagination |
+| `get_contract` | Get contract details and extracted text |
+| `delete_contract` | Delete a contract |
 | `list_folders` | List folders |
 | `create_folder` | Create a new folder |
+| `delete_folder` | Delete a folder (optionally with all contents) |
+| `search_contracts` | Search contracts with text query, date filters, and pagination |
+| `analyze_contract` | AI-powered contract analysis with risk score and insights |
 
 ## Workflow
 
-1. **AI generates a contract** → calls `create_contract_from_html` → PDF is created in AiDocX
+1. **AI generates a contract** → calls `create_contract` → PDF is created in AiDocX
 2. **Open the signing workspace URL** returned by the tool
 3. **Place signature fields** and send to signers in the AiDocX web app
 

package/build/api-client.d.ts

@@ -5,7 +5,8 @@ export declare class AiDocxClient {
     private get headers();
     get appUrl(): string;
     private url;
+    private formatError;
     get<T = any>(path: string, params?: Record<string, string>): Promise<T>;
     post<T = any>(path: string, body: Record<string, any>): Promise<T>;
-    delete<T = any>(path: string): Promise<T>;
+    delete<T = any>(path: string, params?: Record<string, string>): Promise<T>;
 }

package/build/api-client.js

@@ -16,6 +16,24 @@ export class AiDocxClient {
     url(path) {
         return `${this.config.apiUrl}/api${path}`;
     }
+    formatError(status, body) {
+        switch (status) {
+            case 401:
+                return new Error(`[${status}] Authentication failed. Your API key or secret is invalid or expired. Regenerate at https://app.aidocx.ai/settings → API Keys.`);
+            case 402:
+                return new Error(`[${status}] Insufficient tokens or subscription required. Upgrade your plan at https://app.aidocx.ai/settings → Billing.`);
+            case 403:
+                return new Error(`[${status}] Permission denied. You do not have access to this resource.`);
+            case 404:
+                return new Error(`[${status}] Resource not found. The requested contract, folder, or resource does not exist.`);
+            case 413:
+                return new Error(`[${status}] File too large. Maximum upload size is 50MB.`);
+            case 429:
+                return new Error(`[${status}] Rate limited. Too many requests — please wait a moment and try again.`);
+            default:
+                return new Error(`[${status}] ${body || "Unknown error"}`);
+        }
+    }
     async get(path, params) {
         const url = new URL(this.url(path));
         if (params) {
@@ -27,7 +45,7 @@ export class AiDocxClient {
         const res = await fetch(url.toString(), { headers: this.headers });
         if (!res.ok) {
             const body = await res.text();
-            throw new Error(`API ${res.status}: ${body}`);
+            throw this.formatError(res.status, body);
         }
         return res.json();
     }
@@ -39,18 +57,25 @@ export class AiDocxClient {
         });
         if (!res.ok) {
             const text = await res.text();
-            throw new Error(`API ${res.status}: ${text}`);
+            throw this.formatError(res.status, text);
         }
         return res.json();
     }
-    async delete(path) {
-        const res = await fetch(this.url(path), {
+    async delete(path, params) {
+        const url = new URL(this.url(path));
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                if (v !== undefined && v !== "")
+                    url.searchParams.set(k, v);
+            }
+        }
+        const res = await fetch(url.toString(), {
             method: "DELETE",
             headers: this.headers,
         });
         if (!res.ok) {
             const text = await res.text();
-            throw new Error(`API ${res.status}: ${text}`);
+            throw this.formatError(res.status, text);
         }
         return res.json();
     }

package/build/index.js

@@ -1,27 +1,38 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { loadConfig } from "./config.js";
 import { AiDocxClient } from "./api-client.js";
-import { register as registerCreateContractHtml } from "./tools/create-contract-html.js";
+import { register as registerCreateContract } from "./tools/create-contract.js";
 import { register as registerUploadContract } from "./tools/upload-contract.js";
 import { register as registerListContracts } from "./tools/list-contracts.js";
 import { register as registerGetContract } from "./tools/get-contract.js";
 import { register as registerListFolders } from "./tools/list-folders.js";
 import { register as registerCreateFolder } from "./tools/create-folder.js";
+import { register as registerDeleteContract } from "./tools/delete-contract.js";
+import { register as registerDeleteFolder } from "./tools/delete-folder.js";
+import { register as registerSearchContracts } from "./tools/search-contracts.js";
+import { register as registerAnalyzeContract } from "./tools/analyze-contract.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
 async function main() {
     const config = loadConfig();
     const client = new AiDocxClient(config);
     const server = new McpServer({
         name: "aidocx",
-        version: "0.1.0",
+        version,
     });
-    registerCreateContractHtml(server, client);
+    registerCreateContract(server, client);
     registerUploadContract(server, client);
     registerListContracts(server, client);
     registerGetContract(server, client);
     registerListFolders(server, client);
     registerCreateFolder(server, client);
+    registerDeleteContract(server, client);
+    registerDeleteFolder(server, client);
+    registerSearchContracts(server, client);
+    registerAnalyzeContract(server, client);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[AiDocX MCP] Server running on stdio");

package/build/tools/analyze-contract.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+const inputSchema = {
+    id: z.string().describe("Contract ID to analyze"),
+};
+export function register(server, client) {
+    server.registerTool("analyze_contract", {
+        description: "Analyze a contract using AI. Returns a summary, risk score (0-100), and detailed insights " +
+            "including key clauses, missing protections, and opportunities for improvement.\n\n" +
+            "NOTE: This operation consumes AI tokens from the user's subscription plan. " +
+            "The analysis may take 10-30 seconds depending on contract length.",
+        inputSchema,
+    }, async ({ id }) => {
+        try {
+            const result = await client.post("/ai/analyze", { id });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            contractId: id,
+                            summary: result.summary,
+                            riskScore: result.riskScore,
+                            insights: result.insights,
+                            tokensUsed: result.tokensUsed,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error: ${error.message}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/create-contract.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AiDocxClient } from "../api-client.js";
+export declare function register(server: McpServer, client: AiDocxClient): void;

package/build/tools/{create-contract-html.js → create-contract.js}

@@ -1,10 +1,9 @@
 import { z } from "zod";
 export function register(server, client) {
     // @ts-expect-error -- MCP SDK generic recursion with zod v3.25+ optional()
-    server.registerTool("create_contract_from_html", {
-        description: "Create a new contract in AiDocX from HTML content. The HTML is rendered to a PDF " +
-            "using Noto Sans KR font and Tailwind CSS, then stored in document management. " +
-            "A4 page size with 2cm margins.\n\n" +
+    server.registerTool("create_contract", {
+        description: "Create a new contract in AiDocX. The content is rendered to a professionally formatted PDF " +
+            "(A4, proper margins) and stored in document management.\n\n" +
             "IMPORTANT: Before calling this tool, you MUST confirm the following with the user:\n" +
             "1. Contract type (e.g., service agreement, employment contract, NDA)\n" +
             "2. Parties involved (company names, representative names, roles)\n" +
@@ -15,9 +14,9 @@ export function register(server, client) {
             "and signature blocks for each signer at the bottom. " +
             "Do NOT include <html>/<head>/<body> wrapper — only the inner content.",
         inputSchema: {
-            name: z.string(),
-            html: z.string(),
-            folderId: z.string().optional(),
+            name: z.string().describe("Contract title"),
+            html: z.string().describe("Contract body content"),
+            folderId: z.string().optional().describe("Target folder ID"),
         },
     }, async ({ name, html, folderId }) => {
         try {

package/build/tools/delete-contract.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AiDocxClient } from "../api-client.js";
+export declare function register(server: McpServer, client: AiDocxClient): void;

package/build/tools/delete-contract.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+const inputSchema = {
+    id: z.string().describe("Contract ID to delete"),
+};
+export function register(server, client) {
+    server.registerTool("delete_contract", {
+        description: "Delete a contract from AiDocX document management. This action is irreversible.\n\n" +
+            "IMPORTANT: Always confirm with the user before deleting a contract.",
+        inputSchema,
+    }, async ({ id }) => {
+        try {
+            await client.delete(`/contracts/${id}`);
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            message: `Contract ${id} has been deleted.`,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error: ${error.message}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/delete-folder.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AiDocxClient } from "../api-client.js";
+export declare function register(server: McpServer, client: AiDocxClient): void;

package/build/tools/delete-folder.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+const inputSchema = {
+    id: z.string().describe("Folder ID to delete"),
+    recursive: z.boolean().optional().describe("If true, delete the folder and all its contents (subfolders and contracts). " +
+        "If false or omitted, the folder must be empty to delete."),
+};
+export function register(server, client) {
+    server.registerTool("delete_folder", {
+        description: "Delete a folder from AiDocX document management.\n\n" +
+            "IMPORTANT: Always confirm with the user before deleting. " +
+            "Use recursive=true only when the user explicitly wants to delete all contents.",
+        inputSchema,
+    }, 
+    // @ts-expect-error -- MCP SDK generic recursion with zod v3.25+ optional()
+    async ({ id, recursive }) => {
+        try {
+            const params = {};
+            if (recursive)
+                params.recursive = "true";
+            await client.delete(`/contracts/folders/${id}`, params);
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            message: `Folder ${id} has been deleted${recursive ? " with all contents" : ""}.`,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error: ${error.message}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/list-contracts.js

@@ -1,31 +1,40 @@
 import { z } from "zod";
 const inputSchema = {
     folderId: z.string().optional().describe("Folder ID to list. Omit for root folder."),
+    limit: z.number().optional().describe("Maximum number of contracts to return. Default: 50"),
+    offset: z.number().optional().describe("Number of contracts to skip. Default: 0"),
 };
 export function register(server, client) {
     server.registerTool("list_contracts", {
-        description: "List contracts in the user's AiDocX document management.",
+        description: "List contracts in the user's AiDocX document management. Supports pagination.",
         inputSchema,
-    }, async ({ folderId }) => {
+    }, async ({ folderId, limit, offset }) => {
         try {
             const params = {};
             if (folderId)
                 params.folderId = folderId;
             const result = await client.get("/contracts", params);
             const contracts = result.contracts || result;
-            const summary = Array.isArray(contracts)
+            const all = Array.isArray(contracts)
                 ? contracts.map((c) => ({
                     id: c.id, name: c.name, fileType: c.fileType,
                     fileSize: c.fileSize, contentType: c.contentType,
                     createdAt: c.createdAt, updatedAt: c.updatedAt,
                 }))
                 : contracts;
+            const effectiveLimit = limit ?? 50;
+            const effectiveOffset = offset ?? 0;
+            const paginated = Array.isArray(all)
+                ? all.slice(effectiveOffset, effectiveOffset + effectiveLimit)
+                : all;
             return {
                 content: [{
                         type: "text",
                         text: JSON.stringify({
-                            count: Array.isArray(summary) ? summary.length : 0,
-                            contracts: summary,
+                            total: Array.isArray(all) ? all.length : 0,
+                            count: Array.isArray(paginated) ? paginated.length : 0,
+                            contracts: paginated,
+                            pagination: { limit: effectiveLimit, offset: effectiveOffset },
                         }, null, 2),
                     }],
             };

package/build/tools/search-contracts.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AiDocxClient } from "../api-client.js";
+export declare function register(server: McpServer, client: AiDocxClient): void;

package/build/tools/search-contracts.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+const inputSchema = {
+    query: z.string().optional().describe("Search query text. Searches contract names and content."),
+    sortBy: z.enum(["relevance", "date", "name"]).optional().describe("Sort results by relevance, date, or name. Default: relevance"),
+    sortOrder: z.enum(["asc", "desc"]).optional().describe("Sort order. Default: desc"),
+    dateFrom: z.string().optional().describe("Filter results from this date (ISO 8601, e.g., '2024-01-01')"),
+    dateTo: z.string().optional().describe("Filter results up to this date (ISO 8601)"),
+    limit: z.number().optional().describe("Maximum results to return (1-100). Default: 20"),
+    offset: z.number().optional().describe("Number of results to skip for pagination. Default: 0"),
+};
+export function register(server, client) {
+    server.registerTool("search_contracts", {
+        description: "Search contracts in AiDocX. Supports text search, date filtering, and pagination. " +
+            "Returns matching contracts sorted by relevance by default.",
+        inputSchema,
+    }, 
+    // @ts-expect-error -- MCP SDK generic recursion with zod v3.25+ optional()
+    async ({ query, sortBy, sortOrder, dateFrom, dateTo, limit, offset }) => {
+        try {
+            const params = { types: "contract" };
+            if (query)
+                params.q = query;
+            if (sortBy)
+                params.sortBy = sortBy;
+            if (sortOrder)
+                params.sortOrder = sortOrder;
+            if (dateFrom)
+                params.dateFrom = dateFrom;
+            if (dateTo)
+                params.dateTo = dateTo;
+            if (limit !== undefined)
+                params.limit = String(limit);
+            if (offset !== undefined)
+                params.offset = String(offset);
+            const result = await client.get("/search", params);
+            const items = result.results || result;
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            total: result.total ?? (Array.isArray(items) ? items.length : 0),
+                            results: Array.isArray(items)
+                                ? items.map((item) => ({
+                                    id: item.id,
+                                    name: item.name,
+                                    type: item.type,
+                                    fileType: item.fileType,
+                                    fileSize: item.fileSize,
+                                    createdAt: item.createdAt,
+                                    updatedAt: item.updatedAt,
+                                }))
+                                : items,
+                            pagination: {
+                                limit: limit ?? 20,
+                                offset: offset ?? 0,
+                            },
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error: ${error.message}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aidocx-mcp-server",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "MCP server for AiDocX - Create, upload, and manage contracts from Claude Desktop and other AI assistants",
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,7 @@
     "aidocx-mcp": "./build/index.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "NODE_OPTIONS=--max-old-space-size=8192 tsc",
     "start": "node build/index.js",
     "dev": "tsx src/index.ts"
   },