@openfinance-sh/mcp 0.1.0

package/build/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/build/index.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer } from "http";
+
+// src/client.ts
+var OpenFinanceClient = class {
+  baseUrl;
+  apiKey;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+  }
+  async request(path, params) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0 && value !== "") {
+          url.searchParams.set(key, value);
+        }
+      }
+    }
+    const res = await fetch(url.toString(), {
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      }
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`API error ${res.status}: ${body}`);
+    }
+    return res.json();
+  }
+  async getAccounts() {
+    return this.request("/api/accounts");
+  }
+  async getTransactions(filter) {
+    const params = {};
+    if (filter?.startDate) params.startDate = filter.startDate;
+    if (filter?.endDate) params.endDate = filter.endDate;
+    if (filter?.searchText) params.search = filter.searchText;
+    if (filter?.merchants?.length)
+      params.merchants = filter.merchants.join(",");
+    if (filter?.accountId !== void 0)
+      params.accountId = String(filter.accountId);
+    if (filter?.limit !== void 0) params.limit = String(filter.limit);
+    if (filter?.cursor) params.cursor = filter.cursor;
+    if (filter?.pending !== void 0) params.pending = String(filter.pending);
+    if (filter?.status?.length) params.status = filter.status.join(",");
+    return this.request("/api/transactions", params);
+  }
+};
+
+// src/tools/accounts.ts
+function registerAccountTools(server, client) {
+  server.tool(
+    "get_accounts",
+    "Get all connected financial accounts with balances and institution info",
+    {},
+    async () => {
+      const { accounts } = await client.getAccounts();
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(accounts, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/transactions.ts
+import { z } from "zod";
+function registerTransactionTools(server, client) {
+  server.tool(
+    "get_transactions",
+    "Search and filter financial transactions. Returns transactions sorted by date (newest first) by default.",
+    {
+      startDate: z.string().describe("Start date filter (YYYY-MM-DD)").optional(),
+      endDate: z.string().describe("End date filter (YYYY-MM-DD)").optional(),
+      search: z.string().describe("Search by transaction name or merchant").optional(),
+      merchants: z.array(z.string()).describe("Filter by exact merchant names").optional(),
+      accountId: z.number().int().describe("Filter by account ID").optional(),
+      limit: z.number().int().positive().max(500).describe("Max results (default 100, max 500)").optional(),
+      cursor: z.string().describe("Cursor for pagination").optional(),
+      pending: z.boolean().describe("Filter pending transactions").optional(),
+      status: z.array(z.enum(["active", "hidden", "deleted"])).describe("Filter by status").optional()
+    },
+    async (params) => {
+      const result = await client.getTransactions({
+        startDate: params.startDate,
+        endDate: params.endDate,
+        searchText: params.search,
+        merchants: params.merchants,
+        accountId: params.accountId,
+        limit: params.limit,
+        cursor: params.cursor,
+        pending: params.pending,
+        status: params.status
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result.transactions, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/index.ts
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let transport = "stdio";
+  let port = 8080;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--transport" && args[i + 1]) {
+      transport = args[i + 1];
+      i++;
+    } else if (args[i] === "--port" && args[i + 1]) {
+      port = parseInt(args[i + 1], 10);
+      i++;
+    }
+  }
+  return { transport, port };
+}
+async function main() {
+  const apiKey = process.env.OPENFINANCE_API_KEY;
+  const baseUrl = process.env.OPENFINANCE_URL || "http://localhost:3000";
+  if (!apiKey) {
+    console.error(
+      "Error: OPENFINANCE_API_KEY environment variable is required"
+    );
+    process.exit(1);
+  }
+  const { transport, port } = parseArgs();
+  const client = new OpenFinanceClient({ baseUrl, apiKey });
+  const server = new McpServer({
+    name: "openfinance",
+    version: "0.1.0"
+  });
+  registerAccountTools(server, client);
+  registerTransactionTools(server, client);
+  if (transport === "stdio") {
+    const stdioTransport = new StdioServerTransport();
+    await server.connect(stdioTransport);
+    console.error("OpenFinance MCP server running on stdio");
+  } else {
+    const httpTransport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: void 0
+    });
+    await server.connect(httpTransport);
+    const httpServer = createServer(async (req, res) => {
+      await httpTransport.handleRequest(req, res);
+    });
+    httpServer.listen(port, () => {
+      console.error(
+        `OpenFinance MCP server running on http://localhost:${port}`
+      );
+    });
+  }
+}
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/manifest.json

@@ -0,0 +1,54 @@
+{
+  "manifest_version": "0.3",
+  "name": "openfinance",
+  "display_name": "OpenFinance",
+  "version": "0.1.0",
+  "description": "Connect your financial accounts to view balances, search transactions, and get spending insights.",
+  "author": {
+    "name": "OpenFinance"
+  },
+  "server": {
+    "type": "node",
+    "entry_point": "build/index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": ["${__dirname}/build/index.js"],
+      "env": {
+        "OPENFINANCE_API_KEY": "${user_config.api_key}",
+        "OPENFINANCE_URL": "${user_config.server_url}"
+      }
+    }
+  },
+  "user_config": {
+    "api_key": {
+      "type": "string",
+      "title": "API Key",
+      "description": "Your OpenFinance API key (starts with sk-)",
+      "sensitive": true,
+      "required": true
+    },
+    "server_url": {
+      "type": "string",
+      "title": "Server URL",
+      "description": "URL of your OpenFinance server",
+      "required": true,
+      "default": "https://api.openfinance.sh"
+    }
+  },
+  "tools": [
+    {
+      "name": "get_accounts",
+      "description": "Get all connected financial accounts with balances and institution info"
+    },
+    {
+      "name": "get_transactions",
+      "description": "Search and filter financial transactions. Returns transactions sorted by date (newest first) by default. For spending analysis, category breakdowns, or questions like 'how much do I spend on X', fetch all transactions (high limit, no search filter) and categorize them client-side by analyzing merchant/transaction names, since transactions do not have category labels."
+    },
+    {
+      "name": "query_transactions",
+      "description": "Run a SQL query against the user's transactions for aggregation and analysis. Write SELECT queries against a `txns` CTE with columns: id, name, amount, date, merchant_name, etc. Runs read-only with 5s timeout and 1000 row limit."
+    }
+  ],
+  "keywords": ["finance", "banking", "transactions", "accounts"],
+  "license": "MIT"
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@openfinance-sh/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "openfinance-mcp": "./build/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsup src/index.ts --format esm --dts --clean --outDir build",
+    "start": "node build/index.js",
+    "bundle": "pnpm build && mcpb pack . openfinance.mcpb"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@openfinance/shared": "workspace:*",
+    "zod": "^3.24.0"
+  },
+  "files": [
+    "build",
+    "manifest.json",
+    "openfinance.mcpb"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@anthropic-ai/mcpb": "^2.1.2",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}