fast-cxt-mcp 1.0.0

package/src/extract-key.mjs

@@ -0,0 +1,235 @@
+/**
+ * Windsurf API Key extraction from local installation.
+ *
+ * Cross-platform: macOS / Windows / Linux.
+ * Supports both legacy (plaintext windsurfAuthStatus) and new
+ * (Chromium safeStorage encrypted) storage formats.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir, platform } from "node:os";
+import { execSync } from "node:child_process";
+import crypto from "node:crypto";
+import Database from "better-sqlite3";
+
+const SECRET_KEY = 'secret://{"extensionId":"codeium.windsurf","key":"windsurf_auth.sessions"}';
+
+/**
+ * Get the platform-specific path to Windsurf's state.vscdb.
+ * @returns {string}
+ */
+export function getDbPath() {
+  const plat = platform();
+  const home = homedir();
+
+  if (plat === "darwin") {
+    return join(home, "Library", "Application Support", "Windsurf", "User", "globalStorage", "state.vscdb");
+  } else if (plat === "win32") {
+    const appdata = process.env.APPDATA || "";
+    if (!appdata) throw new Error("Cannot determine APPDATA path");
+    return join(appdata, "Windsurf", "User", "globalStorage", "state.vscdb");
+  } else {
+    // Linux
+    const config = process.env.XDG_CONFIG_HOME || join(home, ".config");
+    return join(config, "Windsurf", "User", "globalStorage", "state.vscdb");
+  }
+}
+
+// ─── Legacy extraction (plaintext windsurfAuthStatus) ──────
+
+/**
+ * Try extracting API key from legacy plaintext storage.
+ * @param {Database.Database} db
+ * @returns {{ api_key?: string } | null} null if key not found
+ */
+function extractFromLegacy(db) {
+  const row = db.prepare("SELECT value FROM ItemTable WHERE key = 'windsurfAuthStatus'").get();
+  if (!row) return null;
+
+  let data;
+  try {
+    data = JSON.parse(row.value);
+  } catch {
+    return null;
+  }
+
+  const apiKey = data.apiKey || "";
+  return apiKey ? { api_key: apiKey } : null;
+}
+
+// ─── New encrypted extraction (Chromium safeStorage) ───────
+
+/**
+ * Retrieve the master password from system keychain.
+ * @returns {string}
+ */
+function getMasterPassword() {
+  const plat = platform();
+
+  if (plat === "darwin") {
+    return execSync(
+      'security find-generic-password -s "Windsurf Safe Storage" -a "Windsurf Key" -w',
+      { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }
+    ).trim();
+  }
+
+  if (plat === "linux") {
+    // Try libsecret (GNOME Keyring / KDE Wallet)
+    try {
+      return execSync(
+        'secret-tool lookup application windsurf service "Windsurf Safe Storage" account "Windsurf Key"',
+        { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }
+      ).trim();
+    } catch {
+      // No keyring available — Chromium falls back to hardcoded password
+      return "peanuts";
+    }
+  }
+
+  // Windows: not applicable (uses DPAPI directly, no master password)
+  return "";
+}
+
+/**
+ * Decrypt safeStorage data on macOS / Linux.
+ * Format: 'v10' (3 bytes) + AES-128-CBC ciphertext (PBKDF2 derived key).
+ * @param {Buffer} encrypted
+ * @param {string} masterPassword
+ * @returns {string}
+ */
+function decryptAesCbc(encrypted, masterPassword) {
+  const plat = platform();
+  const iterations = plat === "darwin" ? 1003 : 1;
+  const derivedKey = crypto.pbkdf2Sync(masterPassword, "saltysalt", iterations, 16, "sha1");
+
+  const ciphertext = encrypted.slice(3); // strip 'v10' prefix
+  const iv = Buffer.alloc(16, 0x20);
+
+  const decipher = crypto.createDecipheriv("aes-128-cbc", derivedKey, iv);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+}
+
+/**
+ * Decrypt safeStorage data on Windows via DPAPI (PowerShell).
+ * Electron on Windows encrypts with CryptProtectData directly — no 'v10' prefix.
+ * Uses -EncodedCommand to avoid cmd.exe quoting/escaping issues.
+ * @param {Buffer} encrypted
+ * @returns {string}
+ */
+function decryptDpapi(encrypted) {
+  const b64 = encrypted.toString("base64");
+  const psScript =
+    `Add-Type -AssemblyName System.Security;` +
+    `$bytes = [Convert]::FromBase64String('${b64}');` +
+    `$dec = [Security.Cryptography.ProtectedData]::Unprotect($bytes, $null, 'CurrentUser');` +
+    `[Text.Encoding]::UTF8.GetString($dec)`;
+
+  // Encode the script as UTF-16LE base64 for -EncodedCommand
+  const encoded = Buffer.from(psScript, "utf16le").toString("base64");
+
+  return execSync(`powershell -NoProfile -EncodedCommand ${encoded}`, {
+    encoding: "utf8",
+    stdio: ["pipe", "pipe", "pipe"],
+  }).trim();
+}
+
+/**
+ * Try extracting API key from encrypted secret storage.
+ * @param {Database.Database} db
+ * @returns {{ api_key?: string, method?: string } | null}
+ */
+function extractFromSecret(db) {
+  const row = db.prepare("SELECT value FROM ItemTable WHERE key = ?").get(SECRET_KEY);
+  if (!row) return null;
+
+  let encryptedBuf;
+  try {
+    const parsed = JSON.parse(row.value);
+    encryptedBuf = Buffer.from(parsed.data);
+  } catch {
+    return null;
+  }
+
+  let decrypted;
+  const plat = platform();
+
+  if (plat === "win32") {
+    // Windows: raw DPAPI blob (no 'v10' prefix)
+    decrypted = decryptDpapi(encryptedBuf);
+  } else {
+    // macOS / Linux: 'v10' + AES-128-CBC
+    const prefix = encryptedBuf.slice(0, 3).toString("utf8");
+    if (prefix !== "v10" && prefix !== "v11") return null;
+    const masterPassword = getMasterPassword();
+    decrypted = decryptAesCbc(encryptedBuf, masterPassword);
+  }
+
+  let sessions;
+  try {
+    sessions = JSON.parse(decrypted);
+  } catch {
+    return null;
+  }
+
+  // sessions is an array — take the first entry with an accessToken
+  const entry = Array.isArray(sessions)
+    ? sessions.find((s) => s.accessToken)
+    : sessions;
+
+  const token = entry?.accessToken || "";
+  return token ? { api_key: token, method: "safeStorage" } : null;
+}
+
+// ─── Main entry point ──────────────────────────────────────
+
+/**
+ * Extract API Key from Windsurf state.vscdb.
+ * Tries legacy plaintext first, then falls back to encrypted safeStorage.
+ * @param {string} [dbPath]
+ * @returns {{ api_key?: string, db_path: string, method?: string, error?: string, hint?: string }}
+ */
+export function extractKey(dbPath) {
+  if (!dbPath) {
+    dbPath = getDbPath();
+  }
+
+  if (!existsSync(dbPath)) {
+    return {
+      error: `Windsurf database not found: ${dbPath}`,
+      hint: "Ensure Windsurf is installed and logged in.",
+      db_path: dbPath,
+    };
+  }
+
+  let db;
+  try {
+    db = new Database(dbPath, { readonly: true });
+  } catch (e) {
+    return { error: `Failed to open database: ${e.message}`, db_path: dbPath };
+  }
+
+  try {
+    // 1) Legacy plaintext
+    const legacy = extractFromLegacy(db);
+    if (legacy) {
+      return { ...legacy, db_path: dbPath, method: "legacy" };
+    }
+
+    // 2) Encrypted safeStorage
+    const secret = extractFromSecret(db);
+    if (secret) {
+      return { ...secret, db_path: dbPath };
+    }
+
+    return {
+      error: "No API key found in database (tried legacy + safeStorage)",
+      hint: "Ensure Windsurf is logged in. You can also set WINDSURF_API_KEY manually.",
+      db_path: dbPath,
+    };
+  } catch (e) {
+    return { error: `Extraction failed: ${e.message}`, db_path: dbPath };
+  } finally {
+    db.close();
+  }
+}

package/src/protobuf.mjs

@@ -0,0 +1,235 @@
+/**
+ * Hand-written Protobuf encoder/decoder + Connect-RPC frame handling.
+ *
+ * Matches the Windsurf wire format exactly.
+ * Python bytearray → Node.js Buffer
+ * struct.pack(">I", len) → buf.writeUInt32BE
+ * gzip.compress/decompress → zlib.gzipSync/gunzipSync
+ */
+
+import { gzipSync, gunzipSync } from "node:zlib";
+
+// ─── Protobuf Encoder ──────────────────────────────────────
+
+export class ProtobufEncoder {
+  constructor() {
+    /** @type {Buffer[]} */
+    this._chunks = [];
+  }
+
+  /**
+   * Encode an unsigned varint into a Buffer.
+   * @param {number} value
+   * @returns {Buffer}
+   */
+  _varint(value) {
+    const bytes = [];
+    while (value > 0x7f) {
+      bytes.push((value & 0x7f) | 0x80);
+      value >>>= 7;
+    }
+    bytes.push(value & 0x7f);
+    return Buffer.from(bytes);
+  }
+
+  /**
+   * Encode a field tag.
+   * @param {number} field
+   * @param {number} wire
+   * @returns {Buffer}
+   */
+  _tag(field, wire) {
+    return this._varint((field << 3) | wire);
+  }
+
+  /**
+   * Write a varint field.
+   * @param {number} field
+   * @param {number} value
+   * @returns {ProtobufEncoder}
+   */
+  writeVarint(field, value) {
+    this._chunks.push(this._tag(field, 0), this._varint(value));
+    return this;
+  }
+
+  /**
+   * Write a length-delimited string field.
+   * @param {number} field
+   * @param {string} value
+   * @returns {ProtobufEncoder}
+   */
+  writeString(field, value) {
+    const data = Buffer.from(value, "utf-8");
+    this._chunks.push(this._tag(field, 2), this._varint(data.length), data);
+    return this;
+  }
+
+  /**
+   * Write a length-delimited bytes field.
+   * @param {number} field
+   * @param {Buffer|Uint8Array} value
+   * @returns {ProtobufEncoder}
+   */
+  writeBytes(field, value) {
+    const buf = Buffer.isBuffer(value) ? value : Buffer.from(value);
+    this._chunks.push(this._tag(field, 2), this._varint(buf.length), buf);
+    return this;
+  }
+
+  /**
+   * Write a nested message field.
+   * @param {number} field
+   * @param {ProtobufEncoder} sub
+   * @returns {ProtobufEncoder}
+   */
+  writeMessage(field, sub) {
+    const data = sub.toBuffer();
+    this._chunks.push(this._tag(field, 2), this._varint(data.length), data);
+    return this;
+  }
+
+  /**
+   * Return the encoded bytes as a Buffer.
+   * @returns {Buffer}
+   */
+  toBuffer() {
+    return Buffer.concat(this._chunks);
+  }
+}
+
+// ─── Varint Decode ─────────────────────────────────────────
+
+/**
+ * Decode a varint from a buffer at the given offset.
+ * @param {Buffer} buf
+ * @param {number} offset
+ * @returns {[number, number]} [value, newOffset]
+ */
+export function decodeVarint(buf, offset) {
+  let value = 0;
+  let shift = 0;
+  while (offset < buf.length) {
+    const b = buf[offset++];
+    value |= (b & 0x7f) << shift;
+    shift += 7;
+    if (!(b & 0x80)) break;
+  }
+  return [value, offset];
+}
+
+// ─── Protobuf String Extraction ────────────────────────────
+
+/**
+ * Extract all UTF-8 strings (length > 5) from raw protobuf data
+ * by parsing wire types. Matches Python proto_extract_strings().
+ * @param {Buffer} data
+ * @returns {string[]}
+ */
+export function extractStrings(data) {
+  const strings = [];
+  let i = 0;
+  while (i < data.length) {
+    // Read tag varint
+    let tag = 0;
+    let shift = 0;
+    while (i < data.length) {
+      const b = data[i++];
+      tag |= (b & 0x7f) << shift;
+      shift += 7;
+      if (!(b & 0x80)) break;
+    }
+    const wire = tag & 0x7;
+    if (wire === 0) {
+      // Varint — skip
+      while (i < data.length) {
+        const b = data[i++];
+        if (!(b & 0x80)) break;
+      }
+    } else if (wire === 1) {
+      // 64-bit fixed
+      i += 8;
+    } else if (wire === 2) {
+      // Length-delimited
+      let length = 0;
+      shift = 0;
+      while (i < data.length) {
+        const b = data[i++];
+        length |= (b & 0x7f) << shift;
+        shift += 7;
+        if (!(b & 0x80)) break;
+      }
+      if (i + length <= data.length) {
+        const raw = data.subarray(i, i + length);
+        try {
+          const text = raw.toString("utf-8");
+          if (text.length > 5) {
+            strings.push(text);
+          }
+        } catch {
+          // Not valid UTF-8, skip
+        }
+      }
+      i += length;
+    } else if (wire === 5) {
+      // 32-bit fixed
+      i += 4;
+    } else {
+      // Unknown wire type — stop
+      break;
+    }
+  }
+  return strings;
+}
+
+// ─── Connect-RPC Frame Encode/Decode ───────────────────────
+
+/**
+ * Encode protobuf bytes into a gzip-compressed Connect-RPC frame.
+ * Frame format: 1-byte flags + 4-byte big-endian length + payload
+ * @param {Buffer} protoBytes
+ * @param {boolean} [compress=true]
+ * @returns {Buffer}
+ */
+export function connectFrameEncode(protoBytes, compress = true) {
+  let payload;
+  let flags;
+  if (compress) {
+    payload = gzipSync(protoBytes);
+    flags = 1; // gzip compressed
+  } else {
+    payload = protoBytes;
+    flags = 0;
+  }
+  const header = Buffer.alloc(5);
+  header[0] = flags;
+  header.writeUInt32BE(payload.length, 1);
+  return Buffer.concat([header, payload]);
+}
+
+/**
+ * Decode Connect-RPC frames from raw response data.
+ * Handles gzip-compressed frames (flags 1 or 3).
+ * @param {Buffer} data
+ * @returns {Buffer[]}
+ */
+export function connectFrameDecode(data) {
+  const frames = [];
+  let i = 0;
+  while (i + 5 <= data.length) {
+    const flags = data[i];
+    const length = data.readUInt32BE(i + 1);
+    i += 5;
+    let payload = data.subarray(i, i + length);
+    i += length;
+    if (flags === 1 || flags === 3) {
+      try {
+        payload = gunzipSync(payload);
+      } catch {
+        // Decompression failed — use raw payload
+      }
+    }
+    frames.push(Buffer.from(payload));
+  }
+  return frames;
+}

package/src/server.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * Windsurf Fast Context MCP Server (Node.js)
+ *
+ * AI-driven semantic code search via reverse-engineered Windsurf protocol.
+ *
+ * Configuration (environment variables):
+ *   WINDSURF_API_KEY     — Windsurf API key (auto-discovered from local install if not set)
+ *   FC_MAX_TURNS         — Search rounds per query (default: 3)
+ *   FC_MAX_COMMANDS      — Max parallel commands per round (default: 8)
+ *   FC_TIMEOUT_MS        — Connect-Timeout-Ms for streaming requests (default: 30000)
+ *
+ * Start:
+ *   node src/server.mjs
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { searchWithContent, extractKeyInfo } from "./core.mjs";
+
+/**
+ * Parse an integer env var with optional clamping.
+ * @param {string} name
+ * @param {number} defaultValue
+ * @param {{ min?: number, max?: number }} [opts]
+ * @returns {number}
+ */
+function readIntEnv(name, defaultValue, opts = {}) {
+  const raw = process.env[name];
+  const parsed = Number.parseInt(raw ?? "", 10);
+  if (!Number.isFinite(parsed)) return defaultValue;
+  const min = typeof opts.min === "number" ? opts.min : null;
+  const max = typeof opts.max === "number" ? opts.max : null;
+  let value = parsed;
+  if (min !== null) value = Math.max(min, value);
+  if (max !== null) value = Math.min(max, value);
+  return value;
+}
+
+// Read config from environment
+const MAX_TURNS = readIntEnv("FC_MAX_TURNS", 3, { min: 1, max: 5 });
+const MAX_COMMANDS = readIntEnv("FC_MAX_COMMANDS", 8, { min: 1, max: 20 });
+const TIMEOUT_MS = readIntEnv("FC_TIMEOUT_MS", 30000, { min: 1000, max: 300000 });
+
+const server = new McpServer({
+  name: "windsurf-fast-context",
+  version: "1.1.0",
+  instructions:
+    "Windsurf Fast Context — AI-driven semantic code search. " +
+    "Returns file paths with line ranges and grep keywords.\n" +
+    "Tunable parameters:\n" +
+    "- tree_depth (1-6, default 3): How much directory structure the remote AI sees. " +
+    "REDUCE if you get payload/size errors. INCREASE for small projects where deeper structure helps.\n" +
+    "- max_turns (1-5, default 3): How many search rounds. " +
+    "INCREASE if results are incomplete. Use 1 for quick lookups.\n" +
+    "- max_results (1-30, default 10): Maximum number of files to return.\n" +
+    "- exclude_paths (string array, default []): Directory/file patterns to exclude from tree. " +
+    "Use for large repos to reduce payload size (e.g. ['node_modules', 'dist', '.git']).\n" +
+    "The response includes [config] and [diagnostic] lines — read them to decide if you should retry with different parameters.",
+});
+
+// ─── Tool: fast_context_search ─────────────────────────────
+
+server.tool(
+  "fast_context_search",
+  "AI-driven semantic code search using Windsurf's Devstral model. " +
+    "Searches a codebase with natural language and returns relevant file paths with line ranges, " +
+    "plus suggested grep keywords for follow-up searches.\n" +
+    "Parameter tuning guide:\n" +
+    "- tree_depth: Controls how much directory structure the remote AI sees before searching. " +
+    "If you get a payload/size error, REDUCE this value. " +
+    "If search results are too shallow (missing files in deep subdirectories), INCREASE this value.\n" +
+    "- max_turns: Controls how many search-execute-feedback rounds the remote AI gets. " +
+    "If results are incomplete or the AI didn't find enough files, INCREASE this value. " +
+    "If you want a quick rough answer, use 1.\n" +
+    "Response includes a [config] line showing actual parameters used — use this to decide adjustments on retry.",
+  {
+    query: z.string().describe(
+      'Natural language search query (e.g. "where is auth handled", "database connection pool")'
+    ),
+    project_path: z
+      .string()
+      .default("")
+      .describe("Absolute path to project root. Empty = current working directory."),
+    tree_depth: z
+      .number()
+      .int()
+      .min(1)
+      .max(6)
+      .default(3)
+      .describe(
+        "Directory tree depth for the initial repo map sent to the remote AI. " +
+        "Default 3. Use 1-2 for huge monorepos (>5000 files) or if you get payload size errors. " +
+        "Use 4-6 for small projects (<200 files) where you want the AI to see deeper structure. " +
+        "Auto falls back to a lower depth if tree output exceeds 250KB."
+      ),
+    max_turns: z
+      .number()
+      .int()
+      .min(1)
+      .max(5)
+      .default(MAX_TURNS)
+      .describe(
+        "Number of search rounds. Each round: remote AI generates search commands → local execution → results sent back. " +
+        "Default 3. Use 1 for quick simple lookups. Use 4-5 for complex queries requiring deep tracing across many files. " +
+        "More rounds = better results but slower and uses more API quota."
+      ),
+    max_results: z
+      .number()
+      .int()
+      .min(1)
+      .max(30)
+      .default(10)
+      .describe(
+        "Maximum number of files to return. Default 10. " +
+        "Use a smaller value (3-5) for focused queries. " +
+        "Use a larger value (15-30) for broad exploration queries."
+      ),
+    exclude_paths: z
+      .array(z.string())
+      .default([])
+      .describe(
+        "Directory/file patterns to exclude from tree and search context. " +
+        "Useful for reducing payload size on large repos. " +
+        "Examples: ['node_modules', 'dist', '.git', 'build', 'coverage', '*.min.*']"
+      ),
+  },
+  async ({ query, project_path, tree_depth, max_turns, max_results, exclude_paths }) => {
+    let projectPath = project_path || process.cwd();
+
+    try {
+      const { statSync } = await import("node:fs");
+      if (!statSync(projectPath).isDirectory()) {
+        return { content: [{ type: "text", text: `Error: project path does not exist: ${projectPath}` }] };
+      }
+    } catch {
+      return { content: [{ type: "text", text: `Error: project path does not exist: ${projectPath}` }] };
+    }
+
+    try {
+      const result = await searchWithContent({
+        query,
+        projectRoot: projectPath,
+        maxTurns: max_turns,
+        maxCommands: MAX_COMMANDS,
+        maxResults: max_results,
+        treeDepth: tree_depth,
+        timeoutMs: TIMEOUT_MS,
+        excludePaths: exclude_paths,
+      });
+      return { content: [{ type: "text", text: result }] };
+    } catch (e) {
+      const code = e.code || "UNKNOWN";
+      return { content: [{ type: "text", text:
+        `Error [${code}]: ${e.message}\n\n` +
+        `[hint] Suggestions based on error type:\n` +
+        `  - Reduce tree_depth (current: ${tree_depth})\n` +
+        `  - Add exclude_paths to filter large directories (e.g. ['node_modules', 'dist'])\n` +
+        `  - Narrow project_path to a subdirectory\n` +
+        `  - Reduce max_turns (current: ${max_turns})`
+      }] };
+    }
+  }
+);
+
+// ─── Tool: extract_windsurf_key ────────────────────────────
+
+server.tool(
+  "extract_windsurf_key",
+  "Extract Windsurf API Key from local installation. " +
+    "Auto-detects OS (macOS/Windows/Linux) and reads the API key from " +
+    "Windsurf's local database. Set the result as WINDSURF_API_KEY env var.",
+  {},
+  async () => {
+    const result = extractKeyInfo();
+
+    if (result.error) {
+      const text = `Error: ${result.error}\n${result.hint || ""}\nDB path: ${result.db_path || "N/A"}`;
+      return { content: [{ type: "text", text }] };
+    }
+
+    const key = result.api_key;
+    const method = result.method === "safeStorage" ? "safeStorage (encrypted)" : "legacy (plaintext)";
+    const text =
+      `Windsurf API Key extracted successfully\n\n` +
+      `  Key: ${key.slice(0, 30)}...${key.slice(-10)}\n` +
+      `  Length: ${key.length}\n` +
+      `  Method: ${method}\n` +
+      `  Source: ${result.db_path}\n\n` +
+      `Usage:\n` +
+      `  export WINDSURF_API_KEY="${key}"`;
+
+    return { content: [{ type: "text", text }] };
+  }
+);
+
+// ─── Start ─────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});