@arkheia/mcp-server 0.1.10 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -6,26 +6,13 @@ Arkheia screens model responses for fabrication using behavioural fingerprinting
6
6
 
7
7
  Free tier: 1,500 detections/month. No credit card.
8
8
 
9
- ## Prerequisites
10
-
11
- ```
12
- Requires:
13
- - Node 18+
14
- - Python 3.10–3.13 with working pyexpat
15
-
16
- macOS note: Homebrew's current `brew install python` installs 3.14,
17
- which has a broken pyexpat link. Use `brew install python@3.12` until
18
- Homebrew ships a fix. Verify with:
19
- python3.12 -c "import pyexpat, ensurepip"
20
- ```
21
-
22
- ## Install
9
+ ## Quick Start
23
10
 
24
11
  ```bash
25
- npm install -g @arkheia/mcp-server
12
+ npx @arkheia/mcp-server
26
13
  ```
27
14
 
28
- Get a free API key at [arkheia.ai/mcp/account](https://arkheia.ai/mcp/account), or via the CLI:
15
+ Get a free API key:
29
16
 
30
17
  ```bash
31
18
  curl -X POST https://arkheia-proxy-production.up.railway.app/v1/provision \
@@ -33,79 +20,29 @@ curl -X POST https://arkheia-proxy-production.up.railway.app/v1/provision \
33
20
  -d '{"email": "you@example.com"}'
34
21
  ```
35
22
 
36
- Set your key:
37
-
38
- ```bash
39
- export ARKHEIA_API_KEY="ak_live_..."
40
- ```
41
-
42
- ## Register with your CLI
43
-
44
- Each AI CLI has a slightly different `mcp add` command. Use the one that matches your tool. All assume you've installed globally with `npm install -g`.
45
-
46
- ### Claude Code
47
-
48
- ```bash
49
- claude mcp add arkheia -s user \
50
- -e ARKHEIA_API_KEY="$ARKHEIA_API_KEY" \
51
- -- mcp-server
52
- ```
53
-
54
- Config lands in: `~/.claude.json` under `mcpServers.arkheia`
55
-
56
- ### Codex
57
-
58
- ```bash
59
- codex mcp add arkheia \
60
- --env ARKHEIA_API_KEY="$ARKHEIA_API_KEY" \
61
- -- mcp-server
62
- ```
63
-
64
- Config lands in: `~/.codex/config.toml` under `[mcp_servers.arkheia.env]`
65
-
66
- Note: `codex login --api-key` is deprecated. Use `printenv OPENAI_API_KEY | codex login --with-api-key` instead.
67
-
68
- ### Gemini
69
-
70
- ```bash
71
- gemini mcp add -s user \
72
- -e ARKHEIA_API_KEY="$ARKHEIA_API_KEY" \
73
- arkheia mcp-server
74
- ```
75
-
76
- Config lands in: `~/.gemini/settings.json` under `mcpServers.arkheia`
77
-
78
- **Gotcha:** `gemini mcp list` only shows project-scope servers. If you registered with `-s user`, verify by reading `~/.gemini/settings.json` directly.
79
-
80
- **Gotcha:** Don't use `npx -y @arkheia/mcp-server` with Gemini — the `-y` flag gets eaten by Gemini's yargs parser as `--yolo`. Use the globally-installed `mcp-server` binary directly.
81
-
82
- ### Grok
83
-
84
- ```bash
85
- grok mcp add arkheia \
86
- -t stdio \
87
- -c mcp-server \
88
- -e ARKHEIA_API_KEY="$ARKHEIA_API_KEY"
23
+ Add to your agent config (Claude Code, Claude Desktop, Cursor, or any MCP-compatible tool):
24
+
25
+ ```json
26
+ {
27
+ "mcpServers": {
28
+ "arkheia": {
29
+ "command": "python",
30
+ "args": ["-m", "mcp_server.server"],
31
+ "cwd": "~/.arkheia/mcp",
32
+ "env": {
33
+ "PYTHONPATH": "~/.arkheia/mcp",
34
+ "ARKHEIA_API_KEY": "ak_live_your_key_here"
35
+ }
36
+ }
37
+ }
38
+ }
89
39
  ```
90
40
 
91
- Config lands in: `~/.grok/settings.json` under `mcpServers.arkheia` (note: env is nested under `transport`, unlike other CLIs)
92
-
93
- ## Verify it works
94
-
95
- ```bash
96
- # Claude Code — live connection test
97
- claude mcp list
98
-
99
- # Codex — shows 'enabled' (not a live check)
100
- codex mcp list
101
-
102
- # Grok — best: spawns the server and lists all 9 tools
103
- grok mcp test arkheia
41
+ Restart your agent. Then ask it:
104
42
 
105
- # Gemini — no built-in test; start a session and try the tool
106
- ```
43
+ > "Use arkheia_verify to check this response: The Kafka 4.1 ConsumerLease API introduces a lease-based partition ownership model."
107
44
 
108
- **Important:** MCP registrations are not hot-reloaded. Restart your CLI session after running `mcp add`.
45
+ It should flag this as **HIGH** risk — because the Kafka 4.1 ConsumerLease API doesn't exist.
109
46
 
110
47
  ## What You Get
111
48
 
@@ -117,9 +54,6 @@ grok mcp test arkheia
117
54
  | `run_gemini` | Call Gemini + screen for fabrication |
118
55
  | `run_ollama` | Call local Ollama model + screen |
119
56
  | `run_together` | Call Together AI (Kimi, DeepSeek) + screen |
120
- | `memory_store` | Persistent knowledge graph — upsert entity |
121
- | `memory_retrieve` | Knowledge graph lookup |
122
- | `memory_relate` | Create relationship between entities |
123
57
 
124
58
  ## 35+ Model Profiles
125
59
 
@@ -134,27 +68,6 @@ GPT-4o, GPT-5.4, Claude Opus/Sonnet/Haiku, Gemini 2.5/3.0, Grok 4, Llama, Mixtra
134
68
  | Professional | $499/month | Unlimited |
135
69
  | Team | $1,999/month | Unlimited |
136
70
 
137
- Manage your account at [arkheia.ai/mcp/account](https://arkheia.ai/mcp/account).
138
-
139
- ## Where API keys are stored
140
-
141
- | CLI | Config file | Key location |
142
- |-----|-------------|-------------|
143
- | Claude Code | `~/.claude.json` | `mcpServers.arkheia.env.ARKHEIA_API_KEY` |
144
- | Codex | `~/.codex/config.toml` | `[mcp_servers.arkheia.env]` section |
145
- | Gemini | `~/.gemini/settings.json` | `mcpServers.arkheia.env.ARKHEIA_API_KEY` |
146
- | Grok | `~/.grok/settings.json` | `mcpServers.arkheia.transport.env.ARKHEIA_API_KEY` |
147
-
148
- ## Troubleshooting
149
-
150
- **"Python 3.10+ is required but not found"** — Install Python 3.12: `brew install python@3.12` (macOS) or download from [python.org](https://python.org).
151
-
152
- **"No module named pip"** — Your Python installation has broken pip (common with Python 3.14 on macOS). Delete `~/.arkheia/venv` and switch to Python 3.12: `brew install python@3.12`.
153
-
154
- **Server registered but tools not showing** — Restart your CLI session. MCP registrations are not hot-reloaded.
155
-
156
- **API key rejected** — Check for trailing whitespace or `\r` characters. If your env file was created on Windows, run `dos2unix` on it. The server will warn about this on startup.
157
-
158
71
  ## Full Documentation
159
72
 
160
73
  See the [GitHub repo](https://github.com/arkheiaai/arkheia-mcp) for:
@@ -173,5 +86,4 @@ Every message is read by the founder.
173
86
  ## Links
174
87
 
175
88
  - Website: https://arkheia.ai
176
- - MCP Account: https://arkheia.ai/mcp/account
177
89
  - GitHub: https://github.com/arkheiaai/arkheia-mcp
@@ -0,0 +1,207 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Arkheia MCP Server — thin Node wrapper that spawns the Python MCP server.
4
+ *
5
+ * This wrapper exists so that MCP clients can install via:
6
+ * npx @arkheia/mcp-server
7
+ * npm install -g @arkheia/mcp-server
8
+ *
9
+ * It:
10
+ * 1. Locates a Python 3.10+ interpreter
11
+ * 2. Ensures mcp_server dependencies are installed (pip install)
12
+ * 3. Spawns `python -m mcp_server.server` with stdio transport
13
+ * 4. Forwards stdin/stdout/stderr (MCP uses stdio)
14
+ *
15
+ * Environment variables:
16
+ * ARKHEIA_API_KEY — API key for hosted detection (required)
17
+ * ARKHEIA_PROXY_URL — Local proxy URL (optional, for enterprise)
18
+ * ARKHEIA_HOSTED_URL — Hosted API URL (default: https://arkheia-proxy-production.up.railway.app)
19
+ */
20
+
21
+ const { spawn, execSync } = require("child_process");
22
+ const path = require("path");
23
+ const fs = require("fs");
24
+
25
+ const ARKHEIA_HOME = path.join(
26
+ process.env.HOME || process.env.USERPROFILE || "/tmp",
27
+ ".arkheia"
28
+ );
29
+ const REPO_DIR = path.join(ARKHEIA_HOME, "mcp");
30
+ const BUNDLED_PYTHON_DIR = path.join(__dirname, "..", "python");
31
+ const VENV_DIR = path.join(ARKHEIA_HOME, "venv");
32
+
33
+ // Determine the real Python source: cloned repo > bundled package
34
+ function getServerDir() {
35
+ // If repo already cloned, use it
36
+ if (fs.existsSync(path.join(REPO_DIR, "mcp_server", "server.py"))) {
37
+ return REPO_DIR;
38
+ }
39
+ // If bundled package has the server code, use it
40
+ if (fs.existsSync(path.join(BUNDLED_PYTHON_DIR, "mcp_server", "server.py"))) {
41
+ return BUNDLED_PYTHON_DIR;
42
+ }
43
+ // Neither exists — clone the repo
44
+ process.stderr.write("[arkheia] Server code not found. Cloning from GitHub...\n");
45
+ try {
46
+ if (!fs.existsSync(ARKHEIA_HOME)) fs.mkdirSync(ARKHEIA_HOME, { recursive: true });
47
+ execSync(`git clone --depth 1 https://github.com/arkheiaai/arkheia-mcp.git "${REPO_DIR}"`, {
48
+ stdio: "inherit",
49
+ timeout: 60000,
50
+ });
51
+ process.stderr.write("[arkheia] Repository cloned successfully.\n");
52
+ return REPO_DIR;
53
+ } catch (err) {
54
+ process.stderr.write(
55
+ `[arkheia] Error: Could not clone repository: ${err.message}\n` +
56
+ "Manual install: git clone https://github.com/arkheiaai/arkheia-mcp.git ~/.arkheia/mcp\n"
57
+ );
58
+ process.exit(1);
59
+ }
60
+ }
61
+
62
+ const PYTHON_DIR = getServerDir();
63
+ const REQUIREMENTS = fs.existsSync(path.join(PYTHON_DIR, "mcp_server", "requirements.txt"))
64
+ ? path.join(PYTHON_DIR, "mcp_server", "requirements.txt")
65
+ : path.join(PYTHON_DIR, "requirements.txt");
66
+
67
+ function findPython() {
68
+ const candidates = ["python3", "python"];
69
+ for (const cmd of candidates) {
70
+ try {
71
+ const version = execSync(`${cmd} --version 2>&1`, {
72
+ encoding: "utf-8",
73
+ timeout: 5000,
74
+ }).trim();
75
+ const match = version.match(/Python (\d+)\.(\d+)/);
76
+ if (match && parseInt(match[1]) >= 3 && parseInt(match[2]) >= 10) {
77
+ return cmd;
78
+ }
79
+ } catch {
80
+ // Try next candidate
81
+ }
82
+ }
83
+ return null;
84
+ }
85
+
86
+ function ensureVenv(python) {
87
+ const venvPython =
88
+ process.platform === "win32"
89
+ ? path.join(VENV_DIR, "Scripts", "python.exe")
90
+ : path.join(VENV_DIR, "bin", "python");
91
+
92
+ if (!fs.existsSync(venvPython)) {
93
+ process.stderr.write("[arkheia] Creating virtual environment...\n");
94
+ execSync(`${python} -m venv "${VENV_DIR}"`, { stdio: "inherit" });
95
+ }
96
+
97
+ return venvPython;
98
+ }
99
+
100
+ function installDeps(venvPython) {
101
+ const marker = path.join(VENV_DIR, ".arkheia-deps-installed");
102
+ if (fs.existsSync(marker)) {
103
+ return; // Already installed
104
+ }
105
+
106
+ process.stderr.write("[arkheia] Installing dependencies...\n");
107
+ execSync(`"${venvPython}" -m pip install --quiet -r "${REQUIREMENTS}"`, {
108
+ stdio: "inherit",
109
+ timeout: 120000,
110
+ });
111
+
112
+ fs.writeFileSync(marker, new Date().toISOString());
113
+ }
114
+
115
+ function main() {
116
+ const python = findPython();
117
+ if (!python) {
118
+ process.stderr.write(
119
+ "[arkheia] Error: Python 3.10+ is required but not found.\n" +
120
+ "Install Python from https://python.org and try again.\n"
121
+ );
122
+ process.exit(1);
123
+ }
124
+
125
+ // ── Load config from ~/.arkheia/config.json ──────────────────
126
+ const configPath = path.join(
127
+ process.env.HOME || process.env.USERPROFILE || "/tmp",
128
+ ".arkheia",
129
+ "config.json"
130
+ );
131
+ let arkheiaConfig = {};
132
+ try {
133
+ if (fs.existsSync(configPath)) {
134
+ arkheiaConfig = JSON.parse(fs.readFileSync(configPath, "utf-8"));
135
+ process.stderr.write(`[arkheia] Loaded config from ${configPath}\n`);
136
+ }
137
+ } catch (err) {
138
+ process.stderr.write(
139
+ `[arkheia] Warning: Could not read ${configPath}: ${err.message}\n`
140
+ );
141
+ }
142
+
143
+ // Inject API key from config if not already in env
144
+ if (!process.env.ARKHEIA_API_KEY && arkheiaConfig.api_key) {
145
+ process.env.ARKHEIA_API_KEY = arkheiaConfig.api_key;
146
+ process.stderr.write("[arkheia] API key loaded from config.json\n");
147
+ }
148
+
149
+ // Inject hosted URL from config if not already in env
150
+ if (!process.env.ARKHEIA_HOSTED_URL && arkheiaConfig.proxy_url) {
151
+ process.env.ARKHEIA_HOSTED_URL = arkheiaConfig.proxy_url;
152
+ process.stderr.write(`[arkheia] Hosted URL: ${arkheiaConfig.proxy_url}\n`);
153
+ }
154
+
155
+ // Check for API key
156
+ if (!process.env.ARKHEIA_API_KEY) {
157
+ process.stderr.write(
158
+ "[arkheia] Warning: ARKHEIA_API_KEY not set.\n" +
159
+ "Get a free API key at https://arkheia.ai/mcp\n" +
160
+ "Then set: export ARKHEIA_API_KEY=ak_live_...\n\n"
161
+ );
162
+ }
163
+
164
+ let venvPython;
165
+ try {
166
+ venvPython = ensureVenv(python);
167
+ installDeps(venvPython);
168
+ } catch (err) {
169
+ process.stderr.write(
170
+ `[arkheia] Error setting up Python environment: ${err.message}\n`
171
+ );
172
+ process.exit(1);
173
+ }
174
+
175
+ // Spawn the MCP server with stdio transport
176
+ const child = spawn(
177
+ venvPython,
178
+ ["-m", "mcp_server.server"],
179
+ {
180
+ cwd: PYTHON_DIR,
181
+ stdio: ["pipe", "pipe", "inherit"], // stdin/stdout piped, stderr inherited
182
+ env: {
183
+ ...process.env,
184
+ PYTHONPATH: PYTHON_DIR,
185
+ },
186
+ }
187
+ );
188
+
189
+ // Forward stdio for MCP protocol
190
+ process.stdin.pipe(child.stdin);
191
+ child.stdout.pipe(process.stdout);
192
+
193
+ child.on("error", (err) => {
194
+ process.stderr.write(`[arkheia] Failed to start MCP server: ${err.message}\n`);
195
+ process.exit(1);
196
+ });
197
+
198
+ child.on("exit", (code) => {
199
+ process.exit(code || 0);
200
+ });
201
+
202
+ // Forward signals
203
+ process.on("SIGINT", () => child.kill("SIGINT"));
204
+ process.on("SIGTERM", () => child.kill("SIGTERM"));
205
+ }
206
+
207
+ main();
package/package.json CHANGED
@@ -1,44 +1,44 @@
1
- {
2
- "name": "@arkheia/mcp-server",
3
- "version": "0.1.10",
4
- "description": "Arkheia MCP Server — Fabrication detection for AI agents. Know when your AI is making things up.",
5
- "main": "dist/index.js",
6
- "bin": {
7
- "mcp-server": "dist/index.js"
8
- },
9
- "scripts": {
10
- "build": "tsc",
11
- "start": "node dist/index.js",
12
- "prepublishOnly": "npm run build",
13
- "postinstall": "node scripts/setup.js"
14
- },
15
- "files": [
16
- "dist/",
17
- "scripts/",
18
- "README.md",
19
- "CLAUDE_MD_TEMPLATE.md"
20
- ],
21
- "keywords": [
22
- "mcp",
23
- "ai",
24
- "fabrication",
25
- "detection",
26
- "hallucination",
27
- "governance"
28
- ],
29
- "author": "Arkheia AI <dmurfet@arkheia.ai>",
30
- "license": "MIT",
31
- "engines": {
32
- "node": ">=18.0.0"
33
- },
34
- "dependencies": {
35
- "@modelcontextprotocol/sdk": "^1.12.0",
36
- "sql.js": "^1.11.0",
37
- "zod": "^3.23.8"
38
- },
39
- "devDependencies": {
40
- "@types/sql.js": "^1.4.9",
41
- "@types/node": "^20.14.10",
42
- "typescript": "^5.5.3"
43
- }
44
- }
1
+ {
2
+ "name": "@arkheia/mcp-server",
3
+ "version": "1.2.0",
4
+ "mcpName": "io.github.arkheiaai/mcp-server",
5
+ "description": "Arkheia MCP Server — Fabrication detection for LLM outputs. Detect hallucination in any model's output with a single tool call.",
6
+ "bin": {
7
+ "mcp-server": "bin/arkheia-mcp.js"
8
+ },
9
+ "scripts": {
10
+ "start": "node bin/arkheia-mcp.js",
11
+ "postinstall": "node scripts/setup.js"
12
+ },
13
+ "keywords": [
14
+ "mcp",
15
+ "ai",
16
+ "fabrication",
17
+ "hallucination",
18
+ "detection",
19
+ "llm",
20
+ "claude",
21
+ "gpt",
22
+ "gemini",
23
+ "governance",
24
+ "audit",
25
+ "grounding",
26
+ "verification"
27
+ ],
28
+ "author": "Arkheia AI <support@arkheia.ai>",
29
+ "license": "MIT",
30
+ "homepage": "https://arkheia.ai/mcp",
31
+ "repository": {
32
+ "type": "git",
33
+ "url": "git+https://github.com/arkheiaai/arkheia-mcp.git"
34
+ },
35
+ "engines": {
36
+ "node": ">=18.0.0"
37
+ },
38
+ "files": [
39
+ "bin/",
40
+ "scripts/",
41
+ "python/",
42
+ "README.md"
43
+ ]
44
+ }
File without changes
@@ -0,0 +1,4 @@
1
+ mcp>=1.26.0
2
+ httpx>=0.27.1
3
+ pydantic>=2.10.0
4
+ pyyaml>=6.0