@arkheia/mcp-server 0.1.5 → 0.1.7

package/dist/providers.js

@@ -0,0 +1,320 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.call_grok = call_grok;
+exports.call_gemini = call_gemini;
+exports.call_together = call_together;
+exports.call_ollama = call_ollama;
+const crypto = __importStar(require("crypto"));
+// Node.js native fetch doesn't have a global logger, use console
+const logger = console;
+const _DEFAULT_TIMEOUT = 60 * 1000; // 60 seconds in milliseconds
+const _OLLAMA_TIMEOUT = 120 * 1000; // 120 seconds in milliseconds
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function _prompt_hash(prompt) {
+    return crypto.createHash('sha256').update(prompt).digest('hex');
+}
+function _err_response(model, prompt, error) {
+    return {
+        response: `[provider_error: ${error}]`,
+        model: model,
+        prompt_hash: _prompt_hash(prompt),
+        error: error,
+    };
+}
+// ---------------------------------------------------------------------------
+// Grok (xAI) — OpenAI-compatible /v1/chat/completions
+// ---------------------------------------------------------------------------
+async function call_grok(prompt, model = "grok-4-fast-non-reasoning", kwargs = {}) {
+    /**
+     * Call xAI Grok chat completions API.
+     *
+     * Returns: {response, model, prompt_hash, error}
+     */
+    const api_key = process.env.XAI_API_KEY;
+    if (!api_key) {
+        return _err_response(model, prompt, "XAI_API_KEY not set");
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), _DEFAULT_TIMEOUT);
+    try {
+        const resp = await fetch("https://api.x.ai/v1/chat/completions", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${api_key}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                model: model,
+                messages: [{ role: "user", content: prompt }],
+                ...kwargs,
+            }),
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!resp.ok) {
+            logger.error(`call_grok: HTTP ${resp.status} for model=${model}`);
+            return _err_response(model, prompt, `http_${resp.status}`);
+        }
+        const data = await resp.json();
+        const response_text = data.choices?.[0]?.message?.content;
+        if (typeof response_text !== 'string') {
+            throw new Error("Invalid response format from Grok API");
+        }
+        return {
+            response: response_text,
+            model: model,
+            prompt_hash: _prompt_hash(prompt),
+            usage: data.usage || {},
+            error: null,
+        };
+    }
+    catch (e) {
+        clearTimeout(timeoutId);
+        if (e.name === 'AbortError') {
+            logger.error(`call_grok: request timed out for model=${model}`);
+            return _err_response(model, prompt, "timeout");
+        }
+        else if (e.name === 'TypeError' && e.message.includes('fetch failed')) {
+            logger.error(`call_grok: network error for model=${model}: ${e.message}`);
+            return _err_response(model, prompt, "network_error");
+        }
+        else {
+            logger.error(`call_grok: unexpected error: ${e.message}`);
+            return _err_response(model, prompt, e.message);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Gemini (Google) — generateContent REST API
+// ---------------------------------------------------------------------------
+async function call_gemini(prompt, model = "gemini-2.5-flash", max_output_tokens = 1000, kwargs = {}) {
+    /**
+     * Call Google Gemini generateContent API.
+     *
+     * Note: gemini-2.5-flash and -pro are thinking models — they need
+     * max_output_tokens >= 1000 to produce content after thinking tokens.
+     *
+     * Returns: {response, model, prompt_hash, error}
+     */
+    const api_key = process.env.GOOGLE_API_KEY;
+    if (!api_key) {
+        return _err_response(model, prompt, "GOOGLE_API_KEY not set");
+    }
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), _DEFAULT_TIMEOUT);
+    try {
+        const resp = await fetch(`${url}?key=${api_key}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                contents: [{ parts: [{ text: prompt }] }],
+                generationConfig: {
+                    maxOutputTokens: max_output_tokens,
+                    ...kwargs,
+                },
+            }),
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!resp.ok) {
+            logger.error(`call_gemini: HTTP ${resp.status} for model=${model}`);
+            return _err_response(model, prompt, `http_${resp.status}`);
+        }
+        const data = await resp.json();
+        const response_text = data.candidates?.[0]?.content?.parts?.[0]?.text;
+        if (typeof response_text !== 'string') {
+            throw new Error("Invalid response format from Gemini API");
+        }
+        return {
+            response: response_text,
+            model: model,
+            prompt_hash: _prompt_hash(prompt),
+            usage: data.usageMetadata || {},
+            error: null,
+        };
+    }
+    catch (e) {
+        clearTimeout(timeoutId);
+        if (e.name === 'AbortError') {
+            logger.error(`call_gemini: request timed out for model=${model}`);
+            return _err_response(model, prompt, "timeout");
+        }
+        else if (e.name === 'TypeError' && e.message.includes('fetch failed')) {
+            logger.error(`call_gemini: network error for model=${model}: ${e.message}`);
+            return _err_response(model, prompt, "network_error");
+        }
+        else {
+            logger.error(`call_gemini: unexpected error: ${e.message}`);
+            return _err_response(model, prompt, e.message);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Together AI — OpenAI-compatible, cloud inference
+// ---------------------------------------------------------------------------
+async function call_together(prompt, model = "moonshotai/Kimi-K2.5", max_tokens = 2048, kwargs = {}) {
+    /**
+     * Call Together AI chat completions API (OpenAI-compatible).
+     *
+     * Default model is Kimi K2.5 — a thinking model that consumes
+     * 100-500 tokens internally before producing output, so max_tokens
+     * must be >= 2048 to reliably get a response.
+     *
+     * Returns: {response, model, prompt_hash, usage, error}
+     */
+    const api_key = process.env.TOGETHER_API_KEY;
+    if (!api_key) {
+        return _err_response(model, prompt, "TOGETHER_API_KEY not set");
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), _DEFAULT_TIMEOUT);
+    try {
+        const resp = await fetch("https://api.together.xyz/v1/chat/completions", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${api_key}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                model: model,
+                max_tokens: max_tokens,
+                messages: [{ role: "user", content: prompt }],
+                ...kwargs,
+            }),
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!resp.ok) {
+            logger.error(`call_together: HTTP ${resp.status} for model=${model}`);
+            return _err_response(model, prompt, `http_${resp.status}`);
+        }
+        const data = await resp.json();
+        const response_text = data.choices?.[0]?.message?.content;
+        if (typeof response_text !== 'string') {
+            throw new Error("Invalid response format from Together AI API");
+        }
+        return {
+            response: response_text,
+            model: model,
+            prompt_hash: _prompt_hash(prompt),
+            usage: data.usage || {},
+            error: null,
+        };
+    }
+    catch (e) {
+        clearTimeout(timeoutId);
+        if (e.name === 'AbortError') {
+            logger.error(`call_together: request timed out for model=${model}`);
+            return _err_response(model, prompt, "timeout");
+        }
+        else if (e.name === 'TypeError' && e.message.includes('fetch failed')) {
+            logger.error(`call_together: network error for model=${model}: ${e.message}`);
+            return _err_response(model, prompt, "network_error");
+        }
+        else {
+            logger.error(`call_together: unexpected error: ${e.message}`);
+            return _err_response(model, prompt, e.message);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Ollama — local inference, no network egress
+// ---------------------------------------------------------------------------
+async function call_ollama(prompt, model = "phi4:14b", kwargs = {}) {
+    /**
+     * Call local Ollama model via /api/generate (non-streaming).
+     *
+     * OLLAMA_BASE_URL defaults to http://localhost:11434.
+     * No network egress — local eval only.
+     *
+     * Returns: {response, model, prompt_hash, eval_count, error}
+     */
+    const base_url = process.env.OLLAMA_BASE_URL || "http://localhost:11434";
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), _OLLAMA_TIMEOUT);
+    try {
+        const resp = await fetch(`${base_url}/api/generate`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                model: model,
+                prompt: prompt,
+                stream: false,
+                ...kwargs,
+            }),
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!resp.ok) {
+            logger.error(`call_ollama: HTTP ${resp.status} for model=${model}`);
+            return _err_response(model, prompt, `http_${resp.status}`);
+        }
+        const data = await resp.json();
+        const response_text = data.response;
+        if (typeof response_text !== 'string') {
+            throw new Error("Invalid response format from Ollama API");
+        }
+        return {
+            response: response_text,
+            model: model,
+            prompt_hash: _prompt_hash(prompt),
+            eval_count: data.eval_count,
+            error: null,
+        };
+    }
+    catch (e) {
+        clearTimeout(timeoutId);
+        if (e.name === 'AbortError') {
+            logger.error(`call_ollama: request timed out for model=${model}`);
+            return _err_response(model, prompt, "timeout");
+        }
+        else if (e.name === 'TypeError' && e.message.includes('fetch failed')) {
+            logger.error(`call_ollama: cannot connect to Ollama at ${base_url}`);
+            return _err_response(model, prompt, "ollama_unavailable");
+        }
+        else {
+            logger.error(`call_ollama: unexpected error: ${e.message}`);
+            return _err_response(model, prompt, e.message);
+        }
+    }
+}

package/dist/proxy-client.js

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyClient = void 0;
+const url_1 = require("url");
+// Node.js native fetch doesn't have a global logger, use console
+const logger = console;
+// Hosted API defaults
+const HOSTED_API_URL = "https://arkheia-proxy-production.up.railway.app";
+class ProxyClient {
+    base_url;
+    timeout; // in milliseconds
+    hosted_url;
+    api_key;
+    _local_available; // optimistic; flips on network errors
+    constructor(base_url, timeout = 10.0, // in seconds
+    hosted_url, api_key) {
+        this.base_url = base_url.endsWith("/") ? base_url.slice(0, -1) : base_url;
+        this.timeout = timeout * 1000; // Convert to milliseconds for fetch AbortController
+        this.hosted_url = (hosted_url || HOSTED_API_URL).endsWith("/")
+            ? (hosted_url || HOSTED_API_URL).slice(0, -1)
+            : (hosted_url || HOSTED_API_URL);
+        this.api_key = api_key || process.env.ARKHEIA_API_KEY;
+        this._local_available = true; // optimistic; flips on ConnectError
+    }
+    async verify(prompt, response, model_id, session_id) {
+        /**
+         * Detect fabrication in a model response.
+         *
+         * Tries local proxy first. If unavailable, falls back to hosted API.
+         * Never raises -- returns UNKNOWN on any error.
+         */
+        // Try local proxy first (if last attempt didn't fail with ConnectError)
+        if (this._local_available) {
+            const result = await this._verify_local(prompt, response, model_id, session_id);
+            if (result.error !== "proxy_unavailable" && result.error !== "proxy_timeout") {
+                return result;
+            }
+            // Local proxy down -- fall through to hosted
+            this._local_available = false;
+            logger.info(`Local proxy unavailable, falling back to hosted API at ${this.hosted_url}`);
+        }
+        // Fallback: hosted API
+        if (this.api_key) {
+            const result = await this._verify_hosted(prompt, response, model_id);
+            if (result.error !== "hosted_unavailable") {
+                return result;
+            }
+            // Hosted also failed -- try local once more in case it came back
+            this._local_available = true; // Reset local availability for next call
+        }
+        // No hosted API key and local is down
+        if (!this.api_key) {
+            logger.warn("Local proxy unavailable and no ARKHEIA_API_KEY set for hosted fallback");
+            return _unavailable("no_detection_available");
+        }
+        return _unavailable("all_detection_paths_failed");
+    }
+    async _verify_local(prompt, response, model_id, session_id) {
+        /** POST /detect/verify on local Enterprise Proxy. */
+        const payload = {
+            prompt: prompt,
+            response: response,
+            model_id: model_id,
+        };
+        if (session_id) {
+            payload["session_id"] = session_id;
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const resp = await fetch(`${this.base_url}/detect/verify`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!resp.ok) {
+                logger.error(`ProxyClient: /detect/verify HTTP error: ${resp.status} ${resp.statusText}`);
+                return _unavailable(`proxy_http_error_${resp.status}`);
+            }
+            return await resp.json();
+        }
+        catch (e) {
+            clearTimeout(timeoutId);
+            if (e.name === 'AbortError') {
+                logger.warn(`ProxyClient: /detect/verify timed out for model=${model_id}`);
+                return _unavailable("proxy_timeout");
+            }
+            else if (e.name === 'TypeError' && e.message.includes('fetch failed')) { // Common for network errors like connection refused
+                logger.warn(`ProxyClient: cannot connect to proxy at ${this.base_url}`);
+                return _unavailable("proxy_unavailable");
+            }
+            else {
+                logger.error(`ProxyClient: /detect/verify unexpected error: ${e.message}`);
+                return _unavailable("proxy_error");
+            }
+        }
+    }
+    async _verify_hosted(prompt, response, model_id) {
+        /** POST /v1/detect on hosted Arkheia API (arkheia-proxy-production.up.railway.app). */
+        const payload = {
+            model: model_id,
+            response: response,
+            prompt: prompt,
+        };
+        const headers = { "X-Arkheia-Key": this.api_key || "" };
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const resp = await fetch(`${this.hosted_url}/v1/detect`, {
+                method: "POST",
+                headers: headers,
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!resp.ok) {
+                const status = resp.status;
+                if (status === 401) {
+                    logger.error("ProxyClient: hosted API rejected API key (401)");
+                    return _unavailable("hosted_auth_failed");
+                }
+                if (status === 429) {
+                    logger.warn("ProxyClient: hosted API rate/quota limit (429)");
+                    return _unavailable("hosted_quota_exceeded");
+                }
+                logger.error(`ProxyClient: hosted /v1/detect HTTP error: ${status} ${resp.statusText}`);
+                return _unavailable(`hosted_http_error_${status}`);
+            }
+            const data = await resp.json();
+            // Map hosted response format to local format
+            return {
+                risk_level: data.risk || "UNKNOWN",
+                confidence: data.confidence || 0.0,
+                features_triggered: data.features_triggered || [],
+                detection_id: data.detection_id,
+                detection_method: data.detection_method,
+                evidence_depth_limited: data.evidence_depth_limited ?? true,
+                source: "hosted",
+            };
+        }
+        catch (e) {
+            clearTimeout(timeoutId);
+            if (e.name === 'AbortError') {
+                logger.warn(`ProxyClient: hosted /v1/detect timed out for model=${model_id}`);
+                return _unavailable("hosted_timeout");
+            }
+            else if (e.name === 'TypeError' && e.message.includes('fetch failed')) {
+                logger.warn(`ProxyClient: cannot connect to hosted API at ${this.hosted_url}`);
+                return _unavailable("hosted_unavailable");
+            }
+            else {
+                logger.error(`ProxyClient: hosted /v1/detect unexpected error: ${e.message}`);
+                return _unavailable("hosted_error");
+            }
+        }
+    }
+    async get_audit_log(session_id, limit = 50) {
+        /**
+         * GET /audit/log
+         *
+         * Returns audit log dict. Never raises -- returns empty log on any error.
+         * Note: audit log is only available from local proxy, not hosted API.
+         */
+        const params = new url_1.URLSearchParams({ limit: String(Math.min(limit, 500)) });
+        if (session_id) {
+            params.append("session_id", session_id);
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const resp = await fetch(`${this.base_url}/audit/log?${params.toString()}`, {
+                method: "GET",
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!resp.ok) {
+                logger.error(`ProxyClient: /audit/log HTTP error: ${resp.status} ${resp.statusText}`);
+                return _empty_log(`proxy_http_error_${resp.status}`);
+            }
+            return await resp.json();
+        }
+        catch (e) {
+            clearTimeout(timeoutId);
+            if (e.name === 'AbortError') {
+                logger.warn("ProxyClient: /audit/log timed out");
+                return _empty_log("proxy_timeout");
+            }
+            else if (e.name === 'TypeError' && e.message.includes('fetch failed')) {
+                logger.warn(`ProxyClient: cannot connect to proxy at ${this.base_url}`);
+                return _empty_log("proxy_unavailable");
+            }
+            else {
+                logger.error(`ProxyClient: /audit/log unexpected error: ${e.message}`);
+                return _empty_log("proxy_error");
+            }
+        }
+    }
+}
+exports.ProxyClient = ProxyClient;
+function _unavailable(error) {
+    /** Standard UNKNOWN response when detection is unreachable. */
+    return {
+        risk_level: "UNKNOWN",
+        confidence: 0.0,
+        features_triggered: [],
+        error: error,
+    };
+}
+function _empty_log(error) {
+    return {
+        events: [],
+        summary: { LOW: 0, MEDIUM: 0, HIGH: 0, UNKNOWN: 0 },
+        error: error,
+    };
+}

package/dist/tool-registry.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyViolation = exports.REGISTRY = exports.Permission = void 0;
+exports.check = check;
+var Permission;
+(function (Permission) {
+    Permission["READ"] = "read";
+    Permission["EXECUTE"] = "execute";
+    Permission["WRITE"] = "write";
+    Permission["DEPLOY"] = "deploy";
+})(Permission || (exports.Permission = Permission = {}));
+// ---------------------------------------------------------------------------
+// The allowlist
+// ---------------------------------------------------------------------------
+exports.REGISTRY = {
+    arkheia_verify: {
+        name: "arkheia_verify",
+        permissions: [Permission.READ],
+        network_egress: true,
+        description: "Screen an AI response for fabrication risk",
+    },
+    arkheia_audit_log: {
+        name: "arkheia_audit_log",
+        permissions: [Permission.READ],
+        network_egress: false,
+        description: "Retrieve structured audit evidence",
+    },
+    run_grok: {
+        name: "run_grok",
+        permissions: [Permission.READ, Permission.EXECUTE],
+        network_egress: true,
+        description: "Call xAI Grok API and screen response through Arkheia",
+    },
+    run_gemini: {
+        name: "run_gemini",
+        permissions: [Permission.READ, Permission.EXECUTE],
+        network_egress: true,
+        description: "Call Google Gemini API and screen response through Arkheia",
+    },
+    run_together: {
+        name: "run_together",
+        permissions: [Permission.READ, Permission.EXECUTE],
+        network_egress: true,
+        description: "Call Together AI API and screen response through Arkheia",
+    },
+    run_ollama: {
+        name: "run_ollama",
+        permissions: [Permission.READ, Permission.EXECUTE],
+        network_egress: false,
+        description: "Call local Ollama model and screen response through Arkheia",
+    },
+    memory_store: {
+        name: "memory_store",
+        permissions: [Permission.READ, Permission.WRITE],
+        network_egress: false,
+        description: "Store an entity and observations in the persistent knowledge graph",
+    },
+    memory_retrieve: {
+        name: "memory_retrieve",
+        permissions: [Permission.READ],
+        network_egress: false,
+        description: "Retrieve entities and their observations from the knowledge graph",
+    },
+    memory_relate: {
+        name: "memory_relate",
+        permissions: [Permission.READ, Permission.WRITE],
+        network_egress: false,
+        description: "Store a named relationship between two entities in the knowledge graph",
+    },
+};
+// ---------------------------------------------------------------------------
+// Policy gate
+// ---------------------------------------------------------------------------
+class PolicyViolation extends Error {
+    tool_name;
+    reason;
+    constructor(tool_name, reason) {
+        super(`Policy violation for '${tool_name}': ${reason}`);
+        this.tool_name = tool_name;
+        this.reason = reason;
+    }
+}
+exports.PolicyViolation = PolicyViolation;
+function check(tool_name) {
+    const policy = exports.REGISTRY[tool_name];
+    if (!policy) {
+        throw new PolicyViolation(tool_name, `not in allowlist — default deny. Known tools: ${Object.keys(exports.REGISTRY).sort().join(", ")}`);
+    }
+    return policy;
+}