@blursec/mcp 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,173 @@
+import { BlursecClientConfig, Blursec } from '@blursec/sdk';
+
+/**
+ * Env-aware Blursec constructor for the MCP server.
+ *
+ * Reads the API key and environment from process env so agent hosts
+ * (Claude Desktop, VS Code, Cursor, ...) can configure the server via
+ * their standard `env` block without ever placing the key in a prompt.
+ *
+ * @module
+ */
+
+/**
+ * Construct a {@link Blursec} client configured from the environment.
+ *
+ * Environment read:
+ *
+ * | env var               | purpose                                          |
+ * |-----------------------|--------------------------------------------------|
+ * | `BLURSEC_API_KEY`     | API key (required unless overridden)             |
+ * | `BLURSEC_ENVIRONMENT` | `production` (default) / `staging` / `local`     |
+ *
+ * Every field of {@link BlursecClientConfig} can be overridden via
+ * the `overrides` argument; `defaultHeaders` are merged (overrides
+ * win on conflict). Outbound traffic is tagged
+ * `X-Blursec-Platform: mcp` so the Blursec ops team can distinguish
+ * agent traffic from application traffic.
+ *
+ * @throws {BlursecValidationError} when neither `overrides.apiKey`
+ *   nor the `BLURSEC_API_KEY` env var is set.
+ */
+declare function createBlursecFromEnv(overrides?: Partial<BlursecClientConfig>): Blursec;
+
+/**
+ * Minimal, zero-dependency MCP server core.
+ *
+ * Implements the subset of the Model Context Protocol a tools-only
+ * server needs — `initialize`, `ping`, `tools/list`, `tools/call` —
+ * as plain JSON-RPC 2.0 message handling, decoupled from any
+ * transport. {@link BlursecMcpServer.handleLine} is what the stdio
+ * CLI feeds; tests drive {@link BlursecMcpServer.handleMessage}
+ * directly.
+ *
+ * Why not `@modelcontextprotocol/sdk`? This package guards a security
+ * product's perimeter: a hand-rolled ~200-line protocol core keeps the
+ * supply chain at zero runtime dependencies, matching the root SDK's
+ * invariant. The protocol subset used here (stdio framing, version
+ * negotiation, tools) has been stable across every spec revision since
+ * 2024-11-05.
+ *
+ * @module
+ */
+
+/** Protocol revisions this server can speak, newest first. */
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+/** JSON-RPC 2.0 error codes used by this server. */
+declare const JSONRPC_ERRORS: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+};
+/** Shape of every reply produced by {@link BlursecMcpServer}. */
+interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+/** Server identity advertised during `initialize`. */
+interface ServerInfo {
+    readonly name: string;
+    readonly version: string;
+}
+/**
+ * Tools-only MCP server bound to a {@link Blursec} client.
+ *
+ * Stateless by design: messages are handled independently, so a host
+ * that re-initializes or probes out of order never wedges the server.
+ *
+ * @example Wire to any line-based transport
+ * ```ts
+ * const server = new BlursecMcpServer(createBlursecFromEnv());
+ * rl.on("line", async (line) => {
+ *   const reply = await server.handleLine(line);
+ *   if (reply !== undefined) process.stdout.write(reply + "\n");
+ * });
+ * ```
+ */
+declare class BlursecMcpServer {
+    private readonly client;
+    private readonly info;
+    constructor(client: Blursec, info?: ServerInfo);
+    /**
+     * Handle one newline-delimited JSON-RPC message and return the
+     * serialized reply, or `undefined` for notifications (which per
+     * JSON-RPC must not be answered).
+     */
+    handleLine(line: string): Promise<string | undefined>;
+    /**
+     * Handle one already-parsed JSON-RPC message.
+     *
+     * Returns `undefined` for notifications; a {@link JsonRpcResponse}
+     * for requests (including error responses — this method never throws).
+     */
+    handleMessage(message: unknown): Promise<JsonRpcResponse | undefined>;
+    private initializeResult;
+    private toolsCall;
+    private ok;
+    private err;
+}
+
+/**
+ * Blursec tool definitions + dispatcher for the MCP server.
+ *
+ * Five read-mostly tools wrapping the SDK surface. Deliberately
+ * excluded: `auth.rotate` (immediately invalidates the live API key —
+ * far too destructive to hand to an autonomous agent).
+ *
+ * Secret-handling rules baked into every tool:
+ *
+ * - Hashing happens in *this* process via the SDK; only a 10-hex-char
+ *   k-anonymity prefix ever reaches the Blursec API.
+ * - Tool results never echo back the input credential/token, so the
+ *   secret does not get duplicated into the model context a second time.
+ * - Agents that can hash locally should prefer `blursec_check_hash`
+ *   so the raw secret never enters the conversation at all.
+ *
+ * @module
+ */
+
+/**
+ * JSON-Schema-shaped tool description, as required by the MCP
+ * `tools/list` response.
+ */
+interface ToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+}
+/**
+ * Result of dispatching one tool call.
+ *
+ * `ok: false` means the *tool* failed (bad arguments, SDK validation,
+ * strict-mode API error) — per the MCP spec this is reported inside
+ * the result with `isError: true`, not as a protocol error, so the
+ * model can read the message and self-correct.
+ */
+interface ToolCallOutcome {
+    readonly ok: boolean;
+    readonly payload: unknown;
+}
+/** Thrown when `tools/call` names a tool this server does not have. */
+declare class UnknownToolError extends Error {
+    constructor(name: string);
+}
+/**
+ * The tool manifest returned by `tools/list`.
+ */
+declare const BLURSEC_TOOLS: readonly ToolDefinition[];
+/**
+ * Dispatch a single tool call against a {@link Blursec} client.
+ *
+ * Argument errors and SDK errors are folded into `ok: false` outcomes
+ * (the model can read them); only {@link UnknownToolError} escapes —
+ * that one is the *caller's* protocol bug and becomes a JSON-RPC error.
+ */
+declare function callBlursecTool(client: Blursec, name: string, args: unknown): Promise<ToolCallOutcome>;
+
+export { BLURSEC_TOOLS, BlursecMcpServer, JSONRPC_ERRORS, type JsonRpcResponse, SUPPORTED_PROTOCOL_VERSIONS, type ServerInfo, type ToolCallOutcome, type ToolDefinition, UnknownToolError, callBlursecTool, createBlursecFromEnv };

package/dist/index.js

@@ -0,0 +1,368 @@
+import { BlursecValidationError, Blursec } from '@blursec/sdk';
+
+// src/env.ts
+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 = overrides?.apiKey ?? readEnvString("BLURSEC_API_KEY");
+  if (typeof apiKey !== "string" || apiKey.trim().length === 0) {
+    throw new 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 = overrides?.environment ?? resolveEnvironment(readEnvString("BLURSEC_ENVIRONMENT"));
+  const mergedHeaders = {
+    [PLATFORM_HEADER]: "mcp",
+    ...overrides?.defaultHeaders ?? {}
+  };
+  return new 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 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 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";
+}
+
+export { BLURSEC_TOOLS, BlursecMcpServer, JSONRPC_ERRORS, SUPPORTED_PROTOCOL_VERSIONS, UnknownToolError, callBlursecTool, createBlursecFromEnv };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@blursec/mcp",
+  "version": "1.0.0",
+  "description": "Official Model Context Protocol (MCP) server for @blursec/sdk — lets AI agents check credentials, tokens, and sessions against live stealer-log threat intel.",
+  "license": "MIT",
+  "author": "Blursec",
+  "homepage": "https://github.com/blur-sec/blursec-sdk/tree/main/packages/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blur-sec/blursec-sdk.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/blur-sec/blursec-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "blursec-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "keywords": [
+    "blursec",
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "credential-leak",
+    "stealer-logs",
+    "threat-intel",
+    "security"
+  ],
+  "peerDependencies": {
+    "@blursec/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@blursec/sdk": "file:../..",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}