@warmio/mcp 1.0.0

package/README.md

@@ -0,0 +1,113 @@
+# Warm MCP Server
+
+MCP server that gives Claude Code (or any MCP client) read-only access to your Warm financial data.
+
+## Quick Install
+
+```bash
+npx @warmio/mcp
+```
+
+Works on macOS, Linux, and Windows. Auto-configures: Claude Code, Cursor, Windsurf, Claude Desktop, OpenCode, Codex CLI, Antigravity, Gemini CLI.
+
+## Manual Installation
+
+### Claude Code (easiest)
+
+```bash
+claude mcp add --scope user --env WARM_API_KEY=your-key warm -- npx -y @warmio/mcp
+```
+
+### Other Tools
+
+Add to your tool's MCP config file:
+
+| Tool           | Config Path                                                       | Format |
+| -------------- | ----------------------------------------------------------------- | ------ |
+| Claude Code    | `~/.claude.json`                                                  | JSON   |
+| Cursor         | `~/.cursor/mcp.json`                                              | JSON   |
+| Windsurf       | `~/.codeium/windsurf/mcp_config.json`                             | JSON   |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | JSON   |
+| OpenCode       | `~/.config/opencode/opencode.json`                                | JSON   |
+| Codex CLI      | `~/.codex/config.toml`                                            | TOML   |
+| Antigravity    | `~/.gemini/antigravity/mcp_config.json`                           | JSON   |
+| Gemini CLI     | `~/.gemini/settings.json`                                         | JSON   |
+
+**JSON format** (most tools):
+
+```json
+{
+  "mcpServers": {
+    "warm": {
+      "command": "npx",
+      "args": ["-y", "@warmio/mcp"],
+      "env": { "WARM_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+**TOML format** (Codex CLI):
+
+```toml
+[mcp_servers.warm]
+command = "npx"
+args = ["-y", "@warmio/mcp"]
+
+[mcp_servers.warm.env]
+WARM_API_KEY = "your-api-key"
+```
+
+Get your API key from [warm.io/settings](https://warm.io/settings) → API Keys.
+
+## Requirements
+
+- **Pro subscription** — API access requires Warm Pro
+- **API key** — Generate in Settings → API Keys
+- **Node.js 18+** — For running the MCP server
+
+## Available Tools
+
+| Tool               | Description                                    |
+| ------------------ | ---------------------------------------------- |
+| `get_accounts`     | List all connected bank accounts with balances |
+| `get_transactions` | Get transactions with date/limit filters       |
+| `get_recurring`    | Show subscriptions and recurring payments      |
+| `get_snapshots`    | Net worth history (daily or monthly)           |
+| `verify_key`       | Check if API key is valid                      |
+
+## Usage
+
+Once configured, just ask Claude naturally:
+
+- "How much did I spend on restaurants last month?"
+- "What's my net worth?"
+- "Show my subscriptions"
+- "What are my biggest expenses?"
+
+Claude will automatically use the MCP tools to query your data.
+
+## Configuration
+
+| Environment Variable | Description                  | Default           |
+| -------------------- | ---------------------------- | ----------------- |
+| `WARM_API_KEY`       | Your Warm API key (required) | —                 |
+| `WARM_API_URL`       | API base URL                 | `https://warm.io` |
+
+## Security
+
+- **Read-only** — Cannot modify, delete, or transfer data
+- **Scoped** — Key only accesses your accounts
+- **Revocable** — Delete key in Settings to revoke instantly
+
+## Development
+
+```bash
+cd mcp
+npm install
+npm run build
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Warm MCP Server
+ *
+ * Provides financial data from the Warm API as MCP tools.
+ * Reads API key from ~/.config/warm/api_key or WARM_API_KEY env var.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+/**
+ * Warm MCP Server
+ *
+ * Provides financial data from the Warm API as MCP tools.
+ * Reads API key from ~/.config/warm/api_key or WARM_API_KEY env var.
+ */
+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 * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+const API_URL = process.env.WARM_API_URL || 'https://warm.io';
+function getApiKey() {
+    // Environment variable takes precedence
+    if (process.env.WARM_API_KEY) {
+        return process.env.WARM_API_KEY;
+    }
+    // Fall back to config file
+    const configPath = path.join(os.homedir(), '.config', 'warm', 'api_key');
+    try {
+        return fs.readFileSync(configPath, 'utf-8').trim();
+    }
+    catch {
+        return null;
+    }
+}
+async function apiRequest(endpoint, params = {}) {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        throw new Error('WARM_API_KEY not set. Add your API key from https://warm.io/settings');
+    }
+    const url = new URL(endpoint, API_URL);
+    Object.entries(params).forEach(([key, value]) => {
+        if (value)
+            url.searchParams.append(key, value);
+    });
+    const response = await fetch(url.toString(), {
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        const errorMessages = {
+            401: 'Invalid or expired API key. Regenerate at https://warm.io/settings',
+            403: 'Pro subscription required. Upgrade at https://warm.io/settings',
+            429: 'Rate limit exceeded. Try again in a few minutes.',
+        };
+        throw new Error(errorMessages[response.status] || `HTTP ${response.status}`);
+    }
+    return response.json();
+}
+const server = new Server({ name: 'warm', version: '1.0.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'get_accounts',
+            description: 'Get all connected bank accounts with balances. Returns account names, types, balances, and institutions.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    since: {
+                        type: 'string',
+                        description: 'Filter accounts updated since this date (ISO format)',
+                    },
+                },
+            },
+        },
+        {
+            name: 'get_transactions',
+            description: 'Get transactions from connected accounts. Supports pagination and date filtering.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    limit: {
+                        type: 'number',
+                        description: 'Maximum number of transactions to return (default: 100)',
+                    },
+                    since: {
+                        type: 'string',
+                        description: 'Get transactions since this date (ISO format, e.g., 2024-01-01)',
+                    },
+                    cursor: {
+                        type: 'string',
+                        description: 'Pagination cursor for fetching more results',
+                    },
+                },
+            },
+        },
+        {
+            name: 'get_recurring',
+            description: 'Get recurring payments and subscriptions detected from transaction history.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    since: {
+                        type: 'string',
+                        description: 'Filter recurring items detected since this date',
+                    },
+                },
+            },
+        },
+        {
+            name: 'get_snapshots',
+            description: 'Get net worth snapshots over time (daily or monthly aggregation).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    granularity: {
+                        type: 'string',
+                        enum: ['daily', 'monthly'],
+                        description: 'Aggregation level (default: daily)',
+                    },
+                    limit: {
+                        type: 'number',
+                        description: 'Number of snapshots to return',
+                    },
+                    since: {
+                        type: 'string',
+                        description: 'Start date for snapshots (ISO format)',
+                    },
+                },
+            },
+        },
+        {
+            name: 'verify_key',
+            description: 'Check if the Warm API key is valid and working.',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case 'get_accounts': {
+                const params = {};
+                if (args?.since)
+                    params.since = String(args.since);
+                const data = await apiRequest('/api/accounts', params);
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            case 'get_transactions': {
+                const params = {};
+                if (args?.limit)
+                    params.limit = String(args.limit);
+                if (args?.since)
+                    params.last_knowledge = String(args.since);
+                if (args?.cursor)
+                    params.cursor = String(args.cursor);
+                const data = await apiRequest('/api/transactions', params);
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            case 'get_recurring': {
+                const params = {};
+                if (args?.since)
+                    params.since = String(args.since);
+                const data = await apiRequest('/api/recurring', params);
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            case 'get_snapshots': {
+                // Fetch transactions which includes snapshots
+                const response = (await apiRequest('/api/transactions', {
+                    limit: '1',
+                }));
+                const snapshots = response.snapshots || [];
+                const granularity = args?.granularity || 'daily';
+                const limit = args?.limit ? Number(args.limit) : granularity === 'daily' ? 100 : 0;
+                const since = args?.since;
+                let filtered = snapshots;
+                if (since) {
+                    filtered = filtered.filter((s) => String(s.snapshot_date) >= since);
+                }
+                if (granularity === 'monthly') {
+                    // Group by month, take last snapshot of each month
+                    const byMonth = new Map();
+                    filtered.forEach((s) => {
+                        const month = String(s.snapshot_date).substring(0, 7);
+                        if (!byMonth.has(month) ||
+                            String(s.snapshot_date) > String(byMonth.get(month).snapshot_date)) {
+                            byMonth.set(month, s);
+                        }
+                    });
+                    filtered = Array.from(byMonth.values());
+                }
+                // Sort descending and limit
+                filtered.sort((a, b) => String(b.snapshot_date).localeCompare(String(a.snapshot_date)));
+                if (limit > 0) {
+                    filtered = filtered.slice(0, limit);
+                }
+                const result = {
+                    granularity,
+                    snapshots: filtered.map((s) => ({
+                        date: s.snapshot_date,
+                        ...(granularity === 'monthly' && {
+                            month: String(s.snapshot_date).substring(0, 7),
+                        }),
+                        net_worth: s.net_worth,
+                        total_assets: s.total_assets,
+                        total_liabilities: s.total_liabilities,
+                    })),
+                };
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'verify_key': {
+                const data = await apiRequest('/api/verify');
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ error: message }, null, 2) }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@warmio/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Warm Financial API",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "warm-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "warm",
+    "financial",
+    "api",
+    "claude"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}