@arkheia/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# Arkheia MCP Server — Fabrication Detection for LLMs
+
+Detect fabrication (hallucination) in any LLM output.
+Free tier included (1,500 detections/month).
+
+## Quick Start
+
+### 1. Clone and install
+
+```bash
+git clone https://github.com/arkheiaai/arkheia-mcp.git ~/.arkheia-mcp
+cd ~/.arkheia-mcp
+pip install -r requirements.txt
+```
+
+### 2. Get an API key (free)
+
+```bash
+curl -X POST https://arkheia-proxy-production.up.railway.app/v1/provision \
+  -H "Content-Type: application/json" \
+  -d '{"email": "you@example.com"}'
+```
+
+### 3. Add to Claude Desktop
+
+Edit your config file:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "arkheia": {
+      "command": "python",
+      "args": ["-m", "mcp_server.server"],
+      "cwd": "~/.arkheia-mcp",
+      "env": {
+        "PYTHONPATH": "~/.arkheia-mcp",
+        "ARKHEIA_API_KEY": "ak_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+On Windows, replace `~/.arkheia-mcp` with the full path (e.g. `C:/Users/YourName/.arkheia-mcp`).
+
+### 4. Restart Claude
+
+The `arkheia_verify` and `arkheia_audit_log` tools will appear automatically.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `arkheia_verify` | Score any model output for fabrication risk (LOW/MEDIUM/HIGH) |
+| `arkheia_audit_log` | Review detection history |
+| `run_grok` | Call xAI Grok + screen for fabrication |
+| `run_gemini` | Call Google Gemini + screen for fabrication |
+| `run_together` | Call Together AI (Kimi, DeepSeek) + screen |
+| `run_ollama` | Call local Ollama model + screen |
+| `memory_store` / `memory_retrieve` / `memory_relate` | Persistent knowledge graph |
+
+## Pricing
+
+- **Free:** 1,500 detections/month (no credit card)
+- **Single Contributor:** $99/month (unlimited)
+- **Professional:** $499/month (20 concurrent)
+- **Team:** $1,999/month (50 concurrent)
+
+## Requirements
+
+- Python 3.10+
+- Git
+
+## Full Setup Guide
+
+See [AGENTS.md](https://github.com/arkheiaai/arkheia-mcp/blob/master/AGENTS.md) for detailed instructions, troubleshooting, and environment variables.
+
+## Links
+
+- Website: https://arkheia.ai
+- GitHub: https://github.com/arkheiaai/arkheia-mcp
+- Support: support@arkheia.ai

package/bin/arkheia-mcp.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * Arkheia MCP Server — thin Node wrapper that spawns the Python MCP server.
+ *
+ * This wrapper exists so that MCP clients can install via:
+ *   npx @arkheia/mcp-server
+ *   npm install -g @arkheia/mcp-server
+ *
+ * It:
+ *   1. Locates a Python 3.10+ interpreter
+ *   2. Ensures mcp_server dependencies are installed (pip install)
+ *   3. Spawns `python -m mcp_server.server` with stdio transport
+ *   4. Forwards stdin/stdout/stderr (MCP uses stdio)
+ *
+ * Environment variables:
+ *   ARKHEIA_API_KEY     — API key for hosted detection (required)
+ *   ARKHEIA_PROXY_URL   — Local proxy URL (optional, for enterprise)
+ *   ARKHEIA_HOSTED_URL  — Hosted API URL (default: https://arkheia-proxy-production.up.railway.app)
+ */
+
+const { spawn, execSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const PYTHON_DIR = path.join(__dirname, "..", "python");
+const REQUIREMENTS = path.join(PYTHON_DIR, "requirements.txt");
+const VENV_DIR = path.join(
+  process.env.HOME || process.env.USERPROFILE || "/tmp",
+  ".arkheia",
+  "venv"
+);
+
+function findPython() {
+  const candidates = ["python3", "python"];
+  for (const cmd of candidates) {
+    try {
+      const version = execSync(`${cmd} --version 2>&1`, {
+        encoding: "utf-8",
+        timeout: 5000,
+      }).trim();
+      const match = version.match(/Python (\d+)\.(\d+)/);
+      if (match && parseInt(match[1]) >= 3 && parseInt(match[2]) >= 10) {
+        return cmd;
+      }
+    } catch {
+      // Try next candidate
+    }
+  }
+  return null;
+}
+
+function ensureVenv(python) {
+  const venvPython =
+    process.platform === "win32"
+      ? path.join(VENV_DIR, "Scripts", "python.exe")
+      : path.join(VENV_DIR, "bin", "python");
+
+  if (!fs.existsSync(venvPython)) {
+    process.stderr.write("[arkheia] Creating virtual environment...\n");
+    execSync(`${python} -m venv "${VENV_DIR}"`, { stdio: "inherit" });
+  }
+
+  return venvPython;
+}
+
+function installDeps(venvPython) {
+  const marker = path.join(VENV_DIR, ".arkheia-deps-installed");
+  if (fs.existsSync(marker)) {
+    return; // Already installed
+  }
+
+  process.stderr.write("[arkheia] Installing dependencies...\n");
+  execSync(`"${venvPython}" -m pip install --quiet -r "${REQUIREMENTS}"`, {
+    stdio: "inherit",
+    timeout: 120000,
+  });
+
+  fs.writeFileSync(marker, new Date().toISOString());
+}
+
+function main() {
+  const python = findPython();
+  if (!python) {
+    process.stderr.write(
+      "[arkheia] Error: Python 3.10+ is required but not found.\n" +
+        "Install Python from https://python.org and try again.\n"
+    );
+    process.exit(1);
+  }
+
+  // ── Load config from ~/.arkheia/config.json ──────────────────
+  const configPath = path.join(
+    process.env.HOME || process.env.USERPROFILE || "/tmp",
+    ".arkheia",
+    "config.json"
+  );
+  let arkheiaConfig = {};
+  try {
+    if (fs.existsSync(configPath)) {
+      arkheiaConfig = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+      process.stderr.write(`[arkheia] Loaded config from ${configPath}\n`);
+    }
+  } catch (err) {
+    process.stderr.write(
+      `[arkheia] Warning: Could not read ${configPath}: ${err.message}\n`
+    );
+  }
+
+  // Inject API key from config if not already in env
+  if (!process.env.ARKHEIA_API_KEY && arkheiaConfig.api_key) {
+    process.env.ARKHEIA_API_KEY = arkheiaConfig.api_key;
+    process.stderr.write("[arkheia] API key loaded from config.json\n");
+  }
+
+  // Inject hosted URL from config if not already in env
+  if (!process.env.ARKHEIA_HOSTED_URL && arkheiaConfig.proxy_url) {
+    process.env.ARKHEIA_HOSTED_URL = arkheiaConfig.proxy_url;
+    process.stderr.write(`[arkheia] Hosted URL: ${arkheiaConfig.proxy_url}\n`);
+  }
+
+  // Check for API key
+  if (!process.env.ARKHEIA_API_KEY) {
+    process.stderr.write(
+      "[arkheia] Warning: ARKHEIA_API_KEY not set.\n" +
+        "Get a free API key at https://arkheia.ai/mcp\n" +
+        "Then set: export ARKHEIA_API_KEY=ak_live_...\n\n"
+    );
+  }
+
+  let venvPython;
+  try {
+    venvPython = ensureVenv(python);
+    installDeps(venvPython);
+  } catch (err) {
+    process.stderr.write(
+      `[arkheia] Error setting up Python environment: ${err.message}\n`
+    );
+    process.exit(1);
+  }
+
+  // Spawn the MCP server with stdio transport
+  const serverDir = PYTHON_DIR;
+  const child = spawn(
+    venvPython,
+    ["-m", "mcp_server.server"],
+    {
+      cwd: serverDir,
+      stdio: ["pipe", "pipe", "inherit"], // stdin/stdout piped, stderr inherited
+      env: {
+        ...process.env,
+        PYTHONPATH: serverDir,
+      },
+    }
+  );
+
+  // Forward stdio for MCP protocol
+  process.stdin.pipe(child.stdin);
+  child.stdout.pipe(process.stdout);
+
+  child.on("error", (err) => {
+    process.stderr.write(`[arkheia] Failed to start MCP server: ${err.message}\n`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code) => {
+    process.exit(code || 0);
+  });
+
+  // Forward signals
+  process.on("SIGINT", () => child.kill("SIGINT"));
+  process.on("SIGTERM", () => child.kill("SIGTERM"));
+}
+
+main();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@arkheia/mcp-server",
+  "version": "0.1.0",
+  "description": "Arkheia MCP Server — Fabrication detection for LLM outputs. Detect hallucination in any model's output with a single tool call.",
+  "bin": {
+    "mcp-server": "bin/arkheia-mcp.js"
+  },
+  "scripts": {
+    "start": "node bin/arkheia-mcp.js",
+    "postinstall": "node scripts/setup.js"
+  },
+  "keywords": [
+    "mcp",
+    "ai",
+    "fabrication",
+    "hallucination",
+    "detection",
+    "llm",
+    "claude",
+    "gpt",
+    "gemini",
+    "governance",
+    "audit",
+    "grounding",
+    "verification"
+  ],
+  "author": "Arkheia AI <support@arkheia.ai>",
+  "license": "MIT",
+  "homepage": "https://arkheia.ai/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arkheiaai/arkheia-mcp.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "python/",
+    "README.md"
+  ]
+}

package/python/requirements.txt

@@ -0,0 +1,4 @@
+mcp>=1.26.0
+httpx>=0.27.1
+pydantic>=2.10.0
+pyyaml>=6.0

package/scripts/build.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Build script — copies Python MCP server source into npm package.
+ * Run before `npm publish`.
+ *
+ * Usage: node scripts/build.js
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const SRC = path.resolve(__dirname, "..", "..", "mcp_server");
+const DEST = path.resolve(__dirname, "..", "python", "mcp_server");
+
+function copyDir(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.name === "__pycache__" || entry.name === "tests") continue;
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else if (entry.name.endsWith(".py")) {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+console.log(`Copying ${SRC} -> ${DEST}`);
+copyDir(SRC, DEST);
+console.log("Build complete. Run `npm publish` from npm-wrapper/.");

package/scripts/setup.js

@@ -0,0 +1,129 @@
+#!/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() {
+  const candidates = ["python3", "python"];
+  for (const cmd of candidates) {
+    try {
+      const version = execSync(`${cmd} --version 2>&1`, {
+        encoding: "utf-8",
+        timeout: 5000,
+      }).trim();
+      const match = version.match(/Python (\d+)\.(\d+)/);
+      if (match && parseInt(match[1]) >= 3 && parseInt(match[2]) >= 10) {
+        return { cmd, version };
+      }
+    } catch {
+      // Try next
+    }
+  }
+  return null;
+}
+
+const python = checkPython();
+
+if (!python) {
+  console.log(`
+  ============================================================
+  Arkheia MCP Server requires Python 3.10+
+
+  Install Python from: https://python.org
+  Then run: npx @arkheia/mcp-server
+  ============================================================
+  `);
+} else {
+  console.log(`
+  ============================================================
+  Arkheia MCP Server installed successfully.
+  Python: ${python.version}
+  ============================================================
+  `);
+}
+
+// ── 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.
+  ============================================================
+  `);
+}