@hoagsmedia/frgur-mcp-server 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 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).
+- Pin-friendly Settings wizard config: `@hoagsmedia/frugr-mcp@0.2.0` (legacy `@hoagsmedia/frgur-mcp-server@0.2.0` still works).
+- Publish branding alias **`@hoagsmedia/frugr-mcp`** (same stdio bridge; `frugr-mcp` bin).
+- **`@hoagsmedia/frgur-mcp-server`** remains supported; `FRGUR_API_TOKEN` / `FRGUR_API_URL` unchanged.
+
+## 0.1.0 — 2026-06-23
+
+- Initial npm publish (HOA-299): stdio MCP bridge to frugr read-only books tools.

package/README.md

@@ -1,20 +1,31 @@
 # @hoagsmedia/frgur-mcp-server
 
+> **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.
 
 ## What it does
 
-It exposes three read-only tools over stdio and forwards each call to the frugr
+It exposes read-only tools over stdio and forwards each call to the frugr
 API using your Personal Access Token:
 
-| Tool                  | Returns                                                   |
-| --------------------- | --------------------------------------------------------- |
-| `get_profit_loss`     | Income, expenses, net, and per-category totals for a year |
-| `search_transactions` | Ledger transactions by text, date range, and/or category  |
-| `get_open_invoices`   | Outstanding receivables with balances by client           |
+| Tool                                    | Returns                                                    |
+| --------------------------------------- | ---------------------------------------------------------- |
+| `get_profit_loss`                       | Income, expenses, net, and per-category totals for a year  |
+| `search_transactions`                   | Ledger transactions by text, date range, and/or category   |
+| `list_categories`                       | Chart-of-accounts category names and kinds                 |
+| `summarize_transactions`                | Transaction totals, rollups, and largest matching rows     |
+| `compare_periods`                       | Period-over-period transaction totals and counts           |
+| `compare_receipts_to_bank_transactions` | Receipt-backed rows vs matching bank rows                  |
+| `get_open_invoices`                     | Outstanding receivables with balances by client            |
+| `get_open_bills`                        | Outstanding payables with due dates and vendor balances    |
+| `get_reconciliation_status`             | Account reconciliation freshness and uncleared counts      |
+| `get_time_mileage_summary`              | Billable time and mileage trip summaries                   |
+| `get_business_snapshot`                 | Compact receivables, payables, spend, and cleanup snapshot |
+| `find_bookkeeping_issues`               | Uncategorized rows, missing receipts, and duplicates       |
 
 The bridge holds no credentials of its own, **never writes** to your books, and
 runs **your** AI client's model under **your** subscription — frugr is only the
@@ -32,9 +43,9 @@ at any time.
 	"mcpServers": {
 		"frgur": {
 			"command": "npx",
-			"args": ["-y", "@hoagsmedia/frgur-mcp-server"],
+			"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"
 			}
 		}
@@ -48,17 +59,19 @@ at any time.
 
 Requires Node.js 18+.
 
+Prefer the **`frugr`** spelling? Use `@hoagsmedia/frugr-mcp@0.2.0` instead — identical bridge.
+
 ## 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", ...]}
 ```
 
@@ -72,12 +85,32 @@ curl -H "Authorization: Bearer frgur_pat_…" https://app.frgur.com/api/mcp
 
 ## Publishing (maintainers)
 
-Package: `@hoagsmedia/frgur-mcp-server` under the [hoagsmedia](https://www.npmjs.com/org/hoagsmedia) npm org.
+Packages (same `index.mjs`, publish both on release):
+
+| npm name                       | Bin         |
+| ------------------------------ | ----------- |
+| `@hoagsmedia/frugr-mcp`        | `frugr-mcp` |
+| `@hoagsmedia/frgur-mcp-server` | `frgur-mcp` |
 
-1. Bump `version` in `mcp-server/package.json`.
-2. Merge to `main`, then either:
+Under the [hoagsmedia](https://www.npmjs.com/org/hoagsmedia) npm org.
+
+1. Bump `version` in `mcp-server/package.json` and add a `CHANGELOG.md` entry.
+2. Run `npm run sync-frugr-alias` in `mcp-server/` (also runs on `prepublishOnly`; CI fails if committed alias copies drift).
+3. Merge to `main`, then **publish before** the pinned Settings copy reaches prod:
    - **GitHub Actions:** run workflow **Publish MCP server** (`workflow_dispatch`), or
-   - **Tag:** push `frgur-mcp-server-vX.Y.Z` (also triggers publish).
-3. Requires `NPM_TOKEN` in repo secrets — use an npm **Granular Access Token** with type **Automation** (publish to `@hoagsmedia`). Legacy/read-write tokens with account 2FA fail CI with `EOTP`; automation tokens skip OTP.
+   - **Tag:** push `frgur-mcp-server-vX.Y.Z` (publishes both packages).
+4. Requires `NPM_TOKEN` in repo secrets — use an npm **Granular Access Token** with type **Automation** (publish to `@hoagsmedia`). Legacy/read-write tokens with account 2FA fail CI with `EOTP`; automation tokens skip OTP.
+
+Local dry run:
 
-Local dry run: `npm publish --dry-run` from `mcp-server/`.
+```sh
+cd mcp-server && npm publish --dry-run
+cd mcp-server/frugr-alias && npm publish --dry-run
+```
+
+Smoke after publish (stderr banner; needs a valid PAT — or use Settings → Test connection):
+
+```sh
+FRGUR_API_TOKEN=frgur_pat_… npx -y @hoagsmedia/frugr-mcp@X.Y.Z 2>&1 | head -1
+# → [frgur-mcp] connected to …
+```

package/index.mjs

@@ -1,19 +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, 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 API_URL = (process.env.FRGUR_API_URL ?? 'https://app.frgur.com').replace(/\/+$/, '');
+const PKG = JSON.parse(
+	readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8')
+);
+
+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`;
 
@@ -50,21 +62,102 @@ 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 THIS computer (e.g. ~/Downloads/receipt.pdf). Reads the ' +
+		'file locally and proposes it to frugr, which files it in the Needs Review queue for your ' +
+		'approval. Max 3 MB; PDF, JPEG, PNG, WebP, GIF, or HEIC.',
+	inputSchema: {
+		type: 'object',
+		properties: {
+			filePath: {
+				type: 'string',
+				description: 'Absolute or ~-relative path to the receipt file on this machine.'
+			}
+		},
+		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') }
+	});
+}
+
 const server = new Server(
-	{ name: 'frgur-books', version: '0.1.0' },
+	{ 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 {
@@ -74,4 +167,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,15 +1,20 @@
 {
 	"name": "@hoagsmedia/frgur-mcp-server",
-	"version": "0.1.0",
-	"description": "Read-only MCP bridge to your frugr books — profit & loss, transaction search, open invoices. Bring your own AI client (Cursor, Claude Desktop, ChatGPT).",
+	"version": "0.3.0",
+	"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"
 	},
 	"files": [
 		"index.mjs",
-		"README.md"
+		"README.md",
+		"CHANGELOG.md"
 	],
+	"scripts": {
+		"sync-frugr-alias": "node scripts/sync-frugr-alias.mjs",
+		"prepublishOnly": "npm run sync-frugr-alias"
+	},
 	"engines": {
 		"node": ">=18"
 	},