@arkheia/mcp-server 0.1.10 → 1.2.1

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/scripts/setup.js CHANGED
@@ -1,241 +1,192 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * Post-install script for @arkheia/mcp-server.
4
- *
5
- * 1. Checks for API key (saves env → config if found)
6
- * 2. Installs/updates Arkheia detection protocol in ~/.claude/CLAUDE.md
7
- * - Versioned managed block with BEGIN/END markers
8
- * - Idempotent, non-destructive, backs up before write
9
- * - Opt-out: ARKHEIA_SKIP_CLAUDE_MD=1
3
+ * Post-install script — verifies Python is available and prints setup instructions.
4
+ * Does NOT auto-install Python dependencies (that happens on first run).
10
5
  */
11
6
 
12
7
  const { execSync } = require("child_process");
13
8
  const fs = require("fs");
14
9
  const path = require("path");
15
- const os = require("os");
16
10
 
17
- // Resolve home dir — handle sudo
18
- const HOME = (process.env.SUDO_USER
19
- ? path.join("/home", process.env.SUDO_USER)
20
- : process.env.HOME || process.env.USERPROFILE || "/tmp");
21
-
22
- const ARKHEIA_DIR = path.join(HOME, ".arkheia");
11
+ const ARKHEIA_DIR = path.join(
12
+ process.env.HOME || process.env.USERPROFILE || "/tmp",
13
+ ".arkheia"
14
+ );
23
15
  const CONFIG_FILE = path.join(ARKHEIA_DIR, "config.json");
24
- const CLAUDE_DIR = path.join(HOME, ".claude");
25
- const CLAUDE_MD = path.join(CLAUDE_DIR, "CLAUDE.md");
26
-
27
- // Read version from package.json
28
- const PKG_VERSION = (() => {
29
- try {
30
- return JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")).version;
31
- } catch { return "unknown"; }
32
- })();
33
-
34
- // Read template from shipped file
35
- const TEMPLATE = (() => {
36
- try {
37
- return fs.readFileSync(path.join(__dirname, "..", "CLAUDE_MD_TEMPLATE.md"), "utf8").trim();
38
- } catch { return ""; }
39
- })();
40
-
41
- const BEGIN_MARKER = `<!-- BEGIN ARKHEIA PROTOCOL v${PKG_VERSION} -->`;
42
- const BEGIN_REGEX = /<!-- BEGIN ARKHEIA PROTOCOL v(.+?) -->/;
43
- const BLOCK_REGEX = /<!-- BEGIN ARKHEIA PROTOCOL v.+? -->[\s\S]*?<!-- END ARKHEIA PROTOCOL -->/;
44
- const END_MARKER = "<!-- END ARKHEIA PROTOCOL -->";
45
-
46
- // ── API key provisioning ───────────────────────────────────────
47
16
 
48
17
  function checkApiKey() {
18
+ // Check if config.json exists and has api_key
49
19
  try {
50
20
  if (fs.existsSync(CONFIG_FILE)) {
51
21
  const config = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
52
- if (config.api_key && config.api_key.length > 0) return config.api_key;
22
+ if (config.api_key && config.api_key.length > 0) {
23
+ return config.api_key;
24
+ }
53
25
  }
54
- } catch {}
26
+ } catch {
27
+ // Corrupt config — treat as missing
28
+ }
29
+
30
+ // Check environment variable
55
31
  if (process.env.ARKHEIA_API_KEY) {
32
+ // Save env-provided key to config for future runs
56
33
  saveConfig(process.env.ARKHEIA_API_KEY);
57
34
  return process.env.ARKHEIA_API_KEY;
58
35
  }
36
+
59
37
  return null;
60
38
  }
61
39
 
62
40
  function saveConfig(apiKey) {
63
41
  try {
64
- if (!fs.existsSync(ARKHEIA_DIR)) fs.mkdirSync(ARKHEIA_DIR, { recursive: true, mode: 0o700 });
65
- fs.writeFileSync(CONFIG_FILE, JSON.stringify({
42
+ if (!fs.existsSync(ARKHEIA_DIR)) {
43
+ fs.mkdirSync(ARKHEIA_DIR, { recursive: true });
44
+ }
45
+ const config = {
66
46
  api_key: apiKey,
67
47
  proxy_url: "https://arkheia-proxy-production.up.railway.app",
68
48
  provisioned_at: new Date().toISOString(),
69
- }, null, 2), "utf-8");
49
+ };
50
+ fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
70
51
  } catch (err) {
71
52
  console.error(` [arkheia] Warning: Could not save config: ${err.message}`);
72
53
  }
73
54
  }
74
55
 
75
- // ── CLAUDE.md managed block install ────────────────────────────
76
-
77
- function installClaudeMd() {
78
- // Opt-out
79
- if (process.env.ARKHEIA_SKIP_CLAUDE_MD === "1") {
80
- console.log(" [arkheia] CLAUDE.md install skipped (ARKHEIA_SKIP_CLAUDE_MD=1)");
81
- return;
56
+ function checkPython() {
57
+ const candidates = ["python3", "python"];
58
+ for (const cmd of candidates) {
59
+ try {
60
+ const version = execSync(`${cmd} --version 2>&1`, {
61
+ encoding: "utf-8",
62
+ timeout: 5000,
63
+ }).trim();
64
+ const match = version.match(/Python (\d+)\.(\d+)/);
65
+ if (match && parseInt(match[1]) >= 3 && parseInt(match[2]) >= 10) {
66
+ return { cmd, version };
67
+ }
68
+ } catch {
69
+ // Try next
70
+ }
82
71
  }
72
+ return null;
73
+ }
83
74
 
84
- if (!TEMPLATE) {
85
- console.log(" [arkheia] Warning: CLAUDE_MD_TEMPLATE.md not found in package");
86
- return;
87
- }
75
+ const python = checkPython();
88
76
 
89
- const newBlock = `${BEGIN_MARKER}\n${TEMPLATE}\n${END_MARKER}`;
77
+ if (!python) {
78
+ console.log(`
79
+ ============================================================
80
+ Arkheia MCP Server requires Python 3.10+
90
81
 
91
- // Ensure ~/.claude exists
92
- try {
93
- if (!fs.existsSync(CLAUDE_DIR)) {
94
- fs.mkdirSync(CLAUDE_DIR, { recursive: true, mode: 0o700 });
95
- }
96
- } catch (err) {
97
- console.error(` [arkheia] Could not create ${CLAUDE_DIR}: ${err.message}`);
98
- return;
99
- }
82
+ Install Python from: https://python.org
83
+ Then run: npx @arkheia/mcp-server
84
+ ============================================================
85
+ `);
86
+ } else {
87
+ console.log(`
88
+ ============================================================
89
+ Arkheia MCP Server installed successfully.
90
+ Python: ${python.version}
91
+ ============================================================
92
+ `);
93
+ }
100
94
 
101
- // Symlink check — don't follow symlinks (chezmoi, yadm)
102
- try {
103
- if (fs.existsSync(CLAUDE_MD) && fs.lstatSync(CLAUDE_MD).isSymbolicLink()) {
104
- console.log(` [arkheia] ${CLAUDE_MD} is a symlink — skipping to avoid corrupting dotfile manager.`);
105
- console.log(` [arkheia] Install the Arkheia block manually. Template at: ${path.join(__dirname, "..", "CLAUDE_MD_TEMPLATE.md")}`);
106
- return;
107
- }
108
- } catch {}
95
+ // ── API key provisioning check ──────────────────────────────────
96
+ const existingKey = checkApiKey();
109
97
 
110
- // Case 1: No CLAUDE.md exists — create fresh
111
- if (!fs.existsSync(CLAUDE_MD)) {
112
- try {
113
- fs.writeFileSync(CLAUDE_MD, newBlock + "\n", "utf-8");
114
- console.log(` [arkheia] Installed detection protocol to ${CLAUDE_MD}`);
115
- } catch (err) {
116
- console.error(` [arkheia] Could not write ${CLAUDE_MD}: ${err.message}`);
117
- }
118
- return;
119
- }
98
+ if (existingKey) {
99
+ const maskedKey =
100
+ existingKey.substring(0, 8) + "..." + existingKey.substring(existingKey.length - 4);
101
+ console.log(`
102
+ ============================================================
103
+ API key found: ${maskedKey}
104
+ Config: ${CONFIG_FILE}
105
+ ============================================================
106
+ `);
107
+ } else {
108
+ console.log(`
109
+ ============================================================
110
+ No Arkheia API key configured.
120
111
 
121
- // Case 2+: CLAUDE.md exists — read it
122
- let content;
123
- try {
124
- content = fs.readFileSync(CLAUDE_MD, "utf-8");
125
- } catch (err) {
126
- console.error(` [arkheia] Could not read ${CLAUDE_MD}: ${err.message}`);
127
- return;
128
- }
112
+ To enable hosted detection and encrypted profiles:
129
113
 
130
- const match = content.match(BEGIN_REGEX);
114
+ 1. Get a free API key at: https://arkheia.ai/mcp
115
+ 2. Set it in your environment:
116
+ export ARKHEIA_API_KEY=ak_live_...
131
117
 
132
- // Case 2: Exists but no Arkheia block — append
133
- if (!match) {
134
- // Check for multiple BEGIN markers (shouldn't happen)
135
- const allMatches = content.match(/<!-- BEGIN ARKHEIA PROTOCOL/g);
136
- if (allMatches && allMatches.length > 1) {
137
- console.log(" [arkheia] Multiple Arkheia blocks found — manual intervention needed. Skipping.");
138
- return;
118
+ Or save it directly to ${CONFIG_FILE}:
119
+ {
120
+ "api_key": "ak_live_...",
121
+ "proxy_url": "https://arkheia-proxy-production.up.railway.app",
122
+ "provisioned_at": "..."
139
123
  }
140
124
 
141
- backup(content);
142
- // Preserve line endings
143
- const eol = content.includes("\r\n") ? "\r\n" : "\n";
144
- const separator = content.endsWith(eol) ? eol : eol + eol;
145
- try {
146
- fs.appendFileSync(CLAUDE_MD, separator + newBlock + eol, "utf-8");
147
- console.log(` [arkheia] Appended detection protocol to existing ${CLAUDE_MD} (backup at ${CLAUDE_MD}.arkheia.bak)`);
148
- } catch (err) {
149
- console.error(` [arkheia] Could not append to ${CLAUDE_MD}: ${err.message}`);
150
- }
151
- return;
152
- }
125
+ The server will work without a key, but encrypted profiles
126
+ and hosted detection will be unavailable.
127
+ ============================================================
128
+ `);
129
+ }
153
130
 
154
- // Case 3: Block exists — check version
155
- const existingVersion = match[1];
156
- const existingBlock = content.match(BLOCK_REGEX);
131
+ // ── CLAUDE.md auto-install ──────────────────────────────────────────────────
132
+ // Appends the Arkheia fabrication-detection protocol to ~/.claude/CLAUDE.md
133
+ // so the arkheia_verify tool is actually invoked in every Claude conversation.
134
+ // Idempotent: skips if the section is already present.
157
135
 
158
- if (existingVersion === PKG_VERSION && existingBlock && existingBlock[0] === newBlock) {
159
- console.log(` [arkheia] Detection protocol already up to date (v${PKG_VERSION})`);
160
- return;
161
- }
136
+ const CLAUDE_MD_SECTION = `
137
+ # Fabrication Detection — Arkheia
162
138
 
163
- // Case 4: Version mismatch or body drifted — replace in place
164
- backup(content);
165
- try {
166
- const updated = content.replace(BLOCK_REGEX, newBlock);
167
- fs.writeFileSync(CLAUDE_MD, updated, "utf-8");
168
- console.log(` [arkheia] Updated detection protocol ${existingVersion} → ${PKG_VERSION} (backup at ${CLAUDE_MD}.arkheia.bak)`);
169
- } catch (err) {
170
- console.error(` [arkheia] Could not update ${CLAUDE_MD}: ${err.message}`);
171
- }
172
- }
139
+ This project uses Arkheia for runtime fabrication detection.
140
+ The \`arkheia_verify\` MCP tool is available in every conversation.
173
141
 
174
- function backup(content) {
175
- try {
176
- fs.writeFileSync(CLAUDE_MD + ".arkheia.bak", content, "utf-8");
177
- } catch {}
178
- }
142
+ ## Verification Protocol
179
143
 
180
- // ── Also install to Codex if present ───────────────────────────
144
+ Before presenting any substantive response to the user:
145
+ 1. Call \`arkheia_verify\` with the model name, prompt, and response
146
+ 2. Check the \`risk\` field in the result
181
147
 
182
- function installCodexMd() {
183
- if (process.env.ARKHEIA_SKIP_CLAUDE_MD === "1") return;
184
- if (!TEMPLATE) return;
148
+ ### Risk Handling
149
+ - **LOW**: Present normally
150
+ - **MEDIUM**: Present with caveat — "Detection flagged medium confidence on this response. Key claims should be verified."
151
+ - **HIGH**: Do not present as-is. Investigate the specific claims against known sources. If claims cannot be verified, regenerate or escalate to the user with the detection result.
185
152
 
186
- const codexDir = path.join(HOME, ".codex");
187
- const codexMd = path.join(codexDir, "CODEX.md");
188
- const newBlock = `${BEGIN_MARKER}\n${TEMPLATE}\n${END_MARKER}`;
153
+ ### Sub-Agent Outputs
154
+ When spawning background agents or parallel workers:
155
+ - Verify each agent's output independently before merging
156
+ - A HIGH risk from any agent blocks the merge until investigated
157
+ - Log all detection results for audit
189
158
 
190
- // Only install if codex CLI exists
191
- try {
192
- execSync(process.platform === "win32" ? "where codex" : "which codex", { stdio: "pipe" });
193
- } catch { return; }
159
+ ### What NOT to Do
160
+ - Do not skip verification because the response "looks correct"
161
+ - Do not suppress HIGH findings — the user needs to know
162
+ - Do not retry the same prompt expecting a different risk score — the fingerprint is consistent
163
+ `;
194
164
 
165
+ function installClaudeMd() {
195
166
  try {
196
- if (!fs.existsSync(codexDir)) fs.mkdirSync(codexDir, { recursive: true, mode: 0o700 });
167
+ const home = process.env.HOME || process.env.USERPROFILE;
168
+ if (!home) return;
197
169
 
198
- if (!fs.existsSync(codexMd)) {
199
- fs.writeFileSync(codexMd, newBlock + "\n", "utf-8");
200
- console.log(` [arkheia] Installed detection protocol to ${codexMd}`);
201
- return;
202
- }
170
+ const claudeDir = path.join(home, ".claude");
171
+ const claudeMdPath = path.join(claudeDir, "CLAUDE.md");
203
172
 
204
- const content = fs.readFileSync(codexMd, "utf-8");
205
- if (content.includes(BEGIN_MARKER)) {
206
- console.log(` [arkheia] Codex protocol already up to date (v${PKG_VERSION})`);
207
- return;
173
+ // Already has the section — skip
174
+ if (fs.existsSync(claudeMdPath)) {
175
+ const existing = fs.readFileSync(claudeMdPath, "utf-8");
176
+ if (existing.includes("Fabrication Detection — Arkheia")) return;
208
177
  }
209
178
 
210
- if (content.match(BEGIN_REGEX)) {
211
- // Upgrade
212
- fs.writeFileSync(codexMd + ".arkheia.bak", content, "utf-8");
213
- const updated = content.replace(BLOCK_REGEX, newBlock);
214
- fs.writeFileSync(codexMd, updated, "utf-8");
215
- console.log(` [arkheia] Updated Codex detection protocol → ${PKG_VERSION}`);
216
- } else {
217
- // Append
218
- fs.writeFileSync(codexMd + ".arkheia.bak", content, "utf-8");
219
- const eol = content.includes("\r\n") ? "\r\n" : "\n";
220
- fs.appendFileSync(codexMd, eol + eol + newBlock + eol, "utf-8");
221
- console.log(` [arkheia] Appended detection protocol to ${codexMd}`);
179
+ // Create ~/.claude/ if needed
180
+ if (!fs.existsSync(claudeDir)) {
181
+ fs.mkdirSync(claudeDir, { recursive: true });
222
182
  }
223
- } catch {}
224
- }
225
-
226
- // ── Main ───────────────────────────────────────────────────────
227
183
 
228
- // API key check
229
- const existingKey = checkApiKey();
230
- if (existingKey) {
231
- const masked = existingKey.substring(0, 8) + "..." + existingKey.substring(existingKey.length - 4);
232
- console.log(`\n [arkheia] API key: ${masked}`);
233
- } else {
234
- console.log(`\n [arkheia] No API key. Get one free at https://arkheia.ai/mcp/account`);
184
+ // Append (or create) the section
185
+ fs.appendFileSync(claudeMdPath, CLAUDE_MD_SECTION, "utf-8");
186
+ console.log(` [arkheia] Fabrication detection protocol installed to ${claudeMdPath}`);
187
+ } catch {
188
+ // Silent — never break the install
189
+ }
235
190
  }
236
191
 
237
- // Install detection protocol
238
192
  installClaudeMd();
239
- installCodexMd();
240
-
241
- console.log(` [arkheia] @arkheia/mcp-server v${PKG_VERSION} ready\n`);
@@ -1,33 +0,0 @@
1
- # Fabrication Detection — Arkheia
2
-
3
- When Arkheia MCP tools are available in this session, follow this protocol.
4
-
5
- ## Detection
6
-
7
- Call `arkheia_verify` on EVERY model response before surfacing it to the user. Do not skip responses that appear obviously correct.
8
-
9
- ## Risk Escalation
10
-
11
- - **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.
12
- - **MEDIUM risk**: Show the response with a brief confidence note.
13
- - **LOW risk**: Show normally.
14
- - **UNKNOWN risk**: Flag for human review. Include the `detection_id`.
15
-
16
- ## Cross-Model Verification
17
-
18
- When HIGH or UNKNOWN risk is detected, offer to verify using: `run_grok`, `run_gemini`, `run_ollama`, `run_together`.
19
-
20
- ## Audit Trail
21
-
22
- Use `arkheia_audit_log` when the user asks about detection history or for compliance evidence.
23
-
24
- ## Persistent Knowledge Graph
25
-
26
- Use `memory_store` to persist facts, `memory_retrieve` to recall them, `memory_relate` to track relationships between entities.
27
-
28
- ## Key Rules
29
-
30
- 1. Never hide a response from the user regardless of risk level
31
- 2. Always include the `detection_id` when reporting HIGH or UNKNOWN risk
32
- 3. Call `arkheia_verify` proactively — do not wait for the user to ask
33
- 4. Audit logging happens automatically through `arkheia_verify`