@aikdna/kdna-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# KDNA MCP Server
+
+`@aikdna/kdna-mcp-server` exposes KDNA as MCP tools so agent runtimes can use
+`.kdna` assets without learning the container internals. Stdio-only, minimal footprint.
+
+## Why MCP instead of the kdna-loader skill?
+
+The `kdna-loader` skill teaches an agent the full KDNA protocol (7-part routing, silent loading, boundary respect). The MCP server provides a lower-level bridge — use it when you need programmatic access to `.kdna` assets through structured tool calls rather than letting the agent drive the CLI.
+
+| Approach | Best for |
+|----------|----------|
+| `kdna-loader` skill | Full KDNA protocol: routing, fit evaluation, silent application |
+| MCP server | Programmatic inspect/verify/load/match from any MCP-compatible runtime |
+
+## Tools
+
+| Tool | Purpose | Input | Output |
+|------|---------|-------|--------|
+| `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.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 |
+| `kdna.available` | Legacy registry compatibility only | `domains.json` path | Legacy domain list |
+
+## Install & Run
+
+```bash
+npm install -g @aikdna/kdna-mcp-server
+kdna-mcp
+```
+
+### Configure in your MCP client
+
+**Claude App / Claude Code (`claude_desktop_config.json`):**
+
+```json
+{
+  "mcpServers": {
+    "kdna": {
+      "command": "npx",
+      "args": ["-y", "@aikdna/kdna-mcp-server"]
+    }
+  }
+}
+```
+
+**Codex:**
+
+```json
+{
+  "mcpServers": {
+    "kdna": {
+      "command": "npx",
+      "args": ["-y", "@aikdna/kdna-mcp-server"]
+    }
+  }
+}
+```
+
+**OpenCode (`opencode.json`):**
+
+```json
+{
+  "mcpServers": {
+    "kdna": {
+      "command": "npx",
+      "args": ["-y", "@aikdna/kdna-mcp-server"]
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `KDNA_ASSET_DIR` | Root directory for `kdna.available-local` (default: `~/.kdna/assets`) |
+| `KDNA_REGISTRY_FILE` | Legacy path to `domains.json` for `kdna.available` |
+| `KDNA_DATA_ROOT` | Override KDNA data directory (default: `~/.kdna`) |
+
+## Local Development
+
+```bash
+cd mcp-server
+npm install
+node bin/kdna-mcp.mjs
+```
+
+## Example: Verify and Load a Domain via MCP
+
+```
+# Client calls kdna.available-local { root: "./dist" }
+# Client calls kdna.verify { assetPath: "./dist/writing.kdna" }
+# Client calls kdna.load { assetPath: "./dist/writing.kdna", profile: "compact" }
+# Agent injects prompt text into system context
+```
+
+## Relationship to kdna-loader skill
+
+The MCP server and kdna-loader skill are complementary:
+- **kdna-loader** = agents that can run CLI commands (Codex, Claude Code, OpenCode, Cursor)
+- **MCP server** = any MCP-compatible runtime (including the above, plus custom agents)
+
+For most users, the kdna-loader skill (installed by `kdna setup`) is the recommended path. Use the MCP server when you need programmatic, tool-based access.

package/bin/kdna-mcp.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const {
+  inspectKDNA,
+  loadKDNA,
+  matchDomain,
+  renderForAgent,
+  verifyAsset,
+} = require('@aikdna/kdna-core');
+const {
+  detectContainerFormat,
+  inspect: inspectV1,
+  isV1SourceDir,
+  loadV1,
+  validate: validateV1,
+} = require('@aikdna/kdna-core/v1');
+
+const tools = [
+  {
+    name: 'kdna.inspect',
+    description: 'Inspect a .kdna asset without extracting it.',
+    inputSchema: {
+      type: 'object',
+      required: ['assetPath'],
+      properties: { assetPath: { type: 'string' }, verify: { type: 'boolean' } },
+    },
+  },
+  {
+    name: 'kdna.verify',
+    description: 'Verify a .kdna asset integrity state.',
+    inputSchema: {
+      type: 'object',
+      required: ['assetPath'],
+      properties: {
+        assetPath: { type: 'string' },
+        asset_digest: { type: 'string' },
+        content_digest: { type: 'string' },
+        requireSignature: { type: 'boolean' },
+      },
+    },
+  },
+  {
+    name: 'kdna.load',
+    description: 'Load a .kdna profile and return agent context.',
+    inputSchema: {
+      type: 'object',
+      required: ['assetPath'],
+      properties: {
+        assetPath: { type: 'string' },
+        profile: { type: 'string', enum: ['index', 'compact', 'scenario', 'full'] },
+        input: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'kdna.available-local',
+    description: 'List local v1 .kdna assets or v1 source directories without using a registry.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        root: { type: 'string' },
+        maxDepth: { type: 'number' },
+      },
+    },
+  },
+  {
+    name: 'kdna.match',
+    description: 'Rank .kdna assets for a task string.',
+    inputSchema: {
+      type: 'object',
+      required: ['input', 'assetPaths'],
+      properties: {
+        input: { type: 'string' },
+        assetPaths: { type: 'array', items: { type: 'string' } },
+      },
+    },
+  },
+  {
+    name: 'kdna.available',
+    description: 'Legacy: list assets from a local Registry domains.json file.',
+    inputSchema: {
+      type: 'object',
+      properties: { registryFile: { type: 'string' } },
+    },
+  },
+];
+
+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`);
+}
+
+function textResult(value) {
+  return {
+    content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }],
+  };
+}
+
+function isV1Asset(assetPath) {
+  if (!assetPath) return false;
+  try {
+    if (fs.existsSync(assetPath) && fs.statSync(assetPath).isDirectory()) {
+      return isV1SourceDir(assetPath);
+    }
+    return detectContainerFormat(assetPath) === 'v1';
+  } catch {
+    return false;
+  }
+}
+
+function defaultAssetRoot() {
+  return process.env.KDNA_ASSET_DIR || path.join(os.homedir(), '.kdna', 'assets');
+}
+
+function findLocalAssets(root = defaultAssetRoot(), maxDepth = 3) {
+  if (!root || !fs.existsSync(root)) return [];
+  const found = [];
+
+  function visit(dir, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    if (isV1SourceDir(dir)) {
+      const inspection = inspectV1(dir);
+      const validation = validateV1(dir);
+      found.push({
+        path: dir,
+        kind: 'v1_source_dir',
+        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 || [],
+      });
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(full, depth + 1);
+      } else if (entry.isFile() && entry.name.endsWith('.kdna') && detectContainerFormat(full) === 'v1') {
+        const inspection = inspectV1(full);
+        const validation = validateV1(full);
+        found.push({
+          path: full,
+          kind: 'v1_container',
+          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 || [],
+        });
+      }
+    }
+  }
+
+  visit(path.resolve(root), 0);
+  return found;
+}
+
+function listRegistry(registryFile) {
+  const file = registryFile || process.env.KDNA_REGISTRY_FILE;
+  if (!file) return [];
+  const registry = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const domains = Array.isArray(registry.domains) ? registry.domains : Object.values(registry.domains || {});
+  return domains.map((d) => ({
+    legacy_registry: true,
+    name: d.name,
+    version: d.version,
+    asset_url: d.asset_url,
+    asset_digest: d.asset_digest,
+  }));
+}
+
+async function callTool(name, args = {}) {
+  if (name === 'kdna.inspect') {
+    if (isV1Asset(args.assetPath)) return textResult(inspectV1(args.assetPath));
+    return textResult(await inspectKDNA(args.assetPath, { verify: args.verify !== false }));
+  }
+  if (name === 'kdna.verify') {
+    if (isV1Asset(args.assetPath)) return textResult(validateV1(args.assetPath));
+    return textResult(await verifyAsset(args.assetPath, {
+      asset_digest: args.asset_digest,
+      content_digest: args.content_digest,
+      requireSignature: Boolean(args.requireSignature),
+    }));
+  }
+  if (name === 'kdna.load') {
+    if (isV1Asset(args.assetPath)) {
+      const profile = args.profile || 'compact';
+      const loaded = loadV1(args.assetPath, { profile, as: 'json' });
+      const prompt = profile === 'index' ? null : loadV1(args.assetPath, { profile, as: 'prompt' }).text;
+      return textResult({ ...loaded, context: prompt });
+    }
+    const loaded = await loadKDNA(args.assetPath, { profile: args.profile || 'compact', input: args.input || '' });
+    const context = args.profile === 'index'
+      ? null
+      : await renderForAgent(args.assetPath, { profile: args.profile || 'compact', input: args.input || '' });
+    return textResult({ ...loaded, context });
+  }
+  if (name === 'kdna.match') {
+    return textResult(await matchDomain(args.input || '', args.assetPaths || []));
+  }
+  if (name === 'kdna.available-local') {
+    return textResult(findLocalAssets(args.root, args.maxDepth || 3));
+  }
+  if (name === 'kdna.available') {
+    return textResult(listRegistry(args.registryFile));
+  }
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+async function handle(message) {
+  const { id, method, params = {} } = message;
+  if (method === 'initialize') {
+    send(id, {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: { name: '@aikdna/kdna-mcp-server', version: '0.1.0' },
+    });
+    return;
+  }
+  if (method === 'tools/list') {
+    send(id, { tools });
+    return;
+  }
+  if (method === 'tools/call') {
+    send(id, await callTool(params.name, params.arguments || {}));
+    return;
+  }
+  if (id !== undefined) send(id, {});
+}
+
+const rl = readline.createInterface({ input: process.stdin });
+rl.on('line', async (line) => {
+  if (!line.trim()) return;
+  try {
+    await handle(JSON.parse(line));
+  } catch (e) {
+    send(undefined, null, e);
+  }
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@aikdna/kdna-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for loading, inspecting, verifying, and matching KDNA .kdna assets.",
+  "type": "module",
+  "bin": {
+    "kdna-mcp": "bin/kdna-mcp.mjs"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@aikdna/kdna-core": "^0.11.1",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/test/mcp-v1.test.mjs

@@ -0,0 +1,93 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { buildChecksumsV1 } = require('@aikdna/kdna-core/v1');
+
+const server = path.join(process.cwd(), 'bin', 'kdna-mcp.mjs');
+
+function callTool(name, args) {
+  const request = {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'tools/call',
+    params: { name, arguments: args },
+  };
+  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 JSON.parse(response.result.content[0].text);
+}
+
+function makeV1Source(root) {
+  const dir = path.join(root, 'writing');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'mimetype'), 'application/vnd.kdna.asset');
+  fs.writeFileSync(path.join(dir, 'kdna.json'), JSON.stringify({
+    kdna_version: '1.0',
+    asset_id: 'kdna:test:writing',
+    asset_uid: 'urn:uuid:11111111-1111-4111-8111-111111111111',
+    asset_type: 'domain',
+    title: 'Test Writing',
+    version: '1.0.0',
+    judgment_version: '1.0.0',
+    created_at: '2026-06-18T00:00:00.000Z',
+    updated_at: '2026-06-18T00:00:00.000Z',
+    creator: { name: 'MCP Test', id: 'mcp-test' },
+    lineage: { type: 'original', fork_of: null, derived_from: null },
+    payload: { path: 'payload.kdnab', encoding: 'json', encrypted: false },
+    compatibility: { min_loader_version: '1.0.0', profile: 'judgment-profile-v1' },
+    load_contract: {
+      default_profile: 'compact',
+      profiles: {
+        index: { requires_decryption: false, max_tokens_hint: 200 },
+        compact: { requires_decryption: false, max_tokens_hint: 2000 },
+        scenario: { requires_decryption: false, selection: 'triggered_sections_only' },
+        full: { requires_decryption: false, intended_for: ['audit'] },
+      },
+    },
+  }, null, 2));
+  fs.writeFileSync(path.join(dir, 'payload.kdnab'), JSON.stringify({
+    profile: 'judgment-profile-v1',
+    core: {
+      highest_question: 'What makes this writing judgment useful?',
+      axioms: [{ id: 'ax1', one_sentence: 'Structure before wording.' }],
+      boundaries: [{ type: 'stance_boundary', stance: 'Do not polish before diagnosis.' }],
+      risk_model: {},
+    },
+    patterns: [],
+    scenarios: [],
+    cases: [],
+    reasoning: { self_checks: ['Did I diagnose before editing?'], failure_modes: [] },
+  }, null, 2));
+  fs.writeFileSync(path.join(dir, 'checksums.json'), JSON.stringify(buildChecksumsV1(dir), null, 2));
+  return dir;
+}
+
+test('available-local discovers v1 source dirs and load returns prompt context', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kdna-mcp-v1-'));
+  try {
+    makeV1Source(root);
+    const available = callTool('kdna.available-local', { root, maxDepth: 1 });
+    assert.equal(available.length, 1);
+    assert.equal(available[0].asset_id, 'kdna:test:writing');
+    assert.equal(available[0].loadable, true, JSON.stringify(available[0]));
+    assert.equal(Object.prototype.hasOwnProperty.call(available[0], 'quality_badge'), false);
+
+    const loaded = callTool('kdna.load', { assetPath: path.join(root, 'writing'), profile: 'compact' });
+    assert.equal(loaded.asset_id, 'kdna:test:writing');
+    assert.match(loaded.context, /Structure before wording/);
+    assert.match(loaded.context, /Do not polish before diagnosis/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});