@aikdna/kdna-mcp-server 0.4.0 → 0.4.2

package/README.md

@@ -22,13 +22,18 @@ server provides a lower-level bridge for structured tool calls.
 |------|---------|-------|--------|
 | `kdna.inspect` | Inspect a `.kdna` 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.plan-load` | Return Core LoadPlan before loading | File path, optional password-presence or entitlement state | LoadPlan JSON |
 | `kdna.load` | Load an authorized `.kdna` profile | File path, optional profile, password, or entitlement state | Runtime Capsule |
 | `kdna.available-local` | List local `.kdna` assets | Root directory | Local asset inventory |
 | `kdna.match` | Rank candidate assets for a task string | Task description | Scored list with fit signals |
 
 ## Install & Run
 
+The commands below currently resolve the published MCP 0.4.1 package. They do
+not install or prove the MCP 0.4.2 / Core 0.20.0 source checkpoint described in
+this repository's current changelog; those candidates must remain a coordinated
+package set and must not be mixed with the published wave.
+
 ```bash
 npm install -g @aikdna/kdna-mcp-server
 kdna-mcp
@@ -106,6 +111,14 @@ node bin/kdna-mcp.mjs
 # Agent consumes only the returned Runtime Capsule context
 ```
 
+In the 0.4.2 source checkpoint, the returned Capsule uses
+`type: "kdna.runtime-capsule"` and
+`contract_version: "0.1.0"`. The KDNA Agent Host protocol has the independent
+coordinate `protocol_version: "0.1.0"`; it is not the MCP transport's
+`protocolVersion`. This bridge does not execute an Agent Host and therefore
+does not create or claim a Host receipt or Judgment Trace. A consuming Host
+must use Core's correlated runtime-contract APIs for that boundary.
+
 ## Relationship to kdna-loader skill
 
 The MCP server and kdna-loader skill are complementary:

package/bin/kdna-mcp.mjs

@@ -7,6 +7,10 @@ import { spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
+const Ajv = require('ajv');
+const Ajv2020 = require('ajv/dist/2020');
+const addFormats = require('ajv-formats');
+const loadPlanSchema = require('@aikdna/kdna-core/schema/load-plan.schema.json');
 const packageInfo = require('../package.json');
 const {
   detectContainerFormat,
@@ -23,6 +27,7 @@ const tools = [
     description: 'Inspect a .kdna asset without extracting it.',
     inputSchema: {
       type: 'object',
+      additionalProperties: false,
       required: ['assetPath'],
       properties: { assetPath: { type: 'string' }, verify: { type: 'boolean' } },
     },
@@ -32,6 +37,7 @@ const tools = [
     description: 'Verify a .kdna asset integrity state.',
     inputSchema: {
       type: 'object',
+      additionalProperties: false,
       required: ['assetPath'],
       properties: {
         assetPath: { type: 'string' },
@@ -46,6 +52,7 @@ const tools = [
     description: 'Load a .kdna profile and return agent context.',
     inputSchema: {
       type: 'object',
+      additionalProperties: false,
       required: ['assetPath'],
       properties: {
         assetPath: { type: 'string' },
@@ -61,6 +68,7 @@ const tools = [
     description: 'Return the Core LoadPlan for a .kdna asset before loading.',
     inputSchema: {
       type: 'object',
+      additionalProperties: false,
       required: ['assetPath'],
       properties: {
         assetPath: { type: 'string' },
@@ -74,9 +82,10 @@ const tools = [
     description: 'List local .kdna files without using a registry.',
     inputSchema: {
       type: 'object',
+      additionalProperties: false,
       properties: {
         root: { type: 'string' },
-        maxDepth: { type: 'number' },
+        maxDepth: { type: 'integer', minimum: 0 },
       },
     },
   },
@@ -85,6 +94,7 @@ const tools = [
     description: 'Rank .kdna assets for a task string.',
     inputSchema: {
       type: 'object',
+      additionalProperties: false,
       required: ['input', 'assetPaths'],
       properties: {
         input: { type: 'string' },
@@ -94,11 +104,52 @@ const tools = [
   },
 ];
 
-function send(id, result, error) {
-  const msg = error
-    ? { jsonrpc: '2.0', id, error: { code: -32000, message: error.message || String(error) } }
-    : { jsonrpc: '2.0', id, result };
-  process.stdout.write(`${JSON.stringify(msg)}\n`);
+const ajv = new Ajv({ allErrors: true, strict: false });
+const toolValidators = new Map(tools.map((tool) => [tool.name, ajv.compile(tool.inputSchema)]));
+const contractAjv = new Ajv2020({ allErrors: true, strict: false });
+addFormats(contractAjv);
+const validateLoadPlan = contractAjv.compile(loadPlanSchema);
+
+class JsonRpcError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function validatedJsonRpcMessage(message) {
+  if (!message || typeof message !== 'object' || Array.isArray(message)) {
+    throw new JsonRpcError(-32600, 'Invalid Request');
+  }
+  if (message.jsonrpc !== '2.0' || typeof message.method !== 'string') {
+    throw new JsonRpcError(-32600, 'Invalid Request');
+  }
+
+  const hasId = Object.prototype.hasOwnProperty.call(message, 'id');
+  if (hasId) {
+    const validId =
+      typeof message.id === 'string' ||
+      (typeof message.id === 'number' && Number.isFinite(message.id));
+    if (!validId) throw new JsonRpcError(-32600, 'Invalid Request');
+  }
+
+  return {
+    id: message.id,
+    method: message.method,
+    params: message.params === undefined ? {} : message.params,
+    paramsValid:
+      message.params === undefined ||
+      (message.params !== null && typeof message.params === 'object' && !Array.isArray(message.params)),
+    isNotification: !hasId,
+  };
+}
+
+function sendResult(id, result) {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, result })}\n`);
+}
+
+function sendError(id, code, message) {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } })}\n`);
 }
 
 function textResult(value) {
@@ -107,6 +158,26 @@ function textResult(value) {
   };
 }
 
+function toolErrorResult(error) {
+  return {
+    content: [{ type: 'text', text: error?.message || String(error) }],
+    isError: true,
+  };
+}
+
+function validatedToolCall(params) {
+  if (!params || typeof params !== 'object' || Array.isArray(params)) {
+    throw new JsonRpcError(-32602, 'Invalid params');
+  }
+  if (typeof params.name !== 'string' || !toolValidators.has(params.name)) {
+    throw new JsonRpcError(-32602, 'Invalid params');
+  }
+  const args = params.arguments === undefined ? {} : params.arguments;
+  const validateInput = toolValidators.get(params.name);
+  if (!validateInput(args)) throw new JsonRpcError(-32602, 'Invalid params');
+  return { name: params.name, args };
+}
+
 function isKdnaAsset(assetPath) {
   if (!assetPath) return false;
   try {
@@ -139,20 +210,35 @@ function findLocalAssets(root = defaultAssetRoot(), maxDepth = 3) {
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) {
         visit(full, depth + 1);
-      } else if (entry.isFile() && entry.name.endsWith('.kdna') && detectContainerFormat(full) === 'kdna') {
-        const inspection = inspect(full);
-        const validation = validate(full);
-        found.push({
-          path: full,
-          kind: 'kdna_asset',
-          asset_id: inspection.asset_id,
-          title: inspection.title,
-          version: inspection.version,
-          judgment_version: inspection.judgment_version,
-          checksums_present: Boolean(inspection.checksums_present),
-          loadable: Boolean(validation.overall_valid),
-          problems: validation.overall_valid ? [] : validation.problems || [],
-        });
+      } else if (entry.isFile() && entry.name.endsWith('.kdna')) {
+        try {
+          if (detectContainerFormat(full) !== 'kdna') continue;
+          const inspection = inspect(full);
+          const validation = validate(full);
+          found.push({
+            path: full,
+            kind: 'kdna_asset',
+            asset_id: inspection.asset_id,
+            title: inspection.title,
+            version: inspection.version,
+            judgment_version: inspection.judgment_version,
+            checksums_present: Boolean(inspection.checksums_present),
+            loadable: Boolean(validation.overall_valid),
+            problems: validation.overall_valid ? [] : validation.problems || [],
+          });
+        } catch {
+          found.push({
+            path: full,
+            kind: 'kdna_asset',
+            asset_id: null,
+            title: null,
+            version: null,
+            judgment_version: null,
+            checksums_present: false,
+            loadable: false,
+            problems: ['KDNA_ASSET_INVALID'],
+          });
+        }
       }
     }
   }
@@ -174,15 +260,31 @@ function runCliPlanLoad(args = {}) {
   if (result.error) {
     throw new Error(`Core planLoad is unavailable and kdna CLI failed: ${result.error.message}`);
   }
+  if (result.status !== 0 && result.status !== 3) {
+    throw new Error(`Core planLoad is unavailable and kdna CLI exited ${result.status}`);
+  }
+  let plan;
   try {
-    if (result.stdout && result.stdout.trim()) return JSON.parse(result.stdout);
+    if (result.stdout && result.stdout.trim()) plan = JSON.parse(result.stdout);
   } catch (error) {
     throw new Error(`Core planLoad is unavailable and kdna CLI returned non-JSON output: ${error.message}`);
   }
-  if (result.status !== 0) {
-    throw new Error(`Core planLoad is unavailable and kdna CLI exited ${result.status}: ${result.stderr || result.stdout}`);
+  if (!validateLoadPlan(plan)) {
+    throw new Error('Core planLoad is unavailable and kdna CLI returned an invalid LoadPlan');
   }
-  throw new Error('Core planLoad is unavailable and kdna CLI returned empty output');
+  if (
+    plan.source.kind !== 'file' ||
+    path.resolve(plan.source.path) !== path.resolve(args.assetPath)
+  ) {
+    throw new Error('Core planLoad is unavailable and kdna CLI returned an uncorrelated LoadPlan');
+  }
+  if (result.status === 0 && plan.can_load_now !== true) {
+    throw new Error('Core planLoad is unavailable and kdna CLI returned a non-loadable success');
+  }
+  if (result.status === 3 && plan.can_load_now !== false) {
+    throw new Error('Core planLoad is unavailable and kdna CLI returned a loadable denial');
+  }
+  return plan;
 }
 
 function planLoadThroughCoreOrCli(args = {}) {
@@ -228,15 +330,14 @@ async function callTool(name, args = {}) {
     return textResult(await matchDomain(args.input || '', args.assetPaths || []));
   }
   if (name === 'kdna.available-local') {
-    return textResult(findLocalAssets(args.root, args.maxDepth || 3));
+    return textResult(findLocalAssets(args.root, args.maxDepth ?? 3));
   }
   throw new Error(`Unknown tool: ${name}`);
 }
 
-async function handle(message) {
-  const { id, method, params = {} } = message;
+async function handle({ id, method, params }) {
   if (method === 'initialize') {
-    send(id, {
+    sendResult(id, {
       protocolVersion: '2024-11-05',
       capabilities: { tools: {} },
       serverInfo: { name: '@aikdna/kdna-mcp-server', version: packageInfo.version },
@@ -244,14 +345,28 @@ async function handle(message) {
     return;
   }
   if (method === 'tools/list') {
-    send(id, { tools });
+    sendResult(id, { tools });
     return;
   }
   if (method === 'tools/call') {
-    send(id, await callTool(params.name, params.arguments || {}));
+    let call;
+    try {
+      call = validatedToolCall(params);
+    } catch (error) {
+      if (error instanceof JsonRpcError) {
+        sendError(id, error.code, error.message);
+        return;
+      }
+      throw error;
+    }
+    try {
+      sendResult(id, await callTool(call.name, call.args));
+    } catch (error) {
+      sendResult(id, toolErrorResult(error));
+    }
     return;
   }
-  if (id !== undefined) send(id, {});
+  if (id !== undefined) sendError(id, -32601, 'Method not found');
 }
 
 const rl = readline.createInterface({ input: process.stdin });
@@ -260,8 +375,31 @@ rl.on('line', async (line) => {
   let message;
   try {
     message = JSON.parse(line);
-    await handle(message);
-  } catch (e) {
-    send(message?.id ?? null, null, e);
+  } catch {
+    sendError(null, -32700, 'Parse error');
+    return;
+  }
+
+  let request;
+  try {
+    request = validatedJsonRpcMessage(message);
+  } catch (error) {
+    if (error instanceof JsonRpcError) {
+      sendError(null, error.code, error.message);
+      return;
+    }
+    sendError(null, -32603, 'Internal error');
+    return;
+  }
+
+  if (request.isNotification) return;
+  if (!request.paramsValid) {
+    sendError(request.id, -32602, 'Invalid params');
+    return;
+  }
+  try {
+    await handle(request);
+  } catch {
+    sendError(request.id, -32603, 'Internal error');
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-mcp-server",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "MCP server for loading, inspecting, verifying, and matching KDNA .kdna assets.",
   "type": "module",
   "homepage": "https://aikdna.com",
@@ -29,12 +29,18 @@
     "NOTICE"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "prepublishOnly": "npm test && node ../scripts/release-check.js"
+    "test": "node scripts/verify-core-candidate.mjs && node ../scripts/check-current-names.mjs && node --test test/*.test.mjs",
+    "check:core-candidate": "node scripts/verify-core-candidate.mjs",
+    "check:current-names": "node ../scripts/check-current-names.mjs",
+    "naming:check": "node ../scripts/check-current-names.mjs",
+    "release:check": "node ../scripts/release-check.js",
+    "release:dependency-guard": "node ../scripts/release-dependency-guard.js",
+    "release:preflight": "node ../scripts/release-preflight.js",
+    "prepublishOnly": "npm test && npm run release:check && npm run release:dependency-guard"
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@aikdna/kdna-core": "0.16.0",
+    "@aikdna/kdna-core": "0.20.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   },