numikeep-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Snowpack Consulting
+
+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,25 @@
+# numikeep-mcp
+
+An MCP server that lets an AI agent add coins to a Numikeep collection, using a
+connection key the collector created in **Numikeep → Settings → Connected apps**.
+
+```json
+{ "mcpServers": { "numikeep": {
+    "command": "node",
+    "args": ["/path/to/numikeep-api/mcp/src/server.mjs"],
+    "env": { "NUMIKEEP_KEY": "nkpat_…", "NUMIKEEP_PHOTO_DIR": "/Users/you/Pictures/Coins" } } } }
+```
+
+Tools: `numikeep_status`, `add_coin`, `update_coin`, `remove_coin`, `add_location`,
+`add_photo`, `list_coins` (only when the key has the see-coins permission).
+
+## Security model
+Assume the agent can be prompt-injected. So:
+- stdio only — no network listener;
+- the key only reaches the configured API (https, or http on loopback), and redirects are refused;
+- photos: only real JPEG/PNG/WebP/HEIC files (magic bytes + matching extension), only from
+  `NUMIKEEP_PHOTO_DIR` after resolving symlinks, and only uploaded to storage.googleapis.com;
+- everything else is enforced by the API: the key adds coins and changes only what it added,
+  and never sees locations, prices paid, notes or photos.
+
+`npm test` covers the guard rails (`test/core.test.mjs`).

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "numikeep-mcp",
+  "version": "0.1.0",
+  "description": "MCP server that lets an AI agent add coins to a Numikeep collection, using a connection key the owner created.",
+  "type": "module",
+  "bin": {
+    "numikeep-mcp": "src/server.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.1",
+    "zod": "4.6.5"
+  },
+  "license": "MIT",
+  "homepage": "https://numikeep.com/developers/",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "numikeep",
+    "mcp",
+    "model-context-protocol",
+    "coins",
+    "numismatics"
+  ]
+}

package/src/core.mjs

@@ -0,0 +1,104 @@
+/**
+ * The security-critical half of the Numikeep MCP server, kept apart from the MCP wiring so
+ * it can be tested directly. Mike, 2026-09-26: "make sure security is absolutely
+ * rock-solid for the API/MCP."
+ *
+ * THE THREAT MODEL. An AI agent drives this server, and an agent can be steered by text it
+ * reads (a web page, a dealer's PDF, an email): prompt injection. So assume every tool call
+ * may be hostile, and make the worst a hostile call can do small:
+ *   - It can only reach Numikeep, only with the owner's key, and the key can only add coins
+ *     and change the coins it added (numikeep-api enforces that, not this file).
+ *   - It can never send a file off the machine unless that file is a real image, under the
+ *     one folder the owner chose (NUMIKEEP_PHOTO_DIR), after resolving symlinks. So
+ *     "upload ~/.ssh/id_rsa as a photo" fails three ways.
+ *   - The key never leaves for any host but the configured API: fetch refuses redirects,
+ *     and photo bytes go only to the Google Cloud Storage URL the API signed.
+ *   - Nothing it returns contains the key, and errors are reduced to Numikeep's error code.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const MAX_PHOTO_BYTES = 25 * 1024 * 1024;
+const KEY_RE = /^nk(pat|at)_[A-Za-z0-9_-]{20,200}$/;
+
+export function loadConfig(env = process.env) {
+  const key = String(env.NUMIKEEP_KEY ?? '').trim();
+  if (!KEY_RE.test(key)) {
+    throw new Error('Set NUMIKEEP_KEY to a Numikeep connection key (Numikeep → Settings → Connected apps).');
+  }
+  const apiUrl = String(env.NUMIKEEP_API_URL ?? 'https://numikeep-api-824632661809.us-east1.run.app').replace(/\/+$/, '');
+  let u;
+  try { u = new URL(apiUrl); } catch { throw new Error('NUMIKEEP_API_URL is not a valid URL.'); }
+  const loopback = ['127.0.0.1', 'localhost', '[::1]'].includes(u.hostname);
+  if (u.protocol !== 'https:' && !(u.protocol === 'http:' && loopback)) {
+    throw new Error('NUMIKEEP_API_URL must be https (http is allowed only on this machine).');
+  }
+  if (u.username || u.password || u.search || u.hash) throw new Error('NUMIKEEP_API_URL must be a plain origin.');
+  const photoDir = env.NUMIKEEP_PHOTO_DIR ? path.resolve(String(env.NUMIKEEP_PHOTO_DIR)) : null;
+  return { key, apiUrl: u.origin, photoDir };
+}
+
+/** Numikeep's own error code, or a generic one — never a stack, a URL or a header. */
+export class NumikeepError extends Error {
+  constructor(status, code) { super(`Numikeep said ${status} ${code}`); this.status = status; this.code = code; }
+}
+
+export function createClient({ key, apiUrl }, fetchImpl = fetch) {
+  async function call(method, route, body) {
+    const res = await fetchImpl(`${apiUrl}${route}`, {
+      method,
+      headers: { authorization: `Bearer ${key}`, ...(body ? { 'content-type': 'application/json' } : {}) },
+      body: body ? JSON.stringify(body) : undefined,
+      // A redirect would carry the key to wherever it points. Numikeep never redirects API
+      // calls, so any redirect is a fault or an attack: refuse it.
+      redirect: 'error',
+      signal: AbortSignal.timeout(30_000),
+    });
+    let json = null;
+    try { json = await res.json(); } catch { /* not JSON */ }
+    if (!res.ok) throw new NumikeepError(res.status, typeof json?.error === 'string' ? json.error.slice(0, 60) : 'error');
+    return json;
+  }
+  return { call };
+}
+
+/** Only ever PUT photo bytes to the Cloud Storage URL the API just signed. */
+export function assertUploadUrl(uploadUrl) {
+  let u;
+  try { u = new URL(uploadUrl); } catch { throw new Error('Numikeep returned an invalid upload address.'); }
+  if (u.protocol !== 'https:' || u.hostname !== 'storage.googleapis.com') {
+    throw new Error('Numikeep returned an unexpected upload address; refusing to send the photo.');
+  }
+  return u.toString();
+}
+
+const SIGNATURES = [
+  { type: 'image/jpeg', test: (b) => b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff },
+  { type: 'image/png', test: (b) => b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) },
+  { type: 'image/webp', test: (b) => b.subarray(0, 4).toString('latin1') === 'RIFF' && b.subarray(8, 12).toString('latin1') === 'WEBP' },
+  { type: 'image/heic', test: (b) => b.subarray(4, 8).toString('latin1') === 'ftyp' && /^(heic|heix|hevc|mif1|msf1)$/.test(b.subarray(8, 12).toString('latin1')) },
+];
+const EXT = { 'image/jpeg': ['.jpg', '.jpeg'], 'image/png': ['.png'], 'image/webp': ['.webp'], 'image/heic': ['.heic', '.heif'] };
+
+/**
+ * Resolve a photo the agent named, or refuse. The file must be: inside the owner's photo
+ * folder AFTER following symlinks, a regular file, at most 25MB, and an image by its first
+ * bytes AND its extension. Returns { buf, contentType }.
+ */
+export async function readPhoto(photoDir, requested) {
+  if (!photoDir) throw new Error('Photo uploads are off. Set NUMIKEEP_PHOTO_DIR to the folder the agent may upload from.');
+  if (typeof requested !== 'string' || !requested || requested.includes('\0')) throw new Error('Give a photo file name.');
+  const root = await fs.realpath(photoDir);
+  const candidate = path.resolve(root, requested);
+  let real;
+  try { real = await fs.realpath(candidate); } catch { throw new Error('That photo was not found in the photo folder.'); }
+  if (real !== root && !real.startsWith(root + path.sep)) throw new Error('That file is outside the photo folder.');
+  const st = await fs.stat(real);
+  if (!st.isFile()) throw new Error('That is not a file.');
+  if (st.size < 12 || st.size > MAX_PHOTO_BYTES) throw new Error('Photos must be between 12 bytes and 25MB.');
+  const buf = await fs.readFile(real);
+  const sig = SIGNATURES.find((s) => s.test(buf));
+  if (!sig) throw new Error('That file is not a JPEG, PNG, WebP or HEIC image.');
+  if (!EXT[sig.type].includes(path.extname(real).toLowerCase())) throw new Error('The file extension does not match its contents.');
+  return { buf, contentType: sig.type };
+}

package/src/server.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Numikeep MCP server — lets an AI agent add coins to the owner's Numikeep collection.
+ *
+ * Local only (stdio). Configure with:
+ *   NUMIKEEP_KEY         a connection key from Numikeep → Settings → Connected apps (required)
+ *   NUMIKEEP_PHOTO_DIR   the one folder the agent may upload photos from (optional; photos are
+ *                        off without it)
+ *   NUMIKEEP_API_URL     override for testing (https, or http on this machine)
+ *
+ * What an agent can do here is exactly what the key allows: add coins, locations and photos,
+ * and change or remove only what this key added. It can list coins only if the owner ticked
+ * "Also let it see which coins you have" — and even then never where they are kept, what was
+ * paid, notes or photos. See core.mjs for the threat model.
+ */
+import { randomUUID } from 'node:crypto';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { loadConfig, createClient, readPhoto, assertUploadUrl, NumikeepError } from './core.mjs';
+
+const cfg = loadConfig();
+const api = createClient(cfg);
+const server = new McpServer({ name: 'numikeep', version: '0.1.0' });
+
+const text = (t) => ({ content: [{ type: 'text', text: t }] });
+const fail = (e) => ({
+  isError: true,
+  content: [{ type: 'text', text: e instanceof NumikeepError ? `Numikeep refused: ${e.code}` : String(e?.message ?? 'failed').slice(0, 300) }],
+});
+const guard = (fn) => async (args) => { try { return await fn(args); } catch (e) { return fail(e); } };
+
+const GRADERS = ['RAW', 'PCGS', 'NGC', 'CACG', 'ANACS', 'ICG', 'OTHER'];
+const coinShape = {
+  name: z.string().min(1).max(300).describe('What the coin is, e.g. "1893-S Morgan Dollar". Add "(GS 1234)" with the Greysheet id if you know it exactly.'),
+  grader: z.enum(GRADERS).default('RAW').describe('Grading service, or RAW if ungraded'),
+  grade: z.string().max(20).optional().describe('e.g. MS65 — required unless RAW'),
+  graderName: z.string().max(100).optional().describe('Only when grader is OTHER'),
+  cac: z.boolean().optional(),
+  cacTier: z.enum(['green', 'gold']).optional(),
+  cert: z.string().max(40).optional().describe('Certification number'),
+  qty: z.number().int().min(1).max(10000).optional(),
+  color: z.enum(['RD', 'RB', 'BN']).optional().describe('Copper colour, if copper'),
+  acquiredDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+  acquiredPriceCents: z.number().int().min(0).max(1e12).optional().describe('What the owner paid, in cents'),
+  locationId: z.string().uuid().optional().describe('A location this connection created with add_location'),
+  notes: z.string().max(5000).optional(),
+};
+const toBody = (a, id) => ({
+  id, catalogItemId: a.name, grader: a.grader ?? 'RAW',
+  ...(a.grade !== undefined ? { grade: a.grade } : {}),
+  ...(a.graderName !== undefined ? { graderName: a.graderName } : {}),
+  ...(a.cac !== undefined ? { cac: a.cac } : {}),
+  ...(a.cacTier !== undefined ? { cacTier: a.cacTier } : {}),
+  ...(a.cert !== undefined ? { cert: a.cert } : {}),
+  ...(a.qty !== undefined ? { qty: a.qty } : {}),
+  ...(a.color !== undefined ? { color: a.color } : {}),
+  ...(a.acquiredDate !== undefined ? { acquiredDate: a.acquiredDate } : {}),
+  ...(a.acquiredPriceCents !== undefined ? { acquiredPriceCents: a.acquiredPriceCents } : {}),
+  ...(a.locationId !== undefined ? { locationId: a.locationId } : {}),
+  ...(a.notes !== undefined ? { notes: a.notes } : {}),
+});
+
+server.registerTool('numikeep_status', {
+  title: 'Check the Numikeep connection',
+  description: 'Confirms the key works and whether this connection may list coins.',
+  inputSchema: {},
+  annotations: { readOnlyHint: true },
+}, guard(async () => {
+  const v = await api.call('GET', '/v2/collection');
+  return text(`Connected to a Numikeep collection. ${Array.isArray(v.coins) ? 'This connection may list coins.' : 'This connection can add coins but not list them.'} Photo uploads are ${cfg.photoDir ? 'on' : 'off'}.`);
+}));
+
+server.registerTool('add_coin', {
+  title: 'Add a coin',
+  description: 'Adds one coin to the owner\'s Numikeep collection. Returns the new coin id — keep it to update or remove the coin later.',
+  inputSchema: coinShape,
+}, guard(async (a) => {
+  const row = await api.call('POST', '/v2/collection/coins', toBody(a, randomUUID()));
+  return text(`Added "${a.name}" (id ${row.id}).`);
+}));
+
+server.registerTool('update_coin', {
+  title: 'Update a coin this connection added',
+  description: 'Replaces the details of a coin this connection added. Coins the owner entered themselves cannot be changed.',
+  inputSchema: { id: z.string().uuid(), ...coinShape },
+}, guard(async (a) => {
+  const row = await api.call('POST', '/v2/collection/coins', toBody(a, a.id));
+  return text(`Updated "${a.name}" (id ${row.id}).`);
+}));
+
+server.registerTool('remove_coin', {
+  title: 'Remove a coin this connection added',
+  description: 'Removes one coin this connection added. Coins the owner entered themselves cannot be removed.',
+  inputSchema: { id: z.string().uuid() },
+  annotations: { destructiveHint: true },
+}, guard(async ({ id }) => {
+  await api.call('DELETE', `/v2/collection/coins/${id}`);
+  return text(`Removed coin ${id}.`);
+}));
+
+server.registerTool('add_location', {
+  title: 'Add a storage location',
+  description: 'Adds a place coins are kept (e.g. "Home safe") that coins added by this connection can be filed under. Locations are private to the owner and are never shown to dealers or other apps.',
+  inputSchema: {
+    label: z.string().min(1).max(200),
+    kind: z.enum(['home_safe', 'bank_box', 'dealer', 'display', 'other']).default('other'),
+  },
+}, guard(async ({ label, kind }) => {
+  const row = await api.call('POST', '/v2/collection/locations', { id: randomUUID(), label, kind });
+  return text(`Added location "${label}" (id ${row.id}).`);
+}));
+
+server.registerTool('add_photo', {
+  title: 'Add a photo to a coin',
+  description: 'Uploads a JPEG, PNG, WebP or HEIC image from the owner\'s photo folder to a coin this connection added. Only files inside NUMIKEEP_PHOTO_DIR can be sent.',
+  inputSchema: {
+    coinId: z.string().uuid(),
+    file: z.string().min(1).max(500).describe('File name inside the photo folder'),
+    side: z.enum(['obverse', 'reverse', 'slab', 'other']).default('obverse'),
+  },
+}, guard(async ({ coinId, file, side }) => {
+  const { buf, contentType } = await readPhoto(cfg.photoDir, file);
+  const up = await api.call('POST', '/v2/collection/photos', { coinId, side, contentType, contentLength: buf.length });
+  const put = await fetch(assertUploadUrl(up.uploadUrl), {
+    method: 'PUT', headers: up.headers, body: buf, redirect: 'error', signal: AbortSignal.timeout(120_000),
+  });
+  if (!put.ok) throw new Error(`The photo upload was refused (${put.status}).`);
+  return text(`Added the ${side} photo to coin ${coinId}.`);
+}));
+
+server.registerTool('list_coins', {
+  title: 'List the owner\'s coins',
+  description: 'Lists what coins the owner has — only if they allowed this connection to see coins. Never includes where coins are kept, prices paid, notes or photos.',
+  inputSchema: {},
+  annotations: { readOnlyHint: true },
+}, guard(async () => {
+  const v = await api.call('GET', '/v2/collection');
+  if (!Array.isArray(v.coins)) return text('This connection is not allowed to see the collection. The owner can make a new key with "Also let it see which coins you have".');
+  // Returned as data, not instructions: names are owner-typed text.
+  return { content: [{ type: 'text', text: JSON.stringify(v.coins) }] };
+}));
+
+await server.connect(new StdioServerTransport());