starkgate-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# 🛡️ starkgate-mcp-server
+
+[![npm](https://img.shields.io/npm/v/starkgate-mcp-server)](https://www.npmjs.com/package/starkgate-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**MCP server** ([Model Context Protocol](https://modelcontextprotocol.io)) qui fait passer les appels d'outils de tes agents IA par le firewall universel **StarkGate** — évaluation **fail-closed**, preuve `auditHash` vérifiable hors-ligne.
+
+## Installation
+
+Aucune installation nécessaire avec npx :
+
+```bash
+npx starkgate-mcp-server
+```
+
+Ou en global :
+
+```bash
+npm install -g starkgate-mcp-server
+```
+
+## Configuration (Claude Desktop & autres clients MCP)
+
+Ajoute à ton `claude_desktop_config.json` :
+
+```json
+{
+  "mcpServers": {
+    "starkgate": {
+      "command": "npx",
+      "args": ["-y", "starkgate-mcp-server"],
+      "env": {
+        "STARKGATE_API_KEY": "sk_live_votre_cle",
+        "STARKGATE_API_URL": "https://sentinel-api.wenjoseph16.workers.dev",
+        "STARKGATE_POLICY_ID": "pol-demo",
+        "STARKGATE_AGENT_ID": "claude-desktop"
+      }
+    }
+  }
+}
+```
+
+| Variable | Requis | Défaut | Description |
+|---|---|---|---|
+| `STARKGATE_API_KEY` | pour evaluate | — | Clé API (`sk_live_…`) — sans elle, `starkgate_evaluate` répond DENY fail-closed |
+| `STARKGATE_API_URL` | non | `https://sentinel-api.wenjoseph16.workers.dev` | URL de l'API StarkGate |
+| `STARKGATE_POLICY_ID` | non | `pol-demo` | Policy par défaut |
+| `STARKGATE_AGENT_ID` | non | `mcp-agent` | Identifiant de l'agent envoyé aux évaluations |
+
+## Tools exposés
+
+### `starkgate_evaluate`
+
+Évalue une action avant exécution :
+
+```json
+{
+  "actionType": "terminal.command",
+  "payload": { "cmd": "rm -rf /" },
+  "agentId": "mon-agent",
+  "policyId": "pol-demo"
+}
+```
+
+Réponse :
+
+```json
+{
+  "decision": "DENY",
+  "reason": "Destructive command blocked by rule 'no-rm-rf'",
+  "matchedRule": "no-rm-rf",
+  "auditHash": "sha256:9f2c…",
+  "riskScore": 95
+}
+```
+
+- **Fail-closed** : erreur réseau/HTTP → `DENY` (jamais de fail-open silencieux).
+- L'`auditHash` permet de **vérifier la preuve hors-ligne** (voir SDK Python `starkgate.local_audit`).
+
+### `starkgate_health`
+
+Ping l'API (aucune clé requise) → `{"status": "ok", "apiUrl": "…"}`.
+
+## Usage programmatique (librairie)
+
+Pour wrapper vos propres tools MCP avec le guard StarkGate :
+
+```typescript
+import { createStarkGateMcpServer } from "starkgate-mcp-server";
+
+const server = createStarkGateMcpServer({
+  apiUrl: "https://sentinel-api.wenjoseph16.workers.dev",
+  apiKey: "sk_live_…",
+  policyId: "pol-demo",
+});
+
+server.wrapTool({
+  name: "read_file",
+  description: "Read a file from the filesystem",
+  inputSchema: { path: z.string() },
+  handler: async (args) => fs.readFile(args.path, "utf-8"),
+});
+
+await server.start();
+```
+
+## Liens
+
+- Docs : https://sentinel-api.wenjoseph16.workers.dev/docs
+- Quickstart : https://sentinel-api.wenjoseph16.workers.dev/quickstart
+- SDK Python : [`pip install starkgate-sdk`](https://pypi.org/project/starkgate-sdk/)
+- Repo : https://github.com/wenjoseph16/starkgate
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * starkgate-mcp-server — CLI (npx starkgate-mcp-server)
+ *
+ * Serveur MCP stdio autonome qui expose StarkGate comme tools MCP :
+ *   - starkgate_evaluate : évalue une action contre une policy (cloud, fail-closed)
+ *   - starkgate_health   : ping de l'API (aucun secret requis)
+ *
+ * Configuration par variables d'environnement :
+ *   STARKGATE_API_KEY   (requis pour evaluate)  ex: sk_live_...
+ *   STARKGATE_API_URL   (optionnel)             défaut: https://sentinel-api.wenjoseph16.workers.dev
+ *   STARKGATE_AGENT_ID  (optionnel)             défaut: mcp-agent
+ *   STARKGATE_POLICY_ID (optionnel)             défaut: pol-demo
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * starkgate-mcp-server — CLI (npx starkgate-mcp-server)
+ *
+ * Serveur MCP stdio autonome qui expose StarkGate comme tools MCP :
+ *   - starkgate_evaluate : évalue une action contre une policy (cloud, fail-closed)
+ *   - starkgate_health   : ping de l'API (aucun secret requis)
+ *
+ * Configuration par variables d'environnement :
+ *   STARKGATE_API_KEY   (requis pour evaluate)  ex: sk_live_...
+ *   STARKGATE_API_URL   (optionnel)             défaut: https://sentinel-api.wenjoseph16.workers.dev
+ *   STARKGATE_AGENT_ID  (optionnel)             défaut: mcp-agent
+ *   STARKGATE_POLICY_ID (optionnel)             défaut: pol-demo
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const DEFAULT_API_URL = "https://sentinel-api.wenjoseph16.workers.dev";
+async function evaluateAction(apiUrl, apiKey, policyId, agentId, actionType, payload) {
+    const failClosed = (decision, reason) => ({
+        decision,
+        reason,
+        matchedRule: null,
+        auditHash: null,
+        riskScore: null,
+    });
+    // Sans clé : pas de round-trip inutile vers l'API — DENY immédiat,
+    // cohérent avec le warning affiché au démarrage.
+    if (!apiKey) {
+        return failClosed("DENY", "StarkGate API key is not set (STARKGATE_API_KEY) — request denied (fail-closed)");
+    }
+    try {
+        const response = await fetch(`${apiUrl}/v1/evaluate`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                agentId,
+                policyId,
+                actionType,
+                payload,
+                nonce: crypto.randomUUID(),
+                timestamp: new Date().toISOString(),
+            }),
+        });
+        if (!response.ok) {
+            // Fail-closed : erreur d'évaluation => DENY (pas de fail-open silencieux).
+            return failClosed("DENY", `StarkGate evaluation failed (HTTP ${response.status})`);
+        }
+        const json = (await response.json());
+        const d = json?.data;
+        if (!d || typeof d.decision !== "string") {
+            return failClosed("DENY", "StarkGate returned an unexpected response");
+        }
+        return {
+            decision: d.decision === "DENY" ? "DENY" : "ALLOW",
+            reason: d.reason ?? "",
+            matchedRule: d.matchedRule ?? null,
+            auditHash: d.auditHash ?? null,
+            riskScore: typeof d.riskScore === "number" ? d.riskScore : null,
+        };
+    }
+    catch (error) {
+        return failClosed("DENY", `StarkGate evaluation error: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+async function healthCheck(apiUrl) {
+    try {
+        const response = await fetch(`${apiUrl}/health`);
+        if (!response.ok)
+            return { status: `http_${response.status}`, apiUrl };
+        const json = (await response.json());
+        return { status: json.status ?? "unknown", apiUrl };
+    }
+    catch (error) {
+        return {
+            status: `unreachable: ${error instanceof Error ? error.message : "unknown"}`,
+            apiUrl,
+        };
+    }
+}
+async function main() {
+    const apiUrl = (process.env.STARKGATE_API_URL || DEFAULT_API_URL).replace(/\/$/, "");
+    const apiKey = process.env.STARKGATE_API_KEY || "";
+    const agentId = process.env.STARKGATE_AGENT_ID || "mcp-agent";
+    const policyId = process.env.STARKGATE_POLICY_ID || "pol-demo";
+    const mcp = new mcp_js_1.McpServer({ name: "starkgate-mcp-server", version: "0.1.0" });
+    mcp.tool("starkgate_evaluate", "Evaluate an agent action against a StarkGate policy (cloud, fail-closed). Returns decision ALLOW/DENY, reason, matched rule and the offline-verifiable auditHash proof.", {
+        actionType: zod_1.z
+            .string()
+            .min(1)
+            .describe("Type of action, e.g. terminal.command, sql_query, send_email"),
+        payload: zod_1.z
+            .record(zod_1.z.string(), zod_1.z.unknown())
+            .describe("Action payload to evaluate, e.g. { \"cmd\": \"rm -rf /\" }"),
+        agentId: zod_1.z.string().min(1).optional().describe("Override agent id (default: STARKGATE_AGENT_ID env or 'mcp-agent')"),
+        policyId: zod_1.z.string().min(1).optional().describe("Override policy id (default: STARKGATE_POLICY_ID env or 'pol-demo')"),
+    }, async (args) => {
+        const out = await evaluateAction(apiUrl, apiKey, args.policyId || policyId, args.agentId || agentId, args.actionType, args.payload);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(out, null, 2),
+                },
+            ],
+        };
+    });
+    mcp.tool("starkgate_health", "Check StarkGate API reachability. No API key required.", {}, async () => {
+        const out = await healthCheck(apiUrl);
+        return {
+            content: [{ type: "text", text: JSON.stringify(out, null, 2) }],
+        };
+    });
+    if (!apiKey) {
+        // Pas de crash : starkgate_evaluate répondra DENY fail-closed avec un
+        // message explicite ; starkgate_health reste utilisable.
+        console.error("starkgate-mcp-server: STARKGATE_API_KEY is not set — starkgate_evaluate will DENY (fail-closed). Set it in your MCP client config.");
+    }
+    const transport = new stdio_js_1.StdioServerTransport();
+    await mcp.connect(transport);
+    console.error(`starkgate-mcp-server started (api: ${apiUrl})`);
+}
+main().catch((error) => {
+    console.error("starkgate-mcp-server fatal:", error);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface StarkGateConfig {
+    apiUrl: string;
+    apiKey: string;
+    policyId: string;
+    failClosed?: boolean;
+}
+export interface EvaluateResult {
+    decision: "ALLOW" | "DENY";
+    reason: string;
+    matchedRule: string | null;
+    wouldBlock: boolean;
+}
+export interface WrappedTool {
+    name: string;
+    description: string;
+    inputSchema: any;
+    handler: (args: any) => Promise<any>;
+}
+/**
+ * Create a StarkGate-guarded MCP server that intercepts all tool calls.
+ *
+ * Usage:
+ * ```typescript
+ * const server = createStarkGateMcpServer({
+ *   apiUrl: "https://starkgate.example.com",
+ *   apiKey: "sk-...",
+ *   policyId: "pol_abc123",
+ * });
+ *
+ * // Wrap any tool
+ * server.wrapTool({
+ *   name: "read_file",
+ *   description: "Read a file from the filesystem",
+ *   inputSchema: { path: z.string() },
+ *   handler: async (args) => fs.readFile(args.path, "utf-8"),
+ * });
+ *
+ * server.start();
+ * ```
+ */
+export declare function createStarkGateMcpServer(config: StarkGateConfig): {
+    wrapTool: (tool: WrappedTool) => void;
+    start: () => Promise<void>;
+    evaluateAction: (agentId: string, actionType: string, payload: Record<string, any>) => Promise<EvaluateResult>;
+    mcp: McpServer;
+};

package/dist/index.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStarkGateMcpServer = createStarkGateMcpServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+/**
+ * Create a StarkGate-guarded MCP server that intercepts all tool calls.
+ *
+ * Usage:
+ * ```typescript
+ * const server = createStarkGateMcpServer({
+ *   apiUrl: "https://starkgate.example.com",
+ *   apiKey: "sk-...",
+ *   policyId: "pol_abc123",
+ * });
+ *
+ * // Wrap any tool
+ * server.wrapTool({
+ *   name: "read_file",
+ *   description: "Read a file from the filesystem",
+ *   inputSchema: { path: z.string() },
+ *   handler: async (args) => fs.readFile(args.path, "utf-8"),
+ * });
+ *
+ * server.start();
+ * ```
+ */
+function createStarkGateMcpServer(config) {
+    const mcp = new mcp_js_1.McpServer({
+        name: "starkgate-mcp-server",
+        version: "0.1.0",
+    });
+    const wrappedTools = new Map();
+    /**
+     * Evaluate an action against StarkGate before executing it.
+     * Returns true if ALLOW, false if DENY.
+     */
+    async function evaluateAction(agentId, actionType, payload) {
+        try {
+            const nonce = crypto.randomUUID();
+            const timestamp = new Date().toISOString();
+            const response = await fetch(`${config.apiUrl}/v1/evaluate`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${config.apiKey}`,
+                },
+                body: JSON.stringify({
+                    agentId,
+                    policyId: config.policyId,
+                    actionType,
+                    payload,
+                    nonce,
+                    timestamp,
+                }),
+            });
+            if (!response.ok) {
+                // Fail-closed: if evaluation fails, deny by default
+                if (config.failClosed !== false) {
+                    return {
+                        decision: "DENY",
+                        reason: `StarkGate evaluation failed (HTTP ${response.status})`,
+                        matchedRule: null,
+                        wouldBlock: false,
+                    };
+                }
+                // Fail-open: allow if explicitly configured
+                return {
+                    decision: "ALLOW",
+                    reason: "StarkGate unavailable, fail-open mode",
+                    matchedRule: null,
+                    wouldBlock: false,
+                };
+            }
+            const result = await response.json();
+            return {
+                decision: result.data.decision,
+                reason: result.data.reason,
+                matchedRule: result.data.matchedRule,
+                wouldBlock: result.data.wouldBlock,
+            };
+        }
+        catch (error) {
+            // Fail-closed on network error
+            if (config.failClosed !== false) {
+                return {
+                    decision: "DENY",
+                    reason: `StarkGate evaluation error: ${error instanceof Error ? error.message : "unknown"}`,
+                    matchedRule: null,
+                    wouldBlock: false,
+                };
+            }
+            return {
+                decision: "ALLOW",
+                reason: "StarkGate unavailable, fail-open mode",
+                matchedRule: null,
+                wouldBlock: false,
+            };
+        }
+    }
+    /**
+     * Wrap a tool with StarkGate guard.
+     * The tool will be evaluated before execution.
+     */
+    function wrapTool(tool) {
+        wrappedTools.set(tool.name, tool);
+        mcp.tool(tool.name, tool.description, tool.inputSchema, async (args) => {
+            // Evaluate against StarkGate before execution
+            const agentId = "mcp-agent"; // Could be configurable
+            const evaluation = await evaluateAction(agentId, tool.name, args);
+            if (evaluation.decision === "DENY") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `🚫 BLOCKED by StarkGate: ${evaluation.reason}${evaluation.matchedRule ? ` (rule: ${evaluation.matchedRule})` : ""}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Execute the original tool
+            try {
+                const result = await tool.handler(args);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error executing ${tool.name}: ${error instanceof Error ? error.message : "unknown error"}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+    /**
+     * Start the MCP server on stdio transport.
+     */
+    async function start() {
+        const transport = new stdio_js_1.StdioServerTransport();
+        await mcp.connect(transport);
+        console.error("StarkGate MCP Server started");
+    }
+    return {
+        wrapTool,
+        start,
+        evaluateAction, // Exposed for testing
+        mcp, // Exposed for testing
+    };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "starkgate-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server that routes agent tool calls through StarkGate's universal firewall — fail-closed evaluation with offline-verifiable proofs.",
+  "license": "MIT",
+  "bin": {
+    "starkgate-mcp-server": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wenjoseph16/starkgate.git",
+    "directory": "starkgate-mcp-server"
+  },
+  "homepage": "https://sentinel-api.wenjoseph16.workers.dev/docs",
+  "bugs": "https://github.com/wenjoseph16/starkgate/issues",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "firewall",
+    "security",
+    "guard",
+    "policy",
+    "starkgate",
+    "claude",
+    "tool-calling"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^4.5.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}