@ledgerful/mcp-server 0.1.8

package/BINARY-LICENSE-NOTICE.md

@@ -0,0 +1,4 @@
+# Binary license notice
+
+The Ledgerful binary downloaded by this package is licensed under the terms in
+`LICENSE`, with the additional permissions in `COMMERCIAL-EXCEPTION.md`.

package/COMMERCIAL-EXCEPTION.md

@@ -0,0 +1,120 @@
+# Ledgerful Small-Entity Commercial Exception (v1.0)
+
+> This file is the additional permission referenced by the `Required Notice:` line in `LICENSE`. 
+> Keep the PolyForm base text verbatim; this Exception only *adds* permissions.
+
+Licensor: **Ledgerful, LLC**. "Software" refers to the software identified by the repository's
+PolyForm `Required Notice:` (Ledgerful, as distributed under the PolyForm Noncommercial License).
+
+## Grant
+
+In addition to the rights granted by the PolyForm Noncommercial License 1.0.0, the Licensor grants a
+**Qualified Small Entity** a royalty-free, worldwide, non-exclusive license to make **Internal
+Business Use** of the Software, subject to all other terms of the PolyForm Noncommercial License and
+the definitions and conditions below.
+
+> **Core constraint: others may not commercialize the new-license Ledgerful.** This Exception grants
+> Internal Business Use only and grants no right to (a) offer the Software itself, (b) offer modified
+> versions or derivative works, (c) provide hosted access to the Software to third parties, or (d)
+> distribute products incorporating substantial portions of it. Commercializing the Software requires
+> a separate written OEM/redistribution agreement.
+
+## Definitions
+
+- **"Entity"** means a corporation, LLC, partnership, sole proprietorship, unincorporated
+  association, or other legal or commercial organization.
+- **"Affiliate"** means any Entity that directly or indirectly Controls, is Controlled by, or is
+  under common Control with another Entity. *(The Affiliate and Control definitions here apply only
+  to eligibility and revenue aggregation under this Exception and do not modify the base PolyForm
+  license, including PolyForm's "Your company.")*
+- **"Control"** means the direct or indirect power to direct or cause the direction of an Entity's
+  management or policies, whether through ownership, voting rights, contract, or otherwise. Control
+  is presumed where a person or Entity (a) owns or controls at least 50% of voting power or equity,
+  (b) may appoint or remove a majority of the governing body, or (c) otherwise has the practical
+  power to direct management or policies. Control may exist below 50%.
+- **"Change of Control"** means a merger, acquisition, sale of substantially all assets, or any
+  transaction or series of transactions that changes which person or Entity Controls You.
+- **"Measurement Date"** means the last day of each calendar month and the effective date of any
+  Change of Control.
+- **"Measurement Period"** means: for a month-end Measurement Date, the twelve completed calendar
+  months ending on that date; for a Change-of-Control Measurement Date, the twelve completed calendar
+  months ending before the transaction date. If an Entity has existed fewer than twelve months, the
+  period begins on its formation date and its Gross Revenue is not annualized (actual revenue only).
+- **"Gross Revenue"** means all revenue, receipts, and other income from any source recognized or
+  accrued under the accounting method the Entity uses consistently in its financial statements or tax
+  returns, before deduction of costs, reduced only by bona fide returns, refunds, and allowances. It
+  excludes: (a) sales/VAT/similar taxes collected for and remitted to a government; (b) proceeds of
+  equity investment or borrowing; (c) capital contributions; (d) proceeds from sales of capital
+  assets outside the ordinary course; and (e) inter-Affiliate amounts eliminated in Aggregated Gross
+  Revenue. An Entity may not change its accounting method primarily to qualify for this Exception;
+  any change must be required by law, applicable accounting standards, or a consistently applied bona
+  fide business practice.
+- **"Aggregated Gross Revenue"** means the sum of Gross Revenue for You and every Entity that is Your
+  Affiliate on the Measurement Date, for the same Measurement Period, eliminating inter-Affiliate
+  transactions. Following an acquisition or Change of Control, it includes the full Measurement-Period
+  Gross Revenue of every current Affiliate. Revenue in a currency other than U.S. dollars is
+  converted using the average exchange rate for the Measurement Period published by the U.S. Federal
+  Reserve (or, if unavailable, another nationally recognized central bank, selected reasonably and
+  applied consistently).
+- **"Qualified Small Entity"** means You and Your Affiliates collectively, provided Aggregated Gross
+  Revenue is less than US$1,000,000 on the applicable Measurement Date. (Eligibility is revenue-based
+  only — available funding, capital raised, or valuation do not affect it.)
+- **"Internal Business Use"** means use of the Software for Your own internal operations (including on
+  Your own or a third-party-managed VM, private CI runner, or cloud environment used for Your
+  internal operations), or to support professional or consulting services You provide, but excludes:
+  (a) offering the Software itself; (b) offering modified versions or derivative works; (c) providing
+  hosted access to the Software to third parties; and (d) distributing products incorporating
+  substantial portions of the Software.
+- **"Authorized Contractor"** means a third party engaged to provide services to a Qualified Small
+  Entity, acting solely for that entity's benefit under written obligations at least as protective as
+  these terms.
+- **"Written Authorization"** means a written Commercial License or other written permission from the
+  Licensor.
+- **"Production Use"** means use of the Software in live operations or to process real or business
+  data, as distinct from testing or evaluation in a non-live environment.
+- **"Evaluation Use"** means internal, non-Production Use to assess commercial fit.
+
+## Conditions and lifecycle
+
+- For a Qualified Small Entity, Internal Business Use is a permitted purpose under the PolyForm
+  Noncommercial License 1.0.0.
+- Eligibility is determined on each Measurement Date. At exactly US$1,000,000 Aggregated Gross
+  Revenue, You are no longer a Qualified Small Entity.
+- **Continuing grant during transition:** if You cease to qualify solely because Aggregated Gross
+  Revenue reaches or exceeds US$1,000,000, or because of a Change of Control, this Exception remains
+  effective for 90 days after the applicable Measurement Date. Before that period expires You must
+  obtain Written Authorization or cease all commercial use.
+- **Requalification:** an Entity that later falls below US$1,000,000 requalifies only after 12
+  consecutive months with Aggregated Gross Revenue below the threshold, and is not entitled to a
+  second 90-day transition within any 24-month period.
+- **Authorized Contractor:** an Authorized Contractor may exercise a Qualified Small Entity's rights
+  solely while providing services to that Qualified Small Entity and solely for its benefit. The
+  Qualified Small Entity remains responsible for the contractor's compliance. No contractor receives
+  rights for its own independent business use.
+- **Eligibility records:** You must make a good-faith eligibility determination on each Measurement
+  Date and retain records reasonably sufficient to support it for three years. No financial
+  disclosure is required unless reasonably requested in connection with a specific eligibility
+  dispute, subject to confidentiality protections.
+- **Effect of breach:** if You breach this Exception, the additional permissions it grants terminate;
+  Your rights under the base PolyForm Noncommercial License continue to the extent independently
+  available. Revenue-based expiration (crossing the threshold) is not a breach and receives the
+  90-day transition above.
+- This Exception adds permissions only; all other terms of the PolyForm Noncommercial License
+  continue to apply.
+
+## Evaluation Exception
+
+The Licensor grants an Entity that is not otherwise eligible (a commercial Entity at or above the
+threshold) a non-exclusive license for Evaluation Use of the Software for 30 days, once per Entity
+and its Affiliate group. The period begins on the Entity's first use of a version distributed under
+this license, does not reset upon
+upgrades, new versions, or Affiliate transfers, and permits internal, non-Production Use only. It
+ends after 30 days unless Written Authorization is obtained. Qualified Small Entities and permitted
+noncommercial users do not need this — they are already licensed.
+
+## Commercial use beyond this Exception
+
+Commercial use at or above the threshold requires a separate written Commercial License. Reselling,
+hosting the Software as a service for third parties, OEM embedding, or distributing products
+incorporating substantial portions of the Software requires a separate written OEM/redistribution
+agreement, regardless of size. Contact: legal@ledgerful.dev

package/LICENSE

@@ -0,0 +1,76 @@
+Required Notice: Copyright 2026 Ledgerful, LLC; additional permissions are stated in COMMERCIAL-EXCEPTION.md.
+
+----------------------------------------------------------------------
+
+PolyForm Noncommercial License 1.0.0
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to Distribution License and make changes or new works based on the software according to Changes and New Works License.
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by Changes and New Works License.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
+
+Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+## Definitions
+
+The licensor is the individual or entity offering these terms, and the software is the software the licensor makes available under these terms.
+
+You refers to the individual or entity agreeing to these terms.
+
+Your company is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. Control means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+Your licenses are all the licenses granted to you for the software under these terms.
+
+Use means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,71 @@
+# Ledgerful MCP Server
+
+`@ledgerful/mcp-server` wraps the Ledgerful CLI's existing `ledgerful mcp`
+stdio server so AI coding agents can install it through npm without building
+Rust locally.
+
+```sh
+npx @ledgerful/mcp-server
+npm install -g @ledgerful/mcp-server
+ledgerful-mcp
+```
+
+The package downloads the matching `ledgerful-{target}` release asset,
+verifies the adjacent `.sha256` checksum file, caches the binary, and launches:
+
+```sh
+ledgerful mcp
+```
+
+Existing `ledgerful` binary naming is intentional: Ledgerful keeps the
+backward-compatible CLI alias while the npm package carries the Ledgerful brand.
+
+## Agent Configuration
+
+Use the installed bin as the MCP command:
+
+```json
+{
+  "mcpServers": {
+    "ledgerful": {
+      "command": "ledgerful-mcp"
+    }
+  }
+}
+```
+
+## Tools
+
+The tool table is cross-checked against `src/commands/mcp/manifest.rs`.
+
+| Tool | Description |
+|---|---|
+| `scan` | Assess the impact and risk of uncommitted changes in the repository. |
+| `search` | High-precision regex and text discovery for code symbols. |
+| `ask` | Conceptual and semantic natural language queries about the codebase. |
+| `ledger_status` | Get the current provenance status, including pending transactions and unaudited drift. |
+| `ledger_search` | Search the architectural history and transaction ledger. |
+| `hotspots` | Identify brittle files with high change frequency or complexity. |
+| `endpoints_changed` | List API endpoints affected by current changes. |
+| `security_boundaries` | Inspect security policy boundaries and their risk status. |
+| `dead_code` | Identify likely unused functions and types based on graph reachability. |
+| `verify_plan` | Predict the verification plan for current changes. |
+
+## Environment
+
+| Variable | Purpose |
+|---|---|
+| `LEDGERFUL_MCP_BIN_OVERRIDE` | Use a local Ledgerful/Ledgerful binary instead of downloading a release asset. Useful for CI and development. |
+| `LEDGERFUL_MCP_CACHE_DIR` | Override the binary cache directory. |
+| `LEDGERFUL_MCP_RELEASE_TAG` | Download from a specific GitHub release tag instead of `latest`. |
+| `LEDGERFUL_MCP_RELEASE_BASE_URL` | Override the complete GitHub release asset base URL. |
+| `LEDGERFUL_MCP_SKIP_DOWNLOAD=1` | Skip the best-effort postinstall download. First run will still need a binary or override. |
+
+## Troubleshooting
+
+- Unsupported platform: the loader supports `linux:x64`, `win32:x64`,
+  `darwin:x64`, and `darwin:arm64`.
+- Download failure: check that the GitHub release has the expected archive and
+  adjacent `.sha256` file, or set `LEDGERFUL_MCP_BIN_OVERRIDE`.
+- Checksum mismatch: the loader refuses to execute the downloaded archive. Clear
+  the cache and verify the release asset was not replaced.

package/bin/ledgerful-mcp.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawn } = require("node:child_process");
+const { ensureBinary } = require("../lib/install");
+
+async function main() {
+  const binary = await ensureBinary({ quiet: false });
+  const child = spawn(binary, ["mcp", ...process.argv.slice(2)], {
+    stdio: "inherit",
+    windowsHide: true
+  });
+
+  child.on("error", (error) => {
+    console.error(`ledgerful-mcp: failed to launch ${binary}: ${error.message}`);
+    process.exitCode = 1;
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+}
+
+main().catch((error) => {
+  console.error(`ledgerful-mcp: ${error.message}`);
+  process.exit(1);
+});

package/lib/install.js

@@ -0,0 +1,171 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnFile } = require("./process");
+const { resolveTarget } = require("./platform");
+
+const OWNER = "Ryan-AI-Studios";
+const REPO = "Ledgerful";
+
+function packageVersion() {
+  const packageJson = require("../package.json");
+  return packageJson.version;
+}
+
+function cacheRoot() {
+  if (process.env.LEDGERFUL_MCP_CACHE_DIR) {
+    return process.env.LEDGERFUL_MCP_CACHE_DIR;
+  }
+  if (process.platform === "win32" && process.env.LOCALAPPDATA) {
+    return path.join(process.env.LOCALAPPDATA, "Ledgerful", "mcp-server");
+  }
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Caches", "ledgerful-mcp-server");
+  }
+  return path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "ledgerful-mcp-server");
+}
+
+function releaseBaseUrl() {
+  if (process.env.LEDGERFUL_MCP_RELEASE_BASE_URL) {
+    return process.env.LEDGERFUL_MCP_RELEASE_BASE_URL.replace(/\/+$/, "");
+  }
+  if (process.env.LEDGERFUL_MCP_RELEASE_TAG) {
+    return `https://github.com/${OWNER}/${REPO}/releases/download/${process.env.LEDGERFUL_MCP_RELEASE_TAG}`;
+  }
+  return `https://github.com/${OWNER}/${REPO}/releases/download/v${packageVersion()}`;
+}
+
+function parseChecksum(text) {
+  const match = text.match(/\b([a-fA-F0-9]{64})\b/);
+  if (!match) {
+    throw new Error("checksum file did not contain a SHA-256 digest");
+  }
+  return match[1].toLowerCase();
+}
+
+function sha256File(filePath) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest("hex");
+}
+
+async function downloadToFile(url, destination) {
+  const response = await fetch(url, {
+    headers: {
+      "user-agent": `ledgerful-mcp-server/${packageVersion()}`
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`download failed for ${url}: HTTP ${response.status}`);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.writeFileSync(destination, buffer);
+}
+
+function findBinary(root, binaryName) {
+  const entries = fs.readdirSync(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      const nested = findBinary(fullPath, binaryName);
+      if (nested) {
+        return nested;
+      }
+    } else if (entry.name === binaryName) {
+      return fullPath;
+    }
+  }
+  return null;
+}
+
+async function extractArchive(archivePath, destination, target) {
+  fs.rmSync(destination, { recursive: true, force: true });
+  fs.mkdirSync(destination, { recursive: true });
+  if (target.extension === ".zip") {
+    await spawnFile("powershell", [
+      "-NoLogo",
+      "-NoProfile",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-Command",
+      "Expand-Archive -LiteralPath $args[0] -DestinationPath $args[1] -Force",
+      archivePath,
+      destination
+    ]);
+  } else {
+    await spawnFile("tar", ["-xzf", archivePath, "-C", destination]);
+  }
+}
+
+async function installFromRelease(target, installDir, options = {}) {
+  const baseUrl = releaseBaseUrl();
+  const archiveUrl = `${baseUrl}/${target.archive}`;
+  const checksumUrl = `${archiveUrl}.sha256`;
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ledgerful-mcp-"));
+  try {
+    const archivePath = path.join(tempDir, target.archive);
+    const checksumPath = `${archivePath}.sha256`;
+    await downloadToFile(archiveUrl, archivePath);
+    await downloadToFile(checksumUrl, checksumPath);
+
+    const expected = parseChecksum(fs.readFileSync(checksumPath, "utf8"));
+    const actual = sha256File(archivePath);
+    if (actual !== expected) {
+      throw new Error(`checksum mismatch for ${target.archive}: expected ${expected}, got ${actual}`);
+    }
+
+    const extractDir = path.join(tempDir, "extract");
+    await extractArchive(archivePath, extractDir, target);
+    const extractedBinary = findBinary(extractDir, target.binary);
+    if (!extractedBinary) {
+      throw new Error(`archive ${target.archive} did not contain ${target.binary}`);
+    }
+
+    fs.mkdirSync(installDir, { recursive: true });
+    const installedBinary = path.join(installDir, target.binary);
+    fs.copyFileSync(extractedBinary, installedBinary);
+    if (process.platform !== "win32") {
+      fs.chmodSync(installedBinary, 0o755);
+    }
+    return installedBinary;
+  } catch (error) {
+    if (!options.quiet) {
+      console.error(`ledgerful-mcp: ${error.message}`);
+    }
+    throw error;
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+async function ensureBinary(options = {}) {
+  if (process.env.LEDGERFUL_MCP_BIN_OVERRIDE) {
+    const override = path.resolve(process.env.LEDGERFUL_MCP_BIN_OVERRIDE);
+    if (!fs.existsSync(override)) {
+      throw new Error(`LEDGERFUL_MCP_BIN_OVERRIDE does not exist: ${override}`);
+    }
+    return override;
+  }
+
+  const target = resolveTarget();
+  const installDir = path.join(cacheRoot(), packageVersion(), target.asset);
+  const binaryPath = path.join(installDir, target.binary);
+  if (fs.existsSync(binaryPath)) {
+    return binaryPath;
+  }
+  return installFromRelease(target, installDir, options);
+}
+
+module.exports = {
+  cacheRoot,
+  ensureBinary,
+  installFromRelease,
+  packageVersion,
+  parseChecksum,
+  releaseBaseUrl,
+  sha256File
+};

package/lib/platform.js

@@ -0,0 +1,36 @@
+"use strict";
+
+const TARGETS = {
+  "linux:x64": {
+    asset: "ledgerful-x86_64-unknown-linux-gnu",
+    extension: ".tar.gz",
+    binary: "ledgerful"
+  },
+  "win32:x64": {
+    asset: "ledgerful-x86_64-pc-windows-msvc",
+    extension: ".zip",
+    binary: "ledgerful.exe"
+  },
+  "darwin:x64": {
+    asset: "ledgerful-x86_64-apple-darwin",
+    extension: ".tar.gz",
+    binary: "ledgerful"
+  },
+  "darwin:arm64": {
+    asset: "ledgerful-aarch64-apple-darwin",
+    extension: ".tar.gz",
+    binary: "ledgerful"
+  }
+};
+
+function resolveTarget(platform = process.platform, arch = process.arch) {
+  const key = `${platform}:${arch}`;
+  const target = TARGETS[key];
+  if (!target) {
+    const supported = Object.keys(TARGETS).join(", ");
+    throw new Error(`unsupported platform ${key}; supported targets: ${supported}`);
+  }
+  return { ...target, key, archive: `${target.asset}${target.extension}` };
+}
+
+module.exports = { TARGETS, resolveTarget };

package/lib/process.js

@@ -0,0 +1,27 @@
+"use strict";
+
+const { spawn } = require("node:child_process");
+
+function spawnFile(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: options.stdio || "pipe",
+      windowsHide: true,
+      ...options
+    });
+    let stderr = "";
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`${command} exited with ${code}${stderr ? `: ${stderr.trim()}` : ""}`));
+    });
+  });
+}
+
+module.exports = { spawnFile };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ledgerful/mcp-server",
+  "version": "0.1.8",
+  "description": "Ledgerful MCP stdio server wrapper for AI coding agents",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ryan-AI-Studios/Ledgerful.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://github.com/Ryan-AI-Studios/Ledgerful#readme",
+  "bugs": {
+    "url": "https://github.com/Ryan-AI-Studios/Ledgerful/issues"
+  },
+  "bin": {
+    "ledgerful-mcp": "bin/ledgerful-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "README.md",
+    "LICENSE",
+    "COMMERCIAL-EXCEPTION.md",
+    "BINARY-LICENSE-NOTICE.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node --test test/*.test.js",
+    "smoke:local": "node test/smoke-local.js",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18.18"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,12 @@
+"use strict";
+
+const { ensureBinary } = require("../lib/install");
+
+if (process.env.LEDGERFUL_MCP_SKIP_DOWNLOAD === "1" || process.env.LEDGERFUL_MCP_BIN_OVERRIDE) {
+  process.exit(0);
+}
+
+ensureBinary({ quiet: true }).catch((error) => {
+  console.warn(`ledgerful-mcp: binary prefetch skipped: ${error.message}`);
+  console.warn("ledgerful-mcp: the first run will retry the download unless LEDGERFUL_MCP_BIN_OVERRIDE is set.");
+});