@lessie/mcp-server 0.0.5 → 0.0.6

package/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: lessie-api
+description: >-
+  调用 Lessie API 的标准流程：API Key 换取 JWT、JWT 缓存刷新、通用请求封装。
+  当需要对接 Lessie 后端、调用 Lessie API、或实现鉴权流程时使用。
+---
+
+# Lessie API 调用流程
+
+## 鉴权：API Key → JWT
+
+环境变量：
+
+- `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: "项目描述",
+});
+```
+

package/dist/index.js

@@ -1,9 +1,19 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
+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;
+    }
+}
 // ── 环境变量 ──────────────────────────────────────────────────────────────────
 const BASE_URL = process.env.LESSIE_BASE_URL || 'https://www.lessie.ai/prod-api';
 const API_KEY = process.env.LESSIE_API_KEY;
@@ -73,11 +83,20 @@ function textResult(data) {
 const server = new McpServer({
     name: "lessie-mcp",
     version: pkg.version,
+}, {
+    instructions: loadInstructions(),
 });
 // ── 工具定义 ──────────────────────────────────────────────────────────────────
 // 命名规范：下划线分隔，动词开头（如 list_xxx、get_xxx、create_xxx）。
 // 写入类工具在 description 中注明"执行前请向用户确认"。
-// 账号信息
+server.tool("get_jwt", "获取当前有效的 JWT token，可用于直接调用 Lessie API。返回 token 字符串和剩余有效时间。", {}, async () => {
+    const token = await getJwt();
+    const remainingMs = jwtCache ? jwtCache.expiry - Date.now() : 0;
+    return textResult({
+        token,
+        remainingSeconds: Math.max(0, Math.floor(remainingMs / 1000)),
+    });
+});
 server.tool("get_account_info", "查看当前 Lessie 账号的详细信息，包括用户名、邮箱、账号状态、角色、邀请码等。", {}, async () => {
     const data = await api("GET", "/agent/account/info");
     return textResult(data);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessie/mcp-server",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

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()` 封装