open-index/open-npm huggingface dataset:
npm package: @lessie/mcp-server
Description: 将 [Lessie](https://lessie.com) 接入 Claude Desktop，通过自然语言操作你的 Lessie 账号。
Latest version: 0.1.4

# Lessie MCP

将 [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+

## 安装

打开 Claude Desktop 配置文件：

| 系统    | 路径                                                        |
| ------- | ----------------------------------------------------------- |
| macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json`               |

添加以下配置：

```json
{
  "mcpServers": {
    "lessie": {
      "command": "npx",
      "args": ["-y", "@lessie/mcp-server"],
      "env": {
        "LESSIE_REMOTE_MCP_URL": "https://your-remote-mcp-server.com/mcp"
      }
    }
  }
}
```

保存后**完全退出并重新打开** Claude Desktop。首次使用时会自动打开浏览器引导登录。

## 环境变量

| 变量                   | 必填 | 说明                 |
| ---------------------- | ---- | -------------------- |
| `LESSIE_REMOTE_MCP_URL`| 否   | 远程 MCP Server 地址 |

## 验证

在对话中发送：

> 查看我的 Lessie 账号信息

## 常见问题

**工具列表中没有 lessie？**
检查配置文件 JSON 格式是否正确，然后完全退出并重启 Claude Desktop。

**连接远程服务器失败？**
确认 `LESSIE_REMOTE_MCP_URL` 地址正确，且远程服务器已实现 OAuth 2.1 端点。

**如何重新登录？**
删除 `~/.lessie/oauth.json` 后重启 Claude Desktop，会重新打开浏览器授权。