@blekline/mcp-server 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,36 @@
+# @blekline/mcp-server
+
+Stdio MCP server exposing Blekline governance tools for **Cursor (P0)**, **Claude Desktop (P1)**, and **Codex (P2)**.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `blekline_mask_prompt` | Mask prompt via control plane |
+| `blekline_classify_risk` | Policy simulation |
+| `blekline_emit_event` | Metadata event ingest |
+| `blekline_evaluate_tool_call` | MCP tool allow/mask/block |
+
+## Env
+
+```bash
+BLEKLINE_WORKSPACE_TOKEN=ws_...
+BLEKLINE_API_URL=https://app.blekline.com  # optional
+BLEKLINE_CLIENT_SURFACE=cursor             # cursor | claude-desktop | codex
+```
+
+## Run
+
+```bash
+pnpm --filter @blekline/mcp-server build
+node packages/mcp-server/dist/index.js
+```
+
+### SSE transport (remote deploy)
+
+```bash
+BLEKLINE_MCP_TRANSPORT=sse BLEKLINE_MCP_PORT=3200 node packages/mcp-server/dist/index.js
+# GET http://127.0.0.1:3200/sse
+```
+
+Generate configs: `pnpm generate:mcp-configs` from repo root.

package/dist/index.js

@@ -0,0 +1,17 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createBleklineMcpServer } from "./server-core.js";
+import { startSseServer } from "./sse-server.js";
+async function main() {
+    const mode = process.env.BLEKLINE_MCP_TRANSPORT?.trim().toLowerCase() ?? "stdio";
+    if (mode === "sse") {
+        await startSseServer();
+        return;
+    }
+    const server = createBleklineMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("[blekline-mcp-server]", err);
+    process.exit(1);
+});

package/dist/server-core.js

@@ -0,0 +1,144 @@
+import { BleklineClient } from "@blekline/client";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+export function envClientSurface() {
+    const v = process.env.BLEKLINE_CLIENT_SURFACE?.trim();
+    if (v === "cursor" || v === "claude-desktop" || v === "codex")
+        return v;
+    return "sdk";
+}
+export function createClient() {
+    const token = process.env.BLEKLINE_WORKSPACE_TOKEN?.trim();
+    if (!token) {
+        throw new Error("BLEKLINE_WORKSPACE_TOKEN is required");
+    }
+    return new BleklineClient({
+        baseUrl: process.env.BLEKLINE_API_URL?.trim(),
+        workspaceToken: token,
+        workspaceId: process.env.BLEKLINE_WORKSPACE_ID?.trim(),
+        metadata: { clientSurface: envClientSurface() },
+    });
+}
+export function createBleklineMcpServer() {
+    const server = new Server({ name: "blekline-mcp-server", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "blekline_mask_prompt",
+                description: "Mask PII and secrets in a prompt via Blekline control plane before sending to an LLM. Call this before any outbound prompt containing sensitive data.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        text: { type: "string", description: "Prompt text to mask" },
+                        platform: { type: "string", description: "Optional platform label (e.g. Cursor, Claude Desktop)" },
+                    },
+                    required: ["text"],
+                },
+            },
+            {
+                name: "blekline_classify_risk",
+                description: "Simulate Blekline redaction policy on a prompt without masking.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        prompt: { type: "string" },
+                        platform: { type: "string" },
+                        sourceHost: { type: "string" },
+                    },
+                    required: ["prompt"],
+                },
+            },
+            {
+                name: "blekline_emit_event",
+                description: "Emit metadata-only governance event to Blekline control plane.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        kind: { type: "string" },
+                        platform: { type: "string" },
+                        entitiesMasked: { type: "number" },
+                        riskTier: { type: "string", enum: ["low", "medium", "high"] },
+                        action: { type: "string" },
+                    },
+                    required: ["kind"],
+                },
+            },
+            {
+                name: "blekline_evaluate_tool_call",
+                description: "Evaluate MCP tool call arguments against Blekline workspace MCP tool policy (allow/mask/block).",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        toolName: { type: "string" },
+                        arguments: { type: "object" },
+                        platform: { type: "string" },
+                    },
+                    required: ["toolName", "arguments"],
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const client = createClient();
+        const name = request.params.name;
+        const args = (request.params.arguments ?? {});
+        if (name === "blekline_mask_prompt") {
+            const text = String(args.text ?? "");
+            const platform = args.platform ? String(args.platform) : "MCP";
+            const result = await client.mask({ text, platform });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            maskedText: result.maskedText,
+                            entitiesMasked: result.entitiesMasked,
+                            decision: result.decision,
+                            provider: result.provider,
+                            requestId: result.requestId,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        if (name === "blekline_classify_risk") {
+            const prompt = String(args.prompt ?? "");
+            const result = await client.simulatePolicy({
+                prompt,
+                platform: args.platform ? String(args.platform) : undefined,
+                sourceHost: args.sourceHost ? String(args.sourceHost) : undefined,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.simulation, null, 2) }],
+            };
+        }
+        if (name === "blekline_emit_event") {
+            await client.emitEvent({
+                kind: String(args.kind ?? "mcp_event"),
+                platform: args.platform ? String(args.platform) : "MCP",
+                entitiesMasked: typeof args.entitiesMasked === "number" ? args.entitiesMasked : 0,
+                riskTier: args.riskTier === "low" || args.riskTier === "medium" || args.riskTier === "high"
+                    ? args.riskTier
+                    : undefined,
+                action: args.action ? String(args.action) : undefined,
+                clientSurface: envClientSurface(),
+            });
+            return { content: [{ type: "text", text: JSON.stringify({ ok: true }) }] };
+        }
+        if (name === "blekline_evaluate_tool_call") {
+            const toolName = String(args.toolName ?? "");
+            const toolArgs = args.arguments && typeof args.arguments === "object"
+                ? args.arguments
+                : {};
+            const result = await client.enforceToolCall({
+                toolName,
+                arguments: toolArgs,
+                platform: args.platform ? String(args.platform) : "MCP",
+                clientSurface: envClientSurface(),
+            });
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        throw new Error(`Unknown tool: ${name}`);
+    });
+    return server;
+}

package/dist/sse-server.js

@@ -0,0 +1,42 @@
+import { createServer } from "node:http";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { createBleklineMcpServer } from "./server-core.js";
+const transports = new Map();
+export async function startSseServer() {
+    const port = Number(process.env.BLEKLINE_MCP_PORT ?? 3200);
+    const host = process.env.BLEKLINE_MCP_HOST ?? "127.0.0.1";
+    const httpServer = createServer(async (req, res) => {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+        if (req.method === "GET" && url.pathname === "/sse") {
+            const transport = new SSEServerTransport("/message", res);
+            transports.set(transport.sessionId, transport);
+            transport.onclose = () => transports.delete(transport.sessionId);
+            const server = createBleklineMcpServer();
+            await server.connect(transport);
+            await transport.start();
+            return;
+        }
+        if (req.method === "POST" && url.pathname === "/message") {
+            const sessionId = url.searchParams.get("sessionId");
+            const transport = sessionId ? transports.get(sessionId) : undefined;
+            if (!transport) {
+                res.writeHead(404, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Unknown MCP session" }));
+                return;
+            }
+            await transport.handlePostMessage(req, res);
+            return;
+        }
+        if (req.method === "GET" && url.pathname === "/health") {
+            json(res, 200, { ok: true, transport: "sse", sessions: transports.size });
+            return;
+        }
+        json(res, 404, { error: "Use GET /sse or POST /message?sessionId=..." });
+    });
+    await new Promise((resolve) => httpServer.listen(port, host, resolve));
+    console.error(`[blekline-mcp-server] SSE listening on http://${host}:${port}/sse`);
+}
+function json(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@blekline/mcp-server",
+  "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-server"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "blekline-mcp-server": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "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"
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createBleklineMcpServer } from "./server-core.js";
+import { startSseServer } from "./sse-server.js";
+
+async function main() {
+  const mode = process.env.BLEKLINE_MCP_TRANSPORT?.trim().toLowerCase() ?? "stdio";
+  if (mode === "sse") {
+    await startSseServer();
+    return;
+  }
+
+  const server = createBleklineMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("[blekline-mcp-server]", err);
+  process.exit(1);
+});

package/src/server-core.ts

@@ -0,0 +1,165 @@
+import { BleklineClient } from "@blekline/client";
+import type { ClientSurface } from "@blekline/contracts";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+export 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 createClient(): BleklineClient {
+  const token = process.env.BLEKLINE_WORKSPACE_TOKEN?.trim();
+  if (!token) {
+    throw new Error("BLEKLINE_WORKSPACE_TOKEN is required");
+  }
+  return new BleklineClient({
+    baseUrl: process.env.BLEKLINE_API_URL?.trim(),
+    workspaceToken: token,
+    workspaceId: process.env.BLEKLINE_WORKSPACE_ID?.trim(),
+    metadata: { clientSurface: envClientSurface() },
+  });
+}
+
+export function createBleklineMcpServer(): Server {
+  const server = new Server(
+    { name: "blekline-mcp-server", version: "0.1.0" },
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: "blekline_mask_prompt",
+        description:
+          "Mask PII and secrets in a prompt via Blekline control plane before sending to an LLM. Call this before any outbound prompt containing sensitive data.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            text: { type: "string", description: "Prompt text to mask" },
+            platform: { type: "string", description: "Optional platform label (e.g. Cursor, Claude Desktop)" },
+          },
+          required: ["text"],
+        },
+      },
+      {
+        name: "blekline_classify_risk",
+        description: "Simulate Blekline redaction policy on a prompt without masking.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            prompt: { type: "string" },
+            platform: { type: "string" },
+            sourceHost: { type: "string" },
+          },
+          required: ["prompt"],
+        },
+      },
+      {
+        name: "blekline_emit_event",
+        description: "Emit metadata-only governance event to Blekline control plane.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            kind: { type: "string" },
+            platform: { type: "string" },
+            entitiesMasked: { type: "number" },
+            riskTier: { type: "string", enum: ["low", "medium", "high"] },
+            action: { type: "string" },
+          },
+          required: ["kind"],
+        },
+      },
+      {
+        name: "blekline_evaluate_tool_call",
+        description: "Evaluate MCP tool call arguments against Blekline workspace MCP tool policy (allow/mask/block).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            toolName: { type: "string" },
+            arguments: { type: "object" },
+            platform: { type: "string" },
+          },
+          required: ["toolName", "arguments"],
+        },
+      },
+    ],
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const client = createClient();
+    const name = request.params.name;
+    const args = (request.params.arguments ?? {}) as Record<string, unknown>;
+
+    if (name === "blekline_mask_prompt") {
+      const text = String(args.text ?? "");
+      const platform = args.platform ? String(args.platform) : "MCP";
+      const result = await client.mask({ text, platform });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                maskedText: result.maskedText,
+                entitiesMasked: result.entitiesMasked,
+                decision: result.decision,
+                provider: result.provider,
+                requestId: result.requestId,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+
+    if (name === "blekline_classify_risk") {
+      const prompt = String(args.prompt ?? "");
+      const result = await client.simulatePolicy({
+        prompt,
+        platform: args.platform ? String(args.platform) : undefined,
+        sourceHost: args.sourceHost ? String(args.sourceHost) : undefined,
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result.simulation, null, 2) }],
+      };
+    }
+
+    if (name === "blekline_emit_event") {
+      await client.emitEvent({
+        kind: String(args.kind ?? "mcp_event"),
+        platform: args.platform ? String(args.platform) : "MCP",
+        entitiesMasked: typeof args.entitiesMasked === "number" ? args.entitiesMasked : 0,
+        riskTier:
+          args.riskTier === "low" || args.riskTier === "medium" || args.riskTier === "high"
+            ? args.riskTier
+            : undefined,
+        action: args.action ? String(args.action) : undefined,
+        clientSurface: envClientSurface(),
+      });
+      return { content: [{ type: "text", text: JSON.stringify({ ok: true }) }] };
+    }
+
+    if (name === "blekline_evaluate_tool_call") {
+      const toolName = String(args.toolName ?? "");
+      const toolArgs =
+        args.arguments && typeof args.arguments === "object"
+          ? (args.arguments as Record<string, unknown>)
+          : {};
+      const result = await client.enforceToolCall({
+        toolName,
+        arguments: toolArgs,
+        platform: args.platform ? String(args.platform) : "MCP",
+        clientSurface: envClientSurface(),
+      });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+
+    throw new Error(`Unknown tool: ${name}`);
+  });
+
+  return server;
+}

package/src/sse-server.ts

@@ -0,0 +1,51 @@
+import { createServer, type ServerResponse } from "node:http";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { createBleklineMcpServer } from "./server-core.js";
+
+const transports = new Map<string, SSEServerTransport>();
+
+export async function startSseServer(): Promise<void> {
+  const port = Number(process.env.BLEKLINE_MCP_PORT ?? 3200);
+  const host = process.env.BLEKLINE_MCP_HOST ?? "127.0.0.1";
+
+  const httpServer = createServer(async (req, res) => {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+
+    if (req.method === "GET" && url.pathname === "/sse") {
+      const transport = new SSEServerTransport("/message", res);
+      transports.set(transport.sessionId, transport);
+      transport.onclose = () => transports.delete(transport.sessionId);
+      const server = createBleklineMcpServer();
+      await server.connect(transport);
+      await transport.start();
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/message") {
+      const sessionId = url.searchParams.get("sessionId");
+      const transport = sessionId ? transports.get(sessionId) : undefined;
+      if (!transport) {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Unknown MCP session" }));
+        return;
+      }
+      await transport.handlePostMessage(req, res);
+      return;
+    }
+
+    if (req.method === "GET" && url.pathname === "/health") {
+      json(res, 200, { ok: true, transport: "sse", sessions: transports.size });
+      return;
+    }
+
+    json(res, 404, { error: "Use GET /sse or POST /message?sessionId=..." });
+  });
+
+  await new Promise<void>((resolve) => httpServer.listen(port, host, resolve));
+  console.error(`[blekline-mcp-server] SSE listening on http://${host}:${port}/sse`);
+}
+
+function json(res: ServerResponse, status: number, body: unknown) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}

package/tsconfig.json

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