@blekline/mcp-proxy 0.1.0

package/LICENSE

@@ -0,0 +1,2 @@
+This package is licensed under the GNU Affero General Public License v3.0.
+See https://github.com/Blekline/blekline-oss/blob/main/LICENSE

package/README.md

@@ -0,0 +1,26 @@
+# @blekline/mcp-proxy
+
+MCP proxy router that intercepts downstream tool calls, runs Blekline enforcement (mask/block), then forwards approved calls to a downstream MCP server (e.g. Daytona sandbox).
+
+## Flow
+
+```
+Model → @blekline/mcp-proxy → POST /api/mcp/enforce-tool-call → downstream MCP
+```
+
+## Env
+
+```bash
+BLEKLINE_WORKSPACE_TOKEN=ws_...
+BLEKLINE_DOWNSTREAM_MCP_COMMAND=...   # optional mock or real Daytona MCP
+BLEKLINE_CLIENT_SURFACE=cursor
+```
+
+## Run
+
+```bash
+pnpm --filter @blekline/mcp-proxy build
+pnpm --filter @blekline/mcp-proxy test
+```
+
+Smoke test: `pnpm demo:mcp-smoke` from repo root.

package/dist/downstream/mcp-client.js

@@ -0,0 +1,77 @@
+import { spawn } from "node:child_process";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+/** Mock downstream tools for demo without Daytona API key. */
+export const MOCK_DOWNSTREAM_TOOLS = [
+    {
+        name: "run_shell",
+        description: "Run a shell command in sandbox (mock)",
+        inputSchema: {
+            type: "object",
+            properties: { command: { type: "string" } },
+            required: ["command"],
+        },
+    },
+    {
+        name: "write_file",
+        description: "Write file in sandbox (mock)",
+        inputSchema: {
+            type: "object",
+            properties: { path: { type: "string" }, content: { type: "string" } },
+            required: ["path", "content"],
+        },
+    },
+];
+export async function listDownstreamTools() {
+    if (process.env.BLEKLINE_MCP_PROXY_MOCK === "1") {
+        return MOCK_DOWNSTREAM_TOOLS;
+    }
+    const cmd = process.env.BLEKLINE_DOWNSTREAM_MCP_COMMAND?.trim();
+    if (!cmd)
+        return MOCK_DOWNSTREAM_TOOLS;
+    const parts = cmd.split(",").map((s) => s.trim()).filter(Boolean);
+    if (parts.length === 0)
+        return MOCK_DOWNSTREAM_TOOLS;
+    const [command, ...args] = parts;
+    const transport = new StdioClientTransport({ command, args, env: process.env });
+    const client = new Client({ name: "blekline-proxy-downstream", version: "0.1.0" }, { capabilities: {} });
+    await client.connect(transport);
+    const listed = await client.listTools();
+    await client.close();
+    return listed.tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+    }));
+}
+export async function callDownstreamTool(name, args) {
+    if (process.env.BLEKLINE_MCP_PROXY_MOCK === "1") {
+        return { ok: true, mock: true, tool: name, received: args };
+    }
+    const cmd = process.env.BLEKLINE_DOWNSTREAM_MCP_COMMAND?.trim();
+    if (!cmd) {
+        return { ok: true, mock: true, tool: name, received: args };
+    }
+    const parts = cmd.split(",").map((s) => s.trim()).filter(Boolean);
+    const [command, ...spawnArgs] = parts;
+    const transport = new StdioClientTransport({
+        command,
+        args: spawnArgs,
+        env: process.env,
+    });
+    const client = new Client({ name: "blekline-proxy-downstream", version: "0.1.0" }, { capabilities: {} });
+    await client.connect(transport);
+    const result = await client.callTool({ name, arguments: args });
+    await client.close();
+    return result;
+}
+/** Spawn helper for health checks (unused in hot path). */
+export function spawnDownstreamCheck() {
+    const cmd = process.env.BLEKLINE_DOWNSTREAM_MCP_COMMAND?.trim();
+    if (!cmd)
+        return;
+    const parts = cmd.split(",").map((s) => s.trim()).filter(Boolean);
+    if (parts.length === 0)
+        return;
+    spawn(parts[0], parts.slice(1), { stdio: "ignore" });
+}

package/dist/enforcement/scan-tool-args.js

@@ -0,0 +1,24 @@
+import { scanTextForSecrets } from "@blekline/contracts";
+const DESTRUCTIVE_RE = /\brm\s+-rf\b|\bformat\s+c:\b|\bdrop\s+database\b/i;
+/** Fast local scan of MCP tool arguments (used before cloud enforce-tool-call). */
+export function scanToolArgs(args) {
+    let blob = "";
+    try {
+        blob = JSON.stringify(args);
+    }
+    catch {
+        blob = String(args);
+    }
+    const findings = [];
+    if (DESTRUCTIVE_RE.test(blob)) {
+        findings.push({ id: "destructive_command", label: "DESTRUCTIVE", field: "arguments" });
+    }
+    for (const s of scanTextForSecrets(blob)) {
+        findings.push({ id: s.id, label: s.label });
+    }
+    return {
+        findings,
+        hasDestructive: DESTRUCTIVE_RE.test(blob),
+        secretCount: findings.filter((f) => f.id !== "destructive_command").length,
+    };
+}

package/dist/index.js

@@ -0,0 +1,63 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { callDownstreamTool, listDownstreamTools } from "./downstream/mcp-client.js";
+import { createProxyContext, interceptToolCall } from "./mcp-proxy.js";
+const server = new Server({ name: "blekline-mcp-proxy", version: "0.1.0" }, { capabilities: { tools: {} } });
+let ctx = null;
+function getCtx() {
+    if (!ctx)
+        ctx = createProxyContext();
+    return ctx;
+}
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const downstream = await listDownstreamTools();
+    return {
+        tools: downstream.map((t) => ({
+            name: t.name,
+            description: t.description ?? `Proxied tool (Blekline governed): ${t.name}`,
+            inputSchema: t.inputSchema ?? { type: "object", properties: {} },
+        })),
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const toolName = request.params.name;
+    const toolArgs = (request.params.arguments ?? {});
+    const enforcement = await interceptToolCall(getCtx(), toolName, toolArgs);
+    if (!enforcement.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: enforcement.message,
+                        action: enforcement.action,
+                        findings: enforcement.findings,
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+    const downstreamResult = await callDownstreamTool(toolName, enforcement.arguments);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    bleklineAction: enforcement.action,
+                    entitiesMasked: enforcement.action === "mask" ? enforcement.entitiesMasked : 0,
+                    result: downstreamResult,
+                }, null, 2),
+            },
+        ],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("[blekline-mcp-proxy]", err);
+    process.exit(1);
+});

package/dist/mcp-proxy.js

@@ -0,0 +1,70 @@
+import { randomUUID } from "node:crypto";
+import { BleklineClient } from "@blekline/client";
+import { enforceToolCallLocally } from "@blekline/contracts";
+function envClientSurface() {
+    const v = process.env.BLEKLINE_CLIENT_SURFACE?.trim();
+    if (v === "cursor" || v === "claude-desktop" || v === "codex")
+        return v;
+    return "sdk";
+}
+export function createProxyContext() {
+    const token = process.env.BLEKLINE_WORKSPACE_TOKEN?.trim();
+    if (!token)
+        throw new Error("BLEKLINE_WORKSPACE_TOKEN is required");
+    return {
+        client: new BleklineClient({
+            baseUrl: process.env.BLEKLINE_API_URL?.trim(),
+            workspaceToken: token,
+            workspaceId: process.env.BLEKLINE_WORKSPACE_ID?.trim(),
+            metadata: { clientSurface: envClientSurface() },
+        }),
+        clientSurface: envClientSurface(),
+        useCloudEnforcement: process.env.BLEKLINE_PROXY_LOCAL_ONLY !== "1",
+    };
+}
+export async function interceptToolCall(ctx, toolName, toolArgs) {
+    const requestId = randomUUID();
+    let result = enforceToolCallLocally({ toolName, arguments: toolArgs, requestId });
+    if (ctx.useCloudEnforcement) {
+        try {
+            result = await ctx.client.enforceToolCall({
+                toolName,
+                arguments: toolArgs,
+                platform: "MCP-Proxy",
+                clientSurface: ctx.clientSurface,
+            });
+        }
+        catch {
+            /* fall back to local result */
+        }
+    }
+    void ctx.client
+        .emitEvent({
+        kind: "tool_call_enforcement",
+        platform: "MCP-Proxy",
+        entitiesMasked: result.entitiesMasked,
+        riskTier: result.riskTier,
+        action: result.action,
+        mcpToolName: toolName,
+        downstreamServer: process.env.BLEKLINE_MCP_PROXY_MOCK === "1" ? "mock" : "daytona",
+        clientSurface: ctx.clientSurface,
+    })
+        .catch(() => { });
+    if (result.action === "block") {
+        return {
+            ok: false,
+            action: "block",
+            message: "Blekline policy: block_and_review",
+            findings: result.findings,
+        };
+    }
+    if (result.action === "mask") {
+        return {
+            ok: true,
+            action: "mask",
+            arguments: result.maskedArguments,
+            entitiesMasked: result.entitiesMasked,
+        };
+    }
+    return { ok: true, action: "allow", arguments: toolArgs };
+}

package/dist/mcp-proxy.test.js

@@ -0,0 +1,21 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { enforceToolCallLocally } from "@blekline/contracts";
+test("blocks destructive shell patterns", () => {
+    const result = enforceToolCallLocally({
+        toolName: "run_shell",
+        arguments: { command: "rm -rf /" },
+        requestId: "test-1",
+    });
+    assert.equal(result.action, "block");
+});
+test("masks AWS key in tool arguments", () => {
+    const result = enforceToolCallLocally({
+        toolName: "run_shell",
+        arguments: { command: "export AWS_KEY=AKIAIOSFODNN7EXAMPLE" },
+        requestId: "test-2",
+    });
+    assert.equal(result.action, "mask");
+    assert.ok(result.entitiesMasked > 0);
+    assert.ok(JSON.stringify(result.maskedArguments).includes("[AWS_KEY]"));
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@blekline/mcp-proxy",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-or-later",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Blekline/blekline-oss.git",
+    "directory": "packages/mcp-proxy"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "blekline-mcp-proxy": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@blekline/client": "0.1.0",
+    "@blekline/contracts": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test dist/mcp-proxy.test.js"
+  }
+}

package/src/downstream/mcp-client.ts

@@ -0,0 +1,88 @@
+import { spawn } from "node:child_process";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+export type DownstreamTool = {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+};
+
+/** Mock downstream tools for demo without Daytona API key. */
+export const MOCK_DOWNSTREAM_TOOLS: DownstreamTool[] = [
+  {
+    name: "run_shell",
+    description: "Run a shell command in sandbox (mock)",
+    inputSchema: {
+      type: "object",
+      properties: { command: { type: "string" } },
+      required: ["command"],
+    },
+  },
+  {
+    name: "write_file",
+    description: "Write file in sandbox (mock)",
+    inputSchema: {
+      type: "object",
+      properties: { path: { type: "string" }, content: { type: "string" } },
+      required: ["path", "content"],
+    },
+  },
+];
+
+export async function listDownstreamTools(): Promise<DownstreamTool[]> {
+  if (process.env.BLEKLINE_MCP_PROXY_MOCK === "1") {
+    return MOCK_DOWNSTREAM_TOOLS;
+  }
+
+  const cmd = process.env.BLEKLINE_DOWNSTREAM_MCP_COMMAND?.trim();
+  if (!cmd) return MOCK_DOWNSTREAM_TOOLS;
+
+  const parts = cmd.split(",").map((s) => s.trim()).filter(Boolean);
+  if (parts.length === 0) return MOCK_DOWNSTREAM_TOOLS;
+
+  const [command, ...args] = parts;
+  const transport = new StdioClientTransport({ command, args, env: process.env as Record<string, string> });
+  const client = new Client({ name: "blekline-proxy-downstream", version: "0.1.0" }, { capabilities: {} });
+  await client.connect(transport);
+  const listed = await client.listTools();
+  await client.close();
+  return listed.tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema as Record<string, unknown>,
+  }));
+}
+
+export async function callDownstreamTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+  if (process.env.BLEKLINE_MCP_PROXY_MOCK === "1") {
+    return { ok: true, mock: true, tool: name, received: args };
+  }
+
+  const cmd = process.env.BLEKLINE_DOWNSTREAM_MCP_COMMAND?.trim();
+  if (!cmd) {
+    return { ok: true, mock: true, tool: name, received: args };
+  }
+
+  const parts = cmd.split(",").map((s) => s.trim()).filter(Boolean);
+  const [command, ...spawnArgs] = parts;
+  const transport = new StdioClientTransport({
+    command,
+    args: spawnArgs,
+    env: process.env as Record<string, string>,
+  });
+  const client = new Client({ name: "blekline-proxy-downstream", version: "0.1.0" }, { capabilities: {} });
+  await client.connect(transport);
+  const result = await client.callTool({ name, arguments: args });
+  await client.close();
+  return result;
+}
+
+/** Spawn helper for health checks (unused in hot path). */
+export function spawnDownstreamCheck(): void {
+  const cmd = process.env.BLEKLINE_DOWNSTREAM_MCP_COMMAND?.trim();
+  if (!cmd) return;
+  const parts = cmd.split(",").map((s) => s.trim()).filter(Boolean);
+  if (parts.length === 0) return;
+  spawn(parts[0], parts.slice(1), { stdio: "ignore" });
+}

package/src/enforcement/scan-tool-args.ts

@@ -0,0 +1,35 @@
+import { scanTextForSecrets } from "@blekline/contracts";
+import type { ToolCallFinding } from "@blekline/contracts";
+
+const DESTRUCTIVE_RE = /\brm\s+-rf\b|\bformat\s+c:\b|\bdrop\s+database\b/i;
+
+export type ScanToolArgsResult = {
+  findings: ToolCallFinding[];
+  hasDestructive: boolean;
+  secretCount: number;
+};
+
+/** Fast local scan of MCP tool arguments (used before cloud enforce-tool-call). */
+export function scanToolArgs(args: Record<string, unknown>): ScanToolArgsResult {
+  let blob = "";
+  try {
+    blob = JSON.stringify(args);
+  } catch {
+    blob = String(args);
+  }
+
+  const findings: ToolCallFinding[] = [];
+  if (DESTRUCTIVE_RE.test(blob)) {
+    findings.push({ id: "destructive_command", label: "DESTRUCTIVE", field: "arguments" });
+  }
+
+  for (const s of scanTextForSecrets(blob)) {
+    findings.push({ id: s.id, label: s.label });
+  }
+
+  return {
+    findings,
+    hasDestructive: DESTRUCTIVE_RE.test(blob),
+    secretCount: findings.filter((f) => f.id !== "destructive_command").length,
+  };
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { callDownstreamTool, listDownstreamTools } from "./downstream/mcp-client.js";
+import { createProxyContext, interceptToolCall } from "./mcp-proxy.js";
+
+const server = new Server(
+  { name: "blekline-mcp-proxy", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+
+let ctx: ReturnType<typeof createProxyContext> | null = null;
+
+function getCtx() {
+  if (!ctx) ctx = createProxyContext();
+  return ctx;
+}
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  const downstream = await listDownstreamTools();
+  return {
+    tools: downstream.map((t) => ({
+      name: t.name,
+      description: t.description ?? `Proxied tool (Blekline governed): ${t.name}`,
+      inputSchema: t.inputSchema ?? { type: "object", properties: {} },
+    })),
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const toolName = request.params.name;
+  const toolArgs = (request.params.arguments ?? {}) as Record<string, unknown>;
+  const enforcement = await interceptToolCall(getCtx(), toolName, toolArgs);
+
+  if (!enforcement.ok) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              error: enforcement.message,
+              action: enforcement.action,
+              findings: enforcement.findings,
+            },
+            null,
+            2
+          ),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  const downstreamResult = await callDownstreamTool(toolName, enforcement.arguments);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            bleklineAction: enforcement.action,
+            entitiesMasked: enforcement.action === "mask" ? enforcement.entitiesMasked : 0,
+            result: downstreamResult,
+          },
+          null,
+          2
+        ),
+      },
+    ],
+  };
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("[blekline-mcp-proxy]", err);
+  process.exit(1);
+});

package/src/mcp-proxy.test.ts

@@ -0,0 +1,23 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { enforceToolCallLocally } from "@blekline/contracts";
+
+test("blocks destructive shell patterns", () => {
+  const result = enforceToolCallLocally({
+    toolName: "run_shell",
+    arguments: { command: "rm -rf /" },
+    requestId: "test-1",
+  });
+  assert.equal(result.action, "block");
+});
+
+test("masks AWS key in tool arguments", () => {
+  const result = enforceToolCallLocally({
+    toolName: "run_shell",
+    arguments: { command: "export AWS_KEY=AKIAIOSFODNN7EXAMPLE" },
+    requestId: "test-2",
+  });
+  assert.equal(result.action, "mask");
+  assert.ok(result.entitiesMasked > 0);
+  assert.ok(JSON.stringify(result.maskedArguments).includes("[AWS_KEY]"));
+});

package/src/mcp-proxy.ts

@@ -0,0 +1,90 @@
+import { randomUUID } from "node:crypto";
+import { BleklineClient } from "@blekline/client";
+import { enforceToolCallLocally, type ClientSurface } from "@blekline/contracts";
+
+export type ProxyEnforcementContext = {
+  client: BleklineClient;
+  clientSurface: ClientSurface;
+  useCloudEnforcement: boolean;
+};
+
+export type InterceptResult =
+  | { ok: true; action: "allow"; arguments: Record<string, unknown> }
+  | { ok: true; action: "mask"; arguments: Record<string, unknown>; entitiesMasked: number }
+  | { ok: false; action: "block"; message: string; findings: unknown[] };
+
+function envClientSurface(): ClientSurface {
+  const v = process.env.BLEKLINE_CLIENT_SURFACE?.trim();
+  if (v === "cursor" || v === "claude-desktop" || v === "codex") return v;
+  return "sdk";
+}
+
+export function createProxyContext(): ProxyEnforcementContext {
+  const token = process.env.BLEKLINE_WORKSPACE_TOKEN?.trim();
+  if (!token) throw new Error("BLEKLINE_WORKSPACE_TOKEN is required");
+  return {
+    client: new BleklineClient({
+      baseUrl: process.env.BLEKLINE_API_URL?.trim(),
+      workspaceToken: token,
+      workspaceId: process.env.BLEKLINE_WORKSPACE_ID?.trim(),
+      metadata: { clientSurface: envClientSurface() },
+    }),
+    clientSurface: envClientSurface(),
+    useCloudEnforcement: process.env.BLEKLINE_PROXY_LOCAL_ONLY !== "1",
+  };
+}
+
+export async function interceptToolCall(
+  ctx: ProxyEnforcementContext,
+  toolName: string,
+  toolArgs: Record<string, unknown>
+): Promise<InterceptResult> {
+  const requestId = randomUUID();
+  let result = enforceToolCallLocally({ toolName, arguments: toolArgs, requestId });
+
+  if (ctx.useCloudEnforcement) {
+    try {
+      result = await ctx.client.enforceToolCall({
+        toolName,
+        arguments: toolArgs,
+        platform: "MCP-Proxy",
+        clientSurface: ctx.clientSurface,
+      });
+    } catch {
+      /* fall back to local result */
+    }
+  }
+
+  void ctx.client
+    .emitEvent({
+      kind: "tool_call_enforcement",
+      platform: "MCP-Proxy",
+      entitiesMasked: result.entitiesMasked,
+      riskTier: result.riskTier,
+      action: result.action,
+      mcpToolName: toolName,
+      downstreamServer: process.env.BLEKLINE_MCP_PROXY_MOCK === "1" ? "mock" : "daytona",
+      clientSurface: ctx.clientSurface,
+    })
+    .catch(() => {});
+
+  if (result.action === "block") {
+    return {
+      ok: false,
+      action: "block",
+      message: "Blekline policy: block_and_review",
+      findings: result.findings,
+    };
+  }
+
+  if (result.action === "mask") {
+    return {
+      ok: true,
+      action: "mask",
+      arguments: result.maskedArguments,
+      entitiesMasked: result.entitiesMasked,
+    };
+  }
+
+  return { ok: true, action: "allow", arguments: toolArgs };
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}