@mintline/mcp 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# Mintline MCP Server
+
+Connect AI assistants to your Mintline receipts and transactions via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Installation
+
+```bash
+npm install -g @mintline/mcp
+```
+
+## Setup
+
+### 1. Get your API key
+
+Create an API key at [mintline.ai/app/settings/api-keys](https://mintline.ai/app/settings/api-keys)
+
+### 2. Configure Claude Desktop
+
+Add to your `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mintline": {
+      "command": "mintline-mcp",
+      "env": {
+        "MINTLINE_API_KEY": "ml_live_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart Claude Desktop
+
+The Mintline tools will now be available.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_receipts` | Search and filter receipts by vendor, status |
+| `get_receipt` | Get receipt details with line items |
+| `list_transactions` | Search and filter bank transactions |
+| `get_transaction` | Get transaction details |
+| `list_statements` | List uploaded bank statements |
+| `list_matches` | View proposed receipt-transaction matches |
+| `confirm_match` | Confirm a proposed match |
+| `reject_match` | Reject a proposed match |
+
+## Example Prompts
+
+- "Show me my unmatched receipts"
+- "Find receipts from Amazon"
+- "What transactions need matching?"
+- "Confirm the top match"
+- "Show details for receipt rcpt_01abc123"
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MINTLINE_API_KEY` | Yes | Your Mintline API key |
+| `MINTLINE_API_URL` | No | API URL (default: https://api.mintline.ai) |
+
+## Development
+
+```bash
+git clone https://github.com/mintlineai/mintline-mcp.git
+cd mintline-mcp
+npm install
+
+# Run locally
+MINTLINE_API_KEY=ml_live_... node src/index.js
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./index.js";

package/dist/index.js

@@ -0,0 +1,382 @@
+// src/index.js
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/client.js
+var BASE_URL = process.env.MINTLINE_API_URL || "https://api.mintline.ai";
+function createClient(apiKey2) {
+  if (!apiKey2) {
+    throw new Error("MINTLINE_API_KEY is required");
+  }
+  async function request(method, path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+      method,
+      headers: {
+        "Authorization": `Bearer ${apiKey2}`,
+        "Content-Type": "application/json"
+      },
+      body: body ? JSON.stringify(body) : void 0
+    });
+    const data = await res.json();
+    if (!data.success) {
+      throw new Error(data.error?.message || "Request failed");
+    }
+    return data;
+  }
+  return {
+    // Receipts
+    async listReceipts(params = {}) {
+      const query = new URLSearchParams();
+      if (params.limit) query.set("limit", params.limit);
+      if (params.offset) query.set("offset", params.offset);
+      if (params.search) query.set("q", params.search);
+      if (params.status) query.set("status", params.status);
+      const qs = query.toString();
+      return request("GET", `/api/receipts${qs ? `?${qs}` : ""}`);
+    },
+    async getReceipt(id) {
+      return request("GET", `/api/receipts/${id}`);
+    },
+    // Transactions
+    async listTransactions(params = {}) {
+      const query = new URLSearchParams();
+      if (params.limit) query.set("limit", params.limit);
+      if (params.offset) query.set("offset", params.offset);
+      if (params.search) query.set("q", params.search);
+      if (params.status) query.set("status", params.status);
+      if (params.statementId) query.set("statementId", params.statementId);
+      const qs = query.toString();
+      return request("GET", `/api/transactions${qs ? `?${qs}` : ""}`);
+    },
+    async getTransaction(id) {
+      return request("GET", `/api/transactions/${id}`);
+    },
+    // Statements
+    async listStatements(params = {}) {
+      const query = new URLSearchParams();
+      if (params.limit) query.set("limit", params.limit);
+      if (params.offset) query.set("offset", params.offset);
+      const qs = query.toString();
+      return request("GET", `/api/statements${qs ? `?${qs}` : ""}`);
+    },
+    // Matches
+    async listMatches(params = {}) {
+      const query = new URLSearchParams();
+      if (params.limit) query.set("limit", params.limit);
+      if (params.offset) query.set("offset", params.offset);
+      if (params.status) query.set("status", params.status);
+      const qs = query.toString();
+      return request("GET", `/api/matches${qs ? `?${qs}` : ""}`);
+    },
+    async confirmMatch(id) {
+      return request("POST", `/api/matches/${id}/confirm`);
+    },
+    async rejectMatch(id, reason) {
+      return request("POST", `/api/matches/${id}/reject`, { reason });
+    }
+  };
+}
+
+// src/tools.js
+var tools = [
+  {
+    name: "list_receipts",
+    description: "List receipts with optional filtering. Use this to find receipts by vendor name, date range, or match status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        search: {
+          type: "string",
+          description: "Search by vendor name"
+        },
+        status: {
+          type: "string",
+          enum: ["all", "matched", "unmatched", "hidden"],
+          description: "Filter by match status"
+        },
+        limit: {
+          type: "number",
+          description: "Max results to return (default 20)"
+        }
+      }
+    }
+  },
+  {
+    name: "get_receipt",
+    description: "Get detailed information about a specific receipt including line items and matched transaction.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Receipt ID (e.g., rcpt_01abc123)"
+        }
+      },
+      required: ["id"]
+    }
+  },
+  {
+    name: "list_transactions",
+    description: "List bank transactions with optional filtering. Use this to find transactions by description or match status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        search: {
+          type: "string",
+          description: "Search by transaction description"
+        },
+        status: {
+          type: "string",
+          enum: ["all", "matched", "unmatched", "hidden"],
+          description: "Filter by match status"
+        },
+        statementId: {
+          type: "string",
+          description: "Filter by bank statement ID"
+        },
+        limit: {
+          type: "number",
+          description: "Max results to return (default 20)"
+        }
+      }
+    }
+  },
+  {
+    name: "get_transaction",
+    description: "Get detailed information about a specific bank transaction.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Transaction ID (e.g., btxn_01abc123)"
+        }
+      },
+      required: ["id"]
+    }
+  },
+  {
+    name: "list_statements",
+    description: "List uploaded bank statements.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "number",
+          description: "Max results to return (default 20)"
+        }
+      }
+    }
+  },
+  {
+    name: "list_matches",
+    description: "List proposed matches between receipts and transactions. Use this to review matches that need confirmation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: {
+          type: "string",
+          enum: ["proposed", "confirmed", "rejected"],
+          description: "Filter by match status (default: proposed)"
+        },
+        limit: {
+          type: "number",
+          description: "Max results to return (default 20)"
+        }
+      }
+    }
+  },
+  {
+    name: "confirm_match",
+    description: "Confirm a proposed match between a receipt and transaction. This links them together permanently.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Match ID to confirm"
+        }
+      },
+      required: ["id"]
+    }
+  },
+  {
+    name: "reject_match",
+    description: "Reject a proposed match. The receipt and transaction will not be suggested as a match again.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Match ID to reject"
+        },
+        reason: {
+          type: "string",
+          description: "Optional reason for rejection"
+        }
+      },
+      required: ["id"]
+    }
+  }
+];
+async function handleTool(client2, name, args) {
+  switch (name) {
+    case "list_receipts": {
+      const result = await client2.listReceipts({
+        search: args.search,
+        status: args.status,
+        limit: args.limit || 20
+      });
+      return formatReceipts(result.data);
+    }
+    case "get_receipt": {
+      const result = await client2.getReceipt(args.id);
+      return formatReceiptDetail(result.data);
+    }
+    case "list_transactions": {
+      const result = await client2.listTransactions({
+        search: args.search,
+        status: args.status,
+        statementId: args.statementId,
+        limit: args.limit || 20
+      });
+      return formatTransactions(result.data);
+    }
+    case "get_transaction": {
+      const result = await client2.getTransaction(args.id);
+      return formatTransaction(result.data);
+    }
+    case "list_statements": {
+      const result = await client2.listStatements({
+        limit: args.limit || 20
+      });
+      return formatStatements(result.data);
+    }
+    case "list_matches": {
+      const result = await client2.listMatches({
+        status: args.status || "proposed",
+        limit: args.limit || 20
+      });
+      return formatMatches(result.data);
+    }
+    case "confirm_match": {
+      await client2.confirmMatch(args.id);
+      return `Match ${args.id} confirmed successfully.`;
+    }
+    case "reject_match": {
+      await client2.rejectMatch(args.id, args.reason);
+      return `Match ${args.id} rejected.${args.reason ? ` Reason: ${args.reason}` : ""}`;
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+function formatReceipts(receipts) {
+  if (!receipts?.length) return "No receipts found.";
+  return receipts.map(
+    (r) => `\u2022 ${r.id}: ${r.vendor?.name || r.vendorName || "Unknown"} - ${r.totalAmount || "?"} ${r.currency || ""} (${r.purchaseDate ? new Date(r.purchaseDate).toLocaleDateString() : "no date"})`
+  ).join("\n");
+}
+function formatReceiptDetail(r) {
+  let text = `Receipt: ${r.id}
+`;
+  text += `Vendor: ${r.vendor?.name || r.vendorName || "Unknown"}
+`;
+  text += `Date: ${r.purchaseDate ? new Date(r.purchaseDate).toLocaleDateString() : "N/A"}
+`;
+  text += `Total: ${r.totalAmount || "?"} ${r.currency || ""}
+`;
+  if (r.items?.length) {
+    text += `
+Line Items:
+`;
+    r.items.forEach((item) => {
+      text += `  \u2022 ${item.description}: ${item.totalPrice}
+`;
+    });
+  }
+  if (r.matchedTransaction) {
+    text += `
+Matched to: ${r.matchedTransaction.id} - ${r.matchedTransaction.description}`;
+  }
+  return text;
+}
+function formatTransactions(transactions) {
+  if (!transactions?.length) return "No transactions found.";
+  return transactions.map(
+    (t) => `\u2022 ${t.id}: ${t.description} - ${t.amount} ${t.currency || ""} (${t.transactionDate ? new Date(t.transactionDate).toLocaleDateString() : "no date"})`
+  ).join("\n");
+}
+function formatTransaction(t) {
+  let text = `Transaction: ${t.id}
+`;
+  text += `Description: ${t.description}
+`;
+  text += `Amount: ${t.amount} ${t.currency || ""}
+`;
+  text += `Date: ${t.transactionDate ? new Date(t.transactionDate).toLocaleDateString() : "N/A"}
+`;
+  text += `Type: ${t.transactionType || "N/A"}`;
+  return text;
+}
+function formatStatements(statements) {
+  if (!statements?.length) return "No statements found.";
+  return statements.map(
+    (s) => `\u2022 ${s.id}: ${s.institutionName} - ${s.statementDate ? new Date(s.statementDate).toLocaleDateString() : "no date"} (${s.transactionCount || 0} transactions)`
+  ).join("\n");
+}
+function formatMatches(matches) {
+  if (!matches?.length) return "No matches found.";
+  return matches.map(
+    (m) => `\u2022 ${m.id}: Receipt ${m.receiptId} \u2194 Transaction ${m.transactionId} (${Math.round(m.confidenceScore * 100)}% confidence) [${m.status}]`
+  ).join("\n");
+}
+
+// src/index.js
+var apiKey = process.env.MINTLINE_API_KEY;
+if (!apiKey) {
+  console.error("Error: MINTLINE_API_KEY environment variable is required");
+  process.exit(1);
+}
+var client = createClient(apiKey);
+var server = new Server(
+  {
+    name: "mintline-mcp",
+    version: "1.0.0"
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    const result = await handleTool(client, name, args || {});
+    return {
+      content: [{ type: "text", text: result }]
+    };
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: `Error: ${error.message}` }],
+      isError: true
+    };
+  }
+});
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Mintline MCP server running");
+}
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mintline/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Mintline - connect AI assistants to your receipts and transactions",
+  "main": "dist/index.js",
+  "bin": {
+    "mintline-mcp": "./dist/cli.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "esbuild src/index.js --bundle --platform=node --format=esm --outfile=dist/index.js --external:@modelcontextprotocol/sdk && node scripts/build-cli.js",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "mintline",
+    "receipts",
+    "ai",
+    "claude"
+  ],
+  "author": "Mintline",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.2"
+  }
+}