@kk-2004/kfile-mcp 0.1.0

package/README.md

@@ -0,0 +1,165 @@
+# kfile-mcp
+
+一个 stdio MCP server，把本地 MCP 客户端（workbuddy、Claude Desktop、Cursor、Cline 等）桥接到 **k-File** 的远程 SSE MCP 服务端，并自动完成 OAuth 网页授权与令牌管理。
+
+装好后首次运行会自动打开浏览器让你登录授权一次，之后全自动复用令牌——无需手动复制 token、无需配 Bearer header。
+
+## 工作原理
+
+```
+你的 MCP 客户端 ──stdio──▶ kfile-mcp ──SSE + Bearer──▶ k-File 后端
+                                │
+                                ├ 首次（无令牌）:
+                                │   起本地回调 → 开浏览器授权 → 收 ?token= → 存文件
+                                └ 之后: 直接读令牌文件连 SSE
+```
+
+## 前置要求
+
+- **Node.js ≥ 18**
+- 已部署的 k-File 后端（提供 `/mcp/sse` 与 `/admin/mcp/authorize`）
+- k-File SUPER 已在「系统设置 → MCP 授权回调白名单」加入 `http://127.0.0.1:` 前缀（否则本地回调会被拒）
+
+## 配置（环境变量）
+
+| 变量 | 必填 | 说明 | 默认 |
+|---|---|---|---|
+| `KFILE_HOST` | | k-File 后端地址，如 `http://localhost:9000`。不设置时连接默认服务 | `https://file.ksite.xin` |
+| `KFILE_TOKEN` | | 直接指定令牌，跳过自动授权流程 | — |
+| `KFILE_TOKEN_FILE` | | 令牌存储路径 | `~/.kfile-mcp/token.json` |
+| `KFILE_CALLBACK_PORT` | | 本地授权回调端口 | 随机 |
+
+## 各客户端接入
+
+### workbuddy
+
+编辑 `~/.workbuddy/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "kfile": {
+      "command": "npx",
+      "args": ["-y", "@kk-2004/kfile-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
+
+```json
+{
+  "mcpServers": {
+    "kfile": {
+      "command": "npx",
+      "args": ["-y", "@kk-2004/kfile-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+`~/.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "kfile": {
+      "command": "npx",
+      "args": ["-y", "@kk-2004/kfile-mcp"]
+    }
+  }
+}
+```
+
+### Cline
+
+`~/.cline/cline_mcp_settings.json`：
+
+```json
+{
+  "mcpServers": {
+    "kfile": {
+      "command": "npx",
+      "args": ["-y", "@kk-2004/kfile-mcp"],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+## 授权流程（在 agent 内完成，无需手动跑终端）
+
+配置好后重启客户端。bridge 启动时**不阻塞**，且**立即列出全部工具**（kfile_login、kfile_logout + k-File 业务工具）。agent 一开始就能看到完整能力清单——未登录时调用真实工具会返回"请先 kfile_login"。
+
+整体功能说明通过 MCP 的 server `instructions` 字段一次性传达给 agent（不重复写在每个工具描述里）。
+
+### 首次使用 / 令牌过期
+
+1. bridge 启动，所有工具可见。
+2. 调用 `kfile_login` → bridge 起本地回调 + 打开浏览器到 `<KFILE_AUTH_HOST>/admin/mcp/authorize`。
+3. 浏览器登录（若未登录）→ 点「授权并跳转」。
+4. 令牌通过 `?token=` 回调到本地，保存到 `~/.kfile-mcp/token.json`，bridge 连接 SSE。
+5. 之后即可调用 k-File 工具。
+
+### 之后使用
+
+bridge 启动时若发现已存令牌，会**静默自动连接**，无需再调 `kfile_login`。
+
+### 退出
+
+调用 `kfile_logout` → 清除本地令牌 + 断开连接，回到未授权态。用于切换账号、令牌失效或安全考虑。
+
+## 故障排查
+
+- **需要连接自部署后端**：在客户端配置的 `env` 里设置 `KFILE_HOST`，例如 `http://localhost:9000`。
+- **调用真实工具返回"未登录"**：还没授权。调用 `kfile_login`（或重启客户端后它会自动用已存令牌）。
+- **`kfile_login` 报 redirect_uri 不合法**：k-File SUPER 没在「系统设置 → MCP 授权回调白名单」放行 `http://127.0.0.1:`。
+- **k-File 工具调用返回 401**：令牌过期或被吊销。调用 `kfile_logout` 再 `kfile_login` 重新授权。
+- **无法自动打开浏览器**（无 GUI / SSH 环境）：`kfile_login` 会打印授权链接，手动复制到浏览器打开即可。
+
+## 可用工具
+
+bridge 启动即列出全部工具（整体功能见 server instructions）：
+
+| 工具 | 用途 |
+|---|---|
+| `kfile_login` | 授权登录（开浏览器），成功后可调用其他工具 |
+| `kfile_logout` | 退出登录并清除令牌，回到未授权态 |
+| `list_my_templates` | 列出可用项目模板 |
+| `create_project` | 创建项目（支持模板回填，仅 SUPER） |
+| `list_my_projects` | 列出有权限的项目 |
+| `get_project_info` | 获取项目详情与用户填写链接 |
+| `list_missing_submitters` | 查某项目未提交名单 |
+| `create_archive_download_link` | 生成打包下载链接 |
+| `ask_user_choice` | 向用户提问让其选项选择 |
+
+## 开发
+
+```bash
+cd mcp-bridge
+npm install
+npm run build       # 输出到 dist/
+npm start           # 本地运行（默认连接 https://file.ksite.xin）
+```
+
+发布：
+
+```bash
+npm publish
+```
+
+## 安全
+
+- 令牌等同你的管理员身份（角色 + 项目权限），有效期 6 个月，保存在 `~/.kfile-mcp/token.json`（权限 0600）。
+- 如怀疑泄露：删除令牌文件 + 在 k-File「管理员与权限设置 → MCP 访问令牌」吊销。
+- bridge 工具集仅含低危操作（创建 + 只读查询 + 未提交查询），不含文件上传/删除/修改项目。
+
+## License
+
+MIT

package/dist/auth.js

@@ -0,0 +1,194 @@
+/**
+ * Token management & first-time OAuth-style authorization for k-File MCP.
+ *
+ * Flow:
+ * 1. Try to read token from KFILE_TOKEN env or the token file.
+ * 2. If no token: start a local HTTP callback server, open the browser to the
+ *    k-File authorization page, receive the token via ?token=, persist it.
+ *
+ * k-File's authorization is non-standard OAuth: the server returns the plaintext
+ * token directly as a `?token=` query param on the redirect_uri (no code exchange).
+ */
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { URL } from 'node:url';
+import open from 'open';
+export function defaultTokenFile() {
+    return process.env.KFILE_TOKEN_FILE || path.join(os.homedir(), '.kfile-mcp', 'token.json');
+}
+/** Read a previously stored token; returns null if missing/invalid. */
+export function loadToken(host) {
+    // Manual override wins.
+    if (process.env.KFILE_TOKEN && process.env.KFILE_TOKEN.trim()) {
+        return process.env.KFILE_TOKEN.trim();
+    }
+    const file = defaultTokenFile();
+    try {
+        const raw = fs.readFileSync(file, 'utf8');
+        const data = JSON.parse(raw);
+        if (data && data.token)
+            return data.token;
+    }
+    catch {
+        /* no token yet */
+    }
+    return null;
+}
+/** Persist token to file (mode 0600). */
+export function saveToken(token, host) {
+    const file = defaultTokenFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const payload = { token, host, savedAt: Date.now() };
+    fs.writeFileSync(file, JSON.stringify(payload, null, 2), { mode: 0o600 });
+}
+/**
+ * Ensure we have a token. If none is stored, run the authorization flow:
+ * start a local callback server, open browser to k-File authorize page,
+ * wait for the ?token= callback, persist, return the token.
+ *
+ * @param host k-File base URL (defaults to https://file.ksite.xin in the CLI)
+ */
+export async function ensureToken(host) {
+    const existing = loadToken(host);
+    if (existing)
+        return existing;
+    return runAuthorizationFlow(host);
+}
+/**
+ * Run the OAuth-style web authorization flow: local callback server + browser.
+ * Returns the plaintext token once the user authorizes in the browser.
+ * Exported so the bridge's kfile_login tool can invoke it on-demand.
+ *
+ * @param host k-File SSE/API backend host (token saved against this)
+ * @param authHost host serving the authorization page (frontend).
+ *                 In dev this differs from `host` (e.g. 5174 vs 9000);
+ *                 in production they are the same. Defaults to `host`.
+ */
+export function runAuthorizationFlow(host, authHost = host) {
+    return new Promise((resolve, reject) => {
+        const preferredPort = process.env.KFILE_CALLBACK_PORT ? parseInt(process.env.KFILE_CALLBACK_PORT, 10) : 0;
+        const server = http.createServer((req, res) => {
+            try {
+                const url = new URL(req.url || '/', `http://127.0.0.1`);
+                const token = url.searchParams.get('token');
+                if (!token) {
+                    res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+                    res.end(renderPage('error', '授权失败', '回调缺少 token 参数，请重新发起授权。'));
+                    return;
+                }
+                saveToken(token, host);
+                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(renderPage('success', '授权成功', '令牌已安全保存，有效期 6 个月。现在可以关闭此页面并返回 agent 继续操作。'));
+                server.close();
+                // Log to stderr so it doesn't corrupt stdio JSON-RPC.
+                console.error('[kfile-mcp-bridge] 授权成功，令牌已保存。');
+                resolve(token);
+            }
+            catch (e) {
+                res.writeHead(500, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(renderPage('error', '服务器错误', '处理授权回调时发生内部错误，请重试。'));
+            }
+        });
+        server.on('error', (err) => {
+            reject(new Error(`无法启动本地回调服务: ${err.message}`));
+        });
+        server.listen(preferredPort, '127.0.0.1', () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr ? addr.port : preferredPort;
+            const redirectUri = `http://127.0.0.1:${port}/callback`;
+            // 授权页是前端路由，用 authHost（开发环境前端 5174；生产同域）
+            const authUrl = `${authHost.replace(/\/$/, '')}/admin/mcp/authorize?redirect_uri=${encodeURIComponent(redirectUri)}`;
+            console.error(`[kfile-mcp-bridge] 首次使用，请在浏览器中完成授权：`);
+            console.error(`[kfile-mcp-bridge]   ${authUrl}`);
+            open(authUrl).catch(() => {
+                // No GUI / open failed: user must copy the URL manually (already printed above).
+                console.error('[kfile-mcp-bridge] 无法自动打开浏览器，请手动复制上方链接到浏览器打开。');
+            });
+        });
+        // Safety timeout (5 min): avoid hanging forever if user never authorizes.
+        setTimeout(() => {
+            try {
+                server.close();
+            }
+            catch { }
+            reject(new Error('授权超时（5 分钟内未完成）。请重新运行。'));
+        }, 5 * 60 * 1000);
+    });
+}
+/** Delete the stored token file (forces re-authorization next run). */
+export function clearToken() {
+    const file = defaultTokenFile();
+    try {
+        fs.unlinkSync(file);
+    }
+    catch { /* ignore */ }
+}
+/**
+ * Render a clean, styled result page for the authorization callback.
+ * type: 'success' | 'error'
+ */
+function renderPage(type, title, message) {
+    const isSuccess = type === 'success';
+    const color = isSuccess ? '#10a37f' : '#ef4444';
+    const bgTint = isSuccess ? '#f0fdf4' : '#fef2f2';
+    const border = isSuccess ? '#bbf7d0' : '#fecaca';
+    // SVG icon: check or cross
+    const icon = isSuccess
+        ? '<path d="M20 6L9 17l-5-5"/>'
+        : '<path d="M18 6L6 18M6 6l12 12"/>';
+    return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title} - k-File MCP</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    background: #f7f7f8;
+    color: #202123;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    min-height: 100vh;
+    padding: 20px;
+  }
+  .card {
+    background: #fff;
+    border-radius: 16px;
+    box-shadow: 0 4px 24px rgba(0,0,0,0.06);
+    max-width: 440px;
+    width: 100%;
+    overflow: hidden;
+    text-align: center;
+  }
+  .icon-wrap {
+    width: 72px;
+    height: 72px;
+    margin: 40px auto 0;
+    border-radius: 50%;
+    background: ${bgTint};
+    border: 2px solid ${border};
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  svg { width: 36px; height: 36px; stroke: ${color}; stroke-width: 2.5; fill: none; stroke-linecap: round; stroke-linejoin: round; }
+  h1 { font-size: 22px; font-weight: 600; margin: 20px 0 8px; color: ${color}; }
+  p { font-size: 14px; line-height: 1.6; color: #6e6e80; padding: 0 32px; margin-bottom: 28px; }
+  .brand { font-size: 12px; color: #b4b4b4; padding: 0 0 28px; letter-spacing: 0.5px; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <div class="icon-wrap"><svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">${icon}</svg></div>
+    <h1>${title}</h1>
+    <p>${message}</p>
+    <div class="brand">k-File MCP Bridge</div>
+  </div>
+</body>
+</html>`;
+}

package/dist/bridge.js

@@ -0,0 +1,318 @@
+/**
+ * stdio ↔ SSE bridge for k-File MCP, with in-protocol authorization.
+ *
+ * Design:
+ *   - A server-level "instructions" string explains the whole MCP's purpose
+ *     and the login flow ONCE, so tool descriptions stay concise (no repeat).
+ *   - ALL tools (5 k-File tools + kfile_login + kfile_logout) are listed from
+ *     startup; no dynamic discovery. Calling a real tool before login returns
+ *     "请先 kfile_login".
+ *   - kfile_login runs the OAuth browser flow + connects SSE.
+ *   - kfile_logout deletes the token + disconnects.
+ *
+ * The k-File tool metadata (names/descriptions/schemas) is a static manifest;
+ * the actual call is forwarded to the remote SSE server (source of truth).
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { runAuthorizationFlow, loadToken, clearToken } from './auth.js';
+/** Server-level instructions: explains the whole MCP once (not per-tool). */
+const INSTRUCTIONS = [
+    'k-File MCP —— 让你（AI agent）代管理员操作 k-File 文件收集系统。',
+    'k-File 是一个文件收集系统：管理员创建"项目"定义收集规则（字段、文件类型、截止时间等），用户按规则提交文件，管理员可查询谁还没提交。',
+    '',
+    '可用能力：创建项目（支持套用模板）、查看有权限的项目、查询某项目未提交名单、向用户提问让其选项选择。',
+    '',
+    '鉴权：首次使用必须先调用 kfile_login 工具登录（会打开浏览器让用户授权）；之后即可调用其他工具。用完可用 kfile_logout 退出。',
+    '权限由授权账号的角色决定：SUPER 可创建项目、看全部项目；ADMIN 只能看被分配给自己的项目、不能创建。',
+    '',
+    '重要约定：凡需用户在确定选项中选择（选模板/选项目/开关取值），优先调用 ask_user_choice 让用户选，而非让用户在输入框手输。',
+    '创建项目第一步必须先调用 ask_user_choice 询问“是否使用模板”，并把结果作为 useTemplate 传给 create_project。',
+    '用户选择使用模板后，必须展示模板列表让用户选择模板，不要让用户手填 templateId；选了模板后开关字段（allowResubmit 等）继承模板值，不要再问用户。useTemplate=false 时每个开关用 ask_user_choice(是/否) 询问、不读默认值。',
+    '创建项目必须先预览再确认：先调用 create_project 且不传 confirmed 或 confirmed=false，展示预览和 confirmationToken 后用 ask_user_choice 让用户确认/修改；用户确认后再以 confirmed=true 和原 confirmationToken 调用创建。',
+].join('\n');
+const LOGIN_TOOL = {
+    name: 'kfile_login',
+    description: '授权并登录 k-File。首次使用或令牌过期时调用：会打开浏览器让用户登录授权，成功后即可调用其他工具。',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+};
+const LOGOUT_TOOL = {
+    name: 'kfile_logout',
+    description: '退出登录并清除本地令牌。之后调用其他工具需重新 kfile_login。用于令牌失效、切换账号或安全考虑。',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+};
+/** Tools provided by the k-File backend (static manifest). */
+const KFILE_TOOLS = [
+    {
+        name: 'list_my_templates',
+        description: '列出当前用户有权限使用的项目模板，含可复用字段。用于 create_project 前选定 templateId。建议用 ask_user_choice 让用户选。',
+        inputSchema: { type: 'object', properties: {}, required: [] },
+    },
+    {
+        name: 'create_project',
+        description: '创建项目。第一步必须先用 ask_user_choice 问用户是否使用模板，并传 useTemplate。useTemplate=true 且未传 templateId 时会返回模板 options，必须用 ask_user_choice 展示给用户选择，不要让用户手填 templateId；useTemplate=false 时手填创建。必须先预览再确认：首次不传 confirmed 或 confirmed=false，只返回预览和 confirmationToken 不创建；展示给用户并让用户确认/修改，用户确认后再以 confirmed=true 和原 confirmationToken 调用才创建。如果参数修改，必须重新预览获取新 token。创建成功返回 submitUrl。仅 SUPER 可创建。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: '项目名称（必填）' },
+                useTemplate: { type: 'boolean', description: '是否使用模板。创建项目第一步必须先问用户，并传入 true/false。' },
+                templateId: { type: 'number', description: '模板 ID。useTemplate=true 时必填，来自用户选择的模板。' },
+                startAt: { type: 'number', description: '开始时间 epoch 毫秒（可选）' },
+                endAt: { type: 'number', description: '截止时间 epoch 毫秒（可选）' },
+                fileSizeLimitBytes: { type: 'number', description: '单文件大小上限字节（可选，null=不限）' },
+                allowedFileTypes: { type: 'array', items: { type: 'string' }, description: '允许的文件扩展名，如 ["pdf","zip"]（可选）' },
+                allowResubmit: { type: 'boolean', description: '可复用覆盖：是否允许重复提交（可选）' },
+                allowMultiFiles: { type: 'boolean', description: '可复用覆盖：是否允许多文件（可选）' },
+                allowOverdue: { type: 'boolean', description: '可复用覆盖：是否允许逾期提交（可选）' },
+                expectedUserFieldsJson: { type: 'string', description: '可复用覆盖：期望字段配置 JSON（可选）' },
+                pathFieldKey: { type: 'string', description: '可复用覆盖：上传路径字段 key（可选）' },
+                pathSegmentsJson: { type: 'string', description: '可复用覆盖：上传路径层级 JSON 数组（可选）' },
+                userSubmitStatusType: { type: 'string', description: '可复用覆盖：状态提示类型 info/warning/success/danger（可选）' },
+                userSubmitStatusText: { type: 'string', description: '可复用覆盖：状态提示文案（可选）' },
+                queryFieldKey: { type: 'string', description: '可复用覆盖：查询主键字段（可选）' },
+                allowedSubmitterKeysJson: { type: 'string', description: '可复用覆盖：允许提交者字段 key JSON 数组（可选）' },
+                allowedSubmitterListJson: { type: 'string', description: '可复用覆盖：允许提交名单 JSON（可选）' },
+                autoFileNamingEnabled: { type: 'boolean', description: '可复用覆盖：是否开启自动命名（可选）' },
+                autoFileNamingConfigJson: { type: 'string', description: '可复用覆盖：自动命名配置 JSON（可选）' },
+                confirmed: { type: 'boolean', description: '用户是否已确认创建。false/不传=只预览；true=确认后真正创建。' },
+                confirmationToken: { type: 'string', description: '预览返回的确认令牌。confirmed=true 时必须提供，且参数不能与预览时不同。' },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'list_my_projects',
+        description: '列出当前用户有权限的项目（SUPER 全部；ADMIN 仅被分配的）。用于后续操作（如查询未提交者）前选定 projectId。建议用 ask_user_choice 让用户选。',
+        inputSchema: { type: 'object', properties: {}, required: [] },
+    },
+    {
+        name: 'get_project_info',
+        description: '获取某个项目详情，并返回用户填写链接 submitUrl。需项目管理权限。建议先用 list_my_projects 让用户选 projectId。',
+        inputSchema: {
+            type: 'object',
+            properties: { projectId: { type: 'number', description: '项目 ID' } },
+            required: ['projectId'],
+        },
+    },
+    {
+        name: 'list_missing_submitters',
+        description: '查询某项目尚未提交的允许提交者名单。需对该项目有管理权限（SUPER 或被分配的 ADMIN）。建议先用 list_my_projects + ask_user_choice 让用户选定 projectId。',
+        inputSchema: {
+            type: 'object',
+            properties: { projectId: { type: 'number', description: '项目 ID' } },
+            required: ['projectId'],
+        },
+    },
+    {
+        name: 'create_archive_download_link',
+        description: '为项目生成打包下载链接。复用后台打包分享逻辑：生成最新有效提交文件的预签名清单并创建 /share?s=... 下载页，访问链接即可打包下载。可选 fieldKey/fieldValue 按提交者字段前缀过滤，expireSeconds 默认 3600。需项目管理权限。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectId: { type: 'number', description: '项目 ID' },
+                fieldKey: { type: 'string', description: '可选：按提交者字段过滤的字段 key' },
+                fieldValue: { type: 'string', description: '可选：按提交者字段过滤的字段值前缀' },
+                expireSeconds: { type: 'number', description: '可选：链接有效期秒数，默认 3600' },
+            },
+            required: ['projectId'],
+        },
+    },
+    {
+        name: 'ask_user_choice',
+        description: '向用户提问让其从选项中选择，返回所选 value。凡需用户在确定选项中选择（选模板/选项目/开关取值）时优先用本工具，而非让用户在输入框手输。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                prompt: { type: 'string', description: '提问说明/标题，向用户清晰呈现要选什么' },
+                options: {
+                    type: 'array',
+                    description: '选项数组，每项 {value, label}',
+                    items: { type: 'object', properties: { value: {}, label: { type: 'string' } } },
+                },
+            },
+            required: ['prompt', 'options'],
+        },
+    },
+];
+const ALL_TOOLS = [LOGIN_TOOL, LOGOUT_TOOL, ...KFILE_TOOLS];
+export async function runBridge(opts) {
+    const { host } = opts;
+    const authHost = (process.env.KFILE_AUTH_HOST || host).trim();
+    const server = new Server({ name: 'kfile-mcp-bridge', version: '0.1.0' }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    let remoteClient = null;
+    let remoteToolNames = new Set();
+    let activeToken = null;
+    /** Connect to k-File SSE with a token. */
+    async function connectRemote(token) {
+        const sseUrl = new URL(`${host.replace(/\/$/, '')}/mcp/sse`);
+        const authHeaders = { Authorization: `Bearer ${token}` };
+        const sseTransport = new SSEClientTransport(sseUrl, {
+            eventSourceInit: { fetch: authedFetch(authHeaders) },
+            requestInit: { headers: authHeaders },
+        });
+        const client = new Client({ name: 'kfile-mcp-bridge', version: '0.1.0' }, { capabilities: {} });
+        await client.connect(sseTransport);
+        remoteClient = client;
+        activeToken = token;
+        try {
+            const listed = await client.listTools();
+            remoteToolNames = new Set((listed.tools || []).map(tool => tool.name));
+            if (remoteToolNames.size === 0) {
+                remoteToolNames = new Set(KFILE_TOOLS.map(tool => tool.name));
+                console.error('[kfile-mcp-bridge] 远端工具列表为空，将使用本地清单。');
+            }
+            else {
+                console.error(`[kfile-mcp-bridge] 远端工具: ${Array.from(remoteToolNames).join(', ')}`);
+            }
+        }
+        catch (e) {
+            remoteToolNames = new Set(KFILE_TOOLS.map(tool => tool.name));
+            console.error(`[kfile-mcp-bridge] 远端工具列表读取失败，将使用本地清单: ${e?.message || e}`);
+        }
+        console.error('[kfile-mcp-bridge] 已连接 k-File SSE，工具可用。');
+    }
+    /** Disconnect (logout). */
+    function disconnectRemote() {
+        if (remoteClient) {
+            try {
+                remoteClient.close();
+            }
+            catch { }
+            remoteClient = null;
+            remoteToolNames = new Set();
+            activeToken = null;
+        }
+    }
+    // tools/list: ALWAYS return the full set, regardless of auth state.
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return { tools: ALL_TOOLS };
+    });
+    // tools/call: route to login/logout or forward to remote.
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (name === 'kfile_login') {
+            if (remoteClient) {
+                return { content: [{ type: 'text', text: '已登录，无需重复授权。可直接调用其他工具。' }] };
+            }
+            try {
+                let token = loadToken(host);
+                if (!token) {
+                    token = await runAuthorizationFlow(host, authHost);
+                }
+                await connectRemote(token);
+                return {
+                    content: [{ type: 'text', text: '授权成功，已连接 k-File。现在可以调用 list_my_projects / create_project 等工具了。' }],
+                };
+            }
+            catch (e) {
+                return { content: [{ type: 'text', text: `授权失败：${e?.message || e}` }], isError: true };
+            }
+        }
+        if (name === 'kfile_logout') {
+            disconnectRemote();
+            clearToken();
+            return { content: [{ type: 'text', text: '已退出登录并清除令牌。需要重新使用时请调用 kfile_login。' }] };
+        }
+        // Any other tool: requires an active connection.
+        if (!remoteClient) {
+            return {
+                content: [{ type: 'text', text: '未登录。请先调用 kfile_login 工具完成授权后再使用此工具。' }],
+                isError: true,
+            };
+        }
+        const remoteName = resolveRemoteToolName(name, remoteToolNames);
+        if (!remoteName) {
+            return {
+                content: [{ type: 'text', text: `未知工具：${name}。远端可用工具：${Array.from(remoteToolNames).join(', ')}` }],
+                isError: true,
+            };
+        }
+        // Forward to the remote k-File server (source of truth).
+        const result = await remoteClient.callTool({
+            name: remoteName,
+            arguments: injectAccessToken(args, activeToken),
+        });
+        console.error(`[kfile-mcp-bridge] 工具 ${remoteName} 返回: ${summarizeResult(result)}`);
+        return normalizeToolResult(result);
+    });
+    // Wire up stdio. All tools are listed immediately.
+    const stdio = new StdioServerTransport();
+    await server.connect(stdio);
+    // If a token is already stored, auto-connect silently.
+    const existing = loadToken(host);
+    if (existing) {
+        try {
+            await connectRemote(existing);
+        }
+        catch (e) {
+            console.error(`[kfile-mcp-bridge] 已存令牌连接失败（可能已过期）：${e?.message || e}`);
+            console.error('[kfile-mcp-bridge] 请调用 kfile_login 重新授权。');
+        }
+    }
+    else {
+        console.error('[kfile-mcp-bridge] 未授权。所有工具已列出，调用真实工具前请先 kfile_login。');
+    }
+}
+function injectAccessToken(args, token) {
+    const out = (args && typeof args === 'object' && !Array.isArray(args))
+        ? { ...args }
+        : {};
+    if (token) {
+        out.__kfile_access_token = token;
+    }
+    return out;
+}
+function resolveRemoteToolName(name, remoteToolNames) {
+    const unprefixed = name.replace(/^mcp__[^_]+__/, '');
+    if (remoteToolNames.size === 0) {
+        return unprefixed;
+    }
+    if (remoteToolNames.has(name)) {
+        return name;
+    }
+    if (remoteToolNames.has(unprefixed)) {
+        return unprefixed;
+    }
+    return null;
+}
+function normalizeToolResult(result) {
+    const content = Array.isArray(result?.content) ? result.content : [];
+    if (content.length > 0) {
+        return result;
+    }
+    if (result?.structuredContent !== undefined) {
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result.structuredContent, null, 2) }],
+            structuredContent: result.structuredContent,
+            isError: Boolean(result?.isError),
+        };
+    }
+    if (result !== undefined) {
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            isError: Boolean(result?.isError),
+        };
+    }
+    return { content: [{ type: 'text', text: 'null' }] };
+}
+function summarizeResult(result) {
+    try {
+        const text = JSON.stringify(result);
+        return text.length > 800 ? `${text.slice(0, 800)}...` : text;
+    }
+    catch {
+        return String(result);
+    }
+}
+/**
+ * fetch wrapper that injects the Authorization header, for the SSE handshake.
+ */
+function authedFetch(headers) {
+    return async (input, init) => {
+        const merged = { ...(init || {}), headers: { ...(init?.headers || {}), ...headers } };
+        return globalThis.fetch(input, merged);
+    };
+}

package/dist/index.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * kfile-mcp-bridge entry point.
+ *
+ * Starts immediately (no blocking on auth). Exposes a `kfile_login` tool the
+ * agent can call to authorize via browser. If a token is already stored, it
+ * auto-connects silently.
+ *
+ * Config (env vars):
+ *   KFILE_HOST          (optional) k-File base URL, default https://file.ksite.xin
+ *   KFILE_TOKEN         (optional) use this token directly (skip kfile_login)
+ *   KFILE_TOKEN_FILE    (optional) token file path, default ~/.kfile-mcp/token.json
+ *   KFILE_CALLBACK_PORT (optional) local callback port, default random
+ */
+import { runBridge } from './bridge.js';
+import { saveToken } from './auth.js';
+const DEFAULT_KFILE_HOST = 'https://file.ksite.xin';
+function fail(msg) {
+    console.error(`[kfile-mcp-bridge] 错误：${msg}`);
+    process.exit(1);
+}
+async function main() {
+    const host = (process.env.KFILE_HOST || DEFAULT_KFILE_HOST).trim().replace(/\/$/, '');
+    if (!/^https?:\/\//i.test(host)) {
+        fail(`KFILE_HOST 必须是 http(s) URL，收到: ${host}`);
+    }
+    // If KFILE_TOKEN is set, persist it so the bridge auto-connects on startup.
+    if (process.env.KFILE_TOKEN && process.env.KFILE_TOKEN.trim()) {
+        saveToken(process.env.KFILE_TOKEN.trim(), host);
+    }
+    try {
+        // Blocks: serves stdio until the client disconnects.
+        await runBridge({ host });
+    }
+    catch (e) {
+        const msg = e?.message || String(e);
+        fail(`桥接失败：${msg}`);
+    }
+}
+main();

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@kk-2004/kfile-mcp",
+  "version": "0.1.0",
+  "description": "stdio MCP server that bridges local MCP clients to a k-File SSE MCP server, with automatic OAuth-style token management.",
+  "license": "MIT",
+  "author": "kk",
+  "type": "module",
+  "bin": {
+    "kfile-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "kfile",
+    "k-file",
+    "sse",
+    "stdio",
+    "bridge"
+  ]
+}