@hoagsmedia/frgur-mcp-server 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 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,5 +1,7 @@
 # @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
 Desktop, Claude Code, or any MCP-capable app — at your accounting data and ask
@@ -7,14 +9,23 @@ 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,7 +43,7 @@ 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_TOKEN": "frgur_pat_your_token_here"
@@ -48,6 +59,8 @@ 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                      |
@@ -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

@@ -12,6 +12,13 @@
 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 { 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_TOKEN = process.env.FRGUR_API_TOKEN ?? '';
@@ -51,7 +58,7 @@ async function call(method, params) {
 }
 
 const server = new Server(
-	{ name: 'frgur-books', version: '0.1.0' },
+	{ name: 'frgur-books', version: PKG.version },
 	{ capabilities: { tools: {} } }
 );
 

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.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.",
 	"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"
 	},