@arkheia/mcp-server 0.1.9 → 0.1.10

package/CLAUDE_MD_TEMPLATE.md

@@ -0,0 +1,33 @@
+# Fabrication Detection — Arkheia
+
+When Arkheia MCP tools are available in this session, follow this protocol.
+
+## Detection
+
+Call `arkheia_verify` on EVERY model response before surfacing it to the user. Do not skip responses that appear obviously correct.
+
+## Risk Escalation
+
+- **HIGH risk**: Warn the user that the response may be fabricated. Include the `detection_id`. Still show the response — never hide or suppress it. Ask the user if they want to verify with a different model.
+- **MEDIUM risk**: Show the response with a brief confidence note.
+- **LOW risk**: Show normally.
+- **UNKNOWN risk**: Flag for human review. Include the `detection_id`.
+
+## Cross-Model Verification
+
+When HIGH or UNKNOWN risk is detected, offer to verify using: `run_grok`, `run_gemini`, `run_ollama`, `run_together`.
+
+## Audit Trail
+
+Use `arkheia_audit_log` when the user asks about detection history or for compliance evidence.
+
+## Persistent Knowledge Graph
+
+Use `memory_store` to persist facts, `memory_retrieve` to recall them, `memory_relate` to track relationships between entities.
+
+## Key Rules
+
+1. Never hide a response from the user regardless of risk level
+2. Always include the `detection_id` when reporting HIGH or UNKNOWN risk
+3. Call `arkheia_verify` proactively — do not wait for the user to ask
+4. Audit logging happens automatically through `arkheia_verify`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkheia/mcp-server",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Arkheia MCP Server — Fabrication detection for AI agents. Know when your AI is making things up.",
   "main": "dist/index.js",
   "bin": {
@@ -16,7 +16,7 @@
     "dist/",
     "scripts/",
     "README.md",
-    "ARKHEIA_CLAUDE.md"
+    "CLAUDE_MD_TEMPLATE.md"
   ],
   "keywords": [
     "mcp",

package/scripts/setup.js

@@ -1,151 +1,241 @@
-#!/usr/bin/env node
-/**
- * Post-install script — verifies Python is available and prints setup instructions.
- * Does NOT auto-install Python dependencies (that happens on first run).
- */
-
-const { execSync } = require("child_process");
-const fs = require("fs");
-const path = require("path");
-
-const ARKHEIA_DIR = path.join(
-  process.env.HOME || process.env.USERPROFILE || "/tmp",
-  ".arkheia"
-);
-const CONFIG_FILE = path.join(ARKHEIA_DIR, "config.json");
-
-function checkApiKey() {
-  // Check if config.json exists and has api_key
-  try {
-    if (fs.existsSync(CONFIG_FILE)) {
-      const config = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
-      if (config.api_key && config.api_key.length > 0) {
-        return config.api_key;
-      }
-    }
-  } catch {
-    // Corrupt config — treat as missing
-  }
-
-  // Check environment variable
-  if (process.env.ARKHEIA_API_KEY) {
-    // Save env-provided key to config for future runs
-    saveConfig(process.env.ARKHEIA_API_KEY);
-    return process.env.ARKHEIA_API_KEY;
-  }
-
-  return null;
-}
-
-function saveConfig(apiKey) {
-  try {
-    if (!fs.existsSync(ARKHEIA_DIR)) {
-      fs.mkdirSync(ARKHEIA_DIR, { recursive: true });
-    }
-    const config = {
-      api_key: apiKey,
-      proxy_url: "https://arkheia-proxy-production.up.railway.app",
-      provisioned_at: new Date().toISOString(),
-    };
-    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
-  } catch (err) {
-    console.error(`  [arkheia] Warning: Could not save config: ${err.message}`);
-  }
-}
-
-function checkPython() {
-  // Try versioned interpreters first — on Homebrew, keg-only formulae like
-  // python@3.12 only expose python3.12, not python3.
-  const candidates = ["python3.13", "python3.12", "python3.11", "python3", "python"];
-  for (const cmd of candidates) {
-    try {
-      // Verify version AND that pyexpat + ensurepip work.
-      // Python 3.14 on macOS has broken pyexpat (missing libexpat symbol).
-      const output = execSync(
-        `${cmd} -c "import sys,pyexpat,ensurepip; print(f'{sys.version_info.major}.{sys.version_info.minor}')"`,
-        { encoding: "utf-8", timeout: 10000, stdio: ["pipe", "pipe", "pipe"] }
-      ).trim();
-      const match = output.match(/^(\d+)\.(\d+)$/);
-      if (match) {
-        const major = parseInt(match[1]);
-        const minor = parseInt(match[2]);
-        if (major === 3 && minor >= 10 && minor <= 13) {
-          const version = execSync(`${cmd} --version 2>&1`, {
-            encoding: "utf-8", timeout: 5000,
-          }).trim();
-          return { cmd, version };
-        }
-      }
-    } catch {
-      // Try next
-    }
-  }
-  return null;
-}
-
-const python = checkPython();
-
-if (!python) {
-  console.error(`
-  ============================================================
-  ERROR: Arkheia MCP Server requires Python 3.10–3.13
-         with working pyexpat and ensurepip.
-
-  macOS (Homebrew):
-    brew install python@3.12
-
-  NOTE: Homebrew's current default 'brew install python'
-  installs 3.14, which has a broken pyexpat link on macOS
-  as of April 2026. Use python@3.12 until Homebrew ships a fix.
-
-  After installing, verify with:
-    python3.12 -c "import pyexpat, ensurepip"
-
-  Other platforms: https://python.org
-  ============================================================
-  `);
-  process.exit(1);
-} else {
-  console.log(`
-  ============================================================
-  Arkheia MCP Server installed successfully.
-  Python: ${python.version} (${python.cmd})
-  ============================================================
-  `);
-}
-
-// ── API key provisioning check ──────────────────────────────────
-const existingKey = checkApiKey();
-
-if (existingKey) {
-  const maskedKey =
-    existingKey.substring(0, 8) + "..." + existingKey.substring(existingKey.length - 4);
-  console.log(`
-  ============================================================
-  API key found: ${maskedKey}
-  Config: ${CONFIG_FILE}
-  ============================================================
-  `);
-} else {
-  console.log(`
-  ============================================================
-  No Arkheia API key configured.
-
-  To enable hosted detection and encrypted profiles:
-
-    1. Get a free API key at: https://arkheia.ai/mcp
-    2. Set it in your environment:
-       export ARKHEIA_API_KEY=ak_live_...
-
-    Or save it directly to ${CONFIG_FILE}:
-    {
-      "api_key": "ak_live_...",
-      "proxy_url": "https://arkheia-proxy-production.up.railway.app",
-      "provisioned_at": "..."
-    }
-
-  The server will work without a key, but encrypted profiles
-  and hosted detection will be unavailable.
-  ============================================================
-  `);
-}
+#!/usr/bin/env node
+/**
+ * Post-install script for @arkheia/mcp-server.
+ *
+ * 1. Checks for API key (saves env → config if found)
+ * 2. Installs/updates Arkheia detection protocol in ~/.claude/CLAUDE.md
+ *    - Versioned managed block with BEGIN/END markers
+ *    - Idempotent, non-destructive, backs up before write
+ *    - Opt-out: ARKHEIA_SKIP_CLAUDE_MD=1
+ */
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+// Resolve home dir — handle sudo
+const HOME = (process.env.SUDO_USER
+  ? path.join("/home", process.env.SUDO_USER)
+  : process.env.HOME || process.env.USERPROFILE || "/tmp");
+
+const ARKHEIA_DIR = path.join(HOME, ".arkheia");
+const CONFIG_FILE = path.join(ARKHEIA_DIR, "config.json");
+const CLAUDE_DIR = path.join(HOME, ".claude");
+const CLAUDE_MD = path.join(CLAUDE_DIR, "CLAUDE.md");
+
+// Read version from package.json
+const PKG_VERSION = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")).version;
+  } catch { return "unknown"; }
+})();
+
+// Read template from shipped file
+const TEMPLATE = (() => {
+  try {
+    return fs.readFileSync(path.join(__dirname, "..", "CLAUDE_MD_TEMPLATE.md"), "utf8").trim();
+  } catch { return ""; }
+})();
+
+const BEGIN_MARKER = `<!-- BEGIN ARKHEIA PROTOCOL v${PKG_VERSION} -->`;
+const BEGIN_REGEX = /<!-- BEGIN ARKHEIA PROTOCOL v(.+?) -->/;
+const BLOCK_REGEX = /<!-- BEGIN ARKHEIA PROTOCOL v.+? -->[\s\S]*?<!-- END ARKHEIA PROTOCOL -->/;
+const END_MARKER = "<!-- END ARKHEIA PROTOCOL -->";
+
+// ── API key provisioning ───────────────────────────────────────
+
+function checkApiKey() {
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      const config = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
+      if (config.api_key && config.api_key.length > 0) return config.api_key;
+    }
+  } catch {}
+  if (process.env.ARKHEIA_API_KEY) {
+    saveConfig(process.env.ARKHEIA_API_KEY);
+    return process.env.ARKHEIA_API_KEY;
+  }
+  return null;
+}
+
+function saveConfig(apiKey) {
+  try {
+    if (!fs.existsSync(ARKHEIA_DIR)) fs.mkdirSync(ARKHEIA_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify({
+      api_key: apiKey,
+      proxy_url: "https://arkheia-proxy-production.up.railway.app",
+      provisioned_at: new Date().toISOString(),
+    }, null, 2), "utf-8");
+  } catch (err) {
+    console.error(`  [arkheia] Warning: Could not save config: ${err.message}`);
+  }
+}
+
+// ── CLAUDE.md managed block install ────────────────────────────
+
+function installClaudeMd() {
+  // Opt-out
+  if (process.env.ARKHEIA_SKIP_CLAUDE_MD === "1") {
+    console.log("  [arkheia] CLAUDE.md install skipped (ARKHEIA_SKIP_CLAUDE_MD=1)");
+    return;
+  }
+
+  if (!TEMPLATE) {
+    console.log("  [arkheia] Warning: CLAUDE_MD_TEMPLATE.md not found in package");
+    return;
+  }
+
+  const newBlock = `${BEGIN_MARKER}\n${TEMPLATE}\n${END_MARKER}`;
+
+  // Ensure ~/.claude exists
+  try {
+    if (!fs.existsSync(CLAUDE_DIR)) {
+      fs.mkdirSync(CLAUDE_DIR, { recursive: true, mode: 0o700 });
+    }
+  } catch (err) {
+    console.error(`  [arkheia] Could not create ${CLAUDE_DIR}: ${err.message}`);
+    return;
+  }
+
+  // Symlink check — don't follow symlinks (chezmoi, yadm)
+  try {
+    if (fs.existsSync(CLAUDE_MD) && fs.lstatSync(CLAUDE_MD).isSymbolicLink()) {
+      console.log(`  [arkheia] ${CLAUDE_MD} is a symlink — skipping to avoid corrupting dotfile manager.`);
+      console.log(`  [arkheia] Install the Arkheia block manually. Template at: ${path.join(__dirname, "..", "CLAUDE_MD_TEMPLATE.md")}`);
+      return;
+    }
+  } catch {}
+
+  // Case 1: No CLAUDE.md exists — create fresh
+  if (!fs.existsSync(CLAUDE_MD)) {
+    try {
+      fs.writeFileSync(CLAUDE_MD, newBlock + "\n", "utf-8");
+      console.log(`  [arkheia] Installed detection protocol to ${CLAUDE_MD}`);
+    } catch (err) {
+      console.error(`  [arkheia] Could not write ${CLAUDE_MD}: ${err.message}`);
+    }
+    return;
+  }
+
+  // Case 2+: CLAUDE.md exists — read it
+  let content;
+  try {
+    content = fs.readFileSync(CLAUDE_MD, "utf-8");
+  } catch (err) {
+    console.error(`  [arkheia] Could not read ${CLAUDE_MD}: ${err.message}`);
+    return;
+  }
+
+  const match = content.match(BEGIN_REGEX);
+
+  // Case 2: Exists but no Arkheia block — append
+  if (!match) {
+    // Check for multiple BEGIN markers (shouldn't happen)
+    const allMatches = content.match(/<!-- BEGIN ARKHEIA PROTOCOL/g);
+    if (allMatches && allMatches.length > 1) {
+      console.log("  [arkheia] Multiple Arkheia blocks found — manual intervention needed. Skipping.");
+      return;
+    }
+
+    backup(content);
+    // Preserve line endings
+    const eol = content.includes("\r\n") ? "\r\n" : "\n";
+    const separator = content.endsWith(eol) ? eol : eol + eol;
+    try {
+      fs.appendFileSync(CLAUDE_MD, separator + newBlock + eol, "utf-8");
+      console.log(`  [arkheia] Appended detection protocol to existing ${CLAUDE_MD} (backup at ${CLAUDE_MD}.arkheia.bak)`);
+    } catch (err) {
+      console.error(`  [arkheia] Could not append to ${CLAUDE_MD}: ${err.message}`);
+    }
+    return;
+  }
+
+  // Case 3: Block exists — check version
+  const existingVersion = match[1];
+  const existingBlock = content.match(BLOCK_REGEX);
+
+  if (existingVersion === PKG_VERSION && existingBlock && existingBlock[0] === newBlock) {
+    console.log(`  [arkheia] Detection protocol already up to date (v${PKG_VERSION})`);
+    return;
+  }
+
+  // Case 4: Version mismatch or body drifted — replace in place
+  backup(content);
+  try {
+    const updated = content.replace(BLOCK_REGEX, newBlock);
+    fs.writeFileSync(CLAUDE_MD, updated, "utf-8");
+    console.log(`  [arkheia] Updated detection protocol ${existingVersion} → ${PKG_VERSION} (backup at ${CLAUDE_MD}.arkheia.bak)`);
+  } catch (err) {
+    console.error(`  [arkheia] Could not update ${CLAUDE_MD}: ${err.message}`);
+  }
+}
+
+function backup(content) {
+  try {
+    fs.writeFileSync(CLAUDE_MD + ".arkheia.bak", content, "utf-8");
+  } catch {}
+}
+
+// ── Also install to Codex if present ───────────────────────────
+
+function installCodexMd() {
+  if (process.env.ARKHEIA_SKIP_CLAUDE_MD === "1") return;
+  if (!TEMPLATE) return;
+
+  const codexDir = path.join(HOME, ".codex");
+  const codexMd = path.join(codexDir, "CODEX.md");
+  const newBlock = `${BEGIN_MARKER}\n${TEMPLATE}\n${END_MARKER}`;
+
+  // Only install if codex CLI exists
+  try {
+    execSync(process.platform === "win32" ? "where codex" : "which codex", { stdio: "pipe" });
+  } catch { return; }
+
+  try {
+    if (!fs.existsSync(codexDir)) fs.mkdirSync(codexDir, { recursive: true, mode: 0o700 });
+
+    if (!fs.existsSync(codexMd)) {
+      fs.writeFileSync(codexMd, newBlock + "\n", "utf-8");
+      console.log(`  [arkheia] Installed detection protocol to ${codexMd}`);
+      return;
+    }
+
+    const content = fs.readFileSync(codexMd, "utf-8");
+    if (content.includes(BEGIN_MARKER)) {
+      console.log(`  [arkheia] Codex protocol already up to date (v${PKG_VERSION})`);
+      return;
+    }
+
+    if (content.match(BEGIN_REGEX)) {
+      // Upgrade
+      fs.writeFileSync(codexMd + ".arkheia.bak", content, "utf-8");
+      const updated = content.replace(BLOCK_REGEX, newBlock);
+      fs.writeFileSync(codexMd, updated, "utf-8");
+      console.log(`  [arkheia] Updated Codex detection protocol → ${PKG_VERSION}`);
+    } else {
+      // Append
+      fs.writeFileSync(codexMd + ".arkheia.bak", content, "utf-8");
+      const eol = content.includes("\r\n") ? "\r\n" : "\n";
+      fs.appendFileSync(codexMd, eol + eol + newBlock + eol, "utf-8");
+      console.log(`  [arkheia] Appended detection protocol to ${codexMd}`);
+    }
+  } catch {}
+}
+
+// ── Main ───────────────────────────────────────────────────────
+
+// API key check
+const existingKey = checkApiKey();
+if (existingKey) {
+  const masked = existingKey.substring(0, 8) + "..." + existingKey.substring(existingKey.length - 4);
+  console.log(`\n  [arkheia] API key: ${masked}`);
+} else {
+  console.log(`\n  [arkheia] No API key. Get one free at https://arkheia.ai/mcp/account`);
+}
+
+// Install detection protocol
+installClaudeMd();
+installCodexMd();
+
+console.log(`  [arkheia] @arkheia/mcp-server v${PKG_VERSION} ready\n`);

package/ARKHEIA_CLAUDE.md

@@ -1,48 +0,0 @@
-# Arkheia Integration — Detection Protocol
-
-When Arkheia MCP tools are available in this session, follow this protocol.
-
-## Fabrication Detection
-
-Call `arkheia_verify` on EVERY model response before surfacing it to the user. Do not skip responses that appear obviously correct.
-
-```
-arkheia_verify(prompt=<original prompt>, response=<model output>, model=<model id>)
-```
-
-## Risk Escalation
-
-- **HIGH risk**: Warn the user that the response may be fabricated. Include the `detection_id`. Still show the response — never hide or suppress it. Ask the user if they want you to verify with a different model.
-- **MEDIUM risk**: Show the response with a brief confidence note (e.g. "Arkheia flagged this at medium confidence").
-- **LOW risk**: Show normally. No annotation needed.
-- **UNKNOWN risk**: Flag for human review. Include the `detection_id` in your response.
-
-## Cross-Model Verification
-
-When a HIGH or UNKNOWN risk is detected, offer to verify using a different model:
-- `run_grok` — xAI Grok
-- `run_gemini` — Google Gemini
-- `run_ollama` — local Ollama model (no network egress)
-- `run_together` — Together AI (Kimi K2.5, DeepSeek)
-
-Compare the alternative response against the original. If they diverge significantly, escalate to the user.
-
-## Audit Trail
-
-Use `arkheia_audit_log` when the user asks about detection history or for compliance evidence. This provides structured event data with timestamps, risk levels, and detection IDs.
-
-## Persistent Knowledge Graph
-
-Use the memory tools to store facts discovered during sessions:
-- `memory_store(name, entity_type, observations)` — remember entities and facts
-- `memory_retrieve(query)` — recall stored knowledge
-- `memory_relate(from_entity, relation_type, to_entity)` — track relationships
-
-Store entities when you learn something the user would want persisted across sessions (contacts, decisions, bugs, architectural patterns).
-
-## Key Rules
-
-1. Never hide a response from the user regardless of risk level
-2. Always include the `detection_id` when reporting HIGH or UNKNOWN risk
-3. Call `arkheia_verify` proactively — do not wait for the user to ask
-4. Audit logging happens automatically through `arkheia_verify` — no extra action needed