@powercess/qq-mcp 0.2.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@powercess/qq-mcp",
+  "version": "0.2.0",
+  "description": "MCP server that reads QQ (Windows NTQQ) chat records, contacts and database schema from local data — offline, no native dependencies.",
+  "type": "module",
+  "license": "MIT",
+  "author": "powercess",
+  "homepage": "https://github.com/powercess/qq-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/powercess/qq-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/powercess/qq-mcp/issues"
+  },
+  "keywords": [
+    "qq",
+    "ntqq",
+    "mcp",
+    "model-context-protocol",
+    "sqlcipher",
+    "chat-history",
+    "reverse-engineering",
+    "windows"
+  ],
+  "bin": {
+    "qq-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "src",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "pretest": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc -w",
+    "test": "node --test \"test/**/*.test.mjs\""
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "os": [
+    "win32"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/scripts/scan_memory.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Dump candidate passphrase tokens from a running process's memory.
+
+Windows + Python 3 stdlib only. NTQQ keeps the SQLCipher device passphrase as a
+short ASCII string in-process; this helper extracts every short printable token
+so the caller can test them against a `.material` file or a database page.
+
+Candidates are printed one per line on stdout; progress goes to stderr.
+"""
+import ctypes
+import ctypes.wintypes as w
+import re
+import sys
+from ctypes import windll
+
+PROCESS_QUERY_INFORMATION = 0x0400
+PROCESS_VM_READ = 0x0010
+MEM_COMMIT = 0x1000
+PAGE_NOACCESS = 0x01
+PAGE_GUARD = 0x100
+
+MIN_LEN = 12
+MAX_LEN = 32
+# Windows emitted for longer runs: QQ passes the passphrase to SQLCipher as a
+# NUL-terminated C string, but a copy can also sit inside a larger blob.
+WINDOW_LENS = (16, 20)
+MAX_WINDOWS_PER_RUN = 64
+CHUNK = 4 * 1024 * 1024
+DEFAULT_MAX_CANDIDATES = 200_000
+
+NARROW = re.compile(rb"[\x20-\x7e]+")
+WIDE = re.compile(rb"(?:[\x20-\x7e]\x00)+")
+
+
+def looks_like_secret(text):
+    """Cheap prior: keys mix case, digits or punctuation; prose rarely does."""
+    classes = sum(
+        (
+            any(c.isdigit() for c in text),
+            any(c.isalpha() for c in text),
+            any(not c.isalnum() for c in text),
+        )
+    )
+    return classes >= 2
+
+
+class MBI(ctypes.Structure):
+    _fields_ = [
+        ("BaseAddress", ctypes.c_void_p),
+        ("AllocationBase", ctypes.c_void_p),
+        ("AllocationProtect", w.DWORD),
+        ("PartitionId", ctypes.c_uint16),
+        ("RegionSize", ctypes.c_size_t),
+        ("State", w.DWORD),
+        ("Protect", w.DWORD),
+        ("Type", w.DWORD),
+    ]
+
+
+k32 = windll.kernel32
+k32.OpenProcess.restype = ctypes.c_void_p
+k32.OpenProcess.argtypes = [w.DWORD, w.BOOL, w.DWORD]
+k32.VirtualQueryEx.argtypes = [ctypes.c_void_p, ctypes.c_void_p, ctypes.POINTER(MBI), ctypes.c_size_t]
+k32.VirtualQueryEx.restype = ctypes.c_size_t
+k32.ReadProcessMemory.argtypes = [
+    ctypes.c_void_p,
+    ctypes.c_void_p,
+    ctypes.c_void_p,
+    ctypes.c_size_t,
+    ctypes.POINTER(ctypes.c_size_t),
+]
+k32.ReadProcessMemory.restype = w.BOOL
+k32.CloseHandle.argtypes = [ctypes.c_void_p]
+
+
+def collect(blob, seen, out, limit):
+    """Adds printable runs (and, for long runs, key-length windows) to `out`."""
+    for pattern, wide in ((NARROW, False), (WIDE, True)):
+        for match in pattern.finditer(blob):
+            raw = match.group(0)
+            text = raw.decode("utf-16-le" if wide else "ascii", "ignore")
+            candidates = [text] if MIN_LEN <= len(text) <= MAX_LEN else []
+            # NTQQ hands SQLCipher 16- or 20-byte passphrases; a copy can sit
+            # inside a longer blob (source text, marshalled constants), so the
+            # key-length windows of every longer run are candidates too.
+            if len(text) > min(WINDOW_LENS) and looks_like_secret(text):
+                for length in WINDOW_LENS:
+                    limit_here = min(len(text) - length, MAX_WINDOWS_PER_RUN)
+                    for start in range(0, limit_here):
+                        candidates.append(text[start : start + length])
+            for candidate in candidates:
+                if candidate in seen:
+                    continue
+                seen.add(candidate)
+                out.append(candidate)
+                if len(out) >= limit:
+                    return True
+    return False
+
+
+def scan(pid, seen, out, limit):
+    handle = k32.OpenProcess(PROCESS_QUERY_INFORMATION | PROCESS_VM_READ, False, pid)
+    if not handle:
+        print(f"open failed for pid {pid}", file=sys.stderr)
+        return
+    addr = 0x10000
+    try:
+        while addr < 0x7FFFFFFFFFFF:
+            mbi = MBI()
+            if k32.VirtualQueryEx(handle, ctypes.c_void_p(addr), ctypes.byref(mbi), ctypes.sizeof(MBI)) == 0:
+                break
+            size = mbi.RegionSize
+            if size <= 0:
+                break
+            base = mbi.BaseAddress or addr
+            if mbi.State == MEM_COMMIT and not (mbi.Protect & PAGE_NOACCESS) and not (mbi.Protect & PAGE_GUARD):
+                offset = 0
+                while offset < size:
+                    chunk = min(CHUNK, size - offset)
+                    buf = ctypes.create_string_buffer(chunk)
+                    read = ctypes.c_size_t()
+                    if (
+                        k32.ReadProcessMemory(handle, ctypes.c_void_p(base + offset), buf, chunk, ctypes.byref(read))
+                        and read.value
+                    ):
+                        if collect(buf.raw[: read.value], seen, out, limit):
+                            return
+                    offset += chunk
+            addr = base + size
+    finally:
+        k32.CloseHandle(handle)
+
+
+def main(argv):
+    limit = DEFAULT_MAX_CANDIDATES
+    if "--max" in argv:
+        index = argv.index("--max")
+        limit = int(argv[index + 1])
+        del argv[index : index + 2]
+    pids = [int(p) for p in argv]
+    if not pids:
+        print("usage: scan_memory.py <pid> [pid ...] [--max N]", file=sys.stderr)
+        return 2
+    seen = set()
+    out = []
+    for pid in pids:
+        scan(pid, seen, out, limit)
+        print(f"pid {pid}: {len(out)} candidates so far", file=sys.stderr)
+    for text in out:
+        print(text, flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/smoke-client.mjs

@@ -0,0 +1,30 @@
+/**
+ * Stdio smoke client: connects to the built MCP server and invokes tools.
+ * Usage: node scripts/smoke-client.mjs [tool] [argsJson]
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const tool = process.argv[2] ?? "get_db_schema";
+const args = process.argv[3] ? JSON.parse(process.argv[3]) : {};
+
+const transport = new StdioClientTransport({
+  command: process.execPath,
+  args: [join(__dirname, "..", "dist", "index.js")],
+  // The SDK filters env down to a safe allowlist; forward ours so
+  // QQ_MCP_PASSPHRASE / QQ_MCP_DATA_DIR reach the server like a real client.
+  env: Object.fromEntries(Object.entries(process.env).filter((entry) => typeof entry[1] === "string")),
+});
+const client = new Client({ name: "smoke", version: "0.0.1" });
+await client.connect(transport);
+
+const tools = await client.listTools();
+console.log("tools:", tools.tools.map((t) => t.name).join(", "));
+
+const res = await client.callTool({ name: tool, arguments: args });
+console.log("result:", res.content?.[0]?.text ?? JSON.stringify(res));
+
+await client.close();

package/src/index.ts

@@ -0,0 +1,341 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { decryptMaterial, extractSchema, DEFAULT_KDF_ITER } from "./schema.js";
+import {
+  chatStats,
+  ensurePlaintext,
+  findQQDataDirs,
+  listContacts,
+  listDataSources,
+  listGroupMembers,
+  openOffline,
+  plaintextCachePath,
+  queryMessages,
+  requirePassphrase,
+  type DataSource,
+} from "./offline.js";
+import { captureOfflineKey, findQQPids, pickOracle, verifyPassphraseEverywhere } from "./keyscan.js";
+import { verifyPassphrase } from "./sqlcipher.js";
+import { resolve } from "node:path";
+
+function ok(payload: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }] };
+}
+
+function fail(error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  return { isError: true, content: [{ type: "text" as const, text: JSON.stringify({ error: message }, null, 2) }] };
+}
+
+/** Finds a local database by name, preferring the most recently written copy. */
+function resolveSource(name: string, explicit?: string): DataSource {
+  if (explicit) {
+    const wanted = resolve(explicit);
+    const dir = wanted.replace(/[\\/][^\\/]*$/, "");
+    const match = listDataSources([dir]).find((s) => resolve(s.dbPath) === wanted);
+    if (match) return match;
+    throw new Error(`${explicit}: no NTQQ database found at that path`);
+  }
+  const candidates = listDataSources().filter((s) => s.name === name || s.name.startsWith(name));
+  const usable = candidates.filter((s) => s.pages > 0).sort((a, b) => b.mtimeMs - a.mtimeMs);
+  if (usable.length === 0) {
+    const dirs = findQQDataDirs();
+    throw new Error(`no local ${name} found (searched: ${dirs.join(", ") || "no NTQQ directories"})`);
+  }
+  return usable[0];
+}
+
+/** Sibling database in the same `nt_db` directory as `source`. */
+function sibling(source: DataSource, name: string): string | undefined {
+  const dir = source.dbPath.replace(/[\\/][^\\/]*$/, "");
+  const found = listDataSources([dir]).find((s) => s.name === name && s.pages > 0);
+  return found?.dbPath;
+}
+
+const server = new McpServer({
+  name: "qq-mcp",
+  version: "0.2.0",
+});
+
+/**
+ * Offline: list locally installed NTQQ databases plus running QQ PIDs.
+ * First step of every offline workflow — pick a database, then decrypt it.
+ */
+server.registerTool(
+  "list_qq_databases",
+  {
+    description:
+      "Lists NTQQ (Windows QQ NT) databases found under Documents/Tencent Files/*/nt_qq/nt_db, " +
+      "with page count, salt, format version and whether a .material key blob exists. Also " +
+      "reports running QQ PIDs. Works fully offline.",
+    inputSchema: {
+      dirs: z.array(z.string()).optional().describe("Extra nt_db directories to scan"),
+    },
+  },
+  async ({ dirs }) => {
+    try {
+      const searchDirs = [...(dirs ?? []), ...findQQDataDirs()];
+      const databases = listDataSources(searchDirs).map((s) => ({
+        name: s.name,
+        path: s.dbPath,
+        bytes: s.bytes,
+        pages: s.pages,
+        saltHex: s.saltHex,
+        formatVersion: s.formatVersion,
+        material: s.materialPath ?? null,
+      }));
+      const pids = await findQQPids().catch(() => []);
+      return ok({ searchedDirs: searchDirs, databases, qqPids: pids });
+    } catch (error) {
+      return fail(error);
+    }
+  }
+);
+
+/**
+ * Online (Windows): recover the device passphrase by scanning QQ's own memory
+ * and accepting the first candidate that decrypts a known artefact. The
+ * passphrase is never written to disk unless `save` is set.
+ */
+server.registerTool(
+  "capture_offline_key",
+  {
+    description:
+      "Recovers the NTQQ device passphrase: scrapes short ASCII tokens from a running QQ " +
+      "process and verifies each against a .material file or database page. Requires a " +
+      "logged-in QQ and Python 3. Pass save=true to persist it to .qqkey (gitignored).",
+    inputSchema: {
+      pids: z.array(z.number().int().positive()).optional().describe("QQ PIDs; defaults to all running QQ.exe"),
+      materialPath: z.string().optional().describe("Any <db>-first.material file to verify against"),
+      dbPath: z.string().optional().describe("Database to verify against when no material is available"),
+      maxCandidates: z.number().int().positive().optional().default(200_000),
+      save: z.boolean().optional().default(false),
+    },
+  },
+  async (args) => {
+    try {
+      const result = await captureOfflineKey(args);
+      if (!result.passphrase) {
+        return ok({
+          found: false,
+          ...result,
+          note: "no candidate decrypted the oracle; make sure QQ is logged in and the target database belongs to this account",
+        });
+      }
+      return ok({ found: true, ...result });
+    } catch (error) {
+      return fail(error);
+    }
+  }
+);
+
+/** Offline: check a passphrase against a database (single target or every local database). */
+server.registerTool(
+  "verify_offline_key",
+  {
+    description:
+      "Verifies an NTQQ device passphrase against a database's page 1 or a .material file. " +
+      "Use all=true to test every database found locally — one passphrase unlocks all of them.",
+    inputSchema: {
+      passphrase: z.string().optional().describe("Defaults to QQ_MCP_PASSPHRASE or .qqkey"),
+      dbPath: z.string().optional(),
+      materialPath: z.string().optional(),
+      all: z.boolean().optional().default(false),
+    },
+  },
+  async ({ passphrase, dbPath, materialPath, all }) => {
+    try {
+      const key = requirePassphrase(passphrase);
+      if (all) return ok({ results: verifyPassphraseEverywhere(key) });
+      if (materialPath) {
+        const { plaintext } = decryptMaterial(materialPath, key);
+        return ok({ materialPath, ok: plaintext.includes(Buffer.from("CREATE TABLE", "utf8")), byteLen: plaintext.length });
+      }
+      const oracle = pickOracle({ dbPath, sources: dbPath ? undefined : listDataSources() });
+      if (!oracle) return ok({ ok: false, note: "no database found to verify against" });
+      if (oracle.kind === "material") {
+        const { plaintext } = decryptMaterial(oracle.materialPath, key);
+        return ok({ oracle: oracle.materialPath, ok: plaintext.includes(Buffer.from("CREATE TABLE", "utf8")) });
+      }
+      return ok({ oracle: oracle.dbPath, ok: verifyPassphrase(oracle.dbPath, key) });
+    } catch (error) {
+      return fail(error);
+    }
+  }
+);
+
+/**
+ * Offline: decrypt a database (WAL replayed) into the plaintext cache and
+ * report its shape. This is the "offline key" payoff — no QQ required.
+ */
+server.registerTool(
+  "decrypt_qq_database",
+  {
+    description:
+      "Decrypts an NTQQ SQLCipher database (AES-256-CBC page cipher, PBKDF2-HMAC-SHA512) " +
+      "into a plaintext SQLite file under exports/plain, replaying committed WAL frames. " +
+      "Returns the plaintext path plus table counts. Cached until the source changes.",
+    inputSchema: {
+      dbPath: z.string().optional().describe("Defaults to the newest local nt_msg.db"),
+      passphrase: z.string().optional().describe("Defaults to QQ_MCP_PASSPHRASE or .qqkey"),
+      force: z.boolean().optional().default(false),
+    },
+  },
+  async ({ dbPath, passphrase, force }) => {
+    try {
+      const source = resolveSource("nt_msg.db", dbPath);
+      const key = requirePassphrase(passphrase);
+      const result = ensurePlaintext(source.dbPath, key, { force });
+      const stats = chatStats(openOffline(source.dbPath, { passphrase: key, plaintextPath: result.path }));
+      return ok({
+        source: source.dbPath,
+        plaintext: result.path,
+        reusedCache: result.reused,
+        decryptMs: result.durationMs,
+        cachePath: plaintextCachePath(source.dbPath),
+        stats,
+      });
+    } catch (error) {
+      return fail(error);
+    }
+  }
+);
+
+/** Offline: query chat messages with decoded protobuf content. */
+server.registerTool(
+  "query_chat_messages",
+  {
+    description:
+      "Queries decrypted chat records offline. Filters by peer QQ (c2c) or group number, " +
+      "time range and keyword (matched on decoded text). Each message carries typed " +
+      "segments (text/image/file/video/sticker/reply/forward/call/system).",
+    inputSchema: {
+      dbPath: z.string().optional().describe("Defaults to the newest local nt_msg.db"),
+      passphrase: z.string().optional(),
+      chat: z.enum(["c2c", "group", "all"]).optional().default("all"),
+      peerQq: z.number().int().positive().optional(),
+      groupQq: z.number().int().positive().optional(),
+      since: z.number().int().optional().describe("Unix seconds, inclusive"),
+      until: z.number().int().optional().describe("Unix seconds, inclusive"),
+      keyword: z.string().optional(),
+      limit: z.number().int().positive().max(5000).optional().default(100),
+      order: z.enum(["asc", "desc"]).optional().default("desc"),
+      maxScan: z.number().int().positive().optional().default(200_000),
+    },
+  },
+  async (args) => {
+    try {
+      const source = resolveSource("nt_msg.db", args.dbPath);
+      const key = requirePassphrase(args.passphrase);
+      const offline = openOffline(source.dbPath, { passphrase: key });
+      const result = queryMessages(offline, args);
+      return ok({ source: source.dbPath, plaintext: offline.plaintextPath, ...result });
+    } catch (error) {
+      return fail(error);
+    }
+  }
+);
+
+/** Offline: real contact book — friends, groups and the QQ↔UID mapping table. */
+server.registerTool(
+  "list_contacts",
+  {
+    description:
+      "Lists contacts offline from recent_contact_v3_table (friends with QQ number, uid, " +
+      "remark/nickname and last-activity time), group_list in group_info.db (group number, " +
+      "name, member count) and the nt_uid_mapping_table QQ↔NT-UID map.",
+    inputSchema: {
+      dbPath: z.string().optional(),
+      passphrase: z.string().optional(),
+      limit: z.number().int().positive().max(5000).optional().default(500),
+    },
+  },
+  async ({ dbPath, passphrase, limit }) => {
+    try {
+      const source = resolveSource("nt_msg.db", dbPath);
+      const key = requirePassphrase(passphrase);
+      const offline = openOffline(source.dbPath, { passphrase: key });
+      const groupInfoPath = sibling(source, "group_info.db");
+      const contacts = listContacts(offline, { groupInfoPath, passphrase: key, limit });
+      return ok({
+        source: source.dbPath,
+        groupInfo: groupInfoPath ?? null,
+        friends: contacts.friends,
+        groups: contacts.groups,
+        uidMappings: contacts.uidMappings,
+      });
+    } catch (error) {
+      return fail(error);
+    }
+  }
+);
+
+/** Offline: group member roster from group_info.db. */
+server.registerTool(
+  "list_group_members",
+  {
+    description:
+      "Lists the offline group member roster from group_info.db.group_member3: member QQ, " +
+      "NT uid, nickname, group card and last-speak time. Filter by groupQq for one group.",
+    inputSchema: {
+      groupQq: z.number().int().positive().optional(),
+      dbPath: z.string().optional().describe("Path to nt_msg.db, used to locate group_info.db"),
+      passphrase: z.string().optional(),
+      limit: z.number().int().positive().max(5000).optional().default(200),
+    },
+  },
+  async ({ groupQq, dbPath, passphrase, limit }) => {
+    try {
+      const source = resolveSource("nt_msg.db", dbPath);
+      const key = requirePassphrase(passphrase);
+      const groupInfoPath = sibling(source, "group_info.db");
+      if (!groupInfoPath) throw new Error("group_info.db not found next to the selected database");
+      const members = listGroupMembers(groupInfoPath, { passphrase: key, groupQq, limit });
+      return ok({ groupInfo: groupInfoPath, count: members.length, members });
+    } catch (error) {
+      return fail(error);
+    }
+  }
+);
+
+/**
+ * Offline: decrypt a QQNT `<db>.material` file (PBKDF2-HMAC-SHA512 + AES-256-CBC,
+ * IV=0) and list the database schema it embeds. Independent of any database.
+ */
+server.registerTool(
+  "get_db_schema",
+  {
+    description:
+      "Decrypts a QQNT .material key-material file and returns the database schema " +
+      "(tables/indexes of nt_msg.db etc). Needs only the passphrase — no database access.",
+    inputSchema: {
+      materialPath: z.string().describe("Path to e.g. nt_msg.db-first.material"),
+      passphrase: z.string().optional().describe("Defaults to QQ_MCP_PASSPHRASE or .qqkey"),
+      kdfIter: z.number().int().positive().optional().default(DEFAULT_KDF_ITER),
+    },
+  },
+  async ({ materialPath, passphrase, kdfIter }) => {
+    try {
+      const key = requirePassphrase(passphrase);
+      const { salt, plaintext } = decryptMaterial(materialPath, key, kdfIter);
+      const tables = extractSchema(plaintext);
+      return ok({
+        saltHex: salt.toString("hex"),
+        byteLen: plaintext.length,
+        tableCount: tables.length,
+        tables: tables.map((t) => ({
+          name: t.name,
+          columns: t.columns ?? [],
+          statement: t.statement?.slice(0, 400) ?? null,
+        })),
+      });
+    } catch (error) {
+      return fail(error);
+    }
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);