@aikdna/kdna-mcp-server 0.1.0 → 0.2.0

package/README.md

@@ -18,6 +18,7 @@ The `kdna-loader` skill teaches an agent the full KDNA protocol (7-part routing,
 |------|---------|-------|--------|
 | `kdna.inspect` | Inspect a v1 `.kdna` asset or legacy asset | File path | Structured metadata |
 | `kdna.verify` | Verify asset integrity state | File path | Pass/fail with reasons |
+| `kdna.plan-load` | Return Core LoadPlan before loading | File path, optional password or entitlement state | LoadPlan JSON |
 | `kdna.load` | Load and render a `.kdna` profile for agent context | File path, optional profile | Prompt-mode text or raw JSON |
 | `kdna.available-local` | List local v1 `.kdna` assets without registry dependency | Root directory | Local v1 asset inventory |
 | `kdna.match` | Rank candidate assets for a task string | Task description | Scored list with fit signals |
@@ -92,6 +93,8 @@ node bin/kdna-mcp.mjs
 ```
 # Client calls kdna.available-local { root: "./dist" }
 # Client calls kdna.verify { assetPath: "./dist/writing.kdna" }
+# Client calls kdna.plan-load { assetPath: "./dist/writing.kdna" }
+# Or kdna.plan-load { assetPath: "./dist/writing.kdna", entitlementStatus: "active" }
 # Client calls kdna.load { assetPath: "./dist/writing.kdna", profile: "compact" }
 # Agent injects prompt text into system context
 ```

package/bin/kdna-mcp.mjs

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline';
+import { spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
@@ -10,6 +11,7 @@ const {
   inspectKDNA,
   loadKDNA,
   matchDomain,
+  planLoad,
   renderForAgent,
   verifyAsset,
 } = require('@aikdna/kdna-core');
@@ -58,6 +60,19 @@ const tools = [
       },
     },
   },
+  {
+    name: 'kdna.plan-load',
+    description: 'Return the Core LoadPlan for a .kdna asset before loading.',
+    inputSchema: {
+      type: 'object',
+      required: ['assetPath'],
+      properties: {
+        assetPath: { type: 'string' },
+        hasPassword: { type: 'boolean' },
+        entitlementStatus: { type: 'string', enum: ['active', 'expired', 'revoked', 'offline_grace'] },
+      },
+    },
+  },
   {
     name: 'kdna.available-local',
     description: 'List local v1 .kdna assets or v1 source directories without using a registry.',
@@ -191,6 +206,43 @@ function listRegistry(registryFile) {
   }));
 }
 
+function runCliPlanLoad(args = {}) {
+  const cliArgs = ['plan-load', args.assetPath, '--json'];
+  if (args.hasPassword) cliArgs.push('--has-password');
+  if (args.entitlementStatus) cliArgs.push('--entitlement-status', args.entitlementStatus);
+
+  const result = spawnSync('kdna', cliArgs, {
+    encoding: 'utf8',
+    timeout: 30_000,
+  });
+
+  if (result.error) {
+    throw new Error(`Core planLoad is unavailable and kdna CLI failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new Error(`Core planLoad is unavailable and kdna CLI exited ${result.status}: ${result.stderr || result.stdout}`);
+  }
+
+  try {
+    return JSON.parse(result.stdout);
+  } catch (error) {
+    throw new Error(`Core planLoad is unavailable and kdna CLI returned non-JSON output: ${error.message}`);
+  }
+}
+
+function planLoadThroughCoreOrCli(args = {}) {
+  if (!args.assetPath) throw new Error('assetPath is required');
+
+  if (typeof planLoad === 'function' && process.env.KDNA_MCP_FORCE_CLI_PLAN_LOAD !== '1') {
+    return planLoad(args.assetPath, {
+      hasPassword: Boolean(args.hasPassword),
+      entitlement: args.entitlementStatus ? { status: args.entitlementStatus } : undefined,
+    });
+  }
+
+  return runCliPlanLoad(args);
+}
+
 async function callTool(name, args = {}) {
   if (name === 'kdna.inspect') {
     if (isV1Asset(args.assetPath)) return textResult(inspectV1(args.assetPath));
@@ -217,6 +269,9 @@ async function callTool(name, args = {}) {
       : await renderForAgent(args.assetPath, { profile: args.profile || 'compact', input: args.input || '' });
     return textResult({ ...loaded, context });
   }
+  if (name === 'kdna.plan-load') {
+    return textResult(planLoadThroughCoreOrCli(args));
+  }
   if (name === 'kdna.match') {
     return textResult(await matchDomain(args.input || '', args.assetPaths || []));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-mcp-server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for loading, inspecting, verifying, and matching KDNA .kdna assets.",
   "type": "module",
   "bin": {
@@ -11,7 +11,7 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@aikdna/kdna-core": "^0.11.1",
+    "@aikdna/kdna-core": "^0.12.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   },

package/test/mcp-v1.test.mjs

@@ -11,7 +11,7 @@ const { buildChecksumsV1 } = require('@aikdna/kdna-core/v1');
 
 const server = path.join(process.cwd(), 'bin', 'kdna-mcp.mjs');
 
-function callTool(name, args) {
+function callTool(name, args, options = {}) {
   const request = {
     jsonrpc: '2.0',
     id: 1,
@@ -21,6 +21,7 @@ function callTool(name, args) {
   const r = spawnSync(process.execPath, [server], {
     input: `${JSON.stringify(request)}\n`,
     encoding: 'utf8',
+    env: options.env || process.env,
   });
   assert.equal(r.status, 0, r.stderr);
   const response = JSON.parse(r.stdout.trim());
@@ -28,6 +29,18 @@ function callTool(name, args) {
   return JSON.parse(response.result.content[0].text);
 }
 
+function listTools() {
+  const request = { jsonrpc: '2.0', id: 1, method: 'tools/list' };
+  const r = spawnSync(process.execPath, [server], {
+    input: `${JSON.stringify(request)}\n`,
+    encoding: 'utf8',
+  });
+  assert.equal(r.status, 0, r.stderr);
+  const response = JSON.parse(r.stdout.trim());
+  assert.ok(!response.error, response.error && response.error.message);
+  return response.result.tools;
+}
+
 function makeV1Source(root) {
   const dir = path.join(root, 'writing');
   fs.mkdirSync(dir, { recursive: true });
@@ -91,3 +104,69 @@ test('available-local discovers v1 source dirs and load returns prompt context',
     fs.rmSync(root, { recursive: true, force: true });
   }
 });
+
+test('plan-load uses the Core API when available', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kdna-mcp-plan-core-'));
+  try {
+    const assetPath = makeV1Source(root);
+    const tools = listTools();
+    assert.ok(tools.some((tool) => tool.name === 'kdna.plan-load'));
+
+    const plan = callTool('kdna.plan-load', { assetPath });
+
+    assert.equal(plan.state, 'ready');
+    assert.equal(plan.required_action, 'load');
+    assert.equal(plan.can_load_now, true);
+    assert.equal(plan.asset.asset_id, 'kdna:test:writing');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('plan-load can fall back to the official CLI when Core API is unavailable', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kdna-mcp-plan-'));
+  try {
+    const assetPath = makeV1Source(root);
+    const binDir = path.join(root, 'bin');
+    const argvFile = path.join(root, 'argv.json');
+    fs.mkdirSync(binDir);
+    const kdnaBin = path.join(binDir, 'kdna');
+    fs.writeFileSync(kdnaBin, `#!/usr/bin/env node
+const fs = require('node:fs');
+fs.writeFileSync(${JSON.stringify(argvFile)}, JSON.stringify(process.argv.slice(2)));
+console.log(JSON.stringify({
+  state: "ready",
+  required_action: "none",
+  can_load_now: true,
+  issues: [{ code: "KDNA_OK" }],
+  asset: { source: process.argv[3] }
+}));
+`);
+    fs.chmodSync(kdnaBin, 0o755);
+
+    const tools = listTools();
+    assert.ok(tools.some((tool) => tool.name === 'kdna.plan-load'));
+
+    const plan = callTool('kdna.plan-load', { assetPath, hasPassword: true, entitlementStatus: 'active' }, {
+      env: {
+        ...process.env,
+        KDNA_MCP_FORCE_CLI_PLAN_LOAD: '1',
+        PATH: `${binDir}${path.delimiter}${process.env.PATH || ''}`,
+      },
+    });
+
+    assert.equal(plan.state, 'ready');
+    assert.equal(plan.required_action, 'none');
+    assert.equal(plan.can_load_now, true);
+    assert.deepEqual(JSON.parse(fs.readFileSync(argvFile, 'utf8')), [
+      'plan-load',
+      assetPath,
+      '--json',
+      '--has-password',
+      '--entitlement-status',
+      'active',
+    ]);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});