@hoagsmedia/frgur-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# @hoagsmedia/frgur-mcp-server
+
+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
+questions in plain language.
+
+## What it does
+
+It exposes three 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           |
+
+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
+data provider. Your token scopes access to a single company and can be revoked
+at any time.
+
+## Setup
+
+1. In frugr, go to **Settings → External AI apps (MCP)** and create a token
+   (owner/admin only). Copy it — it's shown once.
+2. Add the bridge to your client's MCP config:
+
+```json
+{
+	"mcpServers": {
+		"frgur": {
+			"command": "npx",
+			"args": ["-y", "@hoagsmedia/frgur-mcp-server"],
+			"env": {
+				"FRGUR_API_URL": "https://app.frgur.com",
+				"FRGUR_API_TOKEN": "frgur_pat_your_token_here"
+			}
+		}
+	}
+}
+```
+
+- **Claude Desktop:** Settings → Developer → Edit Config.
+- **Cursor:** `.cursor/mcp.json` in your project (or the global equivalent).
+- **Claude Code:** `claude mcp add` or your `mcp.json`.
+
+Requires Node.js 18+.
+
+## Environment
+
+| Variable          | Required | Default                 | Notes                      |
+| ----------------- | -------- | ----------------------- | -------------------------- |
+| `FRGUR_API_TOKEN` | yes      | —                       | Your Personal Access Token |
+| `FRGUR_API_URL`   | no       | `https://app.frgur.com` | Your frugr origin          |
+
+## Verifying a token
+
+```sh
+curl -H "Authorization: Bearer frgur_pat_…" https://app.frgur.com/api/mcp
+# → {"ok":true,"transport":"frgur-mcp","tools":["get_profit_loss", ...]}
+```
+
+## Security
+
+- Read-only: the only reachable code path queries your books; nothing writes.
+- Org-scoped: a token resolves to exactly one company server-side; the tools
+  never accept a tenant id from the client.
+- Rate-limited and audited per token on the frugr side.
+- Revoke a token instantly from Settings → External AI apps (MCP).
+
+## Publishing (maintainers)
+
+Package: `@hoagsmedia/frgur-mcp-server` under the [hoagsmedia](https://www.npmjs.com/org/hoagsmedia) npm org.
+
+1. Bump `version` in `mcp-server/package.json`.
+2. Merge to `main`, then either:
+   - **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.
+
+Local dry run: `npm publish --dry-run` from `mcp-server/`.

package/index.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// @hoagsmedia/frgur-mcp-server — a thin, READ-ONLY 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.
+//
+// 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)
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const API_URL = (process.env.FRGUR_API_URL ?? 'https://app.frgur.com').replace(/\/+$/, '');
+const API_TOKEN = process.env.FRGUR_API_TOKEN ?? '';
+const ENDPOINT = `${API_URL}/api/mcp`;
+
+// Diagnostics MUST go to stderr — stdout is the MCP protocol channel.
+function logErr(msg) {
+	process.stderr.write(`[frgur-mcp] ${msg}\n`);
+}
+
+if (!API_TOKEN) {
+	logErr('FRGUR_API_TOKEN is required. Create one in frugr → Settings → External AI apps (MCP).');
+	process.exit(1);
+}
+
+/** POST one bridge request to the frugr endpoint, authenticated by the PAT. */
+async function call(method, params) {
+	let res;
+	try {
+		res = await fetch(ENDPOINT, {
+			method: 'POST',
+			headers: { 'content-type': 'application/json', authorization: `Bearer ${API_TOKEN}` },
+			body: JSON.stringify({ method, params })
+		});
+	} catch (e) {
+		throw new Error(`Could not reach frugr at ${ENDPOINT}: ${e?.message ?? e}`, { cause: e });
+	}
+	const text = await res.text();
+	let data;
+	try {
+		data = text ? JSON.parse(text) : {};
+	} catch {
+		data = { error: text };
+	}
+	if (!res.ok) throw new Error(data?.error ?? `frugr API error ${res.status}`);
+	return data;
+}
+
+const server = new Server(
+	{ name: 'frgur-books', version: '0.1.0' },
+	{ capabilities: { tools: {} } }
+);
+
+// Tool list comes straight from frugr, so adding a tool server-side surfaces it
+// to every client with no package update.
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+	const { tools } = await call('tools/list');
+	return { tools: tools ?? [] };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+	const { name, arguments: args } = request.params;
+	const result = 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 {
+		content: result.content ?? [{ type: 'text', text: JSON.stringify(result) }],
+		isError: Boolean(result.isError)
+	};
+});
+
+await server.connect(new StdioServerTransport());
+logErr(`connected to ${API_URL} — read-only books tools available.`);

package/package.json

@@ -0,0 +1,23 @@
+{
+	"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).",
+	"type": "module",
+	"bin": {
+		"frgur-mcp": "index.mjs"
+	},
+	"files": [
+		"index.mjs",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.29.0"
+	}
+}