@oliverames/ynab-mcp-server 1.7.1 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oliverames/ynab-mcp-server",
-  "version": "1.7.1",
+  "version": "2.1.1",
   "description": "YNAB MCP server with full API coverage",
   "type": "module",
   "main": "index.js",
@@ -8,12 +8,22 @@
     "ynab-mcp-server": "index.js"
   },
   "files": [
-    "index.js"
+    "index.js",
+    "scripts/",
+    "assets/icon.png",
+    "docs/hosted-oauth-connector.md"
   ],
   "scripts": {
     "start": "node index.js",
-    "pretest": "[ -d node_modules ] || npm ci --silent --no-audit --no-fund",
-    "test": "node test.js"
+    "pretest": "node --input-type=module -e \"await import('@modelcontextprotocol/sdk/client/index.js')\" >/dev/null 2>&1 || npm ci --silent --no-audit --no-fund",
+    "test": "node test.js",
+    "smoke:list-tools": "node scripts/smoke-list-tools.mjs",
+    "smoke:review-unapproved": "node scripts/smoke-review-unapproved.mjs",
+    "smoke:batch-verify": "node scripts/smoke-batch-verify.mjs",
+    "release:check": "node scripts/check-release-consistency.mjs",
+    "release:check:registry": "node scripts/check-release-consistency.mjs --registry",
+    "build:mcpb": "node scripts/build-mcpb.mjs",
+    "test:safety": "node scripts/test-safety-model.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/scripts/build-mcpb.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const projectRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, "package.json"), "utf8"));
+const force = process.argv.includes("--force");
+const distDir = path.join(projectRoot, "dist");
+const outputPath = path.join(distDir, `ynab-mcp-server-${pkg.version}.mcpb`);
+
+if (fs.existsSync(outputPath) && !force) {
+  console.error(`Refusing to overwrite existing artifact: ${outputPath}`);
+  console.error("Pass --force to rebuild this generated artifact.");
+  process.exit(1);
+}
+
+const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), "ynab-mcpb-"));
+
+function copyFile(relativePath) {
+  const source = path.join(projectRoot, relativePath);
+  const destination = path.join(stagingDir, relativePath);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(source, destination);
+}
+
+function writeJson(relativePath, value) {
+  const destination = path.join(stagingDir, relativePath);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.writeFileSync(destination, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+const bundlePackage = {
+  name: pkg.name,
+  version: pkg.version,
+  description: pkg.description,
+  type: pkg.type,
+  main: pkg.main,
+  dependencies: pkg.dependencies,
+  engines: pkg.engines,
+};
+
+writeJson("package.json", bundlePackage);
+copyFile("package-lock.json");
+copyFile("index.js");
+copyFile("README.md");
+copyFile("LICENSE");
+copyFile("assets/icon.png");
+
+writeJson("manifest.json", {
+  manifest_version: "0.3",
+  name: "ynab-mcp-server",
+  display_name: "YNAB MCP Server",
+  version: pkg.version,
+  description: "Complete MCP server for YNAB budget operations.",
+  author: {
+    name: "Oliver Ames",
+    url: "https://github.com/oliverames",
+  },
+  repository: {
+    type: "git",
+    url: "https://github.com/oliverames/ynab-mcp-server.git",
+  },
+  homepage: "https://github.com/oliverames/ynab-mcp-server#readme",
+  documentation: "https://github.com/oliverames/ynab-mcp-server#readme",
+  support: "https://github.com/oliverames/ynab-mcp-server/issues",
+  icon: "assets/icon.png",
+  server: {
+    type: "node",
+    entry_point: "index.js",
+    mcp_config: {
+      command: "node",
+      args: ["${__dirname}/index.js"],
+      env: {
+        YNAB_API_TOKEN: "${user_config.ynab_api_token}",
+        YNAB_BUDGET_ID: "${user_config.ynab_budget_id}",
+        YNAB_ALLOW_WRITES: "${user_config.ynab_allow_writes}",
+      },
+    },
+  },
+  tools_generated: true,
+  keywords: ["mcp", "model-context-protocol", "ynab", "budgeting", "personal-finance"],
+  license: "MIT",
+  privacy_policies: ["https://www.ynab.com/privacy-policy"],
+  compatibility: {
+    platforms: ["darwin", "win32", "linux"],
+    runtimes: {
+      node: ">=18.0.0",
+    },
+  },
+  user_config: {
+    ynab_api_token: {
+      type: "string",
+      title: "YNAB API Token",
+      description: "Personal access token from YNAB Developer Settings.",
+      required: true,
+      sensitive: true,
+    },
+    ynab_budget_id: {
+      type: "string",
+      title: "Default Budget ID",
+      description: "Optional default budget ID. Leave blank to use YNAB's last-used budget.",
+      required: false,
+    },
+    ynab_allow_writes: {
+      type: "string",
+      title: "Enable Write Tools",
+      description: "Set to 1 to expose tools that create, update, import, or delete YNAB data. Leave blank or set to 0 for read-only mode.",
+      required: false,
+      default: "0",
+    },
+  },
+});
+
+execFileSync("npm", ["ci", "--omit=dev", "--no-audit", "--no-fund"], {
+  cwd: stagingDir,
+  stdio: "inherit",
+});
+
+fs.mkdirSync(distDir, { recursive: true });
+if (force) {
+  fs.rmSync(outputPath, { force: true });
+}
+execFileSync("zip", ["-qr", outputPath, "."], {
+  cwd: stagingDir,
+  stdio: "inherit",
+});
+
+const size = fs.statSync(outputPath).size;
+console.log(`Built ${outputPath} (${size} bytes)`);

package/scripts/check-release-consistency.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const projectRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const checkRegistry = process.argv.includes("--registry");
+
+function readJson(relativePath) {
+  return JSON.parse(fs.readFileSync(path.join(projectRoot, relativePath), "utf8"));
+}
+
+function readText(relativePath) {
+  return fs.readFileSync(path.join(projectRoot, relativePath), "utf8");
+}
+
+const errors = [];
+const checks = [];
+
+function pass(message) {
+  checks.push(message);
+}
+
+function assert(condition, message) {
+  if (condition) {
+    pass(message);
+  } else {
+    errors.push(message);
+  }
+}
+
+const pkg = readJson("package.json");
+const lock = readJson("package-lock.json");
+const indexJs = readText("index.js");
+const readme = readText("README.md");
+const version = pkg.version;
+
+assert(lock.version === version, `package-lock root version matches ${version}`);
+assert(lock.packages?.[""]?.version === version, `package-lock package version matches ${version}`);
+assert(indexJs.includes(`version: "${version}"`), `index.js McpServer version matches ${version}`);
+
+const registeredToolNames = [...indexJs.matchAll(/^\s*registerTool\(\s*\n\s*"([^"]+)"/gm)]
+  .map((match) => match[1]);
+const registeredToolCount = registeredToolNames
+  .filter((name) => !name.startsWith("ynab_"))
+  .length;
+const discoveryHelpers = ["ynab_auth_status", "ynab_tool_index", "ynab_tool_execute", "ynab_write_tool_execute"];
+for (const helperName of discoveryHelpers) {
+  assert(registeredToolNames.includes(helperName), `discovery helper ${helperName} is registered`);
+}
+const readmeToolCounts = [...new Set(
+  [...readme.matchAll(/\b(\d+) tools\b/gi)].map((match) => Number(match[1]))
+)];
+assert(
+  readmeToolCounts.length > 0 && readmeToolCounts.every((count) => count === registeredToolCount),
+  readmeToolCounts.length > 0
+    ? `README tool count references match ${registeredToolCount}`
+    : "README includes at least one tool count reference"
+);
+
+const releaseVersions = [
+  ...readme.matchAll(/github\.com\/oliverames\/ynab-mcp-server\/releases\/(?:tag|download)\/v(\d+\.\d+\.\d+)/g),
+].map((match) => match[1]);
+const staleReleaseVersions = [...new Set(releaseVersions.filter((releaseVersion) => releaseVersion !== version))];
+assert(
+  staleReleaseVersions.length === 0,
+  staleReleaseVersions.length === 0
+    ? `README release links match v${version}`
+    : `README has stale release link versions: ${staleReleaseVersions.join(", ")}`
+);
+
+const mcpbVersions = [...readme.matchAll(/ynab-mcp-server-(\d+\.\d+\.\d+)\.mcpb/g)].map((match) => match[1]);
+const staleMcpbVersions = [...new Set(mcpbVersions.filter((mcpbVersion) => mcpbVersion !== version))];
+assert(
+  staleMcpbVersions.length === 0 && mcpbVersions.length > 0,
+  staleMcpbVersions.length === 0
+    ? `README MCPB artifact references match ${version}`
+    : `README has stale MCPB artifact versions: ${staleMcpbVersions.join(", ")}`
+);
+
+if (checkRegistry) {
+  const npmVersion = execFileSync("npm", ["view", pkg.name, "version"], {
+    cwd: projectRoot,
+    encoding: "utf8",
+  }).trim();
+  assert(npmVersion === version, `npm latest matches ${version}`);
+}
+
+if (errors.length > 0) {
+  for (const message of errors) {
+    console.error(`FAIL: ${message}`);
+  }
+  process.exit(1);
+}
+
+for (const message of checks) {
+  console.log(`PASS: ${message}`);
+}

package/scripts/lib/smoke-client.mjs

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const scriptsDir = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+export const projectRoot = path.dirname(scriptsDir);
+export const packageJson = JSON.parse(fs.readFileSync(path.join(projectRoot, "package.json"), "utf8"));
+
+function envWithStringsOnly(source) {
+  return Object.fromEntries(
+    Object.entries(source).filter(([, value]) => typeof value === "string")
+  );
+}
+
+function readArg(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function usage() {
+  return [
+    "Usage: npm run smoke:list-tools -- [--published | --package <pkg> | --server-command <command>]",
+    "       npm run smoke:review-unapproved -- [--published | --package <pkg> | --server-command <command>]",
+    "       YNAB_ALLOW_WRITES=1 npm run smoke:batch-verify -- [--published | --package <pkg> | --server-command <command>]",
+    "",
+    "Defaults to the local checkout entrypoint: node index.js",
+    "Use --published to test npx -y @oliverames/ynab-mcp-server@latest from /tmp.",
+  ].join("\n");
+}
+
+export function parseSmokeOptions(args = process.argv.slice(2)) {
+  const options = {
+    mode: "local",
+    packageSpec: `${packageJson.name}@latest`,
+    serverCommand: null,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      console.log(usage());
+      process.exit(0);
+    }
+    if (arg === "--published") {
+      options.mode = "published";
+      continue;
+    }
+    if (arg === "--package") {
+      options.mode = "published";
+      options.packageSpec = readArg(args, i, arg);
+      i += 1;
+      continue;
+    }
+    if (arg === "--server-command") {
+      options.mode = "custom";
+      options.serverCommand = readArg(args, i, arg);
+      i += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}\n\n${usage()}`);
+  }
+
+  return options;
+}
+
+export function serverParamsForOptions(options) {
+  if (options.mode === "published") {
+    return {
+      label: `npx -y ${options.packageSpec}`,
+      command: "npx",
+      args: ["-y", options.packageSpec],
+      cwd: "/tmp",
+    };
+  }
+
+  if (options.mode === "custom") {
+    return {
+      label: options.serverCommand,
+      command: "bash",
+      args: ["-lc", options.serverCommand],
+      cwd: projectRoot,
+    };
+  }
+
+  return {
+    label: "node index.js",
+    command: "node",
+    args: ["index.js"],
+    cwd: projectRoot,
+  };
+}
+
+export async function withSmokeClient(options, callback) {
+  const params = serverParamsForOptions(options);
+  const transport = new StdioClientTransport({
+    command: params.command,
+    args: params.args,
+    cwd: params.cwd,
+    env: envWithStringsOnly(process.env),
+    stderr: "pipe",
+  });
+
+  const stderrChunks = [];
+  transport.stderr?.on("data", (chunk) => stderrChunks.push(chunk.toString()));
+
+  const client = new Client({ name: "ynab-mcp-smoke", version: packageJson.version });
+  try {
+    await client.connect(transport);
+    return await callback(client, params);
+  } catch (error) {
+    const stderr = stderrChunks.join("").trim();
+    if (stderr) {
+      console.error("\nServer stderr:");
+      console.error(stderr);
+    }
+    throw error;
+  } finally {
+    await client.close().catch(() => {});
+  }
+}
+
+export function parseTextToolResult(result) {
+  const textItem = result.content?.find((item) => item.type === "text" && item.text);
+  if (!textItem) {
+    throw new Error("Tool result did not include text content");
+  }
+  return JSON.parse(textItem.text);
+}

package/scripts/smoke-batch-verify.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+import { parseSmokeOptions, parseTextToolResult, withSmokeClient } from "./lib/smoke-client.mjs";
+
+const options = parseSmokeOptions();
+
+if (process.env.YNAB_ALLOW_WRITES !== "1") {
+  throw new Error("smoke:batch-verify creates, updates, and deletes a transaction. Re-run with YNAB_ALLOW_WRITES=1.");
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+async function call(client, name, args = {}) {
+  const result = await client.callTool({ name, arguments: args });
+  if (result.isError) {
+    throw new Error(result.content?.[0]?.text || `${name} returned an MCP error`);
+  }
+  return parseTextToolResult(result);
+}
+
+await withSmokeClient(options, async (client, params) => {
+  let transactionId;
+
+  try {
+    const review = await call(client, "review_unapproved", { summary: true });
+
+    const accounts = await call(client, "list_accounts");
+    const account = accounts.find((item) => !item.closed && !item.deleted);
+    if (!account) throw new Error("No active account found for smoke transaction");
+
+    const categoryGroups = await call(client, "list_categories");
+    const category = categoryGroups
+      .filter((group) => !group.hidden && !group.deleted && group.name !== "Internal Master Category")
+      .flatMap((group) => group.categories)
+      .find((item) => !item.hidden && !item.deleted);
+    if (!category) throw new Error("No active category found for smoke transaction");
+
+    const created = await call(client, "create_transaction", {
+      accountId: account.id,
+      date: today(),
+      amount: -4.56,
+      payeeName: "MCP Batch Verify Smoke",
+      memo: "MCP smoke test - safe to delete",
+      approved: false,
+    });
+    transactionId = created.id;
+
+    const updated = await call(client, "update_transactions", {
+      transactions: [{
+        id: transactionId,
+        categoryId: category.id,
+        approved: true,
+      }],
+    });
+
+    if (updated.verification?.checked !== 1) {
+      throw new Error(`Expected one verified update, got ${updated.verification?.checked}`);
+    }
+    if (updated.verification.failed?.length) {
+      throw new Error(`Verification failed: ${JSON.stringify(updated.verification.failed)}`);
+    }
+
+    const refetched = await call(client, "get_transaction", { transactionId });
+    if (refetched.approved !== true) throw new Error("Approval did not persist");
+    if (refetched.category_id !== category.id) {
+      throw new Error(`Category did not persist: ${refetched.category_id}`);
+    }
+
+    console.log(`Connected to ${params.label}`);
+    console.log(`review_unapproved summary total: ${review.total}`);
+    console.log("Batch category+approval update verified by post-write refetch");
+    console.log(`Verification checked: ${updated.verification.checked}`);
+    console.log(`Verification retried: ${updated.verification.retried.length}`);
+  } finally {
+    if (transactionId) {
+      await call(client, "delete_transaction", { transactionId });
+    }
+  }
+});

package/scripts/smoke-list-tools.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { parseSmokeOptions, withSmokeClient } from "./lib/smoke-client.mjs";
+
+const requiredTools = [
+  "review_unapproved",
+  "get_transactions",
+  "search_categories",
+  "search_payees",
+  "ynab_auth_status",
+  "ynab_tool_index",
+  "ynab_tool_execute",
+];
+
+const options = parseSmokeOptions();
+const requiredWriteTools = process.env.YNAB_ALLOW_WRITES === "1"
+  ? ["update_transactions", "approve_transactions", "ynab_write_tool_execute"]
+  : [];
+
+await withSmokeClient(options, async (client, params) => {
+  const result = await client.listTools();
+  const toolNames = result.tools.map((tool) => tool.name).sort();
+  const expectedTools = [...requiredTools, ...requiredWriteTools];
+  const missing = expectedTools.filter((name) => !toolNames.includes(name));
+
+  if (missing.length > 0) {
+    throw new Error(`Missing expected YNAB tools: ${missing.join(", ")}`);
+  }
+
+  console.log(`Connected to ${params.label}`);
+  console.log(`Listed ${toolNames.length} tools`);
+  console.log(`Required tools present: ${expectedTools.join(", ")}`);
+});

package/scripts/smoke-review-unapproved.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import { parseSmokeOptions, parseTextToolResult, withSmokeClient } from "./lib/smoke-client.mjs";
+
+const options = parseSmokeOptions();
+
+await withSmokeClient(options, async (client, params) => {
+  const result = await client.callTool({
+    name: "review_unapproved",
+    arguments: { summary: true },
+  });
+
+  if (result.isError) {
+    throw new Error(result.content?.[0]?.text || "review_unapproved returned an MCP error");
+  }
+
+  const payload = parseTextToolResult(result);
+  if (typeof payload.total !== "number") {
+    throw new Error("review_unapproved summary did not include a numeric total");
+  }
+
+  console.log(`Connected to ${params.label}`);
+  console.log("Called review_unapproved with summary: true");
+  console.log(`Total unapproved: ${payload.total}`);
+  console.log(`Ready to approve: ${payload.ready_to_approve?.count ?? 0}`);
+  console.log(`Needs category first: ${payload.needs_category_first?.count ?? 0}`);
+});

package/scripts/test-safety-model.mjs

@@ -0,0 +1,140 @@
+import assert from "node:assert/strict";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const projectRoot = path.resolve(path.dirname(__filename), "..");
+
+const writeTools = [
+  "create_account",
+  "update_month_category",
+  "update_category",
+  "create_category",
+  "create_category_group",
+  "update_category_group",
+  "update_payee",
+  "create_payee",
+  "create_transaction",
+  "create_transactions",
+  "update_transaction",
+  "delete_transaction",
+  "update_transactions",
+  "approve_transactions",
+  "reassign_payee_transactions",
+  "import_transactions",
+  "create_scheduled_transaction",
+  "update_scheduled_transaction",
+  "delete_scheduled_transaction",
+  "ynab_write_tool_execute",
+];
+
+const requiredReadTools = [
+  "get_user",
+  "list_budgets",
+  "get_budget",
+  "list_accounts",
+  "get_transactions",
+  "review_unapproved",
+  "search_categories",
+  "search_payees",
+];
+
+function buildEnv(overrides = {}) {
+  const env = Object.fromEntries(
+    Object.entries(process.env).filter(([, value]) => typeof value === "string"),
+  );
+  env.YNAB_API_TOKEN = "test-token-for-list-tools";
+  env.YNAB_RATE_LIMIT_PER_HOUR = "0";
+
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) {
+      delete env[key];
+    } else {
+      env[key] = value;
+    }
+  }
+
+  return env;
+}
+
+async function listTools(overrides = {}) {
+  const client = new Client({
+    name: "ynab-safety-model-test",
+    version: "1.0.0",
+  });
+
+  const transport = new StdioClientTransport({
+    command: "node",
+    args: ["index.js"],
+    cwd: projectRoot,
+    env: buildEnv(overrides),
+    stderr: "pipe",
+  });
+
+  try {
+    await client.connect(transport);
+    const response = await client.listTools();
+    return response.tools;
+  } finally {
+    await client.close();
+  }
+}
+
+const readOnlyTools = await listTools({ YNAB_ALLOW_WRITES: undefined });
+const readOnlyNames = new Set(readOnlyTools.map((tool) => tool.name));
+
+const discoveryOnlyTools = await listTools({
+  YNAB_API_TOKEN: undefined,
+  YNAB_API_TOKEN_FILE: undefined,
+  YNAB_OP_PATH: undefined,
+  YNAB_ALLOW_WRITES: undefined,
+});
+const discoveryOnlyNames = new Set(discoveryOnlyTools.map((tool) => tool.name));
+
+for (const name of requiredReadTools) {
+  assert.ok(readOnlyNames.has(name), `expected read tool ${name} to be available by default`);
+  assert.ok(discoveryOnlyNames.has(name), `expected read tool ${name} to be discoverable without auth`);
+}
+
+for (const name of writeTools) {
+  assert.ok(!readOnlyNames.has(name), `expected write tool ${name} to be hidden by default`);
+}
+
+for (const tool of readOnlyTools) {
+  assert.equal(
+    tool.annotations?.readOnlyHint,
+    true,
+    `expected ${tool.name} to be annotated read-only`,
+  );
+}
+
+const writableTools = await listTools({ YNAB_ALLOW_WRITES: "1" });
+const writableNames = new Set(writableTools.map((tool) => tool.name));
+
+for (const name of writeTools) {
+  assert.ok(writableNames.has(name), `expected write tool ${name} when writes are enabled`);
+}
+
+for (const tool of writableTools.filter((tool) => writeTools.includes(tool.name))) {
+  assert.equal(
+    tool.annotations?.readOnlyHint,
+    false,
+    `expected ${tool.name} to be annotated writable`,
+  );
+}
+
+const destructiveTools = new Map(writableTools.map((tool) => [tool.name, tool]));
+assert.equal(
+  destructiveTools.get("delete_transaction")?.annotations?.destructiveHint,
+  true,
+  "expected delete_transaction to be annotated destructive",
+);
+assert.equal(
+  destructiveTools.get("delete_scheduled_transaction")?.annotations?.destructiveHint,
+  true,
+  "expected delete_scheduled_transaction to be annotated destructive",
+);
+
+console.log("Safety model checks passed");