@truecalc/mcp-local 1.0.0

package/README.md

@@ -0,0 +1,58 @@
+# @truecalc/mcp-local
+
+Run **TrueCalc Local** — a native MCP server exposing TrueCalc's spreadsheet
+document engine (read/edit cells, formulas, formatting, charts, pivots, and
+more, over 70 tools) — with no install step:
+
+```sh
+npx -y @truecalc/mcp-local
+```
+
+This package is a thin wrapper: `npx` resolves it, its `optionalDependencies`
+bring in the prebuilt `truecalc-mcp-local` binary for your OS/CPU
+(`@truecalc/mcp-local-darwin-arm64`, `@truecalc/mcp-local-darwin-x64`,
+`@truecalc/mcp-local-linux-x64`, `@truecalc/mcp-local-win32-x64`), and the
+`truecalc-mcp-local` bin script execs it with stdio inherited. The server
+itself is the same Rust `mcp-server` binary built from
+[truecalc/pro](https://github.com/truecalc/pro) — one implementation, no
+second copy of tool behavior to keep in sync.
+
+**This is a paid product ($49, one-time license).** The binary gates every
+tool call except `license:activate` behind a valid, locally-cached license —
+see `license:activate` in the parent repo's README for the full activation,
+device-binding, and re-validation flow. Buy a key at
+<https://buy.polar.sh/polar_cl_n4cNoheqSQgeTpENhUaWOVzTA3ENvI1jkNhzC2fY6fS>
+(the same URL `mcp-server` itself points an unlicensed caller at —
+`TRUECALC_CHECKOUT_URL`'s default in `src/commands/license/gate.rs`).
+
+## MCP client configuration
+
+Add this to your client's MCP server config (e.g. Claude Desktop's
+`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "truecalc-local": {
+      "command": "npx",
+      "args": ["-y", "@truecalc/mcp-local"]
+    }
+  }
+}
+```
+
+Restart the client, then call the `license:activate` tool with your license
+key before using any other tool.
+
+## Supported platforms
+
+macOS (arm64, x64), Linux (x64), Windows (x64). Linux arm64 is a planned
+fast-follow, not yet published. On an unsupported platform, running
+`npx -y @truecalc/mcp-local` prints an actionable error naming the platforms
+that are supported instead of failing silently or with a stack trace.
+
+## Learn more
+
+- [truecalc/pro](https://github.com/truecalc/pro) — full tool documentation,
+  the MCP server's design, and `cargo build --release --bin mcp-server` for
+  building from source.

package/bin/truecalc-mcp-local.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("node:path");
+const fs = require("node:fs");
+const { spawnSync } = require("node:child_process");
+const { resolveTarget } = require("../lib/resolve.js");
+
+// Resolves the on-disk path to the platform binary. `pkgName` only ever comes
+// from the fixed PLATFORM_PACKAGES map in lib/resolve.js (never from argv or
+// the environment), so require.resolve here can't be steered by untrusted
+// input — it either finds the real optionalDependency package or it doesn't.
+function resolveBinaryPath(platform, arch) {
+  const { pkgName, binName } = resolveTarget(platform, arch);
+
+  let pkgJsonPath;
+  try {
+    pkgJsonPath = require.resolve(`${pkgName}/package.json`);
+  } catch {
+    throw new Error(
+      `@truecalc/mcp-local could not find its optional dependency '${pkgName}'.\n` +
+        "npm likely skipped installing it (e.g. --omit=optional, --no-optional, " +
+        "or an npm/yarn/pnpm version that mishandles OS/CPU-scoped optionalDependencies).\n" +
+        "Reinstall with optional dependencies included: npm install --include=optional @truecalc/mcp-local",
+    );
+  }
+
+  const binaryPath = path.join(path.dirname(pkgJsonPath), "bin", binName);
+  if (!fs.existsSync(binaryPath)) {
+    throw new Error(`@truecalc/mcp-local found '${pkgName}' but its binary is missing at ${binaryPath}.`);
+  }
+  return binaryPath;
+}
+
+function main() {
+  let binaryPath;
+  try {
+    binaryPath = resolveBinaryPath(process.platform, process.arch);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // spawnSync with an argv array and no `shell: true`: process.argv and the
+  // resolved binary path are passed as discrete arguments to execve, never
+  // interpolated into a shell command line, so nothing in either can inject
+  // a second command. stdio is inherited because MCP speaks JSON-RPC over
+  // stdio — this process is a transparent relay for stdin/stdout/stderr, and
+  // license:activate's own network/filesystem calls happen unmodified inside
+  // the real binary, not this launcher.
+  const result = spawnSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+  if (result.error) {
+    process.stderr.write(`@truecalc/mcp-local failed to start ${binaryPath}: ${result.error.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  // null status means the child was killed by a signal; propagate a non-zero
+  // exit rather than silently reporting success.
+  process.exitCode = result.status === null ? 1 : result.status;
+}
+
+main();

package/lib/resolve.js

@@ -0,0 +1,43 @@
+"use strict";
+
+// Maps Node's own process.platform/process.arch values to the npm platform
+// package that ships the matching truecalc-mcp-local (core-pro) binary. Keys
+// use Node's naming exactly ('arm64', 'x64', 'darwin', 'win32', 'linux') —
+// NOT the Rust target triple's naming ('aarch64', 'x86_64') — because
+// process.arch/process.platform are what this shim actually receives at
+// runtime.
+//
+// Four platforms at launch (darwin-arm64, darwin-x64, linux-x64, win32-x64).
+// linux-arm64 is a deliberate fast-follow, not an oversight — see the
+// release workflow's own comment and the wrapper README for the same note.
+const PLATFORM_PACKAGES = {
+  "darwin-arm64": "@truecalc/mcp-local-darwin-arm64",
+  "darwin-x64": "@truecalc/mcp-local-darwin-x64",
+  "linux-x64": "@truecalc/mcp-local-linux-x64",
+  "win32-x64": "@truecalc/mcp-local-win32-x64",
+};
+
+const SUPPORTED = Object.keys(PLATFORM_PACKAGES).sort();
+
+// Pure function: given (platform, arch), return which platform package and
+// binary filename it maps to, or throw a clear, actionable error. No
+// filesystem or require.resolve calls here — that's what makes it testable
+// with mocked process.platform/process.arch values.
+function resolveTarget(platform, arch) {
+  const key = `${platform}-${arch}`;
+  const pkgName = PLATFORM_PACKAGES[key];
+  if (!pkgName) {
+    throw new Error(
+      `@truecalc/mcp-local does not support ${platform}/${arch}.\n` +
+        `Supported platforms: ${SUPPORTED.join(", ")}.\n` +
+        (platform === "linux" && arch === "arm64"
+          ? "linux/arm64 is a planned fast-follow, not yet published.\n"
+          : "") +
+        "Build truecalc-core-pro's mcp-server from source instead: https://github.com/truecalc/pro",
+    );
+  }
+  const binName = platform === "win32" ? "truecalc-mcp-local.exe" : "truecalc-mcp-local";
+  return { pkgName, binName };
+}
+
+module.exports = { resolveTarget, PLATFORM_PACKAGES };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@truecalc/mcp-local",
+  "version": "1.0.0",
+  "description": "TrueCalc Local — a native MCP server exposing TrueCalc's spreadsheet document engine (read/edit cells, formulas, formatting, charts, pivots, and more) as MCP tools over stdio. Paid, one-time-license product; run via npx.",
+  "license": "LicenseRef-proprietary",
+  "homepage": "https://buy.polar.sh/polar_cl_n4cNoheqSQgeTpENhUaWOVzTA3ENvI1jkNhzC2fY6fS",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/truecalc/pro",
+    "directory": "npm/wrapper"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "spreadsheet",
+    "truecalc",
+    "ai",
+    "claude"
+  ],
+  "bin": {
+    "truecalc-mcp-local": "bin/truecalc-mcp-local.js"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "@truecalc/mcp-local-darwin-arm64": "1.0.0",
+    "@truecalc/mcp-local-darwin-x64": "1.0.0",
+    "@truecalc/mcp-local-linux-x64": "1.0.0",
+    "@truecalc/mcp-local-win32-x64": "1.0.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}