@arkheia/mcp-server 1.2.1 → 1.2.4
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/CLAUDE_MD_TEMPLATE.md +33 -0
- package/README.md +99 -31
- package/dist/egress.js +91 -0
- package/dist/index.js +272 -0
- package/dist/memory.js +192 -0
- package/dist/providers.js +329 -0
- package/dist/proxy-client.js +243 -0
- package/dist/tool-registry.js +90 -0
- package/package.json +27 -26
- package/scripts/setup-claude.js +169 -0
- package/scripts/setup.js +22 -181
- package/bin/arkheia-mcp.js +0 -207
- package/python/mcp_server/__init__.py +0 -0
- package/python/requirements.txt +0 -4
|
@@ -0,0 +1,33 @@
|
|
|
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`
|
package/README.md
CHANGED
|
@@ -6,13 +6,26 @@ 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
|
-
##
|
|
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
|
|
10
23
|
|
|
11
24
|
```bash
|
|
12
|
-
|
|
25
|
+
npm install -g @arkheia/mcp-server
|
|
13
26
|
```
|
|
14
27
|
|
|
15
|
-
Get a free API key:
|
|
28
|
+
Get a free API key at [arkheia.ai/mcp/account](https://arkheia.ai/mcp/account), or via the CLI:
|
|
16
29
|
|
|
17
30
|
```bash
|
|
18
31
|
curl -X POST https://arkheia-proxy-production.up.railway.app/v1/provision \
|
|
@@ -20,49 +33,79 @@ curl -X POST https://arkheia-proxy-production.up.railway.app/v1/provision \
|
|
|
20
33
|
-d '{"email": "you@example.com"}'
|
|
21
34
|
```
|
|
22
35
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
```
|
|
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
|
-
}
|
|
36
|
+
Set your key:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
export ARKHEIA_API_KEY="ak_live_..."
|
|
39
40
|
```
|
|
40
41
|
|
|
41
|
-
|
|
42
|
+
## Register with your CLI
|
|
42
43
|
|
|
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`.
|
|
44
45
|
|
|
45
|
-
|
|
46
|
+
### Claude Code
|
|
46
47
|
|
|
47
|
-
|
|
48
|
+
```bash
|
|
49
|
+
claude mcp add arkheia -s user \
|
|
50
|
+
-e ARKHEIA_API_KEY="$ARKHEIA_API_KEY" \
|
|
51
|
+
-- mcp-server
|
|
52
|
+
```
|
|
48
53
|
|
|
49
|
-
|
|
54
|
+
Config lands in: `~/.claude.json` under `mcpServers.arkheia`
|
|
50
55
|
|
|
51
|
-
Codex
|
|
56
|
+
### Codex
|
|
52
57
|
|
|
53
58
|
```bash
|
|
54
|
-
codex \
|
|
55
|
-
|
|
56
|
-
|
|
59
|
+
codex mcp add arkheia \
|
|
60
|
+
--env ARKHEIA_API_KEY="$ARKHEIA_API_KEY" \
|
|
61
|
+
-- mcp-server
|
|
57
62
|
```
|
|
58
63
|
|
|
59
|
-
|
|
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
|
|
60
83
|
|
|
61
84
|
```bash
|
|
62
|
-
|
|
85
|
+
grok mcp add arkheia \
|
|
86
|
+
-t stdio \
|
|
87
|
+
-c mcp-server \
|
|
88
|
+
-e ARKHEIA_API_KEY="$ARKHEIA_API_KEY"
|
|
63
89
|
```
|
|
64
90
|
|
|
65
|
-
|
|
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
|
|
104
|
+
|
|
105
|
+
# Gemini — no built-in test; start a session and try the tool
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
**Important:** MCP registrations are not hot-reloaded. Restart your CLI session after running `mcp add`.
|
|
66
109
|
|
|
67
110
|
## What You Get
|
|
68
111
|
|
|
@@ -74,6 +117,9 @@ Use MCP for targeted checks and the proxy for automatic workflow-level detection
|
|
|
74
117
|
| `run_gemini` | Call Gemini + screen for fabrication |
|
|
75
118
|
| `run_ollama` | Call local Ollama model + screen |
|
|
76
119
|
| `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 |
|
|
77
123
|
|
|
78
124
|
## 35+ Model Profiles
|
|
79
125
|
|
|
@@ -88,6 +134,27 @@ GPT-4o, GPT-5.4, Claude Opus/Sonnet/Haiku, Gemini 2.5/3.0, Grok 4, Llama, Mixtra
|
|
|
88
134
|
| Professional | $499/month | Unlimited |
|
|
89
135
|
| Team | $1,999/month | Unlimited |
|
|
90
136
|
|
|
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
|
+
|
|
91
158
|
## Full Documentation
|
|
92
159
|
|
|
93
160
|
See the [GitHub repo](https://github.com/arkheiaai/arkheia-mcp) for:
|
|
@@ -106,4 +173,5 @@ Every message is read by the founder.
|
|
|
106
173
|
## Links
|
|
107
174
|
|
|
108
175
|
- Website: https://arkheia.ai
|
|
176
|
+
- MCP Account: https://arkheia.ai/mcp/account
|
|
109
177
|
- GitHub: https://github.com/arkheiaai/arkheia-mcp
|
package/dist/egress.js
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.DEFAULT_VERIFIER_URL = exports.DEFAULT_OLLAMA_URL = exports.HOSTED_API_URL = void 0;
|
|
4
|
+
exports.isLoopbackOrigin = isLoopbackOrigin;
|
|
5
|
+
exports.displayHost = displayHost;
|
|
6
|
+
exports.isArkheiaHostedOrigin = isArkheiaHostedOrigin;
|
|
7
|
+
exports.computeEgress = computeEgress;
|
|
8
|
+
exports.applyEgress = applyEgress;
|
|
9
|
+
const tool_registry_js_1 = require("./tool-registry.js");
|
|
10
|
+
// The built-in hosted API address (the same one ProxyClient defaults to).
|
|
11
|
+
exports.HOSTED_API_URL = "https://arkheia-proxy-production.up.railway.app";
|
|
12
|
+
exports.DEFAULT_OLLAMA_URL = "http://localhost:11434";
|
|
13
|
+
exports.DEFAULT_VERIFIER_URL = "http://localhost:8098";
|
|
14
|
+
/** True only for http(s) addresses whose host is localhost, 127.0.0.0/8 or ::1 (any port, any case). */
|
|
15
|
+
function isLoopbackOrigin(value) {
|
|
16
|
+
if (!value)
|
|
17
|
+
return false;
|
|
18
|
+
let u;
|
|
19
|
+
try {
|
|
20
|
+
u = new URL(value);
|
|
21
|
+
}
|
|
22
|
+
catch {
|
|
23
|
+
return false;
|
|
24
|
+
}
|
|
25
|
+
if (u.protocol !== "http:" && u.protocol !== "https:")
|
|
26
|
+
return false;
|
|
27
|
+
const h = u.hostname.toLowerCase();
|
|
28
|
+
if (h === "localhost" || h === "[::1]")
|
|
29
|
+
return true;
|
|
30
|
+
const m = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
|
|
31
|
+
return !!m && m[1] === "127" && m.slice(2).every((o) => Number(o) <= 255);
|
|
32
|
+
}
|
|
33
|
+
/** The origin only (host and port), never userinfo, path or query. */
|
|
34
|
+
function displayHost(value) {
|
|
35
|
+
try {
|
|
36
|
+
return new URL(value || "").host || "an address that is not valid";
|
|
37
|
+
}
|
|
38
|
+
catch {
|
|
39
|
+
return "an address that is not valid";
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* True when the address is the Arkheia hosted service: the built-in hosted origin or the configured custom hosted
|
|
44
|
+
* URL (origins compared parsed: host case-insensitive, default ports normalised). An address that cannot be parsed is
|
|
45
|
+
* refused (returns true), so the local-only path never sends to something it cannot classify.
|
|
46
|
+
*/
|
|
47
|
+
function isArkheiaHostedOrigin(value, customHostedUrl) {
|
|
48
|
+
let origin;
|
|
49
|
+
try {
|
|
50
|
+
origin = new URL(value || "").origin;
|
|
51
|
+
}
|
|
52
|
+
catch {
|
|
53
|
+
return true;
|
|
54
|
+
}
|
|
55
|
+
if (origin === "null")
|
|
56
|
+
return true;
|
|
57
|
+
const hosted = [exports.HOSTED_API_URL, customHostedUrl].filter((x) => !!x);
|
|
58
|
+
for (const h of hosted) {
|
|
59
|
+
try {
|
|
60
|
+
if (new URL(h).origin === origin)
|
|
61
|
+
return true;
|
|
62
|
+
}
|
|
63
|
+
catch { /* an unparseable hosted setting cannot match */ }
|
|
64
|
+
}
|
|
65
|
+
return false;
|
|
66
|
+
}
|
|
67
|
+
function computeEgress(env) {
|
|
68
|
+
const ollama = env.OLLAMA_BASE_URL || exports.DEFAULT_OLLAMA_URL;
|
|
69
|
+
const verifier = env.ARKHEIA_PROXY_URL || exports.DEFAULT_VERIFIER_URL;
|
|
70
|
+
const remote = [];
|
|
71
|
+
if (!isLoopbackOrigin(ollama))
|
|
72
|
+
remote.push(`Ollama at ${displayHost(ollama)}`);
|
|
73
|
+
if (!isLoopbackOrigin(verifier))
|
|
74
|
+
remote.push(`verifier at ${displayHost(verifier)}`);
|
|
75
|
+
const run_ollama = remote.length === 0
|
|
76
|
+
? { network_egress: false, description: "Uses local addresses: calls the Ollama address and the verifier address configured here (both recognised local addresses). Never contacts the Arkheia hosted service. If the local verifier is unavailable the response is returned unchecked." }
|
|
77
|
+
: { network_egress: true, description: `Calls the Ollama address and verifier address you configured (outside the recognised local addresses: ${remote.join(" and ")}). Never contacts the Arkheia hosted service.` };
|
|
78
|
+
const audit = isLoopbackOrigin(verifier)
|
|
79
|
+
? { network_egress: false, description: "Retrieve structured audit evidence for compliance review. Reads the audit log from the verifier address configured here (a recognised local address)." }
|
|
80
|
+
: { network_egress: true, description: `Retrieve structured audit evidence for compliance review. Reads the audit log from the verifier address you configured (outside the recognised local addresses: ${displayHost(verifier)}).` };
|
|
81
|
+
return { run_ollama, arkheia_audit_log: audit };
|
|
82
|
+
}
|
|
83
|
+
/** Sets the registry's egress flags and descriptions from the actual configuration; returns them for the tool descriptions. */
|
|
84
|
+
function applyEgress(env) {
|
|
85
|
+
const e = computeEgress(env);
|
|
86
|
+
for (const k of ["run_ollama", "arkheia_audit_log"]) {
|
|
87
|
+
tool_registry_js_1.REGISTRY[k].network_egress = e[k].network_egress;
|
|
88
|
+
tool_registry_js_1.REGISTRY[k].description = e[k].description;
|
|
89
|
+
}
|
|
90
|
+
return e;
|
|
91
|
+
}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
4
|
+
if (k2 === undefined) k2 = k;
|
|
5
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
6
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
7
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
8
|
+
}
|
|
9
|
+
Object.defineProperty(o, k2, desc);
|
|
10
|
+
}) : (function(o, m, k, k2) {
|
|
11
|
+
if (k2 === undefined) k2 = k;
|
|
12
|
+
o[k2] = m[k];
|
|
13
|
+
}));
|
|
14
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
15
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
16
|
+
}) : function(o, v) {
|
|
17
|
+
o["default"] = v;
|
|
18
|
+
});
|
|
19
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
20
|
+
var ownKeys = function(o) {
|
|
21
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
22
|
+
var ar = [];
|
|
23
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
24
|
+
return ar;
|
|
25
|
+
};
|
|
26
|
+
return ownKeys(o);
|
|
27
|
+
};
|
|
28
|
+
return function (mod) {
|
|
29
|
+
if (mod && mod.__esModule) return mod;
|
|
30
|
+
var result = {};
|
|
31
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
32
|
+
__setModuleDefault(result, mod);
|
|
33
|
+
return result;
|
|
34
|
+
};
|
|
35
|
+
})();
|
|
36
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
37
|
+
const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
|
|
38
|
+
const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
|
|
39
|
+
const zod_1 = require("zod");
|
|
40
|
+
const path = __importStar(require("path"));
|
|
41
|
+
const os = __importStar(require("os"));
|
|
42
|
+
const fs = __importStar(require("fs"));
|
|
43
|
+
const proxy_client_js_1 = require("./proxy-client.js");
|
|
44
|
+
const tool_registry_js_1 = require("./tool-registry.js");
|
|
45
|
+
const egress_js_1 = require("./egress.js");
|
|
46
|
+
const providers_js_1 = require("./providers.js");
|
|
47
|
+
const memory_js_1 = require("./memory.js");
|
|
48
|
+
// ---------------------------------------------------------------------------
|
|
49
|
+
// Config Loading
|
|
50
|
+
// ---------------------------------------------------------------------------
|
|
51
|
+
function loadConfig() {
|
|
52
|
+
const configPath = path.join(os.homedir(), '.arkheia', 'config.json');
|
|
53
|
+
if (!fs.existsSync(configPath))
|
|
54
|
+
return;
|
|
55
|
+
try {
|
|
56
|
+
const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
|
|
57
|
+
if (config.api_key && !process.env.ARKHEIA_API_KEY) {
|
|
58
|
+
process.env.ARKHEIA_API_KEY = config.api_key;
|
|
59
|
+
process.stderr.write(`[arkheia] API key loaded from ${configPath}\n`);
|
|
60
|
+
}
|
|
61
|
+
if (config.proxy_url && !process.env.ARKHEIA_HOSTED_URL) {
|
|
62
|
+
process.env.ARKHEIA_HOSTED_URL = config.proxy_url;
|
|
63
|
+
process.stderr.write(`[arkheia] Hosted URL: ${config.proxy_url}\n`);
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
catch (e) {
|
|
67
|
+
process.stderr.write(`[arkheia] Warning: Could not read ${configPath}\n`);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
function checkCRLF() {
|
|
71
|
+
for (const k of ['ARKHEIA_API_KEY', 'ARKHEIA_PROXY_URL', 'ARKHEIA_HOSTED_URL']) {
|
|
72
|
+
const v = process.env[k];
|
|
73
|
+
if (v && /[\r\n]/.test(v)) {
|
|
74
|
+
process.stderr.write(`[arkheia] WARNING: ${k} contains whitespace/newline characters. Run 'dos2unix' on your env file.\n`);
|
|
75
|
+
process.env[k] = v.trim();
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
// ---------------------------------------------------------------------------
|
|
80
|
+
// Helpers
|
|
81
|
+
// ---------------------------------------------------------------------------
|
|
82
|
+
function wrapResult(result) {
|
|
83
|
+
return { content: [{ type: "text", text: JSON.stringify(result) }] };
|
|
84
|
+
}
|
|
85
|
+
function handleError(toolName, e) {
|
|
86
|
+
if (e instanceof tool_registry_js_1.PolicyViolation) {
|
|
87
|
+
return wrapResult({ error: e.reason, risk_level: "UNKNOWN" });
|
|
88
|
+
}
|
|
89
|
+
process.stderr.write(`[arkheia] ${toolName} error: ${e.message}\n`);
|
|
90
|
+
return wrapResult({ error: e.message, risk_level: "UNKNOWN" });
|
|
91
|
+
}
|
|
92
|
+
// ---------------------------------------------------------------------------
|
|
93
|
+
// Main
|
|
94
|
+
// ---------------------------------------------------------------------------
|
|
95
|
+
const CURRENT_VERSION = "1.2.4";
|
|
96
|
+
async function checkForUpdate() {
|
|
97
|
+
// Check once per day — skip if checked recently
|
|
98
|
+
const markerPath = path.join(os.homedir(), '.arkheia', '.update-check');
|
|
99
|
+
try {
|
|
100
|
+
if (fs.existsSync(markerPath)) {
|
|
101
|
+
const age = Date.now() - fs.statSync(markerPath).mtimeMs;
|
|
102
|
+
if (age < 24 * 60 * 60 * 1000)
|
|
103
|
+
return; // checked within 24h
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
catch { }
|
|
107
|
+
try {
|
|
108
|
+
const resp = await fetch('https://registry.npmjs.org/@arkheia/mcp-server/latest', {
|
|
109
|
+
redirect: 'error',
|
|
110
|
+
signal: AbortSignal.timeout(5000),
|
|
111
|
+
});
|
|
112
|
+
if (resp.ok) {
|
|
113
|
+
const data = await resp.json();
|
|
114
|
+
if (data.version && data.version !== CURRENT_VERSION) {
|
|
115
|
+
process.stderr.write(`[arkheia] Update available: ${CURRENT_VERSION} → ${data.version}\n` +
|
|
116
|
+
`[arkheia] Run: npm update -g @arkheia/mcp-server\n`);
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
// Touch marker regardless of result
|
|
120
|
+
const dir = path.dirname(markerPath);
|
|
121
|
+
if (!fs.existsSync(dir))
|
|
122
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
123
|
+
fs.writeFileSync(markerPath, new Date().toISOString());
|
|
124
|
+
}
|
|
125
|
+
catch {
|
|
126
|
+
// Network failure — silently skip, don't block startup
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
async function main() {
|
|
130
|
+
// --setup flag: install protocol + register MCP with all detected CLIs, then exit
|
|
131
|
+
if (process.argv.includes('--setup')) {
|
|
132
|
+
const { execSync } = await import('child_process');
|
|
133
|
+
const setupScript = path.join(__dirname, '..', 'scripts', 'setup-claude.js');
|
|
134
|
+
execSync(`node "${setupScript}"`, { stdio: 'inherit', env: process.env });
|
|
135
|
+
process.exit(0);
|
|
136
|
+
}
|
|
137
|
+
loadConfig();
|
|
138
|
+
checkCRLF();
|
|
139
|
+
// Opt-in only: the check writes ~/.arkheia/.update-check, and a default run must change nothing in the user's
|
|
140
|
+
// home (B-288, Codex R1). Set ARKHEIA_UPDATE_CHECK=1 to enable it.
|
|
141
|
+
if (process.env.ARKHEIA_UPDATE_CHECK === "1")
|
|
142
|
+
checkForUpdate(); // fire-and-forget, never blocks startup
|
|
143
|
+
const ARKHEIA_PROXY_URL = process.env.ARKHEIA_PROXY_URL || "http://localhost:8098";
|
|
144
|
+
const ARKHEIA_HOSTED_URL = process.env.ARKHEIA_HOSTED_URL || "https://arkheia-proxy-production.up.railway.app";
|
|
145
|
+
const ARKHEIA_API_KEY = process.env.ARKHEIA_API_KEY;
|
|
146
|
+
if (!ARKHEIA_API_KEY) {
|
|
147
|
+
process.stderr.write("[arkheia] Warning: ARKHEIA_API_KEY not set.\n" +
|
|
148
|
+
"Get a free API key at https://arkheia.ai/mcp\n" +
|
|
149
|
+
"Then set: export ARKHEIA_API_KEY=ak_live_...\n\n");
|
|
150
|
+
}
|
|
151
|
+
const egress = (0, egress_js_1.applyEgress)(process.env);
|
|
152
|
+
const proxy = new proxy_client_js_1.ProxyClient(ARKHEIA_PROXY_URL, 10.0, ARKHEIA_HOSTED_URL, ARKHEIA_API_KEY);
|
|
153
|
+
const server = new mcp_js_1.McpServer({ name: "arkheia-trust", version: "1.2.4" });
|
|
154
|
+
// ── Detection & audit ──────────────────────────────────────────
|
|
155
|
+
server.tool("arkheia_verify", "Verify whether an AI response shows signs of fabrication. Call this on EVERY model response before acting on it. Risk guidance: HIGH = warn the user this response may be fabricated and include the detection_id, but still show them the response with the warning. MEDIUM = show with a brief confidence note. LOW = show normally. Never hide or suppress a response — always surface it to the user with the appropriate risk context.", { prompt: zod_1.z.string(), response: zod_1.z.string(), model: zod_1.z.string() }, async ({ prompt, response, model }) => {
|
|
156
|
+
try {
|
|
157
|
+
(0, tool_registry_js_1.check)("arkheia_verify");
|
|
158
|
+
const result = await proxy.verify(prompt, response, model);
|
|
159
|
+
return wrapResult(result);
|
|
160
|
+
}
|
|
161
|
+
catch (e) {
|
|
162
|
+
return handleError("arkheia_verify", e);
|
|
163
|
+
}
|
|
164
|
+
});
|
|
165
|
+
server.tool("arkheia_audit_log", egress.arkheia_audit_log.description, { session_id: zod_1.z.string().optional(), limit: zod_1.z.number().int().min(1).max(500).default(50) }, async ({ session_id, limit }) => {
|
|
166
|
+
try {
|
|
167
|
+
(0, tool_registry_js_1.check)("arkheia_audit_log");
|
|
168
|
+
const result = await proxy.get_audit_log(session_id, Math.min(limit, 500));
|
|
169
|
+
return wrapResult(result);
|
|
170
|
+
}
|
|
171
|
+
catch (e) {
|
|
172
|
+
return handleError("arkheia_audit_log", e);
|
|
173
|
+
}
|
|
174
|
+
});
|
|
175
|
+
// ── Provider wrappers ──────────────────────────────────────────
|
|
176
|
+
server.tool("run_grok", "Call xAI Grok and screen the response through Arkheia for fabrication.", { prompt: zod_1.z.string(), model: zod_1.z.string().default("grok-4-fast-non-reasoning") }, async ({ prompt, model }) => {
|
|
177
|
+
try {
|
|
178
|
+
(0, tool_registry_js_1.check)("run_grok");
|
|
179
|
+
const pr = await (0, providers_js_1.call_grok)(prompt, model);
|
|
180
|
+
if (pr.error)
|
|
181
|
+
return wrapResult({ ...pr, arkheia: { risk_level: "UNKNOWN", error: pr.error } });
|
|
182
|
+
const risk = await proxy.verify(prompt, pr.response, model);
|
|
183
|
+
return wrapResult({ ...pr, arkheia: risk });
|
|
184
|
+
}
|
|
185
|
+
catch (e) {
|
|
186
|
+
return handleError("run_grok", e);
|
|
187
|
+
}
|
|
188
|
+
});
|
|
189
|
+
server.tool("run_gemini", "Call Google Gemini and screen the response through Arkheia for fabrication.", { prompt: zod_1.z.string(), model: zod_1.z.string().default("gemini-2.5-flash") }, async ({ prompt, model }) => {
|
|
190
|
+
try {
|
|
191
|
+
(0, tool_registry_js_1.check)("run_gemini");
|
|
192
|
+
const pr = await (0, providers_js_1.call_gemini)(prompt, model);
|
|
193
|
+
if (pr.error)
|
|
194
|
+
return wrapResult({ ...pr, arkheia: { risk_level: "UNKNOWN", error: pr.error } });
|
|
195
|
+
const risk = await proxy.verify(prompt, pr.response, model);
|
|
196
|
+
return wrapResult({ ...pr, arkheia: risk });
|
|
197
|
+
}
|
|
198
|
+
catch (e) {
|
|
199
|
+
return handleError("run_gemini", e);
|
|
200
|
+
}
|
|
201
|
+
});
|
|
202
|
+
server.tool("run_ollama", egress.run_ollama.description, { prompt: zod_1.z.string(), model: zod_1.z.string().default("phi4:14b") }, async ({ prompt, model }) => {
|
|
203
|
+
try {
|
|
204
|
+
(0, tool_registry_js_1.check)("run_ollama");
|
|
205
|
+
// Never contact the Arkheia hosted service from this tool: refuse before the model request sends anything.
|
|
206
|
+
const ollamaUrl = process.env.OLLAMA_BASE_URL || egress_js_1.DEFAULT_OLLAMA_URL;
|
|
207
|
+
if ((0, egress_js_1.isArkheiaHostedOrigin)(ollamaUrl, process.env.ARKHEIA_HOSTED_URL)) {
|
|
208
|
+
const err = "configuration_error: OLLAMA_BASE_URL is the Arkheia hosted service (or cannot be read as an address); nothing was sent. Set it to your Ollama server.";
|
|
209
|
+
return wrapResult({ response: "", model, error: err, arkheia: { risk_level: "UNKNOWN", error: "not_checked_ollama_address_not_usable" } });
|
|
210
|
+
}
|
|
211
|
+
const pr = await (0, providers_js_1.call_ollama)(prompt, model);
|
|
212
|
+
if (pr.error)
|
|
213
|
+
return wrapResult({ ...pr, arkheia: { risk_level: "UNKNOWN", error: pr.error } });
|
|
214
|
+
const risk = await proxy.verify(prompt, pr.response, model, undefined, { allowHosted: false });
|
|
215
|
+
return wrapResult({ ...pr, arkheia: risk });
|
|
216
|
+
}
|
|
217
|
+
catch (e) {
|
|
218
|
+
return handleError("run_ollama", e);
|
|
219
|
+
}
|
|
220
|
+
});
|
|
221
|
+
server.tool("run_together", "Call Together AI (Kimi K2.5, DeepSeek, etc.) and screen the response through Arkheia.", { prompt: zod_1.z.string(), model: zod_1.z.string().default("moonshotai/Kimi-K2.5") }, async ({ prompt, model }) => {
|
|
222
|
+
try {
|
|
223
|
+
(0, tool_registry_js_1.check)("run_together");
|
|
224
|
+
const pr = await (0, providers_js_1.call_together)(prompt, model);
|
|
225
|
+
if (pr.error)
|
|
226
|
+
return wrapResult({ ...pr, arkheia: { risk_level: "UNKNOWN", error: pr.error } });
|
|
227
|
+
const risk = await proxy.verify(prompt, pr.response, model);
|
|
228
|
+
return wrapResult({ ...pr, arkheia: risk });
|
|
229
|
+
}
|
|
230
|
+
catch (e) {
|
|
231
|
+
return handleError("run_together", e);
|
|
232
|
+
}
|
|
233
|
+
});
|
|
234
|
+
// ── Memory / Knowledge Graph ───────────────────────────────────
|
|
235
|
+
server.tool("memory_store", "Store an entity and its observations in the persistent knowledge graph. Entities are upserted by name+type.", { name: zod_1.z.string(), entity_type: zod_1.z.string(), observations: zod_1.z.array(zod_1.z.string()) }, async ({ name, entity_type, observations }) => {
|
|
236
|
+
try {
|
|
237
|
+
(0, tool_registry_js_1.check)("memory_store");
|
|
238
|
+
const result = await (0, memory_js_1.store_entity)(name, entity_type, observations);
|
|
239
|
+
return wrapResult(result);
|
|
240
|
+
}
|
|
241
|
+
catch (e) {
|
|
242
|
+
return handleError("memory_store", e);
|
|
243
|
+
}
|
|
244
|
+
});
|
|
245
|
+
server.tool("memory_retrieve", "Search entities in the persistent knowledge graph by name (case-insensitive).", { query: zod_1.z.string(), entity_type: zod_1.z.string().optional(), limit: zod_1.z.number().int().min(1).max(50).default(10) }, async ({ query, entity_type, limit }) => {
|
|
246
|
+
try {
|
|
247
|
+
(0, tool_registry_js_1.check)("memory_retrieve");
|
|
248
|
+
const result = await (0, memory_js_1.retrieve_entities)(query, entity_type, Math.min(limit, 50));
|
|
249
|
+
return wrapResult(result);
|
|
250
|
+
}
|
|
251
|
+
catch (e) {
|
|
252
|
+
return handleError("memory_retrieve", e);
|
|
253
|
+
}
|
|
254
|
+
});
|
|
255
|
+
server.tool("memory_relate", "Store a named relationship between two entities in the knowledge graph.", { from_entity: zod_1.z.string(), relation_type: zod_1.z.string(), to_entity: zod_1.z.string() }, async ({ from_entity, relation_type, to_entity }) => {
|
|
256
|
+
try {
|
|
257
|
+
(0, tool_registry_js_1.check)("memory_relate");
|
|
258
|
+
const result = await (0, memory_js_1.store_relation)(from_entity, relation_type, to_entity);
|
|
259
|
+
return wrapResult(result);
|
|
260
|
+
}
|
|
261
|
+
catch (e) {
|
|
262
|
+
return handleError("memory_relate", e);
|
|
263
|
+
}
|
|
264
|
+
});
|
|
265
|
+
// ── Start ──────────────────────────────────────────────────────
|
|
266
|
+
const transport = new stdio_js_1.StdioServerTransport();
|
|
267
|
+
await server.connect(transport);
|
|
268
|
+
}
|
|
269
|
+
main().catch((err) => {
|
|
270
|
+
process.stderr.write(`[arkheia] Fatal error: ${err}\n`);
|
|
271
|
+
process.exit(1);
|
|
272
|
+
});
|