@lessie/mcp-server 0.0.8 → 0.1.1

package/dist/remote.js

@@ -37,13 +37,24 @@ let cachedTools = [];
 let reconnecting = null;
 let authCompletion = null;
 let onAuthComplete = null;
+let onAuthError = null;
+let lastAuthError = null;
 /** 注册授权完成回调（用于发送 logging 通知） */
 export function setOnAuthComplete(cb) {
     onAuthComplete = cb;
 }
+/** 注册授权失败回调（用于主动通知 Agent） */
+export function setOnAuthError(cb) {
+    onAuthError = cb;
+}
 export function isRemoteConnected() {
     return client !== null;
 }
+/** 若授权流程正在进行中，等待其完成（成功或失败） */
+export async function waitForAuthCompletion() {
+    if (authCompletion)
+        await authCompletion;
+}
 /** 启动时静默连接：有缓存令牌才尝试，无令牌或连接失败则跳过 */
 export async function connectToRemote() {
     if (!REMOTE_MCP_URL)
@@ -61,37 +72,62 @@ export async function connectToRemote() {
     }
 }
 /**
- * 发起 OAuth 授权流程。
- * - 若已连接，返回 { connected: true }
- * - 若有缓存令牌未连接，尝试连接
- * - 若需要授权，直接调用 SDK auth() 获取授权 URL，不经过 transport
+ * 发起 OAuth 授权流程，返回结构化结果。
+ *
+ * 状态说明：
+ *   connected  — 已连接远程服务器
+ *   auth_url   — 生成了授权链接，等待用户浏览器完成登录
+ *   waiting    — 授权流程进行中，正在等待浏览器回调
+ *   error      — 授权流程出错（附带错误码和引导信息）
  */
 export async function initiateAuth() {
-    if (client)
-        return { connected: true };
-    if (!REMOTE_MCP_URL)
-        throw new Error("LESSIE_REMOTE_MCP_URL is not configured");
-    // 复用已有的待完成授权流程
-    if (authProvider.pendingAuthUrl) {
-        ensureAuthCompletion();
-        return { authUrl: authProvider.pendingAuthUrl };
+    if (client) {
+        const tools = await listRemoteTools();
+        return { status: "connected", toolCount: tools.length };
+    }
+    if (!REMOTE_MCP_URL) {
+        return { status: "error", errorCode: "not_configured", message: "LESSIE_REMOTE_MCP_URL is not configured" };
+    }
+    // 授权流程进行中：告诉 Agent 当前等待状态
+    if (authProvider.pendingAuthUrl && authCompletion) {
+        const elapsed = authProvider.waitingSince
+            ? Date.now() - authProvider.waitingSince
+            : 0;
+        return {
+            status: "waiting",
+            authUrl: authProvider.pendingAuthUrl,
+            elapsedMs: elapsed,
+        };
     }
+    // 上次异步错误（超时、授权拒绝等），记录后清除
+    const prevError = lastAuthError;
+    lastAuthError = null;
     const serverUrl = REMOTE_MCP_URL;
-    // 直接调用 SDK auth()：发现元数据 → 注册客户端 → 生成 PKCE → redirectToAuthorization
-    const result = await auth(authProvider, { serverUrl, fetchFn });
-    if (result === "AUTHORIZED") {
-        const url = new URL(serverUrl);
-        client = await tryConnect(url);
-        const { tools } = await client.listTools();
-        cachedTools = tools;
-        return { connected: true };
+    try {
+        await authProvider.prepareCallbackServer();
+        const result = await auth(authProvider, { serverUrl, fetchFn });
+        if (result === "AUTHORIZED") {
+            const url = new URL(serverUrl);
+            client = await tryConnect(url);
+            const { tools } = await client.listTools();
+            cachedTools = tools;
+            return { status: "connected", toolCount: tools.length };
+        }
+        const authUrl = authProvider.pendingAuthUrl;
+        if (!authUrl) {
+            return { status: "error", errorCode: "no_auth_url", message: "OAuth flow initiated but no authorization URL was generated" };
+        }
+        ensureAuthCompletion();
+        return {
+            status: "auth_url",
+            authUrl,
+            ...(prevError ? { previousError: prevError.message } : {}),
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        return { status: "error", errorCode: categorizeAuthError(error), message: error.message };
     }
-    // 'REDIRECT' — 用户需要访问授权 URL
-    const authUrl = authProvider.pendingAuthUrl;
-    if (!authUrl)
-        throw new Error("OAuth flow initiated but no authorization URL was generated");
-    ensureAuthCompletion();
-    return { authUrl };
 }
 /** 启动后台任务：等待用户浏览器回调 → 交换令牌 → 连接远程服务器 */
 function ensureAuthCompletion() {
@@ -111,6 +147,10 @@ function ensureAuthCompletion() {
         }
         catch (e) {
             authProvider.pendingAuthUrl = null;
+            const error = e instanceof Error ? e : new Error(String(e));
+            const code = categorizeAuthError(error);
+            lastAuthError = { code, message: error.message };
+            onAuthError?.({ code, message: error.message });
             console.error("[lessie] Authorization completion failed:", e);
         }
         finally {
@@ -118,6 +158,19 @@ function ensureAuthCompletion() {
         }
     })();
 }
+function categorizeAuthError(err) {
+    const msg = err.message.toLowerCase();
+    const code = err.code;
+    if (code === "EADDRINUSE" || msg.includes("already in use") || msg.includes("no available port"))
+        return "port_in_use";
+    if (msg.includes("timed out") || msg.includes("timeout"))
+        return "timeout";
+    if (msg.includes("authorization denied") || msg.includes("access_denied"))
+        return "auth_denied";
+    if (msg.includes("callback server"))
+        return "server_error";
+    return "unknown";
+}
 async function tryConnect(url) {
     const c = new Client({ name: "lessie-mcp-proxy", version: pkg.version });
     await c.connect(new StreamableHTTPClientTransport(url, { authProvider, fetch: fetchFn }));
@@ -154,14 +207,25 @@ export async function callRemoteTool(name, args) {
     try {
         return (await client.callTool({ name, arguments: args }));
     }
-    catch {
+    catch (err) {
+        if (!isAuthError(err)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `工具 ${name} 调用失败: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
         await reconnect();
         if (!client) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: `工具 ${name} 调用失败，请使用 authorize 工具重新登录。`,
+                        text: `工具 ${name} 调用失败（认证过期），请使用 authorize 工具重新登录。`,
                     },
                 ],
                 isError: true,
@@ -170,6 +234,17 @@ export async function callRemoteTool(name, args) {
         return (await client.callTool({ name, arguments: args }));
     }
 }
+function isAuthError(err) {
+    const obj = err;
+    const status = obj?.status ?? obj?.statusCode;
+    if (status === 401 || status === 403)
+        return true;
+    if (err instanceof Error) {
+        const msg = err.message.toLowerCase();
+        return msg.includes("unauthorized") || msg.includes("forbidden");
+    }
+    return false;
+}
 /**
  * 重连，关闭旧连接；并发调用共享同一个 Promise 避免竞争。
  * 静默尝试连接，若令牌已失效则 client 保持 null。

package/dist/schema.js

@@ -0,0 +1,71 @@
+/**
+ * JSON Schema (MCP Tool inputSchema) → Zod shape 转换。
+ *
+ * MCP 工具的 inputSchema 是 JSON Schema 的受限子集（type: "object"），
+ * 这里只处理 properties 中可能出现的常见类型。
+ * 不支持的类型回退为 z.unknown()。
+ */
+import { z } from "zod";
+function convertProperty(prop) {
+    const types = Array.isArray(prop.type) ? prop.type : prop.type ? [prop.type] : [];
+    const hasNull = types.includes("null");
+    const nonNullTypes = types.filter((t) => t !== "null");
+    const primaryType = nonNullTypes[0];
+    let schema;
+    if (prop.enum && Array.isArray(prop.enum)) {
+        const values = prop.enum.filter((v) => v !== null);
+        schema = values.length > 0 ? z.enum(values) : z.unknown();
+    }
+    else {
+        switch (primaryType) {
+            case "string":
+                schema = z.string();
+                break;
+            case "number":
+            case "integer":
+                schema = z.number();
+                break;
+            case "boolean":
+                schema = z.boolean();
+                break;
+            case "array":
+                schema = prop.items ? z.array(convertProperty(prop.items)) : z.array(z.unknown());
+                break;
+            case "object":
+                if (prop.properties) {
+                    schema = z.object(convertShape(prop.properties, prop.required));
+                }
+                else {
+                    schema = z.record(z.unknown());
+                }
+                break;
+            default:
+                schema = z.unknown();
+        }
+    }
+    if (hasNull)
+        schema = schema.nullable();
+    if (prop.description)
+        schema = schema.describe(prop.description);
+    return schema;
+}
+function convertShape(properties, required) {
+    const requiredSet = new Set(required ?? []);
+    const shape = {};
+    for (const [key, prop] of Object.entries(properties)) {
+        let field = convertProperty(prop);
+        if (!requiredSet.has(key))
+            field = field.optional();
+        shape[key] = field;
+    }
+    return shape;
+}
+/**
+ * 将 MCP Tool 的 inputSchema（JSON Schema object）转换为 Zod raw shape。
+ * 返回的 shape 可以直接传给 McpServer.registerTool() 的 inputSchema 参数。
+ */
+export function jsonSchemaToZodShape(inputSchema) {
+    if (!inputSchema.properties || Object.keys(inputSchema.properties).length === 0)
+        return undefined;
+    return convertShape(inputSchema.properties, inputSchema.required);
+}

package/dist/tools.js

@@ -2,63 +2,144 @@
  * 本地工具注册。
  *
  * 定义不依赖远程 MCP Server 的工具（如鉴权辅助工具）。
- * 新增工具时在 LOCAL_TOOLS 中声明元数据，在 localHandlers 中注册处理函数。
+ * 新增工具时在 registerTools() 中通过 server.registerTool() 注册。
  */
-import { authProvider } from "./auth.js";
-import { initiateAuth, listRemoteTools } from "./remote.js";
-export const LOCAL_TOOLS = [
-    {
-        name: "authorize",
-        description: "连接到远程 Lessie 服务。首次使用或授权过期时返回授权链接，用户需在浏览器中打开完成登录。已连接时返回当前状态。",
-        inputSchema: { type: "object", properties: {}, required: [], additionalProperties: false },
-    },
-    {
-        name: "get_access_token",
-        description: "获取当前有效的 OAuth access token，可用于直接调用 Lessie API。返回 token 字符串和剩余有效时间。",
-        inputSchema: { type: "object", properties: {}, required: [], additionalProperties: false },
-    },
-];
-export const localHandlers = new Map();
-localHandlers.set("authorize", async () => {
-    const result = await initiateAuth();
-    if ("connected" in result) {
-        const tools = await listRemoteTools();
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `已连接到远程 MCP 服务器，共发现 ${tools.length} 个远程工具，无需重新授权。`,
-                },
-            ],
-        };
+import { z } from "zod";
+import { initiateAuth, listRemoteTools, callRemoteTool, isRemoteConnected, waitForAuthCompletion } from "./remote.js";
+import { DEFAULT_CALLBACK_PORT, PORT_SCAN_RANGE } from "./auth.js";
+function portInUseGuidance() {
+    const endPort = DEFAULT_CALLBACK_PORT + PORT_SCAN_RANGE - 1;
+    return [
+        `授权回调服务器启动失败：端口 ${DEFAULT_CALLBACK_PORT}–${endPort} 均被占用。`,
+        "",
+        "可能原因：上次授权流程未正常关闭，或其他程序占用了这些端口。",
+        `请执行 \`lsof -i :${DEFAULT_CALLBACK_PORT}-${endPort}\` 查看占用进程并终止，然后重新调用此工具重试。`,
+    ].join("\n");
+}
+const ERROR_GUIDANCE = {
+    port_in_use: portInUseGuidance,
+    timeout: [
+        "授权超时：2 分钟内未收到浏览器回调。",
+        "",
+        "可能原因：",
+        "  - 用户未在浏览器中完成授权流程",
+        "  - 浏览器页面已关闭或未正确加载",
+        "  - 网络连接问题导致回调未到达",
+        "",
+        "请重新调用此工具生成新的授权链接，并提醒用户在浏览器中完成授权。",
+    ].join("\n"),
+    auth_denied: [
+        "用户拒绝了授权请求。",
+        "",
+        "如果用户需要使用远程功能，请重新调用此工具生成新的授权链接，",
+        "并请用户在浏览器中点击「允许」完成授权。",
+    ].join("\n"),
+    server_error: [
+        "授权回调服务器运行异常。",
+        "",
+        "请重新调用此工具重试。如果问题持续出现，可能需要检查系统网络配置或防火墙设置。",
+    ].join("\n"),
+    not_configured: [
+        "远程 MCP 服务器地址未配置。",
+        "",
+        "请检查环境变量 LESSIE_REMOTE_MCP_URL 是否正确设置。",
+    ].join("\n"),
+};
+function formatAuthResult(result) {
+    switch (result.status) {
+        case "connected":
+            return {
+                content: [{
+                        type: "text",
+                        text: `已连接到远程 MCP 服务器，共发现 ${result.toolCount} 个远程工具，无需重新授权。\n\n可通过 use_lessie 工具调用远程功能：不传 tool 参数可列出所有工具，传入 tool 和 arguments 可调用指定工具。`,
+                    }],
+            };
+        case "auth_url": {
+            const lines = [];
+            if (result.previousError) {
+                lines.push(`⚠ 上次授权尝试失败：${result.previousError}`);
+                lines.push("已自动发起新的授权流程。");
+                lines.push("");
+            }
+            lines.push("需要授权登录。请在浏览器中打开以下链接完成授权：", "", result.authUrl, "", "授权完成后，使用 use_lessie 工具调用远程功能（不传 tool 参数可查看所有可用工具）。", `如果 2 分钟内未完成授权，流程将超时，届时请重新调用此工具重试。`);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        case "waiting": {
+            const elapsedSec = Math.floor(result.elapsedMs / 1000);
+            const remainingSec = Math.max(0, 120 - elapsedSec);
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            `授权流程进行中，正在等待用户在浏览器中完成登录。`,
+                            `已等待 ${elapsedSec} 秒，剩余超时时间约 ${remainingSec} 秒。`,
+                            "",
+                            "请提醒用户在浏览器中完成授权。如果用户已关闭页面，可以重新访问以下链接：",
+                            "",
+                            result.authUrl,
+                        ].join("\n"),
+                    }],
+            };
+        }
+        case "error": {
+            const entry = ERROR_GUIDANCE[result.errorCode];
+            const guidance = typeof entry === "function" ? entry()
+                : entry ?? `授权失败：${result.message}\n\n请重新调用此工具重试。`;
+            return {
+                content: [{ type: "text", text: guidance }],
+                isError: true,
+            };
+        }
     }
-    return {
-        content: [
-            {
-                type: "text",
-                text: [
-                    "需要授权登录。请在浏览器中打开以下链接完成授权：",
-                    "",
-                    result.authUrl,
-                    "",
-                    "授权完成后，远程工具将自动可用。",
-                ].join("\n"),
-            },
-        ],
-    };
-});
-localHandlers.set("get_access_token", async () => {
-    const tokens = await authProvider.tokens();
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({
-                    access_token: tokens?.access_token,
-                    token_type: tokens?.token_type,
-                    remainingSeconds: authProvider.remainingSeconds(),
-                }, null, 2),
-            },
-        ],
-    };
-});
+}
+export function registerTools(server) {
+    server.registerTool("authorize", {
+        description: "连接到远程 Lessie 服务。首次使用或授权过期时返回授权链接，用户需在浏览器中打开完成登录。已连接时返回当前状态。授权异常时返回诊断信息和修复建议。",
+    }, async () => {
+        const result = await initiateAuth();
+        return formatAuthResult(result);
+    });
+    server.registerTool("use_lessie", {
+        description: "调用远程 Lessie 工具的统一入口。不传 tool 参数时列出所有可用的远程工具及其参数说明；传入 tool 和 arguments 时调用指定的远程工具。需先通过 authorize 完成授权。",
+        inputSchema: {
+            tool: z.string().optional().describe("要调用的远程工具名称，留空则列出所有可用工具"),
+            arguments: z.record(z.unknown()).optional().describe("传递给远程工具的参数"),
+        },
+    }, async (args) => {
+        const toolName = args.tool;
+        await waitForAuthCompletion();
+        if (!isRemoteConnected()) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "远程 MCP 服务器未连接。请先调用 authorize 工具完成授权。",
+                    }],
+                isError: true,
+            };
+        }
+        if (!toolName) {
+            const tools = await listRemoteTools();
+            if (tools.length === 0) {
+                return {
+                    content: [{ type: "text", text: "当前没有可用的远程工具。" }],
+                };
+            }
+            const listing = tools.map((t) => {
+                const params = t.inputSchema?.properties
+                    ? Object.entries(t.inputSchema.properties)
+                        .map(([k, v]) => `    - ${k} (${v.type ?? "any"}): ${v.description ?? ""}`)
+                        .join("\n")
+                    : "    （无参数）";
+                const required = t.inputSchema?.required?.join(", ") ?? "";
+                return `## ${t.name}\n${t.description ?? ""}\n  参数:\n${params}${required ? `\n  必填: ${required}` : ""}`;
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: `共 ${tools.length} 个远程工具可用：\n\n${listing.join("\n\n")}`,
+                    }],
+            };
+        }
+        return callRemoteTool(toolName, args.arguments ?? {});
+    });
+}

package/package.json

@@ -1,23 +1,27 @@
 {
   "name": "@lessie/mcp-server",
-  "version": "0.0.8",
+  "version": "0.1.1",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "lessie-mcp-server": "dist/index.js"
+    "lessie-mcp-server": "dist/cli.js"
   },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
-    "inspector": "npx @modelcontextprotocol/inspector node dist/index.js"
+    "inspector": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "mcpb:pack": "bash mcpb/pack.sh"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.10.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.2",
+    "@modelcontextprotocol/inspector": "^0.21.1",
     "@types/node": "^20.0.0",
+    "esbuild": "^0.27.4",
     "typescript": "^5.4.0"
   },
   "publishConfig": {

package/dist/server/auth.js

@@ -1,36 +0,0 @@
-import { createHash, randomBytes } from "node:crypto";
-import jwt from "jsonwebtoken";
-const JWT_SECRET = process.env.JWT_SECRET || "change-me-in-production";
-const JWT_EXPIRES_IN = 3600; // 1 hour
-// ── API Key 生成 ─────────────────────────────────────────────────────────────
-export function generateApiKey() {
-    const rawKey = "sk-live-v1-" + randomBytes(24).toString("base64url");
-    const keyHash = hashApiKey(rawKey);
-    const keyHint = rawKey.slice(0, 20) + "...";
-    return { rawKey, keyHash, keyHint };
-}
-export function hashApiKey(rawKey) {
-    return createHash("sha256").update(rawKey).digest("hex");
-}
-// ── JWT 签发 ─────────────────────────────────────────────────────────────────
-export function signJwt(payload) {
-    const token = jwt.sign(payload, JWT_SECRET, { expiresIn: JWT_EXPIRES_IN });
-    return { token, expiresIn: JWT_EXPIRES_IN };
-}
-// ── JWT 验证中间件（登录态保护） ──────────────────────────────────────────────
-export function requireAuth(req, res, next) {
-    const header = req.headers.authorization;
-    if (!header?.startsWith("Bearer ")) {
-        res.status(401).json({ error: "Missing or invalid Authorization header" });
-        return;
-    }
-    const token = header.slice(7);
-    try {
-        const decoded = jwt.verify(token, JWT_SECRET);
-        req.user = decoded;
-        next();
-    }
-    catch {
-        res.status(401).json({ error: "Invalid or expired token" });
-    }
-}

package/dist/server/db.js

@@ -1,5 +0,0 @@
-import pg from "pg";
-const pool = new pg.Pool({
-    connectionString: process.env.DATABASE_URL,
-});
-export default pool;

package/dist/server/index.js

@@ -1,11 +0,0 @@
-import express from "express";
-import apiKeysRouter from "./routes/api-keys.js";
-import authTokenRouter from "./routes/auth-token.js";
-const app = express();
-const PORT = parseInt(process.env.PORT || "3000", 10);
-app.use(express.json());
-app.use("/api-keys", apiKeysRouter);
-app.use("/auth/token", authTokenRouter);
-app.listen(PORT, () => {
-    console.log(`Server listening on port ${PORT}`);
-});

package/dist/server/routes/api-keys.js

@@ -1,78 +0,0 @@
-import { Router } from "express";
-import pool from "../db.js";
-import { generateApiKey, requireAuth } from "../auth.js";
-const router = Router();
-router.use(requireAuth);
-const MAX_KEYS_PER_USER = 10;
-// POST /api-keys — 创建 API Key
-router.post("/", async (req, res) => {
-    try {
-        const userId = req.user.sub;
-        const { name, scopes } = req.body;
-        if (!name || typeof name !== "string" || name.trim().length === 0) {
-            res.status(400).json({ error: "name is required" });
-            return;
-        }
-        const validScopes = scopes ?? ["read"];
-        const countResult = await pool.query("SELECT COUNT(*) FROM api_keys WHERE user_id = $1 AND revoked_at IS NULL", [userId]);
-        if (parseInt(countResult.rows[0].count, 10) >= MAX_KEYS_PER_USER) {
-            res.status(400).json({ error: `Maximum ${MAX_KEYS_PER_USER} active API keys allowed` });
-            return;
-        }
-        const { rawKey, keyHash, keyHint } = generateApiKey();
-        await pool.query(`INSERT INTO api_keys (user_id, name, key_hash, key_hint, scopes)
-       VALUES ($1, $2, $3, $4, $5)`, [userId, name.trim(), keyHash, keyHint, validScopes]);
-        res.status(201).json({
-            key: rawKey,
-            hint: keyHint,
-            name: name.trim(),
-            scopes: validScopes,
-        });
-    }
-    catch (err) {
-        console.error("POST /api-keys error:", err);
-        res.status(500).json({ error: "Internal server error" });
-    }
-});
-// GET /api-keys — 列出 API Keys
-router.get("/", async (req, res) => {
-    try {
-        const userId = req.user.sub;
-        const result = await pool.query(`SELECT id, name, key_hint, scopes, last_used_at, created_at
-       FROM api_keys
-       WHERE user_id = $1 AND revoked_at IS NULL
-       ORDER BY created_at DESC`, [userId]);
-        res.json(result.rows.map((row) => ({
-            id: row.id,
-            name: row.name,
-            keyHint: row.key_hint,
-            scopes: row.scopes,
-            lastUsedAt: row.last_used_at,
-            createdAt: row.created_at,
-        })));
-    }
-    catch (err) {
-        console.error("GET /api-keys error:", err);
-        res.status(500).json({ error: "Internal server error" });
-    }
-});
-// DELETE /api-keys/:id — 吊销 API Key（软删除）
-router.delete("/:id", async (req, res) => {
-    try {
-        const userId = req.user.sub;
-        const { id } = req.params;
-        const result = await pool.query(`UPDATE api_keys SET revoked_at = now()
-       WHERE id = $1 AND user_id = $2 AND revoked_at IS NULL
-       RETURNING id`, [id, userId]);
-        if (result.rowCount === 0) {
-            res.status(404).json({ error: "API key not found" });
-            return;
-        }
-        res.status(204).send();
-    }
-    catch (err) {
-        console.error("DELETE /api-keys/:id error:", err);
-        res.status(500).json({ error: "Internal server error" });
-    }
-});
-export default router;