@kinlab/kin-mcp 0.2.0 → 0.2.2

package/README.md

@@ -4,12 +4,27 @@
 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:
+SHA-256 checksum, extracts both the `kin` CLI and the `kin-daemon` it depends on
+into a local cache, and runs:
 
 ```sh
 kin mcp start
 ```
 
+On first run it:
+
+- provisions `kin-daemon` next to `kin` and points the CLI at it with
+  `KIN_DAEMON_BIN`, so the MCP path never depends on a locally-built `kin`, a
+  stale daemon on `PATH`, or a pre-existing daemon;
+- defaults `KIN_MCP_TOOL_PROFILE=agent-default`, so agents see the small curated
+  tool surface instead of the full internal one;
+- starts (or reuses) the repo daemon automatically, and only then serves tools;
+- requires an explicit `kin init` (no silent init) unless you opt in with
+  `KIN_MCP_AUTO_INIT=1`.
+
+If a runnable Kin cannot be provisioned (unsupported target, release download
+blocked), the wrapper exits with a precise guided fix instead of a stack trace.
+
 ## Usage
 
 Use it directly from an MCP client with `npx`:
@@ -48,7 +63,7 @@ Windows users should run Kin through WSL2 during the alpha.
 
 ## Cache
 
-The wrapper caches the downloaded `kin` binary under:
+The wrapper caches the downloaded `kin` and `kin-daemon` binaries under:
 
 - macOS: `~/Library/Caches/kin-mcp`
 - Linux: `~/.cache/kin-mcp`
@@ -57,16 +72,33 @@ 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_MCP_KIN_BINARY`: run a specific local `kin` binary instead of downloading
+  one (you are then responsible for its `kin-daemon`)
 - `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_TOOL_PROFILE`: override the default `agent-default` tool profile
 - `KIN_MCP_RELEASE_BASE_URL`: override the GitHub release download base URL
 
 ## Local Check
 
 ```sh
-npx -y @kinlab/kin-mcp --print-bin
+npx -y @kinlab/kin-mcp --print-bin         # provisioned kin path
+npx -y @kinlab/kin-mcp --print-daemon-bin  # provisioned kin-daemon path
 ```
 
 Then initialize a repository and let the MCP client launch `kin-mcp`.
+
+## First-run smoke proof
+
+`test/smoke-first-run.mjs` exercises the whole first-run path against built Kin
+binaries: it stages `kin` + `kin-daemon` into a throwaway cache (no pre-existing
+daemon, no dev `PATH` state), runs the wrapper, and drives the MCP stdio protocol
+through one safe semantic tool (`kin_graph_status`). Run it with:
+
+```sh
+cargo build --release -p kin-cli -p kin-daemon
+KIN_BIN=target/release/kin \
+KIN_DAEMON_BIN=target/release/kin-daemon \
+npm run smoke
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinlab/kin-mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Start Kin's MCP server through an npm-friendly wrapper.",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
   ],
   "scripts": {
     "test": "node --test",
-    "lint": "node --check ./bin/kin-mcp.js && node --check ./src/index.js && node --check ./test/index.test.js"
+    "lint": "node --check ./bin/kin-mcp.js && node --check ./src/index.js && node --check ./test/index.test.js && node --check ./test/smoke-first-run.mjs",
+    "smoke": "node ./test/smoke-first-run.mjs"
   },
   "engines": {
     "node": ">=20"

package/src/index.js

@@ -20,33 +20,40 @@ export function resolveReleaseTag(version = PACKAGE_VERSION) {
   return version.startsWith('v') ? version : `v${version}`;
 }
 
+export const PRIMARY_BINARY_NAME = 'kin';
+export const DAEMON_BINARY_NAME = 'kin-daemon';
+
 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'
+      binaryName: PRIMARY_BINARY_NAME,
+      daemonBinaryName: DAEMON_BINARY_NAME
     };
   }
   if (platform === 'darwin' && arch === 'x64') {
     return {
       assetName: 'kin-macos-x86_64',
       archiveName: 'kin-macos-x86_64.tar.gz',
-      binaryName: 'kin'
+      binaryName: PRIMARY_BINARY_NAME,
+      daemonBinaryName: DAEMON_BINARY_NAME
     };
   }
   if (platform === 'linux' && arch === 'x64') {
     return {
       assetName: 'kin-linux-x86_64',
       archiveName: 'kin-linux-x86_64.tar.gz',
-      binaryName: 'kin'
+      binaryName: PRIMARY_BINARY_NAME,
+      daemonBinaryName: DAEMON_BINARY_NAME
     };
   }
   if (platform === 'linux' && arch === 'arm64') {
     return {
       assetName: 'kin-linux-aarch64',
       archiveName: 'kin-linux-aarch64.tar.gz',
-      binaryName: 'kin'
+      binaryName: PRIMARY_BINARY_NAME,
+      daemonBinaryName: DAEMON_BINARY_NAME
     };
   }
 
@@ -115,11 +122,16 @@ export async function ensureKinBinary({
     cacheRoot
   });
 
-  if (await isRunnable(binaryPath, platform)) {
+  const daemonPath = path.join(path.dirname(binaryPath), DAEMON_BINARY_NAME);
+  if (
+    (await isRunnable(binaryPath, platform)) &&
+    (await isRunnable(daemonPath, platform))
+  ) {
     return binaryPath;
   }
 
   await installKinBinary({ binaryPath, env, platform, arch, version });
+  await assertDaemonProvisioned(binaryPath, platform);
   return binaryPath;
 }
 
@@ -127,6 +139,7 @@ export async function runKinMcp(argv = [], options = {}) {
   const stdout = options.stdout || process.stdout;
   const stderr = options.stderr || process.stderr;
   const env = options.env || process.env;
+  const platform = options.platform || process.platform;
 
   if (argv.includes('--help') || argv.includes('-h')) {
     stdout.write(renderHelp());
@@ -138,9 +151,18 @@ export async function runKinMcp(argv = [], options = {}) {
     return 0;
   }
 
-  if (argv.includes('--print-bin')) {
-    const binaryPath = await ensureKinBinary(options);
-    stdout.write(`${binaryPath}\n`);
+  if (argv.includes('--print-bin') || argv.includes('--print-daemon-bin')) {
+    let binaryPath;
+    try {
+      binaryPath = await ensureKinBinary(options);
+    } catch (error) {
+      stderr.write(`${guidedProvisioningFailure(error)}\n`);
+      return 1;
+    }
+    const target = argv.includes('--print-daemon-bin')
+      ? resolveDaemonBinaryPath(binaryPath)
+      : binaryPath;
+    stdout.write(`${target}\n`);
     return 0;
   }
 
@@ -151,7 +173,18 @@ export async function runKinMcp(argv = [], options = {}) {
     return 2;
   }
 
-  const binaryPath = await ensureKinBinary(options);
+  let binaryPath;
+  try {
+    binaryPath = await ensureKinBinary(options);
+  } catch (error) {
+    stderr.write(`${guidedProvisioningFailure(error)}\n`);
+    return 1;
+  }
+
+  const spawnOptions = {
+    ...options,
+    env: childEnv(env, binaryPath, platform)
+  };
 
   const cwd = options.cwd || process.cwd();
   if (!await kinRepoExists(cwd)) {
@@ -162,14 +195,45 @@ export async function runKinMcp(argv = [], options = {}) {
       return 2;
     }
     stderr.write('No .kin/ found; KIN_MCP_AUTO_INIT=1, running kin init...\n');
-    const initCode = await spawnKin(binaryPath, ['init', '.'], { ...options, cwd });
+    const initCode = await spawnKin(binaryPath, ['init', '.'], { ...spawnOptions, cwd });
     if (initCode !== 0) {
       stderr.write('kin init failed. Cannot start MCP server.\n');
       return initCode;
     }
   }
 
-  return spawnKin(binaryPath, ['mcp', 'start'], options);
+  return spawnKin(binaryPath, ['mcp', 'start'], spawnOptions);
+}
+
+export function resolveDaemonBinaryPath(kinBinaryPath) {
+  return path.join(path.dirname(kinBinaryPath), DAEMON_BINARY_NAME);
+}
+
+export function childEnv(env, kinBinaryPath, platform = process.platform) {
+  const next = { ...env };
+
+  if (!next.KIN_MCP_TOOL_PROFILE) {
+    next.KIN_MCP_TOOL_PROFILE = 'agent-default';
+  }
+
+  const usesManagedBinary = !(env.KIN_MCP_KIN_BINARY || env.KIN_BINARY_PATH);
+  if (usesManagedBinary && !next.KIN_DAEMON_BIN) {
+    next.KIN_DAEMON_BIN = resolveDaemonBinaryPath(kinBinaryPath);
+  }
+
+  return next;
+}
+
+function guidedProvisioningFailure(error) {
+  const detail = error && error.message ? error.message : String(error);
+  return [
+    `kin-mcp could not provision a runnable Kin: ${detail}`,
+    'Fixes:',
+    '  - Install Kin directly and run `kin setup` to configure your agent, then point',
+    '    this wrapper at it with KIN_MCP_KIN_BINARY=/path/to/kin.',
+    '  - Or retry on a supported target (macOS/Linux). On Windows use WSL2 for this alpha.',
+    '  - Or override the release source with KIN_MCP_RELEASE_BASE_URL if you mirror releases.'
+  ].join('\n');
 }
 
 function isTruthyEnv(value) {
@@ -182,25 +246,34 @@ function renderHelp() {
 Usage:
   kin-mcp
   kin-mcp --print-bin
+  kin-mcp --print-daemon-bin
   kin-mcp --version
 
-This wrapper downloads a matching Kin release binary on demand, caches it
-locally, and then runs:
+This wrapper downloads a matching Kin release archive on demand, extracts both
+the kin CLI and the kin-daemon it depends on into a local cache, and then runs:
 
   kin mcp start
 
+It defaults KIN_MCP_TOOL_PROFILE=agent-default so first-run agents see the small
+curated tool surface, and points the kin CLI at the cached kin-daemon via
+KIN_DAEMON_BIN so it never depends on a stale daemon on PATH.
+
 Environment:
-  KIN_MCP_KIN_BINARY   Use a specific kin binary
+  KIN_MCP_KIN_BINARY   Use a specific kin binary (you manage its kin-daemon)
   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_TOOL_PROFILE Override the default agent-default tool profile
   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 { assetName, archiveName, binaryName, daemonBinaryName } = resolveReleaseAsset(
+    platform,
+    arch
+  );
   const tag = resolveReleaseTag(version);
   const baseUrl = (env.KIN_MCP_RELEASE_BASE_URL || DEFAULT_RELEASE_BASE_URL).replace(
     /\/$/,
@@ -227,6 +300,7 @@ async function installKinBinary({ binaryPath, env, platform, arch, version }) {
     archiveName,
     assetName,
     binaryName,
+    daemonBinaryName,
     binaryPath,
     platform
   });
@@ -237,32 +311,82 @@ async function installFromArchive({
   archiveName,
   assetName,
   binaryName,
+  daemonBinaryName,
   binaryPath,
   platform
 }) {
   const tmpRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'kin-mcp-install-'));
   const archivePath = path.join(tmpRoot, archiveName);
-  const tmpPath = `${binaryPath}.download`;
+  const installDir = path.dirname(binaryPath);
+  const daemonPath = path.join(installDir, daemonBinaryName);
+  const staged = [];
 
   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);
+    const kinStaged = await stageBinary({
+      tmpRoot,
+      assetName,
+      sourceName: binaryName,
+      destination: binaryPath,
+      platform,
+      required: true
+    });
+    staged.push(kinStaged);
+
+    const daemonStaged = await stageBinary({
+      tmpRoot,
+      assetName,
+      sourceName: daemonBinaryName,
+      destination: daemonPath,
+      platform,
+      required: true,
+      missingHint:
+        'the published release archive is missing kin-daemon; the daemon is required for MCP'
+    });
+    staged.push(daemonStaged);
+
+    for (const item of staged) {
+      await fsp.rename(item.tmpPath, item.destination);
     }
-    await fsp.rename(tmpPath, binaryPath);
   } catch (error) {
-    await fsp.unlink(tmpPath).catch(() => {});
-    throw new Error(`failed to install ${binaryName} from ${archiveName}: ${error.message}`);
+    await Promise.all(staged.map(item => fsp.unlink(item.tmpPath).catch(() => {})));
+    throw new Error(
+      `failed to install ${binaryName} from ${archiveName}: ${error.message}`
+    );
   } finally {
     await fsp.rm(tmpRoot, { recursive: true, force: true });
   }
 }
 
+async function stageBinary({
+  tmpRoot,
+  assetName,
+  sourceName,
+  destination,
+  platform,
+  required,
+  missingHint
+}) {
+  const extracted = path.join(tmpRoot, assetName, sourceName);
+  try {
+    await fsp.access(extracted, fs.constants.R_OK);
+  } catch {
+    if (required) {
+      throw new Error(missingHint || `archive is missing ${sourceName}`);
+    }
+    return null;
+  }
+
+  const tmpPath = `${destination}.download`;
+  await fsp.copyFile(extracted, tmpPath);
+  if (platform !== 'win32') {
+    await fsp.chmod(tmpPath, 0o755);
+  }
+  return { destination, tmpPath };
+}
+
 function execFile(file, args, options = {}) {
   return new Promise((resolve, reject) => {
     cp.execFile(file, args, options, (error, stdout, stderr) => {
@@ -331,6 +455,15 @@ async function assertRunnable(filePath, platform) {
   }
 }
 
+async function assertDaemonProvisioned(kinBinaryPath, platform) {
+  const daemonPath = resolveDaemonBinaryPath(kinBinaryPath);
+  if (!(await isRunnable(daemonPath, platform))) {
+    throw new Error(
+      `kin-daemon was not provisioned next to ${kinBinaryPath}; the MCP server cannot start without it`
+    );
+  }
+}
+
 async function isRunnable(filePath, platform) {
   try {
     const mode = platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK;