@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/README.md +109 -177
- package/bin/arkheia-mcp.js +207 -0
- package/package.json +26 -26
- package/python/mcp_server/__init__.py +0 -0
- package/python/requirements.txt +4 -0
- package/scripts/build.js +33 -33
- package/scripts/setup.js +130 -179
- package/CLAUDE_MD_TEMPLATE.md +0 -33
- package/dist/index.js +0 -260
- package/dist/memory.js +0 -187
- package/dist/providers.js +0 -320
- package/dist/proxy-client.js +0 -219
- package/dist/tool-registry.js +0 -90
- package/scripts/setup-claude.js +0 -163
package/scripts/setup.js
CHANGED
|
@@ -1,241 +1,192 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
/**
|
|
3
|
-
* Post-install script
|
|
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
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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)
|
|
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))
|
|
65
|
-
|
|
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
|
-
}
|
|
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
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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
|
-
|
|
85
|
-
console.log(" [arkheia] Warning: CLAUDE_MD_TEMPLATE.md not found in package");
|
|
86
|
-
return;
|
|
87
|
-
}
|
|
75
|
+
const python = checkPython();
|
|
88
76
|
|
|
89
|
-
|
|
77
|
+
if (!python) {
|
|
78
|
+
console.log(`
|
|
79
|
+
============================================================
|
|
80
|
+
Arkheia MCP Server requires Python 3.10+
|
|
90
81
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
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
|
-
|
|
102
|
-
|
|
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
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
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
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
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
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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
|
-
|
|
159
|
-
|
|
160
|
-
return;
|
|
161
|
-
}
|
|
136
|
+
const CLAUDE_MD_SECTION = `
|
|
137
|
+
# Fabrication Detection — Arkheia
|
|
162
138
|
|
|
163
|
-
|
|
164
|
-
|
|
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
|
-
|
|
175
|
-
try {
|
|
176
|
-
fs.writeFileSync(CLAUDE_MD + ".arkheia.bak", content, "utf-8");
|
|
177
|
-
} catch {}
|
|
178
|
-
}
|
|
142
|
+
## Verification Protocol
|
|
179
143
|
|
|
180
|
-
|
|
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
|
-
|
|
183
|
-
|
|
184
|
-
|
|
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
|
-
|
|
187
|
-
|
|
188
|
-
|
|
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
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
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
|
-
|
|
167
|
+
const home = process.env.HOME || process.env.USERPROFILE;
|
|
168
|
+
if (!home) return;
|
|
197
169
|
|
|
198
|
-
|
|
199
|
-
|
|
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
|
-
|
|
205
|
-
if (
|
|
206
|
-
|
|
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
|
|
211
|
-
|
|
212
|
-
fs.
|
|
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
|
-
//
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
}
|
|
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`);
|
package/CLAUDE_MD_TEMPLATE.md
DELETED
|
@@ -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`
|