@ackuity/inline-proxy 0.7.0

package/LICENSE

@@ -0,0 +1,12 @@
+Ackuity MCP Proxy - A security-focused Model Context Protocol proxy component for multi-agent AI systems.
+This license applies solely to the MCP Proxy component of the Ackuity AI Security Platform. Other components of the platform may be subject to separate license terms.
+ 
+MIT License
+ 
+Copyright (c) 2026 Ackuity, Inc.
+ 
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ 
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# Ackuity Inline MCP Proxy
+
+A transparent MCP proxy that intercepts tool calls and evaluates them against the [Ackuity Inline Decision Engine](https://ackuity.ai) before they reach the MCP server. Destructive operations (DELETE, DROP, TRUNCATE) are blocked in real time.
+
+## How It Works
+
+```
+MCP Client (LLM Agent)
+        │
+        ▼
+┌──────────────────────┐
+│  Ackuity Inline      │
+│  MCP Proxy           │──── tools/call ──▶ Inline Decision Engine
+│                      │◀─── allow/block ──┘
+└──────────────────────┘
+        │ (if allowed)
+        ▼
+   MCP Server (e.g. DAB)
+```
+
+The proxy sits between any MCP client and MCP server. When it sees a `tools/call` request, it sends the tool name and arguments to the Ackuity `protect_tools` API. If the decision is **block**, an error is returned to the client and the call never reaches the MCP server.
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+Set these environment variables, or add them to a `.env` file in the project root:
+
+| Variable           | Required | Description                                      | Default                                              |
+|--------------------|----------|--------------------------------------------------|------------------------------------------------------|
+| `INLINE_API_TOKEN` | Yes      | Bearer token for the Inline Decision Engine      | —  |
+| `INLINE_URL`       | Yes      | Protect tools endpoint URL                       | —  |
+| `INLINE_AGENT_ID`  | Yes      | Agent ID registered with the Inline Engine       | —  |
+
+## Usage
+
+The proxy supports three modes depending on how your MCP client and server communicate.
+
+### Mode 1: stdio
+
+Client connects via stdin/stdout. Proxy spawns the MCP server as a child process.
+
+```bash
+node dist/main.js --mode stdio --cmd "dab start --config dab-config.json"
+```
+
+Use this when your MCP client (e.g. Claude Desktop, Cursor) expects to launch a command.
+
+### Mode 2: stdio-to-server
+
+Client connects via stdin/stdout. Proxy forwards to an already-running HTTP MCP server.
+
+```bash
+node dist/main.js --mode stdio-to-server --target http://localhost:5000/mcp
+```
+
+Use this when your MCP server is already running on HTTP and your client expects stdio.
+
+### Mode 3: server
+
+Proxy runs as an HTTP server. Both client and MCP server communicate over HTTP.
+
+```bash
+node dist/main.js --mode server --target http://localhost:5000/mcp --port 7500
+```
+
+Use this when your MCP client connects over HTTP (e.g. a web app or remote agent).
+
+## How to Use with Your Agent
+
+### Option 1: Spawn the proxy from your agent (stdio / stdio-to-server)
+
+If your agent uses the MCP SDK, you can launch the proxy as a subprocess using `StdioClientTransport`. The proxy reads Ackuity credentials from environment variables, so pass them via `env`.
+
+Replace `<ACKUITY-DIST-REF>` in the examples below depending on how you installed the proxy:
+
+| Install method | `command` | `<ACKUITY-DIST-REF>` |
+|---|---|---|
+| Cloned and built locally | `node` | `path/to/ackuity-inline-proxy/dist/main.js` |
+| npx from GitHub | `npx` | `github:Ackuity/ackuity-mcp-proxy` |
+| Published to npm | `npx` | `ackuity-inline-proxy` |
+
+**TypeScript / JavaScript**
+
+```typescript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({
+  command: "npx",  // or "node" if running locally
+  args: [
+    "<ACKUITY-DIST-REF>",
+    "--mode", "stdio-to-server",
+    "--target", "http://localhost:5000/mcp",
+  ],
+  env: {
+    ...process.env,
+    INLINE_API_TOKEN: "your_token_here",
+    INLINE_URL: "https://inline.ackuity.ai/api/v1/inline/protect_tools",
+    INLINE_AGENT_ID: "your_agent_id_here",
+  },
+});
+
+const client = new Client({ name: "my-agent", version: "1.0.0" });
+await client.connect(transport);
+
+// All tool calls now go through the Ackuity Inline Decision Engine
+const tools = await client.listTools();
+const result = await client.callTool({ name: "read_records", arguments: { entity: "Employees" } });
+```
+
+> **Tip:** Use `--mode stdio` with `--cmd` instead if you want the proxy to also spawn the MCP server:
+> ```typescript
+> args: [
+>   "<ACKUITY-DIST-REF>",
+>   "--mode", "stdio",
+>   "--cmd", "npx @azure/data-api-builder start --config dab-config.json",
+> ],
+> ```
+
+**Python**
+
+```python
+from mcp.client.stdio import stdio_client, StdioServerParameters
+
+server = StdioServerParameters(
+    command="npx",  # or "node" if running locally
+    args=[
+        "<ACKUITY-DIST-REF>",
+        "--mode", "stdio-to-server",
+        "--target", "http://localhost:5000/mcp",
+    ],
+    env={
+        **os.environ,
+        "INLINE_API_TOKEN": "your_token_here",
+        "INLINE_URL": "https://inline.ackuity.ai/api/v1/inline/protect_tools",
+        "INLINE_AGENT_ID": "your_agent_id_here",
+    },
+)
+
+async with stdio_client(server) as (read_stream, write_stream):
+    async with ClientSession(read_stream, write_stream) as session:
+        await session.initialize()
+        result = await session.call_tool("read_records", {"entity": "Employees"})
+```
+
+### Option 2: Run the proxy as a Docker container (server mode)
+
+When running in **server mode**, the proxy exposes an HTTP endpoint at `/mcp`. This is ideal for containerized deployments where your agent and MCP server are separate services.
+
+**docker-compose.yml**
+
+```yaml
+services:
+  mcp-server:
+    image: your-mcp-server-image
+    ports:
+      - "5000:5000"
+
+  ackuity-proxy:
+    image: node:22-slim
+    working_dir: /app
+    command: npx <ACKUITY-DIST-REF> --mode server --target http://mcp-server:5000/mcp --port 7500
+    ports:
+      - "7500:7500"
+    environment:
+      INLINE_API_TOKEN: ${INLINE_API_TOKEN}
+      INLINE_URL: ${INLINE_URL}
+      INLINE_AGENT_ID: ${INLINE_AGENT_ID}
+    depends_on:
+      - mcp-server
+
+  agent:
+    image: your-agent-image
+    environment:
+      MCP_ENDPOINT: http://ackuity-proxy:7500/mcp
+    depends_on:
+      - ackuity-proxy
+```
+
+Your agent connects to `http://ackuity-proxy:7500/mcp` instead of directly to the MCP server. All tool calls are evaluated by the Ackuity Inline Decision Engine before reaching the MCP server.
+
+**With a `.env` file**
+
+```env
+INLINE_API_TOKEN=your_token_here
+INLINE_URL=https://inline.ackuity.ai/api/v1/inline/protect_tools
+INLINE_AGENT_ID=your_agent_id_here
+```
+
+Then run:
+
+```bash
+docker compose up
+```
+
+## Fail-Closed Behavior
+
+If the Inline Decision Engine is unreachable or returns an error (e.g. invalid token), the proxy **blocks the tool call** rather than forwarding it. This prevents destructive operations from slipping through during outages.
+
+## Project Structure
+
+```
+src/
+├── main.ts            Entry point, arg parsing, mode selection
+├── common.ts          Shared utilities (logging, arg parser, constants)
+├── inline_engine.ts   Protect Tools API types, response manager, API call
+└── mode.ts            ProxyMode interface and implementations (Stdio, StdioToServer, Server)
+```
+
+## Logging
+
+All MCP traffic is logged to `proxy_traffic.txt` in the working directory. Status messages are written to stderr with a `[PROXY]` prefix.

package/dist/common.js

@@ -0,0 +1,51 @@
+import * as fs from "node:fs";
+// --- Arg parsing ---
+export class ProxyProcessArguments {
+    params = {};
+    constructor(args) {
+        args.forEach((arg) => {
+            const pArg = "--".concat(arg);
+            const index = process.argv.indexOf(pArg);
+            this.params[arg] = index === -1 ? undefined : process.argv[index + 1];
+        });
+    }
+    mode() {
+        return this.params.mode;
+    }
+    target() {
+        return this.params.target;
+    }
+    cmd() {
+        return this.params.cmd;
+    }
+    port() {
+        return this.params.port;
+    }
+    toolName() {
+        return this.params["tool-name"];
+    }
+}
+// --- Traffic logging ---
+const logFile = fs.createWriteStream("proxy_traffic.txt", { flags: "a" });
+export function logTraffic(direction, msg) {
+    const timestamp = new Date().toISOString();
+    const pretty = JSON.stringify(msg, null, 2);
+    logFile.write(`\n--- ${direction} ${timestamp} ---\n${pretty}\n`);
+}
+export function logToStderr(text) {
+    process.stderr.write(`[PROXY] ${text}\n`);
+}
+// --- Error formatting ---
+export function formatError(err) {
+    if (!(err instanceof Error))
+        return String(err);
+    const cause = err.cause;
+    if (cause instanceof AggregateError) {
+        const reasons = cause.errors.map((e) => e.message).join("; ");
+        return `${err.message} (${reasons})`;
+    }
+    if (cause instanceof Error) {
+        return `${err.message} (${cause.message})`;
+    }
+    return cause ? `${err.message} (${cause})` : err.message;
+}

package/dist/config.js

@@ -0,0 +1,7 @@
+import { ServerMode, StdioMode, StdioToServerMode } from "./mode.js";
+export const DEFAULT_SERVER_PORT = "7500";
+export const modes = new Map([
+    ["stdio", StdioMode],
+    ["stdio-to-server", StdioToServerMode],
+    ["server", ServerMode],
+]);

package/dist/inline_engine.js

@@ -0,0 +1,69 @@
+// --- Protect Tools API types ---
+export class ProtectToolsResponseManager {
+    request_id;
+    session_id;
+    request_time;
+    response_time;
+    status;
+    request_evaluation_ms;
+    result;
+    error;
+    error_description;
+    constructor(response) {
+        Object.assign(this, response);
+    }
+    isBlocked() {
+        return this.result?.decision === "block";
+    }
+    isAllowed() {
+        return this.result?.decision === "allow";
+    }
+    isError() {
+        return this.status === "error";
+    }
+    getReasons() {
+        return this.result?.reason ?? [];
+    }
+}
+// --- Protect Tools API call ---
+if (!process.env.INLINE_URL) {
+    throw new Error("Missing required environment variable: INLINE_URL");
+}
+if (!process.env.INLINE_API_TOKEN) {
+    throw new Error("Missing required environment variable: INLINE_API_TOKEN");
+}
+if (!process.env.INLINE_AGENT_ID) {
+    throw new Error("Missing required environment variable: INLINE_AGENT_ID");
+}
+const PROTECT_TOOLS_URL = process.env.INLINE_URL;
+const INLINE_API_TOKEN = process.env.INLINE_API_TOKEN;
+const INLINE_AGENT_ID = process.env.INLINE_AGENT_ID;
+let TOOL_NAME = "unknown";
+export function setToolName(name) {
+    TOOL_NAME = name;
+}
+export async function callProtectTools(mcpMethod, actionName, toolArguments) {
+    const request = {
+        messages: [],
+        agent: { agent_name: TOOL_NAME, agent_id: INLINE_AGENT_ID },
+        tool_calls: [
+            {
+                tool_name: TOOL_NAME,
+                tool_type: "mcp",
+                method: mcpMethod,
+                action: actionName,
+                arguments: toolArguments,
+            },
+        ],
+    };
+    const res = await fetch(PROTECT_TOOLS_URL, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${INLINE_API_TOKEN}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(request),
+    });
+    const data = await res.json();
+    return new ProtectToolsResponseManager(data);
+}

package/dist/main.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { logToStderr, ProxyProcessArguments } from "./common.js";
+import { modes } from "./config.js";
+import { setToolName } from "./inline_engine.js";
+const programArgs = new ProxyProcessArguments([
+    "mode",
+    "target",
+    "cmd",
+    "port",
+    "tool-name",
+]);
+const modeName = programArgs.mode();
+const toolName = programArgs.toolName();
+if (toolName) {
+    setToolName(toolName);
+}
+logToStderr(`mode: ${modeName}`);
+const ModeClass = modeName ? modes.get(modeName) : undefined;
+if (!ModeClass) {
+    logToStderr(`ERROR: --mode required (${[...modes.keys()].join(" | ")})`);
+    process.exit(1);
+}
+const mode = new ModeClass();
+mode.init(programArgs);
+mode.start();

package/dist/mode.js

@@ -0,0 +1,208 @@
+import * as crypto from "node:crypto";
+import { createServer, } from "node:http";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { formatError, logToStderr, logTraffic, } from "./common.js";
+import { DEFAULT_SERVER_PORT } from "./config.js";
+import { callProtectTools } from "./inline_engine.js";
+// --- Interception logic ---
+async function inspectRequest(msg) {
+    logTraffic("to", msg);
+    if ("method" in msg) {
+        logToStderr(`to ${msg.method}`);
+        if (msg.method === "tools/call" && msg.params) {
+            const params = msg.params;
+            logToStderr(`  tool: ${params.name}, args: ${JSON.stringify(params.arguments)}`);
+            try {
+                const decision = await callProtectTools(msg.method, params.name ?? "unknown", params.arguments);
+                if (decision.isError()) {
+                    logToStderr(`  protect_tools error: ${decision.error} - ${decision.error_description}`);
+                    return null;
+                }
+                else if (decision.isBlocked()) {
+                    logToStderr(`  BLOCKED: ${decision.getReasons().join(", ")}`);
+                    return null;
+                }
+            }
+            catch (err) {
+                logToStderr(`  protect_tools call failed: ${formatError(err)}`);
+                return null;
+            }
+        }
+    }
+    return msg;
+}
+function inspectResponse(msg) {
+    logTraffic("from", msg);
+    const rpcMsg = msg;
+    if ("result" in msg) {
+        logToStderr(`from response id:${rpcMsg.id}`);
+    }
+    else if ("error" in msg) {
+        logToStderr(`from error id:${rpcMsg.id}: ${rpcMsg.error?.message}`);
+    }
+    return msg;
+}
+// --- Wire up two transports ---
+async function startProxy(agentTransport, serverTransport, onClose) {
+    let closing = false;
+    const closeSession = (reason) => {
+        if (closing)
+            return;
+        closing = true;
+        logToStderr(reason);
+        agentTransport.close();
+        serverTransport.close();
+        onClose?.();
+    };
+    agentTransport.onmessage = async (msg) => {
+        const allowed = await inspectRequest(msg);
+        if (allowed) {
+            await serverTransport.send(allowed);
+        }
+        else {
+            if ("id" in msg && msg.id !== undefined) {
+                await agentTransport.send({
+                    jsonrpc: "2.0",
+                    id: msg.id,
+                    error: { code: -32001, message: "Blocked by security policy" },
+                });
+            }
+        }
+    };
+    serverTransport.onmessage = async (msg) => {
+        const allowed = inspectResponse(msg);
+        if (allowed) {
+            await agentTransport.send(allowed);
+        }
+    };
+    agentTransport.onerror = (err) => logToStderr(`agent error: ${err}`);
+    serverTransport.onerror = (err) => logToStderr(`server error: ${err}`);
+    agentTransport.onclose = () => closeSession("agent closed");
+    serverTransport.onclose = () => closeSession("server closed");
+    await serverTransport.start();
+    logToStderr("server transport started");
+    await agentTransport.start();
+    logToStderr("agent transport started");
+}
+// --- Mode: stdio ---
+export class StdioMode {
+    cmd;
+    init(args) {
+        const cmd = args.cmd();
+        if (!cmd) {
+            logToStderr("ERROR: --cmd required for stdio mode");
+            process.exit(1);
+        }
+        this.cmd = cmd;
+        logToStderr(`cmd: ${this.cmd}`);
+    }
+    start() {
+        const parts = this.cmd.split(" ");
+        const agentTransport = new StdioServerTransport();
+        const serverTransport = new StdioClientTransport({
+            command: parts[0],
+            args: parts.slice(1),
+        });
+        startProxy(agentTransport, serverTransport, () => process.exit(0));
+    }
+}
+// --- Mode: stdio-to-server ---
+export class StdioToServerMode {
+    target;
+    init(args) {
+        const target = args.target();
+        if (!target) {
+            logToStderr("ERROR: --target required for stdio-to-server mode");
+            process.exit(1);
+        }
+        this.target = target;
+        logToStderr(`target: ${this.target}`);
+    }
+    start() {
+        const agentTransport = new StdioServerTransport();
+        const serverTransport = new StreamableHTTPClientTransport(new URL(this.target));
+        startProxy(agentTransport, serverTransport, () => process.exit(0));
+    }
+}
+// --- Mode: server ---
+export class ServerMode {
+    target;
+    port;
+    init(args) {
+        const target = args.target();
+        if (!target) {
+            logToStderr("ERROR: --target required for server mode");
+            process.exit(1);
+        }
+        this.target = target;
+        this.port = args.port() ?? DEFAULT_SERVER_PORT;
+        logToStderr(`starting HTTP server on port ${this.port} to ${this.target}`);
+    }
+    start() {
+        const target = this.target;
+        const sessions = new Map();
+        const httpServer = createServer(async (req, res) => {
+            if (req.url !== "/mcp") {
+                res.writeHead(404);
+                res.end("Not found");
+                return;
+            }
+            const sessionId = req.headers["mcp-session-id"];
+            if (sessionId && sessions.has(sessionId)) {
+                const session = sessions.get(sessionId);
+                if (!session)
+                    return;
+                const { agent } = session;
+                await agent.handleRequest(req, res);
+            }
+            else if (req.method === "POST") {
+                const agentTransport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => crypto.randomUUID(),
+                });
+                const forwardHeaders = {};
+                const skipHeaders = [
+                    "host",
+                    "content-length",
+                    "transfer-encoding",
+                    "connection",
+                ];
+                for (const [key, val] of Object.entries(req.headers)) {
+                    if (val && !skipHeaders.includes(key)) {
+                        forwardHeaders[key] = Array.isArray(val) ? val.join(", ") : val;
+                    }
+                }
+                const serverTransport = new StreamableHTTPClientTransport(new URL(target), {
+                    requestInit: {
+                        headers: forwardHeaders,
+                    },
+                });
+                await startProxy(agentTransport, serverTransport, () => {
+                    const sid = agentTransport.sessionId;
+                    if (sid) {
+                        sessions.delete(sid);
+                        logToStderr(`session cleaned up: ${sid}`);
+                    }
+                });
+                await agentTransport.handleRequest(req, res);
+                const newSessionId = agentTransport.sessionId;
+                if (newSessionId) {
+                    sessions.set(newSessionId, {
+                        agent: agentTransport,
+                        server: serverTransport,
+                    });
+                    logToStderr(`new session: ${newSessionId}`);
+                }
+            }
+            else {
+                res.writeHead(405);
+                res.end("Method not allowed");
+            }
+        });
+        httpServer.listen(Number(this.port), () => {
+            logToStderr(`listening on http://localhost:${this.port}/mcp`);
+        });
+    }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@ackuity/inline-proxy",
+  "version": "0.7.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/main.js",
+  "bin": {
+    "ackuity-mcp-proxy": "dist/main.js"
+  },
+  "scripts": {
+    "build": "tsc && npx biome check src/",
+    "prepare": "tsc",
+    "start": "node dist/main.js",
+    "lint": "npx biome check src/",
+    "lint:fix": "npx biome check --write src/"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "dotenv": "^16.4.7"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.9",
+    "@types/node": "^25.4.0",
+    "typescript": "^5.9.3"
+  }
+}