@numeratica/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Numeratica / Francis Townsend-Merino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @numeratica/mcp
+
+A thin [MCP](https://modelcontextprotocol.io) bridge that connects any MCP client (Claude Desktop, Cursor, …) to the **[Numeratica](https://docs.numeratica.com)** financial-planning API — retirement Monte Carlo, taxes, RMDs, Social Security, Roth conversions, and more.
+
+**Get a free key at [https://docs.numeratica.com](https://docs.numeratica.com).**
+
+## How it works
+
+This package is a **transport bridge, nothing more**. It reads JSON-RPC from stdin and forwards each message to the hosted `POST /mcp` endpoint with your API key as a bearer token, then writes the response back to stdout. The tool list and all results come straight from the API — so the bridge always stays in sync and ships no calculation logic of its own. Your key is sent only in the `Authorization` header and **is never logged**.
+
+- **Zero runtime dependencies** (Node ≥ 18 built-in `fetch` + `node:readline`).
+- Open source (MIT). The interesting part is the API; this is just the wire.
+
+## Install
+
+No install needed — your MCP client runs it on demand with `npx`. (You can also `npm i -g @numeratica/mcp` to get the `numeratica-mcp` command.)
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "numeratica": {
+      "command": "npx",
+      "args": ["-y", "@numeratica/mcp"],
+      "env": { "NUMERATICA_API_KEY": "nmr_sk_your_key_here" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (or a project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "numeratica": {
+      "command": "npx",
+      "args": ["-y", "@numeratica/mcp"],
+      "env": { "NUMERATICA_API_KEY": "nmr_sk_your_key_here" }
+    }
+  }
+}
+```
+
+Restart the client and the Numeratica tools appear. Try: *"Run a retirement Monte Carlo for a 40-year-old retiring at 65."*
+
+## Configuration
+
+| Variable | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `NUMERATICA_API_KEY` | **yes** | — | Your key. Get one free at [docs.numeratica.com](https://docs.numeratica.com). Never logged. |
+| `NUMERATICA_BASE_URL` | no | `https://api.numeratica.com` | Override the API base (e.g. for testing). |
+
+You can also pass the key with `--key <value>` instead of the env var.
+
+## Links
+
+- **API docs & reference:** [https://docs.numeratica.com](https://docs.numeratica.com)
+- **Get a free key:** [https://docs.numeratica.com/get-key](https://docs.numeratica.com/get-key)
+
+## License
+
+MIT © Numeratica / Francis Townsend-Merino

package/bin/numeratica-mcp.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/bridge.js';
+
+main();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@numeratica/mcp",
+  "version": "0.1.0",
+  "description": "Thin stdio MCP bridge to the Numeratica financial-planning API — add retirement, tax, and planning tools to any MCP client with npx.",
+  "type": "module",
+  "bin": {
+    "numeratica-mcp": "bin/numeratica-mcp.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "numeratica",
+    "retirement",
+    "tax",
+    "finance",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/numeratica/mcp.git"
+  },
+  "homepage": "https://docs.numeratica.com",
+  "bugs": {
+    "url": "https://github.com/numeratica/mcp/issues"
+  },
+  "license": "MIT",
+  "author": "Numeratica / Francis Townsend-Merino",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/bridge.js

@@ -0,0 +1,144 @@
+// Numeratica MCP bridge — a stdio <-> hosted /mcp transport shim.
+//
+// It is deliberately dumb: it knows nothing about the tool catalog or any
+// calculation. Every JSON-RPC message read from stdin is forwarded verbatim to
+// the hosted /mcp endpoint and the response is written back to stdout. So
+// `initialize`, `tools/list`, and `tools/call` are all answered by the server —
+// the bridge auto-syncs with the API and can leak nothing about it.
+
+import { createInterface } from 'node:readline';
+
+const DEFAULT_BASE_URL = 'https://api.numeratica.com';
+
+/**
+ * @typedef {Object} Config
+ * @property {string|undefined} apiKey
+ * @property {string} baseUrl
+ */
+
+/**
+ * Resolve configuration from argv (`--key <value>`) and the environment.
+ * @param {string[]} argv  process args (without node/script)
+ * @param {Record<string,string|undefined>} env
+ * @returns {Config}
+ */
+export function loadConfig(argv, env) {
+  let apiKey = env.NUMERATICA_API_KEY;
+  const i = argv.indexOf('--key');
+  if (i !== -1 && argv[i + 1]) apiKey = argv[i + 1];
+  const baseUrl = (env.NUMERATICA_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, '');
+  return { apiKey, baseUrl };
+}
+
+/**
+ * Validate config. Returns an error message string if invalid, else null.
+ * The message never contains the key (there is nothing to leak when it's absent).
+ * @param {Config} config
+ * @returns {string|null}
+ */
+export function validateConfig(config) {
+  if (!config.apiKey) {
+    return 'NUMERATICA_API_KEY is required. Get a free key at https://docs.numeratica.com';
+  }
+  return null;
+}
+
+/**
+ * Build a JSON-RPC 2.0 error response string.
+ * @param {number|string|null} id
+ * @param {number} code
+ * @param {string} message
+ * @returns {string}
+ */
+function jsonRpcError(id, code, message) {
+  return JSON.stringify({ jsonrpc: '2.0', id: id ?? null, error: { code, message } });
+}
+
+/**
+ * Forward one raw JSON-RPC line to the hosted endpoint. Returns the text to
+ * write to stdout, or null when there is nothing to write (a notification ack).
+ * @param {string} line
+ * @param {{ baseUrl: string, apiKey: string, fetch: typeof globalThis.fetch }} opts
+ * @returns {Promise<string|null>}
+ */
+export async function forward(line, opts) {
+  const body = line.trim();
+  if (!body) return null;
+
+  // Parse only to learn the id and whether this is a notification (no `id`), so
+  // we can echo a matching id on error. The body is still forwarded verbatim.
+  let id = null;
+  let isNotification = false;
+  try {
+    const msg = JSON.parse(body);
+    if (msg && typeof msg === 'object' && !Array.isArray(msg)) {
+      id = msg.id ?? null;
+      isNotification = msg.id === undefined;
+    }
+  } catch {
+    // Not valid JSON; forward as-is. We just can't echo a matching id on error.
+  }
+
+  let res;
+  try {
+    res = await opts.fetch(`${opts.baseUrl}/mcp`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${opts.apiKey}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body,
+    });
+  } catch (err) {
+    if (isNotification) return null;
+    const detail = err instanceof Error ? err.message : 'unknown error';
+    return jsonRpcError(id, -32000, `transport error contacting Numeratica: ${detail}`);
+  }
+
+  // Notification acks (202/204) carry no body — write nothing.
+  if (res.status === 202 || res.status === 204) return null;
+
+  const text = (await res.text()).trim();
+
+  if (!res.ok) {
+    if (isNotification) return null;
+    const detail = text ? `: ${text.slice(0, 500)}` : '';
+    return jsonRpcError(id, -32000, `Numeratica API error (HTTP ${res.status})${detail}`);
+  }
+
+  return text === '' ? null : text;
+}
+
+/**
+ * Run the bridge: read newline-delimited JSON-RPC from `stdin`, forward each
+ * message in order, and write each response with `write`. Resolves on stdin EOF.
+ * @param {{ stdin: NodeJS.ReadableStream, write: (s: string) => void, fetch: typeof globalThis.fetch, baseUrl: string, apiKey: string }} opts
+ * @returns {Promise<void>}
+ */
+export async function run(opts) {
+  const rl = createInterface({ input: opts.stdin, crlfDelay: Infinity });
+  for await (const line of rl) {
+    const out = await forward(line, opts);
+    if (out !== null) opts.write(out);
+  }
+}
+
+/** CLI entrypoint: wire process stdio + global fetch, or exit cleanly on misconfig. */
+export async function main() {
+  const config = loadConfig(process.argv.slice(2), process.env);
+  const err = validateConfig(config);
+  if (err) {
+    process.stderr.write(`numeratica-mcp: ${err}\n`);
+    process.exit(1);
+    return;
+  }
+  await run({
+    stdin: process.stdin,
+    write: (s) => process.stdout.write(s.endsWith('\n') ? s : s + '\n'),
+    fetch: globalThis.fetch,
+    baseUrl: config.baseUrl,
+    apiKey: /** @type {string} */ (config.apiKey),
+  });
+  process.exit(0);
+}