@actions-json/bridge 0.1.118

package/README.md

@@ -0,0 +1,55 @@
+# @actions-json/bridge
+
+Run the [actions.json](https://yaniv256.github.io/actions.json/) MCP bridge with
+`npx` — no Rust toolchain required. On first run this downloads the prebuilt
+`actions-json-mcp` binary for your platform from the GitHub release, caches it,
+and runs it with the arguments you pass.
+
+## Usage
+
+```bash
+npx @actions-json/bridge mcp \
+  --bind 0.0.0.0:17345 \
+  --actions /abs/path/to/overlay.actions.json \
+  --storage-root /abs/path/to/actions.json.storage
+```
+
+Register it with a coding agent the same way — for Claude Code:
+
+```bash
+claude mcp add actions-json -- \
+  npx -y @actions-json/bridge mcp \
+  --bind 0.0.0.0:17345 \
+  --actions /abs/path/to/overlay.actions.json \
+  --storage-root /abs/path/to/actions.json.storage
+```
+
+For Codex (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.actions-json]
+command = "npx"
+args = [
+  "-y", "@actions-json/bridge", "mcp",
+  "--bind", "0.0.0.0:17345",
+  "--actions", "/abs/path/to/overlay.actions.json",
+  "--storage-root", "/abs/path/to/actions.json.storage",
+]
+```
+
+All arguments after the binary are passed straight through to `actions-json-mcp`.
+See [Getting Started](https://yaniv256.github.io/actions.json/getting-started.html).
+
+## Platforms
+
+Prebuilt binaries are published for **linux-x64**. On other platforms the wrapper
+prints build-from-source instructions (clone the repo and
+`cargo build --release --manifest-path mcp/actions-json-mcp/Cargo.toml`).
+
+## How it works
+
+The package ships no binary. On first invocation it downloads
+`actions-json-mcp-<version>-<platform>.tar.gz` from the matching
+`extension-v<version>` GitHub release, extracts the binary into a local cache
+(`.bin/<version>-<slug>/`), and execs it. Subsequent runs reuse the cached
+binary.

package/bin/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+
+// Thin launcher: ensure the prebuilt actions-json-mcp binary is present
+// (downloading it on first run), then exec it with whatever args were passed.
+// Example:
+//   npx @actions-json/bridge mcp --bind 0.0.0.0:17345 --actions ... --storage-root ...
+
+const { spawn } = require('node:child_process');
+const { ensureBinary } = require('../lib/install');
+
+async function main() {
+  let bin;
+  try {
+    bin = await ensureBinary();
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    process.exit(err.code === 'UNSUPPORTED_PLATFORM' ? 2 : 1);
+    return;
+  }
+
+  const args = process.argv.slice(2);
+  const child = spawn(bin, args, { stdio: 'inherit' });
+
+  // Forward termination signals so the bridge shuts down cleanly.
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(sig, () => child.kill(sig));
+  }
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code == null ? 0 : code);
+    }
+  });
+  child.on('error', (err) => {
+    process.stderr.write(`failed to launch actions-json-mcp: ${err.message}\n`);
+    process.exit(1);
+  });
+}
+
+main();

package/lib/install.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const https = require('node:https');
+const { execFileSync } = require('node:child_process');
+const { assetSlug, downloadUrl, BINARY_NAME } = require('./platform');
+
+// Resolve the package version (used to pick the matching release).
+function packageVersion() {
+  const pkg = require('../package.json');
+  return pkg.version;
+}
+
+// Where we cache the downloaded binary: alongside the package, keyed by version
+// + slug so a version bump re-downloads rather than running a stale binary.
+function binaryDir(version, slug) {
+  return path.join(__dirname, '..', '.bin', `${version}-${slug}`);
+}
+
+function binaryPath(version, slug) {
+  return path.join(binaryDir(version, slug), BINARY_NAME);
+}
+
+function follow(url, redirectsLeft, cb) {
+  https
+    .get(url, { headers: { 'User-Agent': 'actions-json-bridge-npx' } }, (res) => {
+      if (
+        res.statusCode >= 300 &&
+        res.statusCode < 400 &&
+        res.headers.location
+      ) {
+        if (redirectsLeft <= 0) {
+          cb(new Error('too many redirects'));
+          return;
+        }
+        res.resume();
+        follow(res.headers.location, redirectsLeft - 1, cb);
+        return;
+      }
+      if (res.statusCode !== 200) {
+        cb(new Error(`download failed: HTTP ${res.statusCode} for ${url}`));
+        res.resume();
+        return;
+      }
+      cb(null, res);
+    })
+    .on('error', cb);
+}
+
+// Download the tarball to a temp file, extract the binary into binaryDir, chmod
+// it executable, and return its path. Synchronous-feeling via a callback the CLI
+// awaits.
+function download(version, slug) {
+  return new Promise((resolve, reject) => {
+    const url = downloadUrl(version, slug);
+    const dir = binaryDir(version, slug);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpTar = path.join(os.tmpdir(), `actions-json-mcp-${version}-${slug}.tar.gz`);
+    const out = fs.createWriteStream(tmpTar);
+
+    follow(url, 5, (err, res) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      res.pipe(out);
+      out.on('finish', () => {
+        out.close(() => {
+          try {
+            // Extract just the binary from the tarball into dir.
+            execFileSync('tar', ['-xzf', tmpTar, '-C', dir, BINARY_NAME], {
+              stdio: 'inherit',
+            });
+            const bin = binaryPath(version, slug);
+            fs.chmodSync(bin, 0o755);
+            fs.rmSync(tmpTar, { force: true });
+            resolve(bin);
+          } catch (e) {
+            reject(e);
+          }
+        });
+      });
+      out.on('error', reject);
+    });
+  });
+}
+
+// Ensure the binary exists locally; download it on first run. Returns the path.
+async function ensureBinary() {
+  const version = packageVersion();
+  const slug = assetSlug(process.platform, process.arch);
+  if (!slug) {
+    const msg =
+      `No prebuilt actions-json-mcp binary for ${process.platform}-${process.arch} yet.\n` +
+      'Build it from source instead:\n' +
+      '  git clone https://github.com/yaniv256/actions.json.git\n' +
+      '  cd actions.json\n' +
+      '  cargo build --release --manifest-path mcp/actions-json-mcp/Cargo.toml\n' +
+      'then run mcp/actions-json-mcp/target/release/actions-json-mcp.';
+    const e = new Error(msg);
+    e.code = 'UNSUPPORTED_PLATFORM';
+    throw e;
+  }
+  const bin = binaryPath(version, slug);
+  if (fs.existsSync(bin)) {
+    return bin;
+  }
+  process.stderr.write(`Downloading actions-json-mcp ${version} (${slug})...\n`);
+  return download(version, slug);
+}
+
+module.exports = { ensureBinary, binaryPath, packageVersion };

package/lib/platform.js

@@ -0,0 +1,35 @@
+'use strict';
+
+// Maps the current Node process platform/arch to the release asset slug used by
+// scripts/package-mcp-bridge.sh (e.g. "linux-x64"). Returns null for platforms
+// that have no prebuilt binary yet, so the CLI can fall back to a clear
+// build-from-source message instead of downloading the wrong file.
+
+const SUPPORTED = {
+  'linux-x64': 'linux-x64',
+};
+
+function assetSlug(platform, arch) {
+  const key = `${platform}-${arch}`;
+  // Node arch "x64" matches the release slug; map the few aliases we care about.
+  const normalized = key
+    .replace('linux-x64', 'linux-x64')
+    .replace('linux-amd64', 'linux-x64');
+  return SUPPORTED[normalized] || null;
+}
+
+// The binary name inside the tarball.
+const BINARY_NAME = 'actions-json-mcp';
+
+// Build the release asset filename for a version + slug.
+function assetFileName(version, slug) {
+  return `${BINARY_NAME}-${version}-${slug}.tar.gz`;
+}
+
+// Build the GitHub release download URL for a given version tag + asset.
+function downloadUrl(version, slug) {
+  const file = assetFileName(version, slug);
+  return `https://github.com/yaniv256/actions.json/releases/download/extension-v${version}/${file}`;
+}
+
+module.exports = { assetSlug, assetFileName, downloadUrl, BINARY_NAME, SUPPORTED };

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@actions-json/bridge",
+  "version": "0.1.118",
+  "description": "Run the actions.json MCP bridge with npx — no Rust toolchain required. Downloads the prebuilt actions-json-mcp binary for your platform and runs it.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yaniv256/actions.json.git",
+    "directory": "adapters/npm-bridge"
+  },
+  "homepage": "https://yaniv256.github.io/actions.json/getting-started.html",
+  "bin": {
+    "actions-json-bridge": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "actions.json",
+    "mcp",
+    "bridge",
+    "browser",
+    "agent"
+  ]
+}