@hoagsmedia/frgur-mcp-server 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.1 — 2026-07-06
+
+- **Skip the double AI pass (HOA-423).** `import_receipt_file` now takes an optional `extracted` object (`{vendor, amountCents, date, category?}`) — the fields your AI client already read off the receipt. When provided, frugr uses them directly instead of running (and billing) its own server-side vision extraction. The tool description instructs the model to include it whenever it has seen the receipt. Fields still land in Needs Review for human approval either way.
+
+## 0.3.0 — 2026-07-06
+
+- **Import receipts from a local file (HOA-416).** New client-side tool `import_receipt_file({ filePath })`: reads a receipt (PDF/JPEG/PNG/WebP/GIF/HEIC, ≤3 MB) from your machine, base64s it, and forwards to frugr's new `propose_expense_from_receipt` server tool. frugr extracts the receipt and either attaches it to the matching unreceipted expense or files a provisional draft in **Needs Review** — never a direct ledger write. Ask your AI client: _"import ~/Downloads/receipt.pdf into my books."_
+- The local tool is advertised only when the connected frugr server actually offers receipt import, so the bridge stays compatible with older deployments.
+- Bridge is no longer strictly read-only (it exposes frugr's review-queue "propose" tools); description/docs updated. Approval always happens in the frugr app.
+
 ## 0.2.0 — 2026-07-02
 
 - Document all **12** read-only books tools (was marketed as 3 in the npm description).

package/README.md

@@ -3,7 +3,7 @@
 > **Branding:** the preferred npm name is now [`@hoagsmedia/frugr-mcp`](https://www.npmjs.com/package/@hoagsmedia/frugr-mcp) — same package, same env vars. `@hoagsmedia/frgur-mcp-server` remains supported for existing configs.
 
 A thin, **read-only** [MCP](https://modelcontextprotocol.io) bridge to your
-[frugr](https://frgur.com) books. Point your own AI client — Cursor, Claude
+[frugr](https://frugr.app) books. Point your own AI client — Cursor, Claude
 Desktop, Claude Code, or any MCP-capable app — at your accounting data and ask
 questions in plain language.
 
@@ -45,7 +45,7 @@ at any time.
 			"command": "npx",
 			"args": ["-y", "@hoagsmedia/frugr-mcp@0.2.0"],
 			"env": {
-				"FRGUR_API_URL": "https://app.frgur.com",
+				"FRGUR_API_URL": "https://frugr.app",
 				"FRGUR_API_TOKEN": "frgur_pat_your_token_here"
 			}
 		}
@@ -63,15 +63,15 @@ Prefer the **`frugr`** spelling? Use `@hoagsmedia/frugr-mcp@0.2.0` instead — i
 
 ## Environment
 
-| Variable          | Required | Default                 | Notes                      |
-| ----------------- | -------- | ----------------------- | -------------------------- |
-| `FRGUR_API_TOKEN` | yes      | —                       | Your Personal Access Token |
-| `FRGUR_API_URL`   | no       | `https://app.frgur.com` | Your frugr origin          |
+| Variable          | Required | Default             | Notes                      |
+| ----------------- | -------- | ------------------- | -------------------------- |
+| `FRGUR_API_TOKEN` | yes      | —                   | Your Personal Access Token |
+| `FRGUR_API_URL`   | no       | `https://frugr.app` | Your frugr origin          |
 
 ## Verifying a token
 
 ```sh
-curl -H "Authorization: Bearer frgur_pat_…" https://app.frgur.com/api/mcp
+curl -H "Authorization: Bearer frgur_pat_…" https://frugr.app/api/mcp
 # → {"ok":true,"transport":"frgur-mcp","tools":["get_profit_loss", ...]}
 ```
 

package/index.mjs

@@ -1,26 +1,31 @@
 #!/usr/bin/env node
-// @hoagsmedia/frgur-mcp-server — a thin, READ-ONLY MCP bridge to your frugr books.
+// @hoagsmedia/frgur-mcp-server — a thin MCP bridge to your frugr books.
 //
 // It exposes frugr's books tools over stdio (for Cursor / Claude Desktop /
 // Claude Code / ChatGPT) and forwards every call to the frugr API using your
-// Personal Access Token. The bridge holds no credentials of its own, runs your
-// own AI client's model (not frugr's), and can only read — it never writes.
+// Personal Access Token. The bridge holds no credentials of its own and runs
+// your own AI client's model (not frugr's). Most tools READ your books; the
+// "propose" tools (incl. receipt import) only ever stage suggestions into
+// frugr's Needs Review queue — nothing writes to your ledger without your
+// approval in the app.
 //
 // Config (env):
 //   FRGUR_API_TOKEN  required — a token from frugr → Settings → External AI apps
-//   FRGUR_API_URL    optional — your frugr origin (default https://app.frgur.com)
+//   FRGUR_API_URL    optional — your frugr origin (default https://frugr.app)
 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 { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { readFileSync, statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, extname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const PKG = JSON.parse(
 	readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8')
 );
 
-const API_URL = (process.env.FRGUR_API_URL ?? 'https://app.frgur.com').replace(/\/+$/, '');
+const API_URL = (process.env.FRGUR_API_URL ?? 'https://frugr.app').replace(/\/+$/, '');
 const API_TOKEN = process.env.FRGUR_API_TOKEN ?? '';
 const ENDPOINT = `${API_URL}/api/mcp`;
 
@@ -57,21 +62,129 @@ async function call(method, params) {
 	return data;
 }
 
+// --- Local file bridge for receipt import (v0.3.0) --------------------------
+// Claude Desktop can't turn a chat attachment into base64, but this bridge runs
+// on the user's machine and can read files. `import_receipt_file` is a
+// CLIENT-SIDE tool: it reads the path locally and forwards the bytes to the
+// server's `propose_expense_from_receipt`.
+const RECEIPT_MAX_BYTES = 3 * 1024 * 1024;
+const RECEIPT_MIME_BY_EXT = {
+	'.pdf': 'application/pdf',
+	'.jpg': 'image/jpeg',
+	'.jpeg': 'image/jpeg',
+	'.png': 'image/png',
+	'.webp': 'image/webp',
+	'.gif': 'image/gif',
+	'.heic': 'image/heic'
+};
+
+export function expandPath(p) {
+	const raw = String(p ?? '').trim();
+	if (!raw) return '';
+	const expanded = raw === '~' ? homedir() : raw.replace(/^~(?=\/|\\)/, homedir());
+	return resolve(expanded);
+}
+
+export function mimeFromExtension(filePath) {
+	return RECEIPT_MIME_BY_EXT[extname(filePath).toLowerCase()] ?? null;
+}
+
+const IMPORT_RECEIPT_TOOL = {
+	name: 'import_receipt_file',
+	description:
+		'Import a receipt from a file on the machine running THIS MCP bridge process (e.g. ' +
+		"~/Downloads/receipt.pdf on the user's computer). filePath resolves against the bridge " +
+		"host's filesystem ONLY — paths from a chat-upload sandbox (e.g. /mnt/user-data/uploads/…) " +
+		'or any other machine will NEVER resolve here; do not retry them. For files you can read ' +
+		'but the bridge cannot, call propose_expense_from_receipt with base64 instead (3 MB decoded ' +
+		'cap; downscale large scans first). Max 3 MB; PDF, JPEG, PNG, WebP, GIF, or HEIC. If you ' +
+		'have already seen the receipt contents, ALWAYS include `extracted` — frugr then uses your ' +
+		'reading instead of running (and billing) its own AI extraction.',
+	inputSchema: {
+		type: 'object',
+		properties: {
+			filePath: {
+				type: 'string',
+				description: 'Absolute or ~-relative path to the receipt file on this machine.'
+			},
+			extracted: {
+				type: 'object',
+				description:
+					'The fields you already read off this receipt. Preferred whenever you have seen it.',
+				properties: {
+					vendor: { type: 'string', description: 'Merchant name as printed.' },
+					amountCents: {
+						type: 'integer',
+						description: 'Receipt TOTAL in cents, positive (e.g. $31.03 -> 3103).'
+					},
+					date: { type: 'string', description: 'Receipt date, YYYY-MM-DD.' },
+					category: { type: 'string', description: 'Optional expense category suggestion.' }
+				},
+				required: ['amountCents']
+			}
+		},
+		required: ['filePath']
+	}
+};
+
+async function importReceiptFile(args) {
+	const filePath = expandPath(args?.filePath);
+	if (!filePath) return { error: 'filePath is required.' };
+
+	let stat;
+	try {
+		stat = statSync(filePath);
+	} catch {
+		return { error: `No file found at ${filePath}.` };
+	}
+	if (!stat.isFile()) return { error: `${filePath} is not a file.` };
+	if (stat.size > RECEIPT_MAX_BYTES) {
+		return {
+			error: `That file is larger than the 3 MB limit (${Math.round(stat.size / 1024)} KB).`
+		};
+	}
+
+	const mimeType = mimeFromExtension(filePath);
+	if (!mimeType) {
+		return { error: 'Unsupported file type. Use a PDF, JPEG, PNG, WebP, GIF, or HEIC receipt.' };
+	}
+
+	const data = await readFile(filePath);
+	return call('tools/call', {
+		name: 'propose_expense_from_receipt',
+		arguments: {
+			filename: basename(filePath),
+			mimeType,
+			dataBase64: data.toString('base64'),
+			...(args?.extracted && typeof args.extracted === 'object'
+				? { extracted: args.extracted }
+				: {})
+		}
+	});
+}
+
 const server = new Server(
 	{ name: 'frgur-books', version: PKG.version },
 	{ capabilities: { tools: {} } }
 );
 
 // Tool list comes straight from frugr, so adding a tool server-side surfaces it
-// to every client with no package update.
+// to every client with no package update. The local file bridge is appended
+// only when the server actually offers receipt import (keeps old servers safe).
 server.setRequestHandler(ListToolsRequestSchema, async () => {
 	const { tools } = await call('tools/list');
-	return { tools: tools ?? [] };
+	const list = tools ?? [];
+	const hasReceiptImport = list.some((t) => t.name === 'propose_expense_from_receipt');
+	return { tools: hasReceiptImport ? [...list, IMPORT_RECEIPT_TOOL] : list };
 });
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
 	const { name, arguments: args } = request.params;
-	const result = await call('tools/call', { name, arguments: args ?? {} });
+	// Intercept the client-side file tool before forwarding.
+	const result =
+		name === 'import_receipt_file'
+			? await importReceiptFile(args ?? {})
+			: await call('tools/call', { name, arguments: args ?? {} });
 	// frugr already returns an MCP CallTool result ({ content, isError }); pass it
 	// through, falling back to stringifying anything unexpected.
 	return {
@@ -81,4 +194,4 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 
 await server.connect(new StdioServerTransport());
-logErr(`connected to ${API_URL} — read-only books tools available.`);
+logErr(`connected to ${API_URL} — books tools available (reads + review-queue proposals).`);

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@hoagsmedia/frgur-mcp-server",
-	"version": "0.2.0",
-	"description": "Read-only MCP bridge to your frugr books — 12 tools (P&L, transactions, invoices, bills, reconciliation, time/mileage, snapshots, bookkeeping issues). Bring your own AI client.",
+	"version": "0.3.1",
+	"description": "MCP bridge to your frugr books — read tools (P&L, transactions, invoices, bills, reconciliation, time/mileage, snapshots) plus review-queue proposals incl. importing a receipt from a local file. Bring your own AI client.",
 	"type": "module",
 	"bin": {
 		"frgur-mcp": "index.mjs"