kbs-upload-mcp 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# kbs-upload-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+知识库（KB）MCP 服务：让 Agent 上传技术文档、检索文档、获取项目分组清单。
+
+上传走 ai-service 中转接口（`POST /api/skt/kb/upload`），文件由内网服务直传
+KB 私有桶并注册落库。**用户侧只需内网可达 ai-service + Skill Token，
+无需 NOS 凭据、无需 VPN。**
+
+## 接入准备
+
+1. 登录 [AI 基础服务](https://ai-service.lofter.com) → 左上导航「Skill Token」→ 新建
+2. 权限勾选：`kb-upload`（上传）、`kb-search`（检索）
+3. 前提：账号已被管理员加入至少一个租户分组
+
+## MCP 配置
+
+```jsonc
+{
+  "mcpServers": {
+    "kbs-upload-mcp": {
+      "command": "npx",
+      "args": ["-y", "kbs-upload-mcp"],
+      "env": {
+        "AI_SERVICE_BASE": "https://ai-service-lofter.hz.netease.com",
+        "SKILL_TOKEN": "skt-xxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+## 工具
+
+| 工具 | 说明 |
+|---|---|
+| `kb_list_projects()` | 获取项目分组清单，上传前必须先调用 |
+| `kb_search(conditions, limit?)` | 检索文档；`conditions` 为 `{title?, summary?, author?, project?}`，字段间 OR |
+| `kb_upload(filePath, title, summary, project, author?, tenantGroup?)` | 上传文档；摘要 80–200 字必填，返回 `{id, downloadUrl}` |
+
+详细使用规范（摘要撰写、错误码、FAQ）见仓库内文档
+`docs/kb-mcp-usage.md`（lofter-ai-service 仓库）。
+
+## 环境变量
+
+| 变量 | 含义 | 默认值 |
+|---|---|---|
+| `AI_SERVICE_BASE` | ai-service 地址（内网） | `http://127.0.0.1:3000` |
+| `SKILL_TOKEN` | Skill Token（skt- 前缀） | 必配 |
+
+要求 Node.js ≥ 18（使用内置 fetch / FormData / Blob）。

package/index.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * kbs-upload-mcp — 知识库（KB）专用 MCP
+ *
+ * 上传走 ai-service 中转接口（POST /api/skt/kb/upload）：文件由内网服务直传
+ * KB 私有桶，用户侧只需内网可达 ai-service + Skill Token，
+ * 无需 NOS 凭据、无需 VPN 容器。
+ *
+ * 协议：MCP stdio（换行分隔 JSON-RPC 2.0），零 npm 依赖，`node index.mjs` 直接运行。
+ */
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+
+// 按扩展名推断 MIME，附在 Blob 上随 multipart 上传（服务端优先采用）
+function guessMime(fileName) {
+  const lower = fileName.toLowerCase();
+  if (lower.endsWith(".md") || lower.endsWith(".markdown")) return "text/markdown";
+  if (lower.endsWith(".html") || lower.endsWith(".htm")) return "text/html";
+  if (lower.endsWith(".pdf")) return "application/pdf";
+  if (lower.endsWith(".txt")) return "text/plain";
+  if (lower.endsWith(".png")) return "image/png";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+  return "application/octet-stream";
+}
+
+// ── 配置（env 注入，见工程 .mcp.json）───────────────────────────────
+const AI_SERVICE_BASE = (process.env.AI_SERVICE_BASE || "http://127.0.0.1:3000").replace(/\/$/, "");
+const SKILL_TOKEN = process.env.SKILL_TOKEN || "";
+
+// ── 服务端 API 封装（Bearer + X-Skill-Token 双头：办公网 WAF 会剥 Authorization）──
+function authHeaders() {
+  return { Authorization: `Bearer ${SKILL_TOKEN}`, "X-Skill-Token": SKILL_TOKEN };
+}
+
+async function serviceApi(path, init = {}) {
+  const resp = await fetch(`${AI_SERVICE_BASE}${path}`, {
+    ...init,
+    headers: {
+      ...authHeaders(),
+      ...(init.body ? { "Content-Type": "application/json" } : {}),
+      ...init.headers,
+    },
+  });
+  const payload = await resp.json().catch(() => ({}));
+  if (!resp.ok) {
+    throw new Error(`ai-service ${resp.status}: ${payload.error || JSON.stringify(payload)}`);
+  }
+  return payload;
+}
+
+// 服务端返回的 downloadUrl 是 path（/api/kb/documents/download/...），
+// 这里递归补全为 AI_SERVICE_BASE 下的完整链接，用户拿到即可直接打开
+function absolutizeDownloadUrl(data) {
+  if (Array.isArray(data)) return data.map(absolutizeDownloadUrl);
+  if (data && typeof data === "object") {
+    return Object.fromEntries(
+      Object.entries(data).map(([k, v]) => [
+        k,
+        k === "downloadUrl" && typeof v === "string" && v.startsWith("/")
+          ? `${AI_SERVICE_BASE}${v}`
+          : absolutizeDownloadUrl(v),
+      ])
+    );
+  }
+  return data;
+}
+
+// ── 三个工具实现 ─────────────────────────────────────────────────────
+async function kbListProjects() {
+  return serviceApi("/api/skt/kb/projects");
+}
+
+async function kbSearch(args) {
+  const sp = new URLSearchParams();
+  for (const k of ["title", "summary", "author", "project"]) {
+    if (args.conditions?.[k]) sp.set(k, String(args.conditions[k]));
+  }
+  if (args.limit) sp.set("limit", String(args.limit));
+  const payload = await serviceApi(`/api/skt/kb/search?${sp}`);
+  return absolutizeDownloadUrl(payload);
+}
+
+async function kbUpload(args) {
+  const { filePath, title, summary, project, author, tenantGroup } = args;
+  if (!filePath || !title?.trim() || !summary?.trim()) {
+    throw new Error("filePath / title / summary 均为必填（summary 80-200字：问题场景/核心结论/关键词）");
+  }
+  const body = readFileSync(filePath);
+  const fileName = basename(filePath);
+
+  // multipart 中转上传：文件 + 元数据一并交给 ai-service（内网服务直传私有桶）
+  const form = new FormData();
+  form.append("file", new Blob([body], { type: guessMime(fileName) }), fileName);
+  form.append("title", title.trim());
+  form.append("summary", summary.trim());
+  if (project?.trim()) form.append("project", project.trim());
+  if (author?.trim()) form.append("author", author.trim());
+  if (tenantGroup?.trim()) form.append("tenantGroup", tenantGroup.trim());
+
+  const resp = await fetch(`${AI_SERVICE_BASE}/api/skt/kb/upload`, {
+    method: "POST",
+    headers: authHeaders(),
+    body: form,
+  });
+  const payload = await resp.json().catch(() => ({}));
+  if (!resp.ok) {
+    throw new Error(`ai-service ${resp.status}: ${payload.error || JSON.stringify(payload)}`);
+  }
+  return { ...absolutizeDownloadUrl(payload), uploadVia: "service-relay" };
+}
+
+// ── MCP stdio 服务（换行分隔 JSON-RPC 2.0）───────────────────────────
+const TOOLS = [
+  {
+    name: "kb_list_projects",
+    description: "获取知识库项目分组清单。上传前必须先调用，结合工程目录（package.json name / git remote）推断项目分组。",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "kb_search",
+    description: "检索知识库文档。conditions 为 {title?, summary?, author?, project?}，已填字段之间是并集（OR）。回答中请附返回的 downloadUrl。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conditions: {
+          type: "object",
+          properties: {
+            title: { type: "string" },
+            summary: { type: "string" },
+            author: { type: "string" },
+            project: { type: "string" },
+          },
+        },
+        limit: { type: "number", description: "返回条数上限，默认 10，最大 50" },
+      },
+    },
+  },
+  {
+    name: "kb_upload",
+    description: "上传文档到知识库（经 ai-service 中转直传私有桶 + 注册落库）。必须先 kb_list_projects 确认分组、拟好 80-200 字摘要并向用户确认后再调用。返回 {id, downloadUrl}。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        filePath: { type: "string", description: "本地文件绝对路径" },
+        title: { type: "string", description: "文档标题" },
+        summary: { type: "string", description: "摘要，80-200字：问题场景/核心结论/关键词" },
+        project: { type: "string", description: "项目名称（来自 kb_list_projects，缺省落 default 分组）" },
+        author: { type: "string", description: "文档作者，缺省为上传者本人" },
+        tenantGroup: { type: "string", description: "租户分组名称，缺省为上传者所属分组；不存在的新分组会自动创建并加入" },
+      },
+      required: ["filePath", "title", "summary", "project"],
+    },
+  },
+];
+
+function rpcResult(id, result) {
+  process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
+}
+function rpcError(id, code, message) {
+  process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + "\n");
+}
+
+let buffer = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buffer += chunk;
+  let idx;
+  while ((idx = buffer.indexOf("\n")) >= 0) {
+    const line = buffer.slice(0, idx).trim();
+    buffer = buffer.slice(idx + 1);
+    if (line) handleMessage(line);
+  }
+});
+// stdin 关闭后不立即退出：等待在途请求完成，事件循环自然排空退出
+process.stdin.on("end", () => {});
+
+function handleMessage(line) {
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return;
+  }
+  const { id, method, params } = msg;
+  if (method === "initialize") {
+    rpcResult(id, {
+      protocolVersion: params?.protocolVersion ?? "2025-06-18",
+      capabilities: { tools: {} },
+      serverInfo: { name: "kbs-upload-mcp", version: "0.2.1" },
+    });
+  } else if (method === "notifications/initialized" || method?.startsWith("notifications/")) {
+    // 通知无需应答
+  } else if (method === "tools/list") {
+    rpcResult(id, { tools: TOOLS });
+  } else if (method === "tools/call") {
+    const tool = params?.name;
+    const args = params?.arguments ?? {};
+    const impl = { kb_list_projects: kbListProjects, kb_search: kbSearch, kb_upload: kbUpload }[tool];
+    if (!impl) {
+      rpcError(id, -32602, `Unknown tool: ${tool}`);
+      return;
+    }
+    impl(args)
+      .then((data) => rpcResult(id, {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+      }))
+      .catch((err) => rpcResult(id, {
+        content: [{ type: "text", text: `上传失败: ${err instanceof Error ? err.message : String(err)}` }],
+        isError: true,
+      }));
+  } else if (method === "ping") {
+    rpcResult(id, {});
+  } else if (id !== undefined) {
+    rpcError(id, -32601, `Method not found: ${method}`);
+  }
+}

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "kbs-upload-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "知识库（KB）MCP：上传技术文档、检索文档、获取项目分组清单（经 ai-service 中转直传私有桶，无需 NOS 凭据）",
+  "type": "module",
+  "bin": {
+    "kbs-upload-mcp": "index.mjs"
+  },
+  "files": [
+    "index.mjs"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "keywords": [
+    "mcp",
+    "kb",
+    "upload",
+    "nos"
+  ]
+}