@kk-irving/knowledge-mcp-server 1.0.0

package/dist/sources/gerrit-sync.js

@@ -0,0 +1,180 @@
+/**
+ * Gerrit 同步：拉 changes 写入本地 gerrit_changes 表。
+ *
+ * 双通道认证（与 gerrit-mcp v1.1.0 一致）：
+ *   - session 模式（首选）：GERRIT_AUTH_HEADER + GERRIT_COOKIE，走 non-/a/ 路径
+ *   - basic 模式（备选）：GERRIT_USERNAME + GERRIT_HTTP_PASSWORD，走 /a/ 路径
+ *
+ * Gerrit 响应首行的 `)]}'` XSSI 防护前缀会被剥离。
+ */
+import { getDb, getSyncState, setSyncState, runInTransaction } from "../db.js";
+const GERRIT_URL = (process.env.GERRIT_URL ?? "").replace(/\/+$/, "");
+const GERRIT_AUTH_HEADER = (process.env.GERRIT_AUTH_HEADER ?? "").trim();
+const GERRIT_COOKIE = (process.env.GERRIT_COOKIE ?? "").trim();
+const GERRIT_USERNAME = (process.env.GERRIT_USERNAME ?? "").trim();
+const GERRIT_HTTP_PASSWORD = process.env.GERRIT_HTTP_PASSWORD ?? "";
+function authMode() {
+    if (GERRIT_AUTH_HEADER && GERRIT_COOKIE)
+        return "session";
+    if (GERRIT_USERNAME && GERRIT_HTTP_PASSWORD)
+        return "basic";
+    return "missing";
+}
+function buildHeaders(mode) {
+    const h = { Accept: "application/json" };
+    if (mode === "session") {
+        h.Authorization = GERRIT_AUTH_HEADER;
+        h.Cookie = GERRIT_COOKIE;
+    }
+    else if (mode === "basic") {
+        const enc = Buffer.from(`${GERRIT_USERNAME}:${GERRIT_HTTP_PASSWORD}`, "utf8").toString("base64");
+        h.Authorization = `Basic ${enc}`;
+    }
+    return h;
+}
+function injectAuthPrefix(p, mode) {
+    const norm = p.startsWith("/") ? p : `/${p}`;
+    if (mode === "session") {
+        if (norm.startsWith("/a/"))
+            return norm.slice(2);
+        return norm;
+    }
+    if (norm === "/a" || norm.startsWith("/a/"))
+        return norm;
+    return `/a${norm}`;
+}
+function stripXssi(text) {
+    if (text.startsWith(")]}'"))
+        return text.slice(4).trimStart();
+    return text;
+}
+async function gerritGet(path, params) {
+    if (!GERRIT_URL)
+        throw new Error("GERRIT_URL 未配置");
+    const mode = authMode();
+    if (mode === "missing") {
+        throw new Error("缺少 Gerrit 凭据：请配置 GERRIT_AUTH_HEADER+GERRIT_COOKIE (session) 或 GERRIT_USERNAME+GERRIT_HTTP_PASSWORD (basic)。运行 scripts/refresh-auth.* 自动生成。");
+    }
+    const apiPath = injectAuthPrefix(path, mode);
+    const url = new URL(apiPath, GERRIT_URL);
+    for (const [k, v] of params)
+        url.searchParams.append(k, v);
+    const res = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(mode),
+    });
+    const text = await res.text();
+    const stripped = stripXssi(text);
+    if (!res.ok) {
+        throw new Error(`Gerrit HTTP ${res.status} (auth_mode=${mode}): ${stripped.slice(0, 300)}`);
+    }
+    if (!stripped)
+        return [];
+    try {
+        return JSON.parse(stripped);
+    }
+    catch (e) {
+        throw new Error(`Gerrit 响应 JSON 解析失败: ${e.message}; preview=${stripped.slice(0, 200)}`);
+    }
+}
+function commitMessageOf(ch) {
+    for (const rev of Object.values(ch.revisions ?? {})) {
+        const msg = rev?.commit?.message ?? "";
+        if (msg)
+            return msg;
+    }
+    return "";
+}
+const UPSERT_SQL = `
+INSERT INTO gerrit_changes (
+  change_id, number, project, branch, subject,
+  commit_message, owner_name, status, created, updated
+) VALUES (
+  @change_id, @number, @project, @branch, @subject,
+  @commit_message, @owner_name, @status, @created, @updated
+)
+ON CONFLICT(change_id) DO UPDATE SET
+  number = excluded.number,
+  project = excluded.project,
+  branch = excluded.branch,
+  subject = excluded.subject,
+  commit_message = excluded.commit_message,
+  owner_name = excluded.owner_name,
+  status = excluded.status,
+  created = excluded.created,
+  updated = excluded.updated
+`;
+function buildQuery(args) {
+    const parts = [];
+    if (args.query)
+        parts.push(args.query);
+    if (args.project)
+        parts.push(`project:${args.project}`);
+    if (args.since)
+        parts.push(`after:"${args.since}"`);
+    if (parts.length === 0)
+        parts.push("status:open OR -status:open"); // all
+    return parts.join(" ");
+}
+/**
+ * 全量/增量同步 Gerrit changes。
+ */
+export async function syncGerrit(args = {}) {
+    const db = getDb();
+    const limit = Math.max(1, Math.min(50000, args.limit ?? 1000));
+    const stateSince = args.since ?? getSyncState("gerrit", "last_full_sync_date") ?? "";
+    const finalQuery = buildQuery({
+        since: stateSince,
+        query: args.query,
+        project: args.project,
+    });
+    const upsert = db.prepare(UPSERT_SQL);
+    function upsertMany(rows) {
+        runInTransaction(db, () => {
+            for (const r of rows)
+                upsert.run(r);
+        });
+    }
+    let offset = 0;
+    let fetched = 0;
+    let upserted = 0;
+    const batchSize = 200;
+    while (fetched < limit) {
+        const remaining = limit - fetched;
+        const n = Math.min(batchSize, remaining);
+        const params = [
+            ["q", finalQuery],
+            ["n", String(n)],
+            ["S", String(offset)],
+            ["o", "CURRENT_REVISION"],
+            ["o", "CURRENT_COMMIT"],
+            ["o", "DETAILED_ACCOUNTS"],
+        ];
+        const changes = await gerritGet("/changes/", params);
+        if (changes.length === 0)
+            break;
+        const rows = changes.map((ch) => ({
+            change_id: ch.change_id ?? String(ch._number ?? ""),
+            number: ch._number ?? null,
+            project: ch.project ?? "",
+            branch: ch.branch ?? "",
+            subject: ch.subject ?? "",
+            commit_message: commitMessageOf(ch),
+            owner_name: ch.owner?.name ?? "",
+            status: ch.status ?? "",
+            created: ch.created ?? "",
+            updated: ch.updated ?? "",
+        }));
+        upsertMany(rows);
+        fetched += changes.length;
+        upserted += changes.length;
+        offset += changes.length;
+        if (changes.length < n)
+            break;
+        if (!changes[changes.length - 1]?._more_changes)
+            break;
+    }
+    const today = new Date().toISOString().slice(0, 10);
+    setSyncState("gerrit", "last_full_sync_date", today);
+    return { source: "gerrit", fetched, upserted, watermark: today, query: finalQuery };
+}

package/dist/sources/zmind-sync.js

@@ -0,0 +1,106 @@
+/**
+ * Zmind 同步：拉 issues 写入本地 zmind_issues 表。
+ *
+ * 复用环境变量：
+ *   - ZMIND_URL          (默认 https://zmind.whaletv.com)
+ *   - ZMIND_API_KEY      必填
+ */
+import { getDb, getSyncState, setSyncState, runInTransaction } from "../db.js";
+const ZMIND_URL = (process.env.ZMIND_URL ?? "https://zmind.whaletv.com").replace(/\/+$/, "");
+const ZMIND_API_KEY = process.env.ZMIND_API_KEY ?? "";
+async function zmindGet(path, params) {
+    if (!ZMIND_API_KEY)
+        throw new Error("ZMIND_API_KEY 未配置");
+    const url = new URL(path, ZMIND_URL + "/");
+    for (const [k, v] of Object.entries(params)) {
+        if (v != null)
+            url.searchParams.set(k, v);
+    }
+    url.searchParams.set("key", ZMIND_API_KEY);
+    const res = await fetch(url.toString(), {
+        headers: { Accept: "application/json" },
+    });
+    if (!res.ok) {
+        throw new Error(`Zmind HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`);
+    }
+    return res.json();
+}
+const UPSERT_SQL = `
+INSERT INTO zmind_issues (
+  id, tracker, subject, description, status, assigned_to,
+  project_id, project_name, created_on, updated_on
+) VALUES (
+  @id, @tracker, @subject, @description, @status, @assigned_to,
+  @project_id, @project_name, @created_on, @updated_on
+)
+ON CONFLICT(id) DO UPDATE SET
+  tracker = excluded.tracker,
+  subject = excluded.subject,
+  description = excluded.description,
+  status = excluded.status,
+  assigned_to = excluded.assigned_to,
+  project_id = excluded.project_id,
+  project_name = excluded.project_name,
+  created_on = excluded.created_on,
+  updated_on = excluded.updated_on
+`;
+/**
+ * 全量/增量同步 Zmind issues。
+ *
+ * @param args.since  仅同步 updated_on >= since 的 issues（YYYY-MM-DD）。未传则用 sync_state 水位。
+ * @param args.limit  最大同步条数（防一次性拉爆）。默认 1000。
+ * @param args.statusId 状态过滤；默认 "*" 全部
+ */
+export async function syncZmind(args = {}) {
+    const db = getDb();
+    const limit = Math.max(1, Math.min(50000, args.limit ?? 1000));
+    const stateSince = args.since ?? getSyncState("zmind", "last_full_sync") ?? "";
+    const upsert = db.prepare(UPSERT_SQL);
+    function upsertMany(rows) {
+        runInTransaction(db, () => {
+            for (const r of rows)
+                upsert.run(r);
+        });
+    }
+    let offset = 0;
+    let fetched = 0;
+    let upserted = 0;
+    const pageSize = 100;
+    while (fetched < limit) {
+        const remaining = limit - fetched;
+        const batch = Math.min(pageSize, remaining);
+        const params = {
+            status_id: args.statusId ?? "*",
+            sort: "updated_on:desc",
+            offset: String(offset),
+            limit: String(batch),
+        };
+        if (stateSince)
+            params.updated_on = `>=${stateSince}`;
+        const data = await zmindGet("/issues.json", params);
+        const issues = data.issues ?? [];
+        if (issues.length === 0)
+            break;
+        const rows = issues.map((i) => ({
+            id: i.id,
+            tracker: i.tracker?.name ?? "",
+            subject: i.subject ?? "",
+            description: i.description ?? "",
+            status: i.status?.name ?? "",
+            assigned_to: i.assigned_to?.name ?? "",
+            project_id: i.project?.id ?? null,
+            project_name: i.project?.name ?? "",
+            created_on: i.created_on ?? "",
+            updated_on: i.updated_on ?? "",
+        }));
+        upsertMany(rows);
+        fetched += issues.length;
+        upserted += issues.length;
+        offset += issues.length;
+        if (issues.length < batch)
+            break;
+    }
+    const watermark = new Date().toISOString();
+    setSyncState("zmind", "last_full_sync", watermark);
+    return { source: "zmind", fetched, upserted, watermark };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@kk-irving/knowledge-mcp-server",
+  "version": "1.0.0",
+  "description": "Local knowledge base MCP Server: vector (BGE-small-zh ONNX) + FTS5 hybrid retrieval across Zmind PR / Gerrit changes / Confluence pages",
+  "type": "module",
+  "bin": {
+    "knowledge-mcp-server": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.12.1",
+    "@xenova/transformers": "^2.17.2",
+    "zod": "3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "24.0.3",
+    "tsx": "4.19.4",
+    "typescript": "5.8.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KK-Irving/whaletv-dev-power.git",
+    "directory": "mcp-servers/knowledge-mcp-server"
+  },
+  "license": "UNLICENSED"
+}