@hoagsmedia/frugr-mcp 0.2.0 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 Preferred npm name for the frugr **read-only** MCP stdio bridge.
 
-This package is identical to [`@hoagsmedia/frgur-mcp-server`](https://www.npmjs.com/package/@hoagsmedia/frgur-mcp-server) v0.2.0 — same `index.mjs`, same env vars (`FRGUR_API_TOKEN`, `FRGUR_API_URL`). The legacy `frgur` spelling remains for backward compatibility.
+This package is identical to [`@hoagsmedia/frgur-mcp-server`](https://www.npmjs.com/package/@hoagsmedia/frgur-mcp-server) v0.3.1 — same `index.mjs`, same env vars (`FRGUR_API_TOKEN`, `FRGUR_API_URL`). The legacy `frgur` spelling remains for backward compatibility.
 
 Full setup, tool list, and security notes: [mcp-server README on GitHub](https://github.com/hoagsmedia/frugr/blob/main/mcp-server/README.md) or the [`frgur-mcp-server` npm page](https://www.npmjs.com/package/@hoagsmedia/frgur-mcp-server).
 
@@ -11,9 +11,9 @@ Full setup, tool list, and security notes: [mcp-server README on GitHub](https:/
 	"mcpServers": {
 		"frugr": {
 			"command": "npx",
-			"args": ["-y", "@hoagsmedia/frugr-mcp@0.2.0"],
+			"args": ["-y", "@hoagsmedia/frugr-mcp@0.3.1"],
 			"env": {
-				"FRGUR_API_URL": "https://app.frgur.com",
+				"FRGUR_API_URL": "https://frugr.app",
 				"FRGUR_API_TOKEN": "frgur_pat_your_token_here"
 			}
 		}

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,6 +1,6 @@
 {
 	"name": "@hoagsmedia/frugr-mcp",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"description": "Read-only MCP bridge to your frugr books (12 tools). Preferred npm name — alias of @hoagsmedia/frgur-mcp-server.",
 	"type": "module",
 	"bin": {