@kinlab/kin-mcp 0.2.0

package/README.md

@@ -0,0 +1,72 @@
+# @kinlab/kin-mcp
+
+`@kinlab/kin-mcp` is the npm-friendly launcher for Kin's MCP server (the installed
+command is still `kin-mcp`).
+
+It downloads the matching Kin release archive from GitHub, verifies the published
+SHA-256 checksum, extracts the `kin` binary into a local cache, and runs:
+
+```sh
+kin mcp start
+```
+
+## Usage
+
+Use it directly from an MCP client with `npx`:
+
+```json
+{
+  "mcpServers": {
+    "kin": {
+      "command": "npx",
+      "args": ["-y", "@kinlab/kin-mcp"]
+    }
+  }
+}
+```
+
+For a pinned version:
+
+```json
+{
+  "mcpServers": {
+    "kin": {
+      "command": "npx",
+      "args": ["-y", "@kinlab/kin-mcp@0.2.0"]
+    }
+  }
+}
+```
+
+## Requirements
+
+- Node.js 20+
+- macOS or Linux
+- A Kin-initialized repository (`kin init`)
+
+Windows users should run Kin through WSL2 during the alpha.
+
+## Cache
+
+The wrapper caches the downloaded `kin` binary under:
+
+- macOS: `~/Library/Caches/kin-mcp`
+- Linux: `~/.cache/kin-mcp`
+
+Set `KIN_MCP_CACHE_DIR` to override the cache location.
+
+## Environment
+
+- `KIN_MCP_KIN_BINARY`: run a specific local `kin` binary instead of downloading one
+- `KIN_BINARY_PATH`: alias for `KIN_MCP_KIN_BINARY`
+- `KIN_MCP_CACHE_DIR`: override the cache directory
+- `KIN_MCP_AUTO_INIT=1`: allow the wrapper to run `kin init .` when `.kin/` is missing
+- `KIN_MCP_RELEASE_BASE_URL`: override the GitHub release download base URL
+
+## Local Check
+
+```sh
+npx -y @kinlab/kin-mcp --print-bin
+```
+
+Then initialize a repository and let the MCP client launch `kin-mcp`.

package/bin/kin-mcp.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { runKinMcp } from '../src/index.js';
+
+const exitCode = await runKinMcp(process.argv.slice(2));
+process.exit(exitCode);

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@kinlab/kin-mcp",
+  "version": "0.2.0",
+  "description": "Start Kin's MCP server through an npm-friendly wrapper.",
+  "type": "module",
+  "bin": {
+    "kin-mcp": "./bin/kin-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "lint": "node --check ./bin/kin-mcp.js && node --check ./src/index.js && node --check ./test/index.test.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "kin",
+    "mcp",
+    "claude",
+    "codex",
+    "gemini"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firelock-ai/kin.git"
+  },
+  "homepage": "https://github.com/firelock-ai/kin",
+  "bugs": {
+    "url": "https://github.com/firelock-ai/kin/issues"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,385 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Firelock, LLC
+
+import cp from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json');
+
+export const PACKAGE_VERSION = packageJson.version;
+export const DEFAULT_RELEASE_BASE_URL =
+  'https://github.com/firelock-ai/kin/releases/download';
+
+export function resolveReleaseTag(version = PACKAGE_VERSION) {
+  return version.startsWith('v') ? version : `v${version}`;
+}
+
+export function resolveReleaseAsset(platform = process.platform, arch = process.arch) {
+  if (platform === 'darwin' && arch === 'arm64') {
+    return {
+      assetName: 'kin-macos-aarch64',
+      archiveName: 'kin-macos-aarch64.tar.gz',
+      binaryName: 'kin'
+    };
+  }
+  if (platform === 'darwin' && arch === 'x64') {
+    return {
+      assetName: 'kin-macos-x86_64',
+      archiveName: 'kin-macos-x86_64.tar.gz',
+      binaryName: 'kin'
+    };
+  }
+  if (platform === 'linux' && arch === 'x64') {
+    return {
+      assetName: 'kin-linux-x86_64',
+      archiveName: 'kin-linux-x86_64.tar.gz',
+      binaryName: 'kin'
+    };
+  }
+  if (platform === 'linux' && arch === 'arm64') {
+    return {
+      assetName: 'kin-linux-aarch64',
+      archiveName: 'kin-linux-aarch64.tar.gz',
+      binaryName: 'kin'
+    };
+  }
+
+  throw new Error(
+    `kin-mcp does not have a published Kin binary for ${platform}/${arch} yet. ` +
+      'On Windows, use WSL2 for this alpha.'
+  );
+}
+
+export function resolveCacheRoot(
+  env = process.env,
+  platform = process.platform,
+  homeDir = os.homedir()
+) {
+  if (env.KIN_MCP_CACHE_DIR) {
+    return path.resolve(env.KIN_MCP_CACHE_DIR);
+  }
+
+  if (platform === 'darwin') {
+    return path.join(homeDir, 'Library', 'Caches', 'kin-mcp');
+  }
+
+  if (platform === 'win32') {
+    const localAppData = env.LOCALAPPDATA || path.join(homeDir, 'AppData', 'Local');
+    return path.join(localAppData, 'kin-mcp', 'Cache');
+  }
+
+  const xdgCacheHome = env.XDG_CACHE_HOME || path.join(homeDir, '.cache');
+  return path.join(xdgCacheHome, 'kin-mcp');
+}
+
+export function resolveCachedBinaryPath({
+  env = process.env,
+  platform = process.platform,
+  arch = process.arch,
+  version = PACKAGE_VERSION,
+  homeDir = os.homedir(),
+  cacheRoot
+} = {}) {
+  const { assetName, binaryName } = resolveReleaseAsset(platform, arch);
+  const root = cacheRoot || resolveCacheRoot(env, platform, homeDir);
+  return path.join(root, resolveReleaseTag(version), assetName, binaryName);
+}
+
+export async function ensureKinBinary({
+  env = process.env,
+  platform = process.platform,
+  arch = process.arch,
+  version = PACKAGE_VERSION,
+  homeDir = os.homedir(),
+  cacheRoot
+} = {}) {
+  const configuredBinary = env.KIN_MCP_KIN_BINARY || env.KIN_BINARY_PATH;
+  if (configuredBinary) {
+    const resolved = path.resolve(configuredBinary);
+    await assertRunnable(resolved, platform);
+    return resolved;
+  }
+
+  const binaryPath = resolveCachedBinaryPath({
+    env,
+    platform,
+    arch,
+    version,
+    homeDir,
+    cacheRoot
+  });
+
+  if (await isRunnable(binaryPath, platform)) {
+    return binaryPath;
+  }
+
+  await installKinBinary({ binaryPath, env, platform, arch, version });
+  return binaryPath;
+}
+
+export async function runKinMcp(argv = [], options = {}) {
+  const stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+  const env = options.env || process.env;
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    stdout.write(renderHelp());
+    return 0;
+  }
+
+  if (argv.includes('--version') || argv.includes('-v')) {
+    stdout.write(`${PACKAGE_VERSION}\n`);
+    return 0;
+  }
+
+  if (argv.includes('--print-bin')) {
+    const binaryPath = await ensureKinBinary(options);
+    stdout.write(`${binaryPath}\n`);
+    return 0;
+  }
+
+  if (argv.length > 0) {
+    stderr.write(
+      'kin-mcp does not accept subcommands. It always runs `kin mcp start`.\n'
+    );
+    return 2;
+  }
+
+  const binaryPath = await ensureKinBinary(options);
+
+  const cwd = options.cwd || process.cwd();
+  if (!await kinRepoExists(cwd)) {
+    if (!isTruthyEnv(env.KIN_MCP_AUTO_INIT)) {
+      stderr.write(
+        'No .kin/ found. Run `kin init .` first, or set KIN_MCP_AUTO_INIT=1 to allow this wrapper to initialize the repo.\n'
+      );
+      return 2;
+    }
+    stderr.write('No .kin/ found; KIN_MCP_AUTO_INIT=1, running kin init...\n');
+    const initCode = await spawnKin(binaryPath, ['init', '.'], { ...options, cwd });
+    if (initCode !== 0) {
+      stderr.write('kin init failed. Cannot start MCP server.\n');
+      return initCode;
+    }
+  }
+
+  return spawnKin(binaryPath, ['mcp', 'start'], options);
+}
+
+function isTruthyEnv(value) {
+  return ['1', 'true', 'TRUE', 'yes', 'YES'].includes(String(value || ''));
+}
+
+function renderHelp() {
+  return `kin-mcp ${PACKAGE_VERSION}
+
+Usage:
+  kin-mcp
+  kin-mcp --print-bin
+  kin-mcp --version
+
+This wrapper downloads a matching Kin release binary on demand, caches it
+locally, and then runs:
+
+  kin mcp start
+
+Environment:
+  KIN_MCP_KIN_BINARY   Use a specific kin binary
+  KIN_BINARY_PATH      Alias for KIN_MCP_KIN_BINARY
+  KIN_MCP_CACHE_DIR    Override the cache directory
+  KIN_MCP_AUTO_INIT    Set to 1 to allow wrapper-initiated kin init
+  KIN_MCP_RELEASE_BASE_URL
+                       Override the release download base URL
+`;
+}
+
+async function installKinBinary({ binaryPath, env, platform, arch, version }) {
+  const { assetName, archiveName, binaryName } = resolveReleaseAsset(platform, arch);
+  const tag = resolveReleaseTag(version);
+  const baseUrl = (env.KIN_MCP_RELEASE_BASE_URL || DEFAULT_RELEASE_BASE_URL).replace(
+    /\/$/,
+    ''
+  );
+  const archiveUrl = `${baseUrl}/${tag}/${archiveName}`;
+  const checksumUrl = `${archiveUrl}.sha256`;
+
+  await fsp.mkdir(path.dirname(binaryPath), { recursive: true });
+
+  const checksumText = await fetchText(checksumUrl);
+  const expectedSha = parseChecksum(checksumText);
+  const archiveBytes = await fetchBytes(archiveUrl);
+  const actualSha = sha256(archiveBytes);
+
+  if (actualSha !== expectedSha) {
+    throw new Error(
+      `checksum mismatch for ${archiveName}: expected ${expectedSha}, got ${actualSha}`
+    );
+  }
+
+  await installFromArchive({
+    archiveBytes,
+    archiveName,
+    assetName,
+    binaryName,
+    binaryPath,
+    platform
+  });
+}
+
+async function installFromArchive({
+  archiveBytes,
+  archiveName,
+  assetName,
+  binaryName,
+  binaryPath,
+  platform
+}) {
+  const tmpRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'kin-mcp-install-'));
+  const archivePath = path.join(tmpRoot, archiveName);
+  const tmpPath = `${binaryPath}.download`;
+
+  try {
+    await fsp.writeFile(archivePath, archiveBytes);
+    await execFile('tar', ['-xzf', archivePath, '-C', tmpRoot]);
+
+    const extractedBinary = path.join(tmpRoot, assetName, binaryName);
+    await fsp.access(extractedBinary, fs.constants.R_OK);
+    await fsp.copyFile(extractedBinary, tmpPath);
+    if (platform !== 'win32') {
+      await fsp.chmod(tmpPath, 0o755);
+    }
+    await fsp.rename(tmpPath, binaryPath);
+  } catch (error) {
+    await fsp.unlink(tmpPath).catch(() => {});
+    throw new Error(`failed to install ${binaryName} from ${archiveName}: ${error.message}`);
+  } finally {
+    await fsp.rm(tmpRoot, { recursive: true, force: true });
+  }
+}
+
+function execFile(file, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    cp.execFile(file, args, options, (error, stdout, stderr) => {
+      if (error) {
+        if (stderr) {
+          error.message = `${error.message}: ${stderr.trim()}`;
+        }
+        reject(error);
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+async function fetchText(url) {
+  const response = await fetch(url, {
+    headers: { 'user-agent': `kin-mcp/${PACKAGE_VERSION}` },
+    signal: AbortSignal.timeout(60_000)
+  });
+
+  if (!response.ok) {
+    throw new Error(`failed to download ${url}: ${response.status} ${response.statusText}`);
+  }
+
+  return response.text();
+}
+
+async function fetchBytes(url) {
+  const response = await fetch(url, {
+    headers: { 'user-agent': `kin-mcp/${PACKAGE_VERSION}` },
+    signal: AbortSignal.timeout(120_000)
+  });
+
+  if (!response.ok) {
+    throw new Error(`failed to download ${url}: ${response.status} ${response.statusText}`);
+  }
+
+  return Buffer.from(await response.arrayBuffer());
+}
+
+function parseChecksum(text) {
+  const match = text.trim().match(/\b([a-fA-F0-9]{64})\b/);
+  if (!match) {
+    throw new Error('failed to parse SHA256 checksum from release metadata');
+  }
+  return match[1].toLowerCase();
+}
+
+function sha256(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+async function kinRepoExists(cwd) {
+  try {
+    const stat = await fsp.stat(path.join(cwd, '.kin'));
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function assertRunnable(filePath, platform) {
+  if (!(await isRunnable(filePath, platform))) {
+    throw new Error(`kin binary not found or not executable: ${filePath}`);
+  }
+}
+
+async function isRunnable(filePath, platform) {
+  try {
+    const mode = platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK;
+    await fsp.access(filePath, mode);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function spawnKin(binaryPath, args, options) {
+  const env = options.env || process.env;
+
+  return new Promise((resolve, reject) => {
+    const child = cp.spawn(binaryPath, args, {
+      cwd: options.cwd || process.cwd(),
+      env,
+      stdio: options.stdio || 'inherit'
+    });
+
+    const handlers = new Map();
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+      const handler = () => {
+        if (!child.killed) {
+          child.kill(signal);
+        }
+      };
+      handlers.set(signal, handler);
+      process.on(signal, handler);
+    }
+
+    const cleanup = () => {
+      for (const [signal, handler] of handlers.entries()) {
+        process.off(signal, handler);
+      }
+    };
+
+    child.on('error', error => {
+      cleanup();
+      reject(error);
+    });
+
+    child.on('exit', (code, signal) => {
+      cleanup();
+      if (signal) {
+        resolve(1);
+        return;
+      }
+      resolve(code ?? 1);
+    });
+  });
+}