@lessie/mcp-server 0.0.6 → 0.1.0

package/README.md

@@ -2,11 +2,70 @@
 
 将 [Lessie](https://lessie.com) 接入 Claude Desktop，通过自然语言操作你的 Lessie 账号。
 
+## 架构
+
+本地 MCP Server 同时充当**代理网关**：通过 stdio 与 Claude Desktop 通信，
+连接远程 MCP Server，将其工具合并暴露给 AI Agent。
+
+```
+Claude Desktop
+     │ stdio
+     ▼
+┌──────────────────────────────┐
+│  本地 MCP Server             │
+│                              │
+│  本地工具（authorize）        │
+│          +                   │      Streamable HTTP / SSE
+│  远程工具代理 ───────────────│──────►  远程 MCP Server
+│                              │       Authorization: Bearer <token>
+└──────────────────────────────┘
+    OAuth 2.1 Authorization Code + PKCE
+```
+
+### 鉴权机制
+
+采用 **OAuth 2.1 Authorization Code + PKCE** 流程，实现了 MCP SDK 的 `OAuthClientProvider` 接口（`src/auth.ts`）。
+
+**首次连接时：**
+
+1. MCP Client 向远程服务器发送请求，收到 401
+2. SDK 发现 OAuth 元数据（`/.well-known/oauth-authorization-server`）
+3. SDK 动态注册客户端（`POST /register`，RFC 7591）
+4. 自动打开浏览器，引导用户到 SaaS 登录页面
+5. 用户登录并授权后，浏览器重定向到本地 `http://127.0.0.1:19836/callback`
+6. SDK 用授权码交换 access_token（`POST /token`）
+7. 令牌持久化到 `~/.lessie/oauth.json`
+
+**后续连接时：**
+
+- 自动读取本地缓存的令牌，无需再次登录
+- 令牌过期时 SDK 自动触发 re-auth
+
+### 模块结构
+
+```
+src/
+├── config.ts   环境变量与静态配置（REMOTE_MCP_URL）
+├── auth.ts     OAuth 鉴权：OAuthClientProvider（Authorization Code + PKCE + 持久化）
+├── remote.ts   远程 MCP 代理客户端：连接、授权重试、工具发现、工具转发
+├── tools.ts    本地工具注册：工具元数据 + handler
+└── index.ts    入口：创建 Server、注册路由（合并本地/远程工具）、启动
+```
+
+**依赖方向**（单向，无循环）：
+
+```
+config ← auth ← tools
+  ↑        ↑
+  └─ remote ┘
+       ↑
+     index（汇总所有模块）
+```
+
 ## 前置条件
 
 - [Claude Desktop](https://claude.ai/download)
 - [Node.js](https://nodejs.org) 18+
-- Lessie API Key（登录 Lessie → 设置 → 开发者 → API Keys）
 
 ## 安装
 
@@ -17,24 +76,29 @@
 | macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
 | Windows | `%APPDATA%\Claude\claude_desktop_config.json`               |
 
-在 `mcpServers` 中添加以下内容，将 `sk-live-v1-你的Key` 替换为你的 API Key：
+添加以下配置：
 
 ```json
 {
   "mcpServers": {
     "lessie": {
       "command": "npx",
-      "args": ["-y", "lessie-mcp"],
+      "args": ["-y", "@lessie/mcp-server"],
       "env": {
-        "SAAS_BASE_URL": "https://api.lessie.com",
-        "SAAS_API_KEY": "sk-live-v1-你的Key"
+        "LESSIE_REMOTE_MCP_URL": "https://your-remote-mcp-server.com/mcp"
       }
     }
   }
 }
 ```
 
-保存后**完全退出并重新打开** Claude Desktop。
+保存后**完全退出并重新打开** Claude Desktop。首次使用时会自动打开浏览器引导登录。
+
+## 环境变量
+
+| 变量                   | 必填 | 说明                 |
+| ---------------------- | ---- | -------------------- |
+| `LESSIE_REMOTE_MCP_URL`| 否   | 远程 MCP Server 地址 |
 
 ## 验证
 
@@ -42,16 +106,13 @@
 
 > 查看我的 Lessie 账号信息
 
-## 可用工具
-
-| 工具              | 说明                                     |
-| ----------------- | ---------------------------------------- |
-| `get_account_info` | 查看当前账号详情（用户名、邮箱、状态、角色等） |
-
 ## 常见问题
 
 **工具列表中没有 lessie？**
 检查配置文件 JSON 格式是否正确，然后完全退出并重启 Claude Desktop。
 
-**报错 `Failed to exchange API key for JWT: 401`？**
-API Key 无效或已被吊销，请在 Lessie 设置页重新生成。
+**连接远程服务器失败？**
+确认 `LESSIE_REMOTE_MCP_URL` 地址正确，且远程服务器已实现 OAuth 2.1 端点。
+
+**如何重新登录？**
+删除 `~/.lessie/oauth.json` 后重启 Claude Desktop，会重新打开浏览器授权。

package/SKILL.md

@@ -1,130 +1,51 @@
 ---
-name: lessie-api
+name: lessie-mcp
 description: >-
-  调用 Lessie API 的标准流程：API Key 换取 JWT、JWT 缓存刷新、通用请求封装。
-  当需要对接 Lessie 后端、调用 Lessie API、或实现鉴权流程时使用。
+  Lessie MCP 使用指南：授权流程与工具调用。
+  当需要连接 Lessie 服务或使用 Lessie 工具时参考。
 ---
 
-# Lessie API 调用流程
+# Lessie MCP
 
-## 鉴权：API Key → JWT
-
-环境变量：
+Lessie MCP 连接远程 Lessie 服务并暴露其工具，使用前需完成 OAuth 授权。
 
-- `LESSIE_BASE_URL` — 后端地址，默认 `https://www.lessie.ai/prod-api`
-- `LESSIE_API_KEY` — 用户的 API Key（`sk-live-v1-xxx`）
+## 首次使用
 
-### 换取 JWT
-
-```typescript
-const res = await fetch(`${LESSIE_BASE_URL}/auth/token`, {
-  method: "POST",
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({ apiKey: LESSIE_API_KEY }),
-});
-const body = await res.json();
-// body 结构: { code: number, msg: string, data: { token: string, expiresIn: number } }
-const { token, expiresIn } = body.data;
-```
-
-- `expiresIn` 单位为秒（通常 3600 = 1 小时）
-- 错误统一返回 401，不区分"不存在"和"已吊销"
-
-### JWT 缓存与刷新
-
-在内存中缓存 `{ token, expiry }`，每次请求前检查：
-
-- 若缓存不存在，或距过期不足 **60 秒**，重新调用 `/auth/token` 换取
-- 进程重启后需重新获取
-
-```typescript
-interface JwtCache {
-  token: string;
-  expiry: number; // Unix timestamp (ms)
-}
-
-let jwtCache: JwtCache | null = null;
-
-async function getJwt(): Promise<string> {
-  const now = Date.now();
-  if (jwtCache && jwtCache.expiry - now > 60_000) {
-    return jwtCache.token;
-  }
-
-  const res = await fetch(`${LESSIE_BASE_URL}/auth/token`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ apiKey: LESSIE_API_KEY }),
-  });
-
-  if (!res.ok) {
-    throw new Error(`Failed to exchange API key for JWT: ${res.status}`);
-  }
-
-  const body = await res.json() as {
-    code: number; msg: string;
-    data: { token: string; expiresIn: number };
-  };
-
-  jwtCache = {
-    token: body.data.token,
-    expiry: now + body.data.expiresIn * 1000,
-  };
-  return jwtCache.token;
-}
-```
-
-## 通用请求封装
-
-```typescript
-async function api<T = unknown>(
-  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
-  path: string,
-  body?: unknown,
-): Promise<T> {
-  const token = await getJwt();
-
-  const res = await fetch(`${LESSIE_BASE_URL}${path}`, {
-    method,
-    headers: {
-      Authorization: token,
-      "Content-Type": "application/json",
-    },
-    body: body !== undefined ? JSON.stringify(body) : undefined,
-  });
-
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new Error(`API error ${res.status}${text ? `: ${text}` : ""}`);
-  }
-
-  if (res.status === 204) return undefined as T;
-
-  const wrapper = await res.json() as { code: number; msg: string; data: T };
-  return wrapper.data;
-}
-```
-
-要点：
-
-- Authorization header 直接传 token（不加 `Bearer ` 前缀）
-- 后端统一返回 `{ code, msg, data }`，`api()` 自动解包返回 `data`
-- 所有 Agent 端点路径以 `/agent/` 开头
-
-## 调用示例
-
-```typescript
-// GET 无参数
-const info = await api("GET", "/agent/account/info");
-
-// GET 带查询参数
-const params = new URLSearchParams({ page: "1", status: "active" });
-const list = await api("GET", `/agent/projects?${params}`);
-
-// POST 带请求体
-const result = await api("POST", "/agent/projects", {
-  name: "新项目",
-  description: "项目描述",
-});
-```
+首次使用时，Agent 应主动调用 `authorize` 工具发起 OAuth 授权：
 
+1. 调用 `authorize` → 获取授权链接
+2. 将授权链接展示给用户，请用户在浏览器中打开完成登录
+3. 用户完成授权后，再次调用 `authorize` 确认连接状态
+4. 授权成功后，通过 `use_lessie` 工具调用远程功能
+
+如果 `authorize` 返回已授权状态，则跳过上述流程，直接使用 `use_lessie` 或已暴露的远程工具。
+
+## 异常处理
+
+`authorize` 工具会返回详细的诊断信息和修复建议，Agent 应按照提示操作：
+
+- **端口占用**（`port_in_use`）：回调服务器端口被占用。按提示帮用户排查占用进程，然后重新调用 `authorize`。
+- **授权超时**（`timeout`）：2 分钟内未收到浏览器回调。重新调用 `authorize` 生成新链接，提醒用户及时完成授权。
+- **用户拒绝授权**（`auth_denied`）：重新调用 `authorize` 并引导用户在浏览器中允许授权。
+- **等待中**（`waiting`）：授权流程进行中。提醒用户在浏览器中完成操作，无需重新发起。
+- **其他错误**：按返回的具体建议操作，通常重新调用 `authorize` 即可重试。
+
+当收到 logging 级别的授权失败通知时，应主动告知用户并建议重新调用 `authorize`。
+
+## 使用远程工具
+
+授权完成后，通过 `use_lessie` 工具调用所有远程功能：
+
+1. 调用 `use_lessie`（不传参数）→ 列出所有可用的远程工具及参数说明
+2. 调用 `use_lessie(tool="工具名", arguments={...})` → 调用指定的远程工具
+
+如果远程工具直接出现在工具列表中（已授权的回访用户），也可以直接调用，无需通过 `use_lessie`。
+
+收到"远程 MCP 服务器未连接"错误时，说明授权已过期，需重新调用 `authorize` 完成授权。
+
+## 本地工具
+
+| 工具        | 说明                                                                                       |
+| ----------- | ------------------------------------------------------------------------------------------ |
+| `authorize` | 发起授权或检查连接状态。返回连接状态、授权链接、等待状态或错误诊断信息（含修复建议） |
+| `use_lessie`       | 远程工具统一入口。不传 `tool` 列出所有远程工具；传入 `tool` 和 `arguments` 调用指定工具 |

package/dist/auth.js

@@ -0,0 +1,256 @@
+/**
+ * OAuth 鉴权（Authorization Code + PKCE + 动态客户端注册）。
+ *
+ * 实现 MCP SDK 的 OAuthClientProvider 接口：
+ *   1. 首次连接时通过 RFC 7591 动态注册客户端（POST /register）
+ *   2. 打开浏览器引导用户到 SaaS 页面登录并授权
+ *   3. 在 localhost HTTP 服务器上接收授权码回调
+ *   4. SDK 自动用授权码交换 access_token（POST /token）
+ *
+ * 端口策略：prepareCallbackServer() 扫描端口范围并创建 HTTP 服务器占住可用端口，
+ * redirectToAuthorization() 直接在该服务器上挂载回调处理逻辑，避免竞争窗口。
+ *
+ * 客户端信息和令牌持久化到 ~/.lessie/oauth.json，进程重启后复用，
+ * 避免每次都打开浏览器。
+ */
+import { createServer } from "node:http";
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+export const DEFAULT_CALLBACK_PORT = 19836;
+export const PORT_SCAN_RANGE = 10;
+const STORAGE_DIR = join(homedir(), ".lessie");
+const STORAGE_FILE = join(STORAGE_DIR, "oauth.json");
+const CALLBACK_TIMEOUT_MS = 120_000;
+function tryListenHttp(port) {
+    return new Promise((resolve) => {
+        const srv = createServer((_req, res) => {
+            res.writeHead(404);
+            res.end();
+        });
+        srv.once("error", () => resolve(null));
+        srv.once("listening", () => resolve(srv));
+        srv.listen(port, "127.0.0.1");
+    });
+}
+// JSON 损坏时返回空对象，用户需重新授权（损坏数据无法恢复）
+function loadStorage() {
+    try {
+        return JSON.parse(readFileSync(STORAGE_FILE, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function persistStorage(data) {
+    mkdirSync(STORAGE_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(STORAGE_FILE, JSON.stringify(data, null, 2), { mode: 0o600 });
+    // writeFileSync mode 仅在创建新文件时生效；已存在文件需 chmod 确保权限正确
+    chmodSync(STORAGE_FILE, 0o600);
+}
+export class LessieAuthProvider {
+    _storage;
+    _codeVerifier = "";
+    _expectedState = "";
+    _callbackPromise = null;
+    _httpServer = null;
+    _callbackTimer = null;
+    _callbackPort;
+    /** 等待用户访问的授权 URL；授权完成后清除 */
+    pendingAuthUrl = null;
+    /** 回调服务器开始监听的时间戳，用于计算等待时长 */
+    waitingSince = null;
+    constructor() {
+        this._storage = loadStorage();
+        this._codeVerifier = this._storage.codeVerifier || "";
+        this._callbackPort = this._storage.callbackPort ?? DEFAULT_CALLBACK_PORT;
+    }
+    get callbackPort() {
+        return this._callbackPort;
+    }
+    /**
+     * 扫描端口范围，创建 HTTP 服务器占住可用端口。
+     * redirectToAuthorization 直接复用该服务器，无需释放重听。
+     * 若端口与上次注册时不同，自动清除客户端信息以触发重新注册。
+     */
+    async prepareCallbackServer() {
+        if (this._httpServer?.listening)
+            return;
+        this._cleanupServer();
+        for (let offset = 0; offset < PORT_SCAN_RANGE; offset++) {
+            const port = DEFAULT_CALLBACK_PORT + offset;
+            const server = await tryListenHttp(port);
+            if (server) {
+                if (this._storage.clientInfo && this._storage.callbackPort != null && this._storage.callbackPort !== port) {
+                    delete this._storage.clientInfo;
+                }
+                this._httpServer = server;
+                this._callbackPort = port;
+                this._storage.callbackPort = port;
+                persistStorage(this._storage);
+                return;
+            }
+        }
+        throw new Error(`No available port found in range ${DEFAULT_CALLBACK_PORT}–${DEFAULT_CALLBACK_PORT + PORT_SCAN_RANGE - 1}`);
+    }
+    get redirectUrl() {
+        return `http://127.0.0.1:${this._callbackPort}/callback`;
+    }
+    get clientMetadata() {
+        return {
+            redirect_uris: [this.redirectUrl],
+            grant_types: ["authorization_code"],
+            response_types: ["code"],
+            client_name: "Lessie MCP",
+            token_endpoint_auth_method: "client_secret_basic",
+        };
+    }
+    clientInformation() {
+        return this._storage.clientInfo;
+    }
+    async saveClientInformation(info) {
+        this._storage.clientInfo = info;
+        persistStorage(this._storage);
+    }
+    async tokens() {
+        return this._storage.tokens;
+    }
+    async saveTokens(tokens) {
+        this._storage.tokens = tokens;
+        this._storage.tokensSavedAt = Date.now();
+        delete this._storage.codeVerifier;
+        this._codeVerifier = "";
+        persistStorage(this._storage);
+    }
+    /** 当前 access_token 的剩余有效秒数（基于本地时钟估算） */
+    remainingSeconds() {
+        if (!this._storage.tokens?.expires_in || !this._storage.tokensSavedAt)
+            return 0;
+        const elapsed = (Date.now() - this._storage.tokensSavedAt) / 1000;
+        return Math.max(0, Math.floor(this._storage.tokens.expires_in - elapsed));
+    }
+    /**
+     * SDK 在需要用户授权时调用此方法。
+     * 在 prepareCallbackServer() 已监听的 HTTP 服务器上挂载回调处理逻辑，等待浏览器回调。
+     *
+     * 必须先调用 prepareCallbackServer()，否则抛出异常。
+     */
+    async redirectToAuthorization(url) {
+        if (!this._httpServer?.listening) {
+            throw new Error("No listening server — prepareCallbackServer() must be called before redirectToAuthorization()");
+        }
+        this._expectedState = url.searchParams.get("state") || "";
+        this.waitingSince = null;
+        let resolveCode;
+        let rejectCode;
+        this._callbackPromise = new Promise((resolve, reject) => {
+            resolveCode = resolve;
+            rejectCode = reject;
+        });
+        this._httpServer.removeAllListeners("request");
+        this._httpServer.removeAllListeners("error");
+        this._httpServer.on("error", (err) => {
+            this._cleanupServer();
+            rejectCode(new Error(`Callback server error: ${err.message}`));
+        });
+        this._httpServer.on("request", (req, res) => {
+            const reqUrl = new URL(req.url, `http://127.0.0.1:${this._callbackPort}`);
+            if (reqUrl.pathname !== "/callback") {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            if (this._expectedState) {
+                const callbackState = reqUrl.searchParams.get("state");
+                if (callbackState !== this._expectedState) {
+                    res.writeHead(403, { "Content-Type": "text/plain" });
+                    res.end("Invalid state parameter");
+                    return;
+                }
+            }
+            const code = reqUrl.searchParams.get("code");
+            if (code) {
+                resolveCode(code);
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end("<!DOCTYPE html><html><body>" +
+                    "<h1>Authorization Successful</h1>" +
+                    "<p>You may close this page and return to your agent.</p>" +
+                    "</body></html>");
+                this._cleanupServer();
+            }
+            else {
+                const error = reqUrl.searchParams.get("error") ?? "unknown_error";
+                rejectCode(new Error(`Authorization denied: ${error}`));
+                res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                res.end("<!DOCTYPE html><html><body>" +
+                    "<h1>Authorization Failed</h1>" +
+                    `<p>${escapeHtml(error)}</p>` +
+                    "</body></html>");
+                this._cleanupServer();
+            }
+        });
+        this.waitingSince = Date.now();
+        this._callbackTimer = setTimeout(() => {
+            this._cleanupServer();
+            rejectCode(new Error("Authorization timed out — no callback received within 2 minutes"));
+        }, CALLBACK_TIMEOUT_MS);
+        this.pendingAuthUrl = url.toString();
+    }
+    _cleanupServer() {
+        if (this._callbackTimer) {
+            clearTimeout(this._callbackTimer);
+            this._callbackTimer = null;
+        }
+        if (this._httpServer) {
+            const server = this._httpServer;
+            this._httpServer = null;
+            this.waitingSince = null;
+            setTimeout(() => server.close(), 500);
+        }
+    }
+    /**
+     * 等待用户在浏览器中完成授权后回调，返回授权码。
+     * 必须在 redirectToAuthorization 之后调用。
+     */
+    async waitForCallback() {
+        if (!this._callbackPromise)
+            throw new Error("No pending authorization flow");
+        return this._callbackPromise;
+    }
+    async saveCodeVerifier(codeVerifier) {
+        this._codeVerifier = codeVerifier;
+        this._storage.codeVerifier = codeVerifier;
+        persistStorage(this._storage);
+    }
+    async codeVerifier() {
+        return this._codeVerifier || this._storage.codeVerifier || "";
+    }
+    async saveDiscoveryState(state) {
+        this._storage.discoveryState = state;
+        persistStorage(this._storage);
+    }
+    discoveryState() {
+        return this._storage.discoveryState;
+    }
+    async invalidateCredentials(scope) {
+        if (scope === "all" || scope === "client") {
+            delete this._storage.clientInfo;
+        }
+        if (scope === "all" || scope === "tokens") {
+            delete this._storage.tokens;
+            delete this._storage.tokensSavedAt;
+        }
+        if (scope === "all" || scope === "verifier") {
+            this._codeVerifier = "";
+        }
+        if (scope === "all" || scope === "discovery") {
+            delete this._storage.discoveryState;
+        }
+        persistStorage(this._storage);
+    }
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+/** 全局单例，供 remote / tools 共享 */
+export const authProvider = new LessieAuthProvider();

package/dist/config.js

@@ -0,0 +1,29 @@
+/**
+ * 环境变量与静态配置。
+ *
+ * 所有外部可配置项在此集中读取，其余模块通过 import 获取，
+ * 避免散落的 process.env 访问。
+ */
+import { readFileSync } from "node:fs";
+function readPkgVersion() {
+    try {
+        const raw = readFileSync(new URL("../package.json", import.meta.url), "utf-8");
+        return JSON.parse(raw).version;
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export const pkg = { version: readPkgVersion() };
+/** 远程 MCP Server 地址 */
+export const REMOTE_MCP_URL = process.env.LESSIE_REMOTE_MCP_URL || "https://www.lessie.ai/mcp-server/mcp";
+/** 读取 SKILL.md 作为 MCP instructions，跳过 YAML front-matter */
+export function loadInstructions() {
+    try {
+        const raw = readFileSync(new URL("../SKILL.md", import.meta.url), "utf-8");
+        return raw.replace(/^---[\s\S]*?---\n*/, "").trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}