@lessie/mcp-server 0.0.5 → 0.0.8

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             │
+│                              │
+│  本地工具（get_access_token） │
+│          +                   │      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

@@ -0,0 +1,62 @@
+---
+name: lessie-mcp
+description: >-
+  Lessie MCP 代理网关：OAuth 鉴权、远程工具代理。
+  当需要理解本项目结构、鉴权机制或使用 Lessie 工具时使用。
+---
+
+# Lessie MCP
+
+Lessie MCP 是一个代理网关，连接远程 Lessie 服务并暴露其工具。使用前需要完成 OAuth 授权。
+
+## 快速开始
+
+### 1. 授权连接
+
+首次使用时，调用 `authorize` 工具。如果需要登录，它会返回一个授权链接：
+
+1. 调用 `authorize`
+2. 将返回的授权链接展示给用户，请用户在浏览器中打开
+3. 用户在浏览器中完成登录授权
+4. 授权完成后，远程工具自动可用，无需再次调用 `authorize`
+
+已授权时调用 `authorize` 会直接返回当前连接状态和可用工具数量。
+
+### 2. 使用远程工具
+
+授权完成后，远程工具会自动出现在工具列表中，直接调用即可。
+
+如果调用远程工具时收到"请先使用 authorize 工具"的错误提示，说明授权已过期，需要重新执行上述授权流程。
+
+## 本地工具
+
+| 工具               | 说明                                                               |
+| ------------------ | ------------------------------------------------------------------ |
+| `authorize`        | 发起授权或检查连接状态。未授权时返回授权链接，已连接时返回状态信息 |
+| `get_access_token` | 获取当前 OAuth access token 及剩余有效时间                         |
+
+## 项目架构（开发参考）
+
+### 鉴权：OAuth Authorization Code + PKCE
+
+`src/auth.ts` 实现 `OAuthClientProvider` 接口：
+
+- 令牌和客户端信息持久化到 `~/.lessie/oauth.json`
+- `redirectToAuthorization(url)` 存储授权 URL（不自动打开浏览器）
+- `waitForCallback()` 在 `127.0.0.1:19836` 监听回调，等待用户完成授权
+
+### 连接策略
+
+`src/remote.ts` 管理远程连接：
+
+- `connectToRemote()` — 启动时静默尝试（用缓存 token），未授权不阻塞
+- `initiateAuth()` — 发起 OAuth 流程，返回授权 URL，后台等待回调自动完成连接
+- `callRemoteTool()` — 授权进行中自动等待；未连接时返回错误引导用户调用 `authorize`
+
+传输层优先使用 Streamable HTTP，不可用时自动降级到 SSE。
+
+### 环境变量
+
+| 变量                    | 必填 | 说明                 |
+| ----------------------- | ---- | -------------------- |
+| `LESSIE_REMOTE_MCP_URL` | 否   | 远程 MCP Server 地址 |

package/dist/auth.js

@@ -0,0 +1,217 @@
+/**
+ * OAuth 鉴权（Authorization Code + PKCE + 动态客户端注册）。
+ *
+ * 实现 MCP SDK 的 OAuthClientProvider 接口：
+ *   1. 首次连接时通过 RFC 7591 动态注册客户端（POST /register）
+ *   2. 打开浏览器引导用户到 SaaS 页面登录并授权
+ *   3. 在 localhost 临时 HTTP 服务器上接收授权码回调
+ *   4. SDK 自动用授权码交换 access_token（POST /token）
+ *
+ * 客户端信息和令牌持久化到 ~/.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";
+import { OAUTH_SERVER_URL, OAUTH_AUTHORIZATION_ENDPOINT, OAUTH_TOKEN_ENDPOINT, OAUTH_REGISTRATION_ENDPOINT, REMOTE_MCP_URL, } from "./config.js";
+const CALLBACK_PORT = 19836;
+const REDIRECT_URL = `http://127.0.0.1:${CALLBACK_PORT}/callback`;
+const STORAGE_DIR = join(homedir(), ".lessie");
+const STORAGE_FILE = join(STORAGE_DIR, "oauth.json");
+const CALLBACK_TIMEOUT_MS = 120_000;
+// 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 = "";
+    _callbackPromise = null;
+    _httpServer = null;
+    _envDiscoveryState;
+    /** 等待用户访问的授权 URL；授权完成后清除 */
+    pendingAuthUrl = null;
+    constructor() {
+        this._storage = loadStorage();
+        this._envDiscoveryState = buildEnvDiscoveryState();
+    }
+    get redirectUrl() {
+        return REDIRECT_URL;
+    }
+    get clientMetadata() {
+        return {
+            redirect_uris: [REDIRECT_URL],
+            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();
+        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 在需要用户授权时调用此方法。
+     * 启动 localhost 临时 HTTP 服务器接收回调，然后打开浏览器。
+     */
+    async redirectToAuthorization(url) {
+        if (this._httpServer) {
+            this._httpServer.close();
+            this._httpServer = null;
+        }
+        this._callbackPromise = new Promise((resolve, reject) => {
+            let timer;
+            const cleanup = () => {
+                clearTimeout(timer);
+                this._httpServer = null;
+                setTimeout(() => server.close(), 500);
+            };
+            const server = createServer((req, res) => {
+                const reqUrl = new URL(req.url, `http://127.0.0.1:${CALLBACK_PORT}`);
+                if (reqUrl.pathname !== "/callback") {
+                    res.writeHead(404);
+                    res.end();
+                    return;
+                }
+                const code = reqUrl.searchParams.get("code");
+                if (code) {
+                    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                    res.end("<!DOCTYPE html><html><body>" +
+                        "<h1>授权成功</h1><p>可以关闭此页面，回到 Claude Desktop 继续使用。</p>" +
+                        "</body></html>");
+                    cleanup();
+                    resolve(code);
+                }
+                else {
+                    const error = reqUrl.searchParams.get("error") ?? "unknown_error";
+                    res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                    res.end(`<!DOCTYPE html><html><body><h1>授权失败</h1><p>${escapeHtml(error)}</p></body></html>`);
+                    cleanup();
+                    reject(new Error(`Authorization denied: ${error}`));
+                }
+            });
+            server.on("error", (err) => {
+                this._httpServer = null;
+                const msg = err.code === "EADDRINUSE"
+                    ? `Port ${CALLBACK_PORT} is already in use`
+                    : `Callback server error: ${err.message}`;
+                reject(new Error(msg));
+            });
+            server.listen(CALLBACK_PORT, "127.0.0.1");
+            this._httpServer = server;
+            timer = setTimeout(() => {
+                this._httpServer = null;
+                server.close();
+                reject(new Error("Authorization timed out — no callback received within 2 minutes"));
+            }, CALLBACK_TIMEOUT_MS);
+        });
+        this.pendingAuthUrl = url.toString();
+    }
+    /**
+     * 等待用户在浏览器中完成授权后回调，返回授权码。
+     * 必须在 redirectToAuthorization 之后调用。
+     */
+    async waitForCallback() {
+        if (!this._callbackPromise)
+            throw new Error("No pending authorization flow");
+        return this._callbackPromise;
+    }
+    async saveCodeVerifier(codeVerifier) {
+        this._codeVerifier = codeVerifier;
+    }
+    async codeVerifier() {
+        return this._codeVerifier;
+    }
+    async saveDiscoveryState(state) {
+        this._storage.discoveryState = state;
+        persistStorage(this._storage);
+    }
+    discoveryState() {
+        return this._envDiscoveryState ?? 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;");
+}
+/**
+ * 从环境变量构建 OAuthDiscoveryState。
+ * 至少需要配置 authorization_endpoint 和 token_endpoint 才会生效；
+ * 未配置则返回 undefined，由 SDK 自动发现。
+ */
+function buildEnvDiscoveryState() {
+    if (!OAUTH_AUTHORIZATION_ENDPOINT || !OAUTH_TOKEN_ENDPOINT)
+        return undefined;
+    const authorizationServerUrl = OAUTH_SERVER_URL || REMOTE_MCP_URL;
+    if (!authorizationServerUrl)
+        return undefined;
+    return {
+        authorizationServerUrl,
+        authorizationServerMetadata: {
+            issuer: authorizationServerUrl,
+            authorization_endpoint: OAUTH_AUTHORIZATION_ENDPOINT,
+            token_endpoint: OAUTH_TOKEN_ENDPOINT,
+            registration_endpoint: OAUTH_REGISTRATION_ENDPOINT,
+            response_types_supported: ["code"],
+            grant_types_supported: ["authorization_code"],
+            code_challenge_methods_supported: ["S256"],
+            token_endpoint_auth_methods_supported: [
+                "client_secret_basic",
+                "client_secret_post",
+                "none",
+            ],
+        },
+        resourceMetadata: {
+            resource: REMOTE_MCP_URL,
+            authorization_servers: [authorizationServerUrl],
+        },
+    };
+}
+/** 全局单例，供 remote / tools 共享 */
+export const authProvider = new LessieAuthProvider();

package/dist/config.js

@@ -0,0 +1,30 @@
+/**
+ * 环境变量与静态配置。
+ *
+ * 所有外部可配置项在此集中读取，其余模块通过 import 获取，
+ * 避免散落的 process.env 访问。
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+export const pkg = require("../package.json");
+/** 远程 MCP Server 地址 */
+export const REMOTE_MCP_URL = process.env.LESSIE_REMOTE_MCP_URL || "https://s6.jennie.im/mcp-server/mcp";
+/**
+ * OAuth 端点配置（可选）。
+ * 未设置时 SDK 通过 RFC 8414 / RFC 9728 自动发现。
+ */
+export const OAUTH_SERVER_URL = process.env.LESSIE_OAUTH_SERVER_URL || "https://s1.jennie.im/sit-api/oauth";
+export const OAUTH_AUTHORIZATION_ENDPOINT = process.env.LESSIE_OAUTH_AUTHORIZATION_ENDPOINT || "https://s1.jennie.im/sit-api/oauth/authorize";
+export const OAUTH_TOKEN_ENDPOINT = process.env.LESSIE_OAUTH_TOKEN_ENDPOINT || "https://s1.jennie.im/sit-api/oauth/token";
+export const OAUTH_REGISTRATION_ENDPOINT = process.env.LESSIE_OAUTH_REGISTRATION_ENDPOINT || "https://s1.jennie.im/sit-api/oauth/register";
+/** 读取 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;
+    }
+}

package/dist/index.js

@@ -1,96 +1,71 @@
 #!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createRequire } from "node:module";
-const require = createRequire(import.meta.url);
-const pkg = require("../package.json");
-// ── 环境变量 ──────────────────────────────────────────────────────────────────
-const BASE_URL = process.env.LESSIE_BASE_URL || 'https://www.lessie.ai/prod-api';
-const API_KEY = process.env.LESSIE_API_KEY;
-if (!BASE_URL) {
-    console.error("Error: LESSIE_BASE_URL is not set");
-    process.exit(1);
-}
-if (!API_KEY) {
-    console.error("Error: LESSIE_API_KEY is not set");
-    process.exit(1);
-}
-let jwtCache = null;
 /**
- * 获取有效的 JWT token。
- * 若缓存不存在或距过期不足 60 秒，则重新向 /auth/token 换取。
+ * 入口：创建 MCP Server，注册请求路由，启动 stdio 传输。
+ *
+ * 使用低级 Server 而非 McpServer，以便手动控制 tools/list 和 tools/call 路由，
+ * 将本地工具与远程代理工具合并到同一个工具列表中返回。
+ *
+ * 工具路由策略：
+ *   tools/list  → 合并本地工具 + 远程工具
+ *   tools/call  → 先匹配本地 handler，未命中则转发到远程 MCP Server
  */
-async function getJwt() {
-    const now = Date.now();
-    const REFRESH_BEFORE_MS = 60 * 1000;
-    if (jwtCache && jwtCache.expiry - now > REFRESH_BEFORE_MS) {
-        return jwtCache.token;
-    }
-    const res = await fetch(`${BASE_URL}/auth/token`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ apiKey: API_KEY }),
-    });
-    if (!res.ok) {
-        throw new Error(`Failed to exchange API key for JWT: ${res.status} ${res.statusText} ${BASE_URL}/auth/token`);
-    }
-    const body = (await res.json());
-    if (!body.data?.token) {
-        throw new Error(`/auth/token response missing data.token. Got: ${JSON.stringify(body)}`);
-    }
-    jwtCache = {
-        token: body.data.token,
-        expiry: now + body.data.expiresIn * 1000,
-    };
-    return jwtCache.token;
-}
-async function api(method, path, body) {
-    const token = await getJwt();
-    const res = await fetch(`${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} ${res.statusText}${text ? `: ${text}` : ""}`);
-    }
-    if (res.status === 204)
-        return undefined;
-    const wrapper = (await res.json());
-    return wrapper.data;
-}
-// ── 工具结果辅助函数 ───────────────────────────────────────────────────────────
-function textResult(data) {
-    return {
-        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
-    };
-}
-// ── MCP Server ────────────────────────────────────────────────────────────────
-const server = new McpServer({
-    name: "lessie-mcp",
-    version: pkg.version,
+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 { REMOTE_MCP_URL, pkg, loadInstructions } from "./config.js";
+import { connectToRemote, listRemoteTools, callRemoteTool, isRemoteConnected, setOnAuthComplete } from "./remote.js";
+import { LOCAL_TOOLS, localHandlers } from "./tools.js";
+const server = new Server({ name: "lessie-mcp", version: pkg.version }, {
+    capabilities: { tools: {} },
+    instructions: loadInstructions(),
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const remoteTools = await listRemoteTools();
+    return { tools: [...LOCAL_TOOLS, ...remoteTools] };
 });
-// ── 工具定义 ──────────────────────────────────────────────────────────────────
-// 命名规范：下划线分隔，动词开头（如 list_xxx、get_xxx、create_xxx）。
-// 写入类工具在 description 中注明"执行前请向用户确认"。
-// 账号信息
-server.tool("get_account_info", "查看当前 Lessie 账号的详细信息，包括用户名、邮箱、账号状态、角色、邀请码等。", {}, async () => {
-    const data = await api("GET", "/agent/account/info");
-    return textResult(data);
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const handler = localHandlers.get(name);
+    if (handler)
+        return handler(args ?? {});
+    return callRemoteTool(name, args);
 });
 // ── 启动 ──────────────────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);
-await getJwt();
-server.sendLoggingMessage({
-    level: "info",
-    logger: "lessie",
-    data: "Token acquired successfully",
+setOnAuthComplete((toolCount) => {
+    server.sendLoggingMessage({
+        level: "info",
+        logger: "lessie",
+        data: `Authorization successful. Connected to remote MCP server. Discovered ${toolCount} tools.`,
+    });
+    server.sendToolListChanged();
 });
+try {
+    await connectToRemote();
+    if (isRemoteConnected()) {
+        const remoteTools = await listRemoteTools();
+        server.sendLoggingMessage({
+            level: "info",
+            logger: "lessie",
+            data: `Connected to remote MCP server (${REMOTE_MCP_URL}). Discovered ${remoteTools.length} tools.`,
+        });
+    }
+    else if (REMOTE_MCP_URL) {
+        server.sendLoggingMessage({
+            level: "warning",
+            logger: "lessie",
+            data: "Remote MCP server requires authorization. Use the 'authorize' tool to connect.",
+        });
+    }
+}
+catch (err) {
+    server.sendLoggingMessage({
+        level: "error",
+        logger: "lessie",
+        data: `Failed to connect to remote MCP server: ${err}`,
+    });
+}
 server.sendLoggingMessage({
     level: "info",
     logger: "lessie",

package/dist/remote.js

@@ -0,0 +1,192 @@
+/**
+ * 远程 MCP 代理客户端。
+ *
+ * 以 MCP Client 身份连接远程 MCP Server，发现其工具并代理调用。
+ * 传输层使用 Streamable HTTP。
+ *
+ * 鉴权策略：
+ *   1. 启动时检查本地缓存令牌，有才尝试连接，无则跳过
+ *   2. 用户通过 authorize 工具触发 OAuth 流程（直接调用 SDK auth()）
+ *   3. 用户在浏览器完成登录后，后台自动交换令牌并连接
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { auth } from "@modelcontextprotocol/sdk/client/auth.js";
+import { REMOTE_MCP_URL, pkg } from "./config.js";
+import { authProvider } from "./auth.js";
+const DEBUG = !!process.env.DEBUG_OAUTH;
+const debugFetch = async (input, init) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    const method = init?.method ?? "GET";
+    console.error(`[OAuth] --> ${method} ${url}`);
+    if (init?.headers)
+        console.error(`[OAuth]     headers:`, JSON.stringify(init.headers));
+    if (init?.body)
+        console.error(`[OAuth]     body:`, String(init.body));
+    const res = await fetch(input, init);
+    const cloned = res.clone();
+    const text = await cloned.text().catch(() => "");
+    console.error(`[OAuth] <-- ${res.status} ${res.statusText}`);
+    if (text)
+        console.error(`[OAuth]     response:`, text.slice(0, 2000));
+    return res;
+};
+const fetchFn = DEBUG ? debugFetch : undefined;
+let client = null;
+let cachedTools = [];
+let reconnecting = null;
+let authCompletion = null;
+let onAuthComplete = null;
+/** 注册授权完成回调（用于发送 logging 通知） */
+export function setOnAuthComplete(cb) {
+    onAuthComplete = cb;
+}
+export function isRemoteConnected() {
+    return client !== null;
+}
+/** 启动时静默连接：有缓存令牌才尝试，无令牌或连接失败则跳过 */
+export async function connectToRemote() {
+    if (!REMOTE_MCP_URL)
+        return;
+    if (!(await authProvider.tokens()))
+        return;
+    const url = new URL(REMOTE_MCP_URL);
+    try {
+        client = await tryConnect(url);
+        const { tools } = await client.listTools();
+        cachedTools = tools;
+    }
+    catch {
+        client = null;
+    }
+}
+/**
+ * 发起 OAuth 授权流程。
+ * - 若已连接，返回 { connected: true }
+ * - 若有缓存令牌未连接，尝试连接
+ * - 若需要授权，直接调用 SDK auth() 获取授权 URL，不经过 transport
+ */
+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 };
+    }
+    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 };
+    }
+    // '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() {
+    if (authCompletion)
+        return;
+    const serverUrl = REMOTE_MCP_URL;
+    const url = new URL(serverUrl);
+    authCompletion = (async () => {
+        try {
+            const code = await authProvider.waitForCallback();
+            await auth(authProvider, { serverUrl, authorizationCode: code, fetchFn });
+            client = await tryConnect(url);
+            const { tools } = await client.listTools();
+            cachedTools = tools;
+            authProvider.pendingAuthUrl = null;
+            onAuthComplete?.(cachedTools.length);
+        }
+        catch (e) {
+            authProvider.pendingAuthUrl = null;
+            console.error("[lessie] Authorization completion failed:", e);
+        }
+        finally {
+            authCompletion = null;
+        }
+    })();
+}
+async function tryConnect(url) {
+    const c = new Client({ name: "lessie-mcp-proxy", version: pkg.version });
+    await c.connect(new StreamableHTTPClientTransport(url, { authProvider, fetch: fetchFn }));
+    return c;
+}
+/** 获取远程工具列表；连接可用时实时刷新，否则返回缓存 */
+export async function listRemoteTools() {
+    if (!client)
+        return cachedTools;
+    try {
+        const { tools } = await client.listTools();
+        cachedTools = tools;
+    }
+    catch (err) {
+        console.warn("[lessie] Failed to refresh remote tools, using cache:", String(err));
+    }
+    return cachedTools;
+}
+/** 转发工具调用到远程 MCP Server；失败时引导用户重新授权 */
+export async function callRemoteTool(name, args) {
+    if (authCompletion)
+        await authCompletion;
+    if (!client) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `无法调用工具 ${name}：远程 MCP 服务器未连接。请先使用 authorize 工具完成登录授权。`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    try {
+        return (await client.callTool({ name, arguments: args }));
+    }
+    catch {
+        await reconnect();
+        if (!client) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `工具 ${name} 调用失败，请使用 authorize 工具重新登录。`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return (await client.callTool({ name, arguments: args }));
+    }
+}
+/**
+ * 重连，关闭旧连接；并发调用共享同一个 Promise 避免竞争。
+ * 静默尝试连接，若令牌已失效则 client 保持 null。
+ */
+async function reconnect() {
+    if (reconnecting)
+        return reconnecting;
+    reconnecting = (async () => {
+        try {
+            const old = client;
+            client = null;
+            await old?.close().catch(() => { });
+            await connectToRemote();
+        }
+        finally {
+            reconnecting = null;
+        }
+    })();
+    return reconnecting;
+}

package/dist/tools.js

@@ -0,0 +1,64 @@
+/**
+ * 本地工具注册。
+ *
+ * 定义不依赖远程 MCP Server 的工具（如鉴权辅助工具）。
+ * 新增工具时在 LOCAL_TOOLS 中声明元数据，在 localHandlers 中注册处理函数。
+ */
+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} 个远程工具，无需重新授权。`,
+                },
+            ],
+        };
+    }
+    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),
+            },
+        ],
+    };
+});

package/docs/oauth-client-guide.md

@@ -0,0 +1,354 @@
+# Lessie MCP OAuth 2.1 接入指南
+
+本文档面向 MCP Client 开发者，描述如何通过 OAuth 2.1 授权流程获取 access_token 并调用 Lessie MCP 接口。
+
+---
+
+## 授权流程概览
+
+```
+MCP Client                                    Lessie 授权服务器
+    │                                               │
+    │ ① POST /mcp (无 token)                        │
+    │──────────────────────────────────────────────►│
+    │◄──────────────── 401 Unauthorized ────────────│
+    │                                               │
+    │ ② GET /.well-known/oauth-authorization-server │
+    │──────────────────────────────────────────────►│
+    │◄──── 元数据 JSON (各端点地址) ─────────────────│
+    │                                               │
+    │ ③ POST /register (动态客户端注册)              │
+    │──────────────────────────────────────────────►│
+    │◄──── { client_id, client_secret }  ───────────│
+    │                                               │
+    │ ④ 打开浏览器 → /authorize?...                 │
+    │          用户登录 → 点击"授权"                 │
+    │◄──── 302 → callback?code=xxx&state=yyy ───────│
+    │                                               │
+    │ ⑤ POST /token (code + code_verifier)          │
+    │──────────────────────────────────────────────►│
+    │◄──── { access_token, token_type, expires_in } │
+    │                                               │
+    │ ⑥ POST /mcp (Authorization: Bearer xxx)       │
+    │──────────────────────────────────────────────►│
+    │◄──── 业务数据 ────────────────────────────────│
+```
+
+> 本服务实现了 OAuth 2.1 + PKCE (S256) 授权码流程，遵循 RFC 8414、RFC 7591、RFC 7636 标准。
+
+---
+
+## 基础地址
+
+| 环境 | Base URL |
+|------|----------|
+| 生产 | `https://www.lessie.ai/prod-api` |
+
+---
+
+## 1. 授权服务器元数据发现
+
+> RFC 8414
+
+**请求**
+
+```
+GET /.well-known/oauth-authorization-server
+```
+
+**响应 200**
+
+```json
+{
+  "issuer": "https://www.lessie.ai/prod-api",
+  "authorization_endpoint": "https://www.lessie.ai/prod-api/authorize",
+  "token_endpoint": "https://www.lessie.ai/prod-api/token",
+  "registration_endpoint": "https://www.lessie.ai/prod-api/register",
+  "response_types_supported": ["code"],
+  "grant_types_supported": ["authorization_code"],
+  "code_challenge_methods_supported": ["S256"],
+  "token_endpoint_auth_methods_supported": [
+    "client_secret_basic",
+    "client_secret_post",
+    "none"
+  ],
+  "scopes_supported": ["read", "write"]
+}
+```
+
+客户端应通过此端点**动态发现**各接口地址，不要硬编码。
+
+---
+
+## 2. 动态客户端注册
+
+> RFC 7591 — 首次连接时调用，无需用户操作
+
+**请求**
+
+```
+POST /register
+Content-Type: application/json
+```
+
+```json
+{
+  "redirect_uris": ["http://127.0.0.1:3000/callback"],
+  "grant_types": ["authorization_code"],
+  "response_types": ["code"],
+  "client_name": "My MCP Client",
+  "token_endpoint_auth_method": "client_secret_basic"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `redirect_uris` | string[] | 是 | 回调地址列表，仅允许 loopback（`127.0.0.1` / `localhost` / `[::1]`）或 `https` |
+| `grant_types` | string[] | 否 | 默认 `["authorization_code"]` |
+| `response_types` | string[] | 否 | 默认 `["code"]` |
+| `client_name` | string | 否 | 默认 `"MCP Client"`，显示在授权页面上 |
+| `token_endpoint_auth_method` | string | 否 | `"client_secret_basic"`（默认）、`"client_secret_post"` 或 `"none"`（public client） |
+
+**响应 201 Created**
+
+```json
+{
+  "client_id": "lessie-aBcDeFgHiJkLmNoP",
+  "client_secret": "sk-xXxXxXxXxXxXxXxX...",
+  "client_name": "My MCP Client",
+  "redirect_uris": ["http://127.0.0.1:3000/callback"],
+  "grant_types": ["authorization_code"]
+}
+```
+
+> **重要**：`client_secret` 仅在注册响应中返回一次，请安全存储。后续无法再次获取。
+
+**错误响应**
+
+| HTTP 状态码 | error | 说明 |
+|-------------|-------|------|
+| 400 | `invalid_redirect_uri` | redirect_uri 格式不合法（必须是 loopback 或 https） |
+| 403 | `client_limit_exceeded` | 客户端注册数量已达上限 |
+| 429 | `too_many_requests` | 注册频率超限，请稍后重试 |
+
+---
+
+## 3. 授权请求
+
+客户端在本地生成 PKCE 参数后，打开浏览器跳转到授权页面。
+
+### 3.1 生成 PKCE 参数
+
+```
+code_verifier  = 随机生成 43-128 字符的 URL-safe 字符串
+code_challenge = BASE64URL(SHA256(code_verifier))
+```
+
+### 3.2 打开浏览器
+
+```
+GET /authorize
+    ?response_type=code
+    &client_id={client_id}
+    &redirect_uri={redirect_uri}
+    &code_challenge={code_challenge}
+    &code_challenge_method=S256
+    &state={随机字符串}
+    &scope=read write
+```
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `response_type` | 是 | 固定为 `code` |
+| `client_id` | 是 | 注册时获取的 client_id |
+| `redirect_uri` | 是 | 必须与注册时提交的地址匹配（loopback 忽略端口） |
+| `code_challenge` | 是 | PKCE challenge (S256) |
+| `code_challenge_method` | 是 | 固定为 `S256` |
+| `state` | 建议 | 防 CSRF 的随机字符串，会原样回传 |
+| `scope` | 否 | 空格分隔，可选值：`read`、`write`。默认 `read write` |
+
+### 3.3 用户操作
+
+1. 用户在浏览器中登录 Lessie 账号（如未登录会自动跳转登录页）
+2. 用户在授权页面看到客户端名称，点击"授权"
+
+### 3.4 授权回调
+
+授权成功后，浏览器 302 重定向到 `redirect_uri`：
+
+```
+http://127.0.0.1:3000/callback?code=xxxx&state=yyyy
+```
+
+| 参数 | 说明 |
+|------|------|
+| `code` | 授权码，10 分钟有效，一次性使用 |
+| `state` | 与请求时一致，客户端应验证其值 |
+
+---
+
+## 4. 令牌交换
+
+用授权码 + PKCE code_verifier 换取 access_token。
+
+**请求**
+
+```
+POST /token
+Content-Type: application/x-www-form-urlencoded
+```
+
+### 4.1 客户端认证方式
+
+**方式 A — Basic Auth（推荐）**
+
+```
+Authorization: Basic base64(client_id:client_secret)
+```
+
+表单参数：
+
+```
+grant_type=authorization_code
+&code={授权码}
+&redirect_uri={与授权请求一致的 redirect_uri}
+&code_verifier={PKCE code_verifier}
+```
+
+**方式 B — Form Body**
+
+```
+grant_type=authorization_code
+&code={授权码}
+&redirect_uri={与授权请求一致的 redirect_uri}
+&code_verifier={PKCE code_verifier}
+&client_id={client_id}
+&client_secret={client_secret}
+```
+
+**方式 C — Public Client（无 secret）**
+
+```
+grant_type=authorization_code
+&code={授权码}
+&redirect_uri={与授权请求一致的 redirect_uri}
+&code_verifier={PKCE code_verifier}
+&client_id={client_id}
+```
+
+**响应 200**
+
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIs...",
+  "token_type": "bearer",
+  "expires_in": 3600,
+  "scope": "read write"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `access_token` | JWT 格式的访问令牌 |
+| `token_type` | 固定为 `bearer` |
+| `expires_in` | 有效期（秒），默认 3600（1 小时） |
+| `scope` | 实际授予的权限范围，空格分隔 |
+
+**错误响应**
+
+| HTTP 状态码 | error | 说明 |
+|-------------|-------|------|
+| 400 | `unsupported_grant_type` | 仅支持 `authorization_code` |
+| 400 | `invalid_request` | 缺少必要参数（code / redirect_uri / code_verifier） |
+| 400 | `invalid_grant` | 授权码无效、已过期、已使用，或 PKCE 验证失败 |
+| 401 | `invalid_client` | 客户端认证失败（client_id 不存在或 secret 错误） |
+
+---
+
+## 5. 调用 MCP 接口
+
+在每次请求中携带 Bearer Token：
+
+```
+POST /mcp
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+Content-Type: application/json
+```
+
+### 401 响应处理
+
+| WWW-Authenticate 值 | 含义 | 处理方式 |
+|---------------------|------|----------|
+| `Bearer` | 未携带 token | 触发完整 OAuth 授权流程 |
+| `Bearer error="invalid_token"` | token 无效或已过期 | 重新走授权流程获取新 token |
+
+---
+
+## 6. 可用 Scope
+
+| Scope | 说明 |
+|-------|------|
+| `read` | 读取数据 |
+| `write` | 写入数据 |
+
+默认授予 `read write`。
+
+---
+
+## 7. 完整接入示例（伪代码）
+
+```python
+# 1. 发现元数据
+metadata = GET("/.well-known/oauth-authorization-server")
+
+# 2. 动态注册（仅首次）
+registration = POST(metadata.registration_endpoint, {
+    "redirect_uris": ["http://127.0.0.1:9876/callback"],
+    "grant_types": ["authorization_code"],
+    "client_name": "My Agent"
+})
+client_id = registration.client_id
+client_secret = registration.client_secret
+
+# 3. 生成 PKCE
+code_verifier = random_url_safe_string(64)
+code_challenge = base64url(sha256(code_verifier))
+
+# 4. 打开浏览器授权
+open_browser(f"{metadata.authorization_endpoint}"
+    f"?response_type=code"
+    f"&client_id={client_id}"
+    f"&redirect_uri=http://127.0.0.1:9876/callback"
+    f"&code_challenge={code_challenge}"
+    f"&code_challenge_method=S256"
+    f"&state={random_state}")
+
+# 5. 本地 HTTP 服务器等待回调，获取 code
+code = wait_for_callback()
+
+# 6. 用 code 换 token
+token_response = POST(metadata.token_endpoint, {
+    "grant_type": "authorization_code",
+    "code": code,
+    "redirect_uri": "http://127.0.0.1:9876/callback",
+    "code_verifier": code_verifier,
+    "client_id": client_id,
+    "client_secret": client_secret
+})
+access_token = token_response.access_token
+
+# 7. 调用 MCP
+response = POST("/mcp", headers={"Authorization": f"Bearer {access_token}"}, ...)
+```
+
+---
+
+## 8. 注意事项
+
+- `redirect_uri` 仅允许 loopback 地址（`127.0.0.1` / `localhost` / `[::1]`，任意端口）或 `https` 地址
+- loopback 回调时端口可以与注册时不同（符合 [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3)）
+- `client_secret` 仅注册时返回一次，请妥善保管
+- 授权码 10 分钟有效，且只能使用一次
+- access_token 有效期 1 小时，过期后需重新走授权流程
+- PKCE (S256) 为强制要求，不支持 plain 方式
+- `state` 参数建议始终使用，用于防止 CSRF 攻击

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessie/mcp-server",
-  "version": "0.0.5",
+  "version": "0.0.8",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -9,7 +9,8 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "start": "node dist/index.js"
+    "start": "node dist/index.js",
+    "inspector": "npx @modelcontextprotocol/inspector node dist/index.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.10.0",

package/.cursor/skills/add-mcp-tool/SKILL.md

@@ -1,132 +0,0 @@
----
-name: add-mcp-tool
-description: >-
-  为 Lessie MCP Server 添加新的 MCP 工具。当用户要求新增 MCP tool、暴露新的 API
-  端点、或为 AI Agent 添加新功能时使用。
----
-
-# 为 Lessie MCP Server 添加工具
-
-## 项目基础设施
-
-`src/index.ts` 已包含以下基础设施，添加工具时直接复用，**不要重复实现**：
-
-- **`getJwt()`** — API Key → JWT 换取 + 内存缓存 + 到期前 60s 自动刷新
-- **`api<T>(method, path, body?)`** — 通用请求封装，自动注入 Authorization header，非 2xx 抛错
-- **`textResult(data)`** — 将返回数据包装为 MCP content 格式
-
-## 添加工具流程
-
-### 1. 确认 API 端点
-
-从 `swagger.json` 中找到目标端点，记录：
-
-- HTTP 方法和路径（如 `GET /agent/account/info`）
-- 请求参数 / 请求体 schema
-- 响应 `data` 字段的结构
-
-### 2. 在工具定义区域添加代码
-
-在 `src/index.ts` 的 `// ── 工具定义` 区域、`// ── 启动` 区域之前添加：
-
-```typescript
-server.tool(
-  "动词_名词",           // 工具名：下划线分隔，动词开头
-  "一句话描述功能和用途", // Agent 靠 description 决定是否调用
-  {                       // zod schema 定义参数，无参数传 {}
-    paramName: z.string().describe("参数说明"),
-  },
-  async ({ paramName }) => {
-    const data = await api("GET", `/agent/your/path?param=${paramName}`);
-    return textResult(data);
-  }
-);
-```
-
-### 3. 命名规范
-
-| 类型 | 前缀 | 示例 |
-|------|------|------|
-| 查询单个 | `get_` | `get_account_info` |
-| 查询列表 | `list_` | `list_projects` |
-| 创建 | `create_` | `create_task` |
-| 更新 | `update_` | `update_task_status` |
-| 删除 | `delete_` | `delete_project` |
-
-### 4. Description 编写要求
-
-- 用中文，一句话说清**做什么**
-- Agent 完全依赖 description 决定是否调用，必须精确
-- **写入类工具**（create / update / delete）在末尾加：`执行前请向用户确认`
-
-好的 description:
-```
-查看当前 Lessie 账号的详细信息，包括用户名、邮箱、账号状态、角色、邀请码等。
-```
-
-差的 description:
-```
-获取账号信息
-```
-
-### 5. 参数定义
-
-- 用 `zod` 定义，每个参数加 `.describe()` 说明用途
-- 可选参数用 `.optional()`
-- 无参数传空对象 `{}`
-
-```typescript
-{
-  projectId: z.string().describe("项目 ID"),
-  status: z.enum(["active", "archived"]).optional().describe("筛选状态"),
-  page: z.number().default(1).describe("页码"),
-}
-```
-
-### 6. 构建验证
-
-添加完工具后运行 `npm run build` 确认 TypeScript 编译通过。
-
-## 完整示例
-
-```typescript
-// 列出项目
-server.tool(
-  "list_projects",
-  "列出当前用户的所有项目，支持按状态筛选。返回项目名称、状态、创建时间等信息。",
-  {
-    status: z.enum(["active", "archived"]).optional().describe("按状态筛选"),
-    page: z.number().default(1).describe("页码"),
-  },
-  async ({ status, page }) => {
-    const params = new URLSearchParams({ page: String(page) });
-    if (status) params.set("status", status);
-    const data = await api("GET", `/agent/projects?${params}`);
-    return textResult(data);
-  }
-);
-
-// 创建项目（写入类，description 要求确认）
-server.tool(
-  "create_project",
-  "创建一个新项目。执行前请向用户确认。",
-  {
-    name: z.string().describe("项目名称"),
-    description: z.string().optional().describe("项目描述"),
-  },
-  async ({ name, description }) => {
-    const data = await api("POST", "/agent/projects", { name, description });
-    return textResult(data);
-  }
-);
-```
-
-## API 响应格式
-
-后端统一返回格式为 `{ code: number, msg: string, data: T }`。`api()` 函数已自动解包，工具 handler 中拿到的就是 `data` 部分。
-
-## 注意事项
-
-- 所有路径以 `/agent/` 开头（Agent 专用端点）
-- `api()` 已处理 token 注入和错误抛出，handler 中只需关注业务逻辑
-- 不要在工具 handler 中直接使用 `fetch`，统一走 `api()` 封装