@blursec/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blursec
+
+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,99 @@
+# @blursec/mcp
+
+Official [Model Context Protocol](https://modelcontextprotocol.io) server for
+[`@blursec/sdk`](https://www.npmjs.com/package/@blursec/sdk) — lets AI agents
+(Claude, GitHub Copilot, Cursor, custom agents) check credentials, session
+tokens, and hashes against live stealer-log threat intel.
+
+> TL;DR — one `npx` command turns Blursec into five agent tools. All hashing
+> happens locally; only a 10-character k-anonymity prefix ever leaves the
+> machine. Zero runtime dependencies — the protocol core is hand-rolled.
+
+## Install & run
+
+```bash
+npm i -g @blursec/mcp @blursec/sdk   # or run via npx, see below
+```
+
+The server reads its configuration from the environment:
+
+| env var               | purpose                                      |
+|-----------------------|----------------------------------------------|
+| `BLURSEC_API_KEY`     | API key (required)                           |
+| `BLURSEC_ENVIRONMENT` | `production` (default) / `staging` / `local` |
+
+Never pass the API key as prompt text or argv — use the host's `env` block.
+
+### Claude Desktop / Claude Code
+
+```json
+{
+  "mcpServers": {
+    "blursec": {
+      "command": "npx",
+      "args": ["-y", "@blursec/mcp"],
+      "env": { "BLURSEC_API_KEY": "bsk_live_..." }
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot)
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "blursec": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@blursec/mcp"],
+      "env": { "BLURSEC_API_KEY": "${input:blursec-api-key}" }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Wraps | Use it for |
+|------|-------|------------|
+| `blursec_check_credential` | `credentials.check` | "Is this email+password leaked?" |
+| `blursec_check_token` | `credentials.checkToken` | Session cookie / bearer token triage |
+| `blursec_check_hash` | `credentials.checkHash` | Pre-hashed checks — **most private**, the raw secret never enters the conversation |
+| `blursec_verify_session` | `sessions.verify` | Incident response on live sessions (auto-detects JWT vs opaque) |
+| `blursec_whoami` | `auth.whoami` | Verify connectivity + key scope |
+
+Deliberately **not** exposed: `auth.rotate` — it invalidates the live API key
+immediately, which is far too destructive to hand to an autonomous agent.
+
+## Security model
+
+- **K-anonymity preserved** — hashing happens inside the server process via
+  the SDK; only the 10-hex-char prefix is transmitted to the Blursec API.
+- **No secret echo** — tool results never repeat the input credential/token,
+  so secrets are not duplicated into the model context.
+- **Fail-open is explicit** — results carry `failedOpen: true` when the
+  database was unreachable. The server's `initialize` instructions tell the
+  model to treat that as *unknown*, never as *safe*.
+- **Zero runtime dependencies** — like the SDK itself, this package ships no
+  third-party code. The MCP protocol subset (stdio framing, initialize,
+  tools) is implemented in ~200 audited lines.
+
+## Embedding in-process
+
+The protocol core is exported for hosts that want a custom transport:
+
+```ts
+import { BlursecMcpServer, createBlursecFromEnv } from "@blursec/mcp";
+
+const server = new BlursecMcpServer(createBlursecFromEnv());
+
+// Feed it newline-delimited JSON-RPC; undefined means "notification, no reply".
+const reply = await server.handleLine(line);
+```
+
+## License
+
+MIT © Blursec

package/dist/cli.cjs

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+'use strict';
+
+var readline = require('readline');
+var sdk = require('@blursec/sdk');
+
+var PLATFORM_HEADER = "X-Blursec-Platform";
+function resolveEnvironment(value) {
+  switch (value) {
+    case "production":
+    case "staging":
+    case "local":
+      return value;
+    default:
+      return "production";
+  }
+}
+function readEnvString(name) {
+  const value = process.env[name];
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function createBlursecFromEnv(overrides) {
+  const apiKey = readEnvString("BLURSEC_API_KEY");
+  if (typeof apiKey !== "string" || apiKey.trim().length === 0) {
+    throw new sdk.BlursecValidationError(
+      "blursec-mcp: BLURSEC_API_KEY is not set. Add it to the `env` block of your MCP host configuration (never pass API keys as prompt text)."
+    );
+  }
+  const environment = resolveEnvironment(readEnvString("BLURSEC_ENVIRONMENT"));
+  const mergedHeaders = {
+    [PLATFORM_HEADER]: "mcp",
+    ...{}
+  };
+  return new sdk.Blursec({
+    ...overrides,
+    apiKey,
+    environment,
+    defaultHeaders: mergedHeaders
+  });
+}
+var UnknownToolError = class extends Error {
+  constructor(name) {
+    super(`Unknown tool: ${name}`);
+    this.name = "UnknownToolError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var CONTEXT_SCHEMA = {
+  type: "object",
+  description: "Optional request context forwarded to Blursec Layer-3 risk scoring.",
+  properties: {
+    ip: { type: "string", description: "Client IP address." },
+    userAgent: { type: "string", description: "Raw User-Agent header." },
+    deviceFingerprint: { type: "string", description: "Stable device fingerprint." },
+    country: { type: "string", description: "ISO 3166-1 alpha-2 country code." },
+    userId: { type: "string", description: "User id, if known at check time." }
+  },
+  additionalProperties: false
+};
+var BLURSEC_TOOLS = [
+  {
+    name: "blursec_check_credential",
+    description: "Check an email + password pair against the live Blursec stealer-log database using k-anonymity (only a 10-character SHA-256 prefix leaves this machine; the raw password is hashed locally and never transmitted or echoed back). Returns leaked status, severity, and a recommended action (allow / monitor / force_reset / kill_sessions / block). If you already have the SHA-256 digest, prefer blursec_check_hash so the raw secret never enters the conversation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        email: { type: "string", description: "The account email address." },
+        password: { type: "string", description: "The password to check." },
+        context: CONTEXT_SCHEMA
+      },
+      required: ["email", "password"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "blursec_check_token",
+    description: "Check a session token / cookie value against the Blursec stealer-log database. Same k-anonymity model as blursec_check_credential \u2014 the token is hashed locally and only a 10-character prefix is transmitted.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sessionToken: {
+          type: "string",
+          description: "The raw session token or cookie value."
+        },
+        context: CONTEXT_SCHEMA
+      },
+      required: ["sessionToken"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "blursec_check_hash",
+    description: "Check a pre-computed SHA-256 hex digest (64 characters) against the Blursec stealer-log database. The most privacy-preserving tool: the raw credential never needs to appear anywhere in the conversation. For email+password pairs the digest must be SHA-256(lowercase(trim(email)) + ':' + password).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sha256: {
+          type: "string",
+          description: "64-character SHA-256 hex digest of the credential.",
+          pattern: "^[0-9a-fA-F]{64}$"
+        },
+        context: CONTEXT_SCHEMA
+      },
+      required: ["sha256"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "blursec_verify_session",
+    description: "Verify a live session token against the stealer-log database. Like blursec_check_token but auto-detects the token shape (JWTs are hashed by signature segment only) and additionally returns tokenType and a compromised flag. Use during incident response to triage active sessions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sessionToken: {
+          type: "string",
+          description: "The raw session token (opaque or JWT)."
+        }
+      },
+      required: ["sessionToken"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "blursec_whoami",
+    description: "Return the principal the configured Blursec API key is authenticated as (id, name, workspace, scopes). Use to verify connectivity and key scope before running checks.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  }
+];
+async function callBlursecTool(client, name, args) {
+  try {
+    switch (name) {
+      case "blursec_check_credential": {
+        const bag = requireArgsObject(args);
+        const email = requireString(bag, "email");
+        const password = requireString(bag, "password");
+        const result = await client.credentials.check(
+          email,
+          password,
+          checkOptions(bag)
+        );
+        return { ok: true, payload: result };
+      }
+      case "blursec_check_token": {
+        const bag = requireArgsObject(args);
+        const sessionToken = requireString(bag, "sessionToken");
+        const result = await client.credentials.checkToken(
+          sessionToken,
+          checkOptions(bag)
+        );
+        return { ok: true, payload: result };
+      }
+      case "blursec_check_hash": {
+        const bag = requireArgsObject(args);
+        const sha256 = requireString(bag, "sha256");
+        const result = await client.credentials.checkHash(
+          sha256,
+          checkOptions(bag)
+        );
+        return { ok: true, payload: result };
+      }
+      case "blursec_verify_session": {
+        const bag = requireArgsObject(args);
+        const sessionToken = requireString(bag, "sessionToken");
+        const result = await client.sessions.verify(sessionToken);
+        return { ok: true, payload: result };
+      }
+      case "blursec_whoami": {
+        const result = await client.auth.whoami();
+        return { ok: true, payload: result };
+      }
+      default:
+        throw new UnknownToolError(name);
+    }
+  } catch (err) {
+    if (err instanceof UnknownToolError) throw err;
+    return {
+      ok: false,
+      payload: {
+        error: err instanceof Error ? err.message : String(err),
+        type: err instanceof Error ? err.name : "UnknownError"
+      }
+    };
+  }
+}
+function requireArgsObject(args) {
+  if (typeof args !== "object" || args === null || Array.isArray(args)) {
+    throw new sdk.BlursecValidationError(
+      "tool arguments must be a JSON object."
+    );
+  }
+  return args;
+}
+function requireString(bag, key) {
+  const value = bag[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new sdk.BlursecValidationError(
+      `missing or empty required string argument: ${key}`
+    );
+  }
+  return value;
+}
+function checkOptions(bag) {
+  const raw = bag["context"];
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return void 0;
+  }
+  const source = raw;
+  const context = {};
+  for (const key of [
+    "ip",
+    "userAgent",
+    "deviceFingerprint",
+    "country",
+    "userId"
+  ]) {
+    const value = source[key];
+    if (typeof value === "string" && value.length > 0) {
+      context[key] = value;
+    }
+  }
+  return Object.keys(context).length > 0 ? { context } : void 0;
+}
+
+// src/server.ts
+var SUPPORTED_PROTOCOL_VERSIONS = [
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05"
+];
+var JSONRPC_ERRORS = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602
+};
+var DEFAULT_SERVER_INFO = {
+  name: "blursec-mcp",
+  version: "1.0.0"
+};
+var BlursecMcpServer = class {
+  client;
+  info;
+  constructor(client, info = DEFAULT_SERVER_INFO) {
+    this.client = client;
+    this.info = info;
+  }
+  /**
+   * Handle one newline-delimited JSON-RPC message and return the
+   * serialized reply, or `undefined` for notifications (which per
+   * JSON-RPC must not be answered).
+   */
+  async handleLine(line) {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return JSON.stringify({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: JSONRPC_ERRORS.PARSE_ERROR, message: "Parse error" }
+      });
+    }
+    const response = await this.handleMessage(message);
+    return response === void 0 ? void 0 : JSON.stringify(response);
+  }
+  /**
+   * Handle one already-parsed JSON-RPC message.
+   *
+   * Returns `undefined` for notifications; a {@link JsonRpcResponse}
+   * for requests (including error responses — this method never throws).
+   */
+  async handleMessage(message) {
+    if (!isRequestShaped(message)) {
+      return {
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+          code: JSONRPC_ERRORS.INVALID_REQUEST,
+          message: "Invalid Request"
+        }
+      };
+    }
+    const { id, method, params } = message;
+    const isNotification = id === void 0;
+    if (isNotification) return void 0;
+    switch (method) {
+      case "initialize":
+        return this.ok(id, this.initializeResult(params));
+      case "ping":
+        return this.ok(id, {});
+      case "tools/list":
+        return this.ok(id, { tools: BLURSEC_TOOLS });
+      case "tools/call":
+        return this.toolsCall(id, params);
+      default:
+        return this.err(
+          id,
+          JSONRPC_ERRORS.METHOD_NOT_FOUND,
+          `Method not found: ${method}`
+        );
+    }
+  }
+  // ── handlers ────────────────────────────────────────────────────────
+  initializeResult(params) {
+    const requested = typeof params === "object" && params !== null && typeof params["protocolVersion"] === "string" ? params["protocolVersion"] : void 0;
+    const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.includes(requested ?? "") ? requested : SUPPORTED_PROTOCOL_VERSIONS[0];
+    return {
+      protocolVersion,
+      capabilities: { tools: {} },
+      serverInfo: this.info,
+      instructions: "Blursec credential-leak threat intel. All check tools hash locally and transmit only a 10-character k-anonymity prefix. Prefer blursec_check_hash when a SHA-256 digest is available so raw secrets stay out of the conversation. Results with failedOpen=true mean the database was unreachable \u2014 treat as 'unknown', never as 'safe'."
+    };
+  }
+  async toolsCall(id, params) {
+    if (typeof params !== "object" || params === null || typeof params["name"] !== "string") {
+      return this.err(
+        id,
+        JSONRPC_ERRORS.INVALID_PARAMS,
+        "tools/call requires params.name (string)"
+      );
+    }
+    const name = params["name"];
+    const args = params["arguments"] ?? {};
+    try {
+      const outcome = await callBlursecTool(this.client, name, args);
+      return this.ok(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(outcome.payload, null, 2)
+          }
+        ],
+        isError: !outcome.ok
+      });
+    } catch (err) {
+      if (err instanceof UnknownToolError) {
+        return this.err(id, JSONRPC_ERRORS.INVALID_PARAMS, err.message);
+      }
+      return this.err(
+        id,
+        JSONRPC_ERRORS.INVALID_REQUEST,
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+  }
+  // ── reply builders ──────────────────────────────────────────────────
+  ok(id, result) {
+    return { jsonrpc: "2.0", id, result };
+  }
+  err(id, code, message) {
+    return { jsonrpc: "2.0", id, error: { code, message } };
+  }
+};
+function isRequestShaped(message) {
+  if (typeof message !== "object" || message === null) return false;
+  const m = message;
+  if (m["jsonrpc"] !== "2.0") return false;
+  if (typeof m["method"] !== "string") return false;
+  const id = m["id"];
+  return id === void 0 || id === null || typeof id === "string" || typeof id === "number";
+}
+
+// src/cli.ts
+function main() {
+  let server;
+  try {
+    server = new BlursecMcpServer(createBlursecFromEnv());
+  } catch (err) {
+    process.stderr.write(
+      `blursec-mcp: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const rl = readline.createInterface({ input: process.stdin, terminal: false });
+  let pipeline = Promise.resolve();
+  rl.on("line", (line) => {
+    if (line.trim().length === 0) return;
+    pipeline = pipeline.then(async () => {
+      try {
+        const reply = await server.handleLine(line);
+        if (reply !== void 0) process.stdout.write(reply + "\n");
+      } catch (err) {
+        process.stderr.write(
+          `blursec-mcp: internal error: ${err instanceof Error ? err.message : String(err)}
+`
+        );
+      }
+    });
+  });
+  rl.on("close", () => {
+    void pipeline.then(() => {
+      process.exitCode = 0;
+    });
+  });
+}
+main();
+//# sourceMappingURL=cli.cjs.map
+//# sourceMappingURL=cli.cjs.map

package/dist/cli.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node