@oliverames/mcp-server-for-wave 1.0.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@oliverames/mcp-server-for-wave",
+  "version": "1.0.0",
+  "description": "Local MCP server for Wave Accounting: invoices, estimates, customers, products, taxes, and bookkeeping",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oliverames/wave-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/oliverames/wave-mcp-server/issues"
+  },
+  "homepage": "https://github.com/oliverames/wave-mcp-server#readme",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "wave",
+    "waveapps",
+    "accounting",
+    "invoicing",
+    "bookkeeping",
+    "small-business"
+  ],
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "mcp-server-for-wave": "index.js",
+    "wave-mcp-server": "index.js"
+  },
+  "files": [
+    "index.js",
+    "scripts/",
+    "assets/icon.png",
+    "docs/hosted-oauth-connector.md",
+    "docs/privacy.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "deps:ensure": "node --input-type=module -e \"await import('@modelcontextprotocol/sdk/server/mcp.js')\" >/dev/null 2>&1 || npm ci --silent --no-audit --no-fund",
+    "pretest": "npm run deps:ensure",
+    "test": "node --test test/unit.test.mjs",
+    "presmoke:list-tools": "npm run deps:ensure",
+    "smoke:list-tools": "node scripts/smoke-list-tools.mjs",
+    "presmoke:schema": "npm run deps:ensure",
+    "smoke:schema": "node scripts/smoke-validate-graphql.mjs",
+    "presmoke:packed": "npm run deps:ensure",
+    "smoke:packed": "node scripts/smoke-packed-install.mjs",
+    "sync:plugin": "node scripts/sync-plugin-metadata.mjs",
+    "version": "npm run sync:plugin && git add .agents/plugins/marketplace.json .claude-plugin/marketplace.json .claude-plugin/plugin.json codex/.codex-plugin/plugin.json codex/.codex-plugin/mcp.json .hermes-plugin/marketplace.json .hermes-plugin/plugin.json .hermes-plugin/mcp.json .antigravity-plugin/marketplace.json .antigravity-plugin/plugin.json .antigravity-plugin/mcp_config.json .mcp.json",
+    "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"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  }
+}

package/scripts/build-mcpb.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+/**
+ * Build an MCPB bundle: a single .mcpb file a desktop MCP host can install
+ * without npm or a terminal.
+ *
+ * The bundle is a zip carrying a manifest, the server, and its production
+ * dependencies. User configuration (the Wave token, the default business,
+ * the write opt-in) is declared in the manifest so the host can prompt for it
+ * and inject the values at launch, which keeps credentials out of the bundle.
+ */
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const projectRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const distDir = path.join(projectRoot, "dist");
+const stageDir = path.join(distDir, "mcpb-stage");
+
+const packageJson = JSON.parse(fs.readFileSync(path.join(projectRoot, "package.json"), "utf8"));
+const { version } = packageJson;
+const outputPath = path.join(distDir, `wave-mcp-server-${version}.mcpb`);
+
+const manifest = {
+  manifest_version: "0.2",
+  name: "wave-mcp-server",
+  display_name: "Wave",
+  version,
+  description: packageJson.description,
+  long_description:
+    "Covers Wave Accounting's public GraphQL API in full: invoices and payments, estimates and deposits, " +
+    "customers, vendors, products, sales taxes, the chart of accounts, and double-entry bookkeeping " +
+    "transactions. Tools that change or send data stay hidden until you enable them.",
+  author: { name: "Oliver Ames", email: "oliverames@gmail.com", url: "https://github.com/oliverames" },
+  homepage: "https://github.com/oliverames/wave-mcp-server#readme",
+  documentation: "https://github.com/oliverames/wave-mcp-server#readme",
+  support: "https://github.com/oliverames/wave-mcp-server/issues",
+  icon: "icon.png",
+  license: "MIT",
+  keywords: packageJson.keywords,
+  server: {
+    type: "node",
+    entry_point: "index.js",
+    mcp_config: {
+      command: "node",
+      args: ["${__dirname}/index.js"],
+      env: {
+        WAVE_ACCESS_TOKEN: "${user_config.access_token}",
+        WAVE_BUSINESS_ID: "${user_config.business_id}",
+        WAVE_ALLOW_WRITES: "${user_config.allow_writes}",
+        // A bundle has no agent config file to read; the host injects values.
+        WAVE_DISABLE_AGENT_CONFIG_FALLBACK: "1",
+      },
+    },
+  },
+  user_config: {
+    access_token: {
+      type: "string",
+      title: "Wave access token",
+      description: "OAuth2 access token from https://developer.waveapps.com/",
+      sensitive: true,
+      required: true,
+    },
+    business_id: {
+      type: "string",
+      title: "Default business ID",
+      description: "Optional. Lets tools omit business_id. Find it with wave_list_businesses.",
+      required: false,
+    },
+    allow_writes: {
+      type: "string",
+      title: "Enable write tools",
+      description:
+        'Set to 1 to enable tools that create, change, delete, or email records. Left empty, the server is read-only.',
+      required: false,
+      default: "",
+    },
+  },
+  compatibility: {
+    claude_desktop: ">=0.10.0",
+    platforms: ["darwin", "win32", "linux"],
+    runtimes: { node: ">=18.0.0" },
+  },
+};
+
+function run(command, args, options = {}) {
+  execFileSync(command, args, { stdio: "inherit", ...options });
+}
+
+fs.rmSync(stageDir, { recursive: true, force: true });
+fs.mkdirSync(stageDir, { recursive: true });
+
+fs.writeFileSync(path.join(stageDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+fs.copyFileSync(path.join(projectRoot, "index.js"), path.join(stageDir, "index.js"));
+fs.copyFileSync(path.join(projectRoot, "package.json"), path.join(stageDir, "package.json"));
+fs.copyFileSync(path.join(projectRoot, "package-lock.json"), path.join(stageDir, "package-lock.json"));
+fs.copyFileSync(path.join(projectRoot, "assets", "icon.png"), path.join(stageDir, "icon.png"));
+fs.copyFileSync(path.join(projectRoot, "LICENSE"), path.join(stageDir, "LICENSE"));
+fs.copyFileSync(path.join(projectRoot, "README.md"), path.join(stageDir, "README.md"));
+
+// Production dependencies only: a bundle ships what it needs to run, and dev
+// tooling would multiply its size for no benefit.
+console.log("Installing production dependencies into the bundle...");
+run("npm", ["ci", "--omit=dev", "--no-audit", "--no-fund"], { cwd: stageDir });
+
+fs.rmSync(outputPath, { force: true });
+console.log(`Packing ${path.relative(projectRoot, outputPath)}...`);
+run("zip", ["-qr", outputPath, "."], { cwd: stageDir });
+
+fs.rmSync(stageDir, { recursive: true, force: true });
+
+const sizeMb = (fs.statSync(outputPath).size / 1024 / 1024).toFixed(2);
+console.log(`Built ${path.relative(projectRoot, outputPath)} (${sizeMb} MB)`);
+
+if (!fs.existsSync(outputPath)) {
+  console.error("Bundle was not produced.");
+  process.exit(1);
+}

package/scripts/check-release-consistency.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+/**
+ * Fail the build when anything about a release disagrees with package.json.
+ *
+ * Version strings live in eight files across five hosts plus the server
+ * handshake. Catching drift here is cheaper than shipping a plugin manifest
+ * that advertises a version npm never published.
+ *
+ * Pass --registry to additionally check whether this version is already on
+ * npm, which prevents a duplicate publish.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+
+const projectRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const packageJson = readJson("package.json");
+const { version, name: packageName } = packageJson;
+const pluginName = "wave-mcp-server";
+
+const problems = [];
+
+// 1. Plugin manifests carry the package version.
+for (const manifestPath of [
+  ".claude-plugin/plugin.json",
+  "codex/.codex-plugin/plugin.json",
+  ".hermes-plugin/plugin.json",
+  ".antigravity-plugin/plugin.json",
+]) {
+  const manifest = readJson(manifestPath);
+  if (manifest.version !== version) {
+    problems.push(`${manifestPath}: version ${manifest.version} != package.json ${version}`);
+  }
+}
+
+// 2. Marketplace entries carry the package version.
+for (const marketplacePath of [
+  ".claude-plugin/marketplace.json",
+  ".agents/plugins/marketplace.json",
+  ".hermes-plugin/marketplace.json",
+  ".antigravity-plugin/marketplace.json",
+]) {
+  const marketplace = readJson(marketplacePath);
+  const plugin = (marketplace.plugins ?? []).find((p) => p.name === pluginName);
+  if (!plugin) {
+    problems.push(`${marketplacePath}: no plugin entry named ${pluginName}`);
+  } else if (plugin.version !== version) {
+    problems.push(`${marketplacePath}: plugin version ${plugin.version} != package.json ${version}`);
+  }
+}
+
+// 3. MCP configs install the right package.
+for (const mcpConfigPath of [
+  ".mcp.json",
+  "codex/.codex-plugin/mcp.json",
+  ".hermes-plugin/mcp.json",
+  ".antigravity-plugin/mcp_config.json",
+]) {
+  const config = readJson(mcpConfigPath);
+  const server = config.mcpServers?.[pluginName] ?? config[pluginName];
+  if (!server) {
+    problems.push(`${mcpConfigPath}: no server entry named ${pluginName}`);
+    continue;
+  }
+  const target = (server.args ?? []).find((arg) => typeof arg === "string" && arg.startsWith("@oliverames/"));
+  if (target !== `${packageName}@latest`) {
+    problems.push(`${mcpConfigPath}: installs ${target}, expected ${packageName}@latest`);
+  }
+}
+
+// 4. The handshake version matches the package.
+const source = fs.readFileSync(path.join(projectRoot, "index.js"), "utf8");
+const declared = source.match(/const SERVER_VERSION = "([^"]*)";/)?.[1];
+if (declared !== version) {
+  problems.push(`index.js: SERVER_VERSION ${declared} != package.json ${version}`);
+}
+
+// 5. Files listed for publish actually exist.
+for (const entry of packageJson.files ?? []) {
+  const target = path.join(projectRoot, entry.replace(/\/$/, ""));
+  if (!fs.existsSync(target)) {
+    problems.push(`package.json files: "${entry}" does not exist`);
+  }
+}
+
+if (problems.length) {
+  console.error("Release consistency check failed:\n");
+  for (const problem of problems) console.error(`  - ${problem}`);
+  console.error("\nRun `npm run sync:plugin` to propagate the version, then re-check.");
+  process.exit(1);
+}
+
+console.log(`Release consistency OK for ${packageName}@${version}.`);
+
+if (process.argv.includes("--registry")) {
+  await checkRegistry();
+}
+
+async function checkRegistry() {
+  const url = `https://registry.npmjs.org/${packageName.replace("/", "%2F")}`;
+  let published;
+  try {
+    const response = await fetch(url);
+    if (response.status === 404) {
+      console.log(`${packageName} is not on npm yet; ${version} would be the first publish.`);
+      return;
+    }
+    published = await response.json();
+  } catch (error) {
+    console.error(`Could not reach the npm registry: ${error.message}`);
+    process.exit(1);
+  }
+
+  const versions = Object.keys(published.versions ?? {});
+  if (versions.includes(version)) {
+    console.error(`${packageName}@${version} is already published. Bump the version before releasing.`);
+    process.exit(1);
+  }
+  console.log(`${packageName}@${version} is not yet published (latest is ${published["dist-tags"]?.latest ?? "none"}).`);
+}
+
+function readJson(relativePath) {
+  return JSON.parse(fs.readFileSync(path.join(projectRoot, relativePath), "utf8"));
+}

package/scripts/smoke-list-tools.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+/**
+ * Launch the server over stdio exactly as an MCP client would, and report what
+ * it advertises.
+ *
+ * This is the check that "the module imports" cannot make: it proves the
+ * process starts, speaks JSON-RPC on stdout, and enumerates its tools and
+ * resources. It needs no Wave credentials.
+ */
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const projectRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const entryPoint = path.join(projectRoot, "index.js");
+
+// Codex CLI kills a server that has not completed initialize in this long.
+const CODEX_STARTUP_BUDGET_MS = 10000;
+
+async function probe({ allowWrites }) {
+  const child = spawn(process.execPath, [entryPoint], {
+    cwd: projectRoot,
+    stdio: ["pipe", "pipe", "ignore"],
+    env: {
+      ...process.env,
+      WAVE_ACCESS_TOKEN: process.env.WAVE_ACCESS_TOKEN || "smoke-test-token",
+      WAVE_ALLOW_WRITES: allowWrites ? "1" : "",
+      // Read only what this probe sets, not the developer's real agent config.
+      WAVE_DISABLE_AGENT_CONFIG_FALLBACK: "1",
+    },
+  });
+
+  let buffer = "";
+  const pending = new Map();
+
+  child.stdout.on("data", (chunk) => {
+    buffer += chunk;
+    let newline;
+    while ((newline = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      const message = JSON.parse(line);
+      const resolve = pending.get(message.id);
+      if (resolve) {
+        pending.delete(message.id);
+        resolve(message);
+      }
+    }
+  });
+
+  const send = (id, method, params = {}) =>
+    new Promise((resolve, reject) => {
+      pending.set(id, resolve);
+      child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+      setTimeout(() => reject(new Error(`${method} timed out`)), CODEX_STARTUP_BUDGET_MS);
+    });
+
+  const started = Date.now();
+  const init = await send(1, "initialize", {
+    protocolVersion: "2025-06-18",
+    capabilities: {},
+    clientInfo: { name: "smoke-list-tools", version: "1" },
+  });
+  const startupMs = Date.now() - started;
+
+  child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}\n`);
+  const tools = (await send(2, "tools/list")).result.tools;
+  const resources = (await send(3, "resources/list")).result.resources;
+
+  child.stdin.end();
+  child.kill();
+
+  return { init: init.result, tools, resources, startupMs };
+}
+
+const readOnly = await probe({ allowWrites: false });
+const readWrite = await probe({ allowWrites: true });
+
+console.log(`server:       ${readOnly.init.serverInfo.name} v${readOnly.init.serverInfo.version}`);
+console.log(`instructions: ${readOnly.init.instructions ? "present" : "MISSING"}`);
+console.log(`startup:      ${readOnly.startupMs}ms (Codex allows ${CODEX_STARTUP_BUDGET_MS}ms)`);
+console.log(`resources:    ${readOnly.resources.length}`);
+console.log(`tools:        ${readOnly.tools.length} read-only, ${readWrite.tools.length} with WAVE_ALLOW_WRITES=1`);
+
+const problems = [];
+if (!readOnly.init.instructions) problems.push("initialize returned no instructions field (Codex reads it)");
+if (readOnly.startupMs > CODEX_STARTUP_BUDGET_MS) problems.push(`startup ${readOnly.startupMs}ms exceeds Codex's budget`);
+if (readWrite.tools.length <= readOnly.tools.length) problems.push("WAVE_ALLOW_WRITES did not register any extra tools");
+
+// Nothing that changes or sends data may appear without the opt-in.
+const readOnlyNames = new Set(readOnly.tools.map((t) => t.name));
+for (const gated of ["wave_delete_invoice", "wave_send_invoice", "wave_delete_customer", "wave_create_invoice"]) {
+  if (readOnlyNames.has(gated)) problems.push(`${gated} is registered without WAVE_ALLOW_WRITES`);
+}
+
+for (const tool of readWrite.tools) {
+  if (!tool.name.startsWith("wave_")) problems.push(`${tool.name} lacks the wave_ prefix`);
+  if (!tool.description) problems.push(`${tool.name} has no description`);
+  if (!tool.annotations?.title) problems.push(`${tool.name} has no annotation title`);
+}
+
+if (problems.length) {
+  console.error("\nProblems:");
+  for (const problem of problems) console.error(`  - ${problem}`);
+  process.exit(1);
+}
+
+console.log("\nAll checks passed.");

package/scripts/smoke-packed-install.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+/**
+ * Pack the package, install it, and start it through its bin symlink.
+ *
+ * This exists because of a bug that every other check missed. npm installs the
+ * bin as a *relative symlink* (`node_modules/.bin/mcp-server-for-wave`), so
+ * `process.argv[1]` is neither absolute nor the real file. An autostart guard
+ * comparing `import.meta.url` to a raw argv[1] therefore never matched, and
+ * the server silently did nothing under `npx` -- the way essentially every
+ * user launches it. Running `node index.js` directly, as the other smoke test
+ * does, works fine and hides it completely.
+ *
+ * So: exercise the artifact the way a user gets it, not the way a developer
+ * runs it.
+ */
+
+import { execFileSync } from "node:child_process";
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const projectRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const workDir = fs.mkdtempSync(path.join(os.tmpdir(), "wave-mcp-packed-"));
+const STARTUP_BUDGET_MS = 15000;
+
+function run(command, args, options = {}) {
+  return execFileSync(command, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...options });
+}
+
+let failed = false;
+
+try {
+  console.log(`Packing into ${workDir} ...`);
+  const packOutput = run("npm", ["pack", "--silent", "--pack-destination", workDir], { cwd: projectRoot });
+  const tarball = path.join(workDir, packOutput.trim().split("\n").pop().trim());
+  if (!fs.existsSync(tarball)) throw new Error(`npm pack did not produce ${tarball}`);
+  console.log(`Packed ${path.basename(tarball)}`);
+
+  fs.writeFileSync(path.join(workDir, "package.json"), JSON.stringify({ name: "packed-smoke", private: true }, null, 2));
+  console.log("Installing the tarball ...");
+  run("npm", ["install", "--silent", "--no-audit", "--no-fund", tarball], { cwd: workDir });
+
+  // Both bin names the package declares must work.
+  for (const binName of ["mcp-server-for-wave", "wave-mcp-server"]) {
+    const binPath = path.join(workDir, "node_modules", ".bin", binName);
+    if (!fs.existsSync(binPath)) throw new Error(`bin ${binName} was not installed`);
+    const stat = fs.lstatSync(binPath);
+    console.log(`\n${binName}: ${stat.isSymbolicLink() ? "symlink" : "file"}`);
+    await probeBin(workDir, binName);
+  }
+
+  console.log("\nPacked install starts and responds over stdio.");
+} catch (error) {
+  console.error(`\nFAILED: ${error.message}`);
+  failed = true;
+} finally {
+  fs.rmSync(workDir, { recursive: true, force: true });
+}
+
+process.exit(failed ? 1 : 0);
+
+/** Launch the installed bin the way a client would, and complete a handshake. */
+async function probeBin(cwd, binName) {
+  // Deliberately relative, matching how npm and npx invoke it.
+  const relativeBin = path.join("node_modules", ".bin", binName);
+
+  const child = spawn(process.execPath, [relativeBin], {
+    cwd,
+    stdio: ["pipe", "pipe", "pipe"],
+    env: {
+      ...process.env,
+      WAVE_ACCESS_TOKEN: "packed-smoke-token",
+      WAVE_DISABLE_AGENT_CONFIG_FALLBACK: "1",
+      WAVE_ALLOW_WRITES: "1",
+      // Must NOT be set: this test is precisely about autostart working.
+      WAVE_MCP_NO_AUTOSTART: "",
+    },
+  });
+
+  let stderr = "";
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk;
+  });
+
+  let buffer = "";
+  const pending = new Map();
+  child.stdout.on("data", (chunk) => {
+    buffer += chunk;
+    let newline;
+    while ((newline = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      const message = JSON.parse(line);
+      const resolve = pending.get(message.id);
+      if (resolve) {
+        pending.delete(message.id);
+        resolve(message);
+      }
+    }
+  });
+
+  const send = (id, method, params = {}) =>
+    new Promise((resolve, reject) => {
+      pending.set(id, resolve);
+      child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+      setTimeout(
+        () =>
+          reject(
+            new Error(
+              `${binName}: ${method} produced no response within ${STARTUP_BUDGET_MS}ms. ` +
+                `The bin likely did not autostart. stderr: ${stderr.trim() || "(empty)"}`
+            )
+          ),
+        STARTUP_BUDGET_MS
+      );
+    });
+
+  try {
+    const init = await send(1, "initialize", {
+      protocolVersion: "2025-06-18",
+      capabilities: {},
+      clientInfo: { name: "packed-smoke", version: "1" },
+    });
+    child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}\n`);
+    const tools = (await send(2, "tools/list")).result.tools;
+
+    console.log(`  serverInfo: ${init.result.serverInfo.name} v${init.result.serverInfo.version}`);
+    console.log(`  tools:      ${tools.length}`);
+    if (tools.length === 0) throw new Error(`${binName} advertised no tools`);
+  } finally {
+    child.stdin.end();
+    child.kill();
+  }
+}