内容
# Perch MCP 服务器
Perch 的模型上下文协议（MCP）服务器。连接 Perch 到任何兼容 MCP 的 AI 客户端（Claude Desktop、Claude Code、Cursor、Zed、ChatGPT），以便您可以用自然语言询问有关您的账户、定期付款和预测的信息。
## 状态
**v0.3（当前）：** 五个只读工具 + 两个传输协议。
| 工具 | 描述 |
|---|---|
| `list_accounts` | 显示您的 Perch 账户及当前余额 |
| `list_recurring_series` | 显示给定账户的定期付款和收入（模板） |
| `list_scheduled_items` | 显示账户中即将到来的具体事项，包括日期和金额 |
| `get_forecast_curve` | 服务器计算的运行余额预测 - 图表时间序列 |
| `simulate_forecast` | 假设：重新运行预测，合并假设事项（只读，永不持久） |
另外五个**管理员（机器对机器）**工具 - 仅在配置了 M2M 凭证时注册（参见[管理员工具](#管理员工具-机器对机器)）：
| 工具 | 所需范围 |
|---|---|
| `admin_get_user` | `users:read` |
| `admin_list_users` | `users:read` |
| `admin_get_user_activity` | `users:read` |
| `admin_get_brand_exposures` | `brand_exposures:read` |
| `admin_get_suppressed_suggestions` | `suppressed_suggestions:read` |
| 传输协议 | 认证方式 | 使用场景 |
|---|---|---|
| **stdio**（默认） | PAT（`PERCH_API_TOKEN` 环境变量） | 通过 Claude Desktop / Cursor / Zed / Claude Code 进行本地安装 |
| **HTTP**（`--http`） | OAuth 2.1 via Hydra（Bearer） | 在 `mcp.theperch.app` 上托管，用于 ChatGPT 和仅限远程的 MCP 客户端 |
## 安装
### Claude Desktop
添加到您的 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"perch": {
"command": "npx",
"args": ["-y", "@perch/mcp-server"],
"env": {
"PERCH_API_TOKEN": "pat_…",
"PERCH_API_URL": "https://api.perch.app"
}
}
}
}
```
重启 Claude Desktop。询问“我的 Perch 账户是什么？”以进行测试。
### Claude Code、Cursor、Zed
相同的配置形状；请参阅客户端的 MCP 设置文档，了解放置位置。
## 认证
从 Perch 的设置页面（或通过 `POST /api/v1/tokens` 端点）生成个人访问令牌。令牌具有范围 - 请求 `read` 仅限此集成。明文令牌仅显示一次；将其粘贴到上面的 `PERCH_API_TOKEN`。
PAT 不能执行管理员操作，也不能创建或撤销其他令牌。
## 管理员工具（机器对机器）
> **设计 + 如何添加范围：** 请参阅 perch-api 中的跨仓库交接文档 - [`docs/api-handoff-m2m-mcp-admin-auth.md`](https://github.com/sprout-labs-ai/perch-api/blob/staging/docs/api-handoff-m2m-mcp-admin-auth.md)（已构建 + “添加范围”配方）。这是整个 M2M 系统的真实来源。
五个 `admin_*` 工具使用**服务器端客户端凭证**而非调用用户的身份验证。它们用于专用的操作员实例（例如维护人员的机器上的 Claude Code），而非多租户 HTTP 部署。
它们**仅在环境中设置了 `PERCH_MCP_CLIENT_ID` 和 `PERCH_MCP_CLIENT_SECRET` 时才注册。** 未设置这些（默认）和托管的 HTTP 服务器运行方式一样，管理员工具不存在 - 无法使用常规用户令牌访问管理员端点。
在 Perch 管理门户下**系统 → MCP 客户端**中创建一个客户端，授予它所需的最小范围（v1 中全部只读），并复制一次密钥。然后配置一个 stdio 实例：
```jsonc
{
"mcpServers": {
"perch-admin": {
"command": "npx",
"args": ["perch-mcp-server"],
"env": {
"PERCH_API_URL": "https://api.perch.app",
"PERCH_MCP_CLIENT_ID": "mcp_…",
"PERCH_MCP_CLIENT_SECRET": "…"
}
}
}
}
```
在后台，服务器使用 `POST /api/v1/oauth/token` 处的 OAuth `client_credentials` 授权交换这些凭证，获得一个短期的（5 分钟）持有者令牌，将其缓存在内存中，在过期前约 30 秒刷新，并在 401 时强制刷新 + 重试。撤销的客户端立即停止工作 - perch-api 在每个请求上都会重新检查客户端行。
## 消费者集成（设置 → 集成）
Perch iOS 应用的**集成**区域 - 连接/断开 ChatGPT 和 Claude 等助手，查看其权限，查看访问活动日志，并设置隐私控制 - 由此 OAuth 2.1 + 资源范围流程驱动。“连接助手”是一种 OAuth 授权码授予，适用于 `mcp.theperch.app` 资源；授予的范围成为人员看到的权限。
> **设计 + 跨仓库契约：** 请参阅 [`docs/handoff-consumer-integrations.md`](docs/handoff-consumer-integrations.md) - 连接标识（`azp → integration` 关联），连接交接，范围 ↔ 权限映射，活动发射和隐私强制，包括必须与 perch-api 共同解决的内容。
这里的内容：
| 关注点 | 模块 |
|---|---|
| 范围 ↔ 消费者权限映射 | [`src/auth/permissions.ts`](src/auth/permissions.ts) |
| 每个工具的访问活动发射 | [`src/activity/`](src/activity) |
| 隐私控制错误呈现 | [`src/api/client.ts`](src/api/client.ts) |
技术范围与 UI 显示的 calm 权限密钥之间的映射：
| 消费者权限 | MCP 范围 | 状态 |
|---|---|---|
| `current_balance` | `read:accounts` | live |
| `upcoming_items` | `read:schedule` | live |
| `activity_history` | `read:series` | live |
| `forecast` | `read:forecast` | live |
| `suggestions` | — | not yet available |
| `changes` | — | not yet available (write) |
来自连接助手的每个成功的工具调用都会发出一个 calm、PII-free 的活动条目（固定摘要 + 权限密钥 - 永远不会是参数、金额、日期、ID 或传输详细信息）到 perch-api，perch-api 会在应用的活动日志中显示出来。账户范围的隐私控制（`allow_integrations`、`require_approval_for_changes`）由 perch-api 强制执行；此服务器将它们的拒绝转换为 calm、consumer-safe 的指导。
## 隐私
此服务器代表您读取 Perch 的 API。它不会：
- 编写或修改任何数据（严格只读 - 用户和管理员工具）
- 将数据发送到 AI 客户端以外的任何地方
用户范围的工具使用您自己的令牌，只能看到您自己的数据。`admin_*` 工具受到单独配置的 M2M 凭证的限制，如果您不明确配置一个（请参见[管理员工具](#管理员工具-机器对机器)），则它们不存在。
AI 客户端（Claude/ChatGPT 等）根据其自己的数据政策处理响应。
## HTTP 传输协议（Hydra OAuth）
对于远程托管（例如，`https://mcp.theperch.app` 用于 ChatGPT 兼容性），服务器在 HTTP 模式下运行，并接受颁发给 MCP 服务器的 Hydra 访问令牌。
```bash
HYDRA_ISSUER=https://mcp-auth.theperch.app \
MCP_AUDIENCE=https://mcp.theperch.app \
PERCH_MCP_PUBLIC_URL=https://mcp.theperch.app \
PERCH_API_URL=https://api.perch.app \
PORT=3001 \
node dist/index.js --http
```
暴露的端点：
| 路径 | 认证方式 | 功能 |
|---|---|---|
| `GET /health` | 无 | 存活探测 |
| `GET /.well-known/oauth-protected-resource` | 无 | RFC 9728 元数据，指向 MCP 客户端到 Hydra 发行者 |
| `POST /mcp` | 持有者（Hydra JWT 用于 MCP 受众） | MCP JSON-RPC 端点，无状态 |
当请求到达时，没有有效的令牌，服务器发出符合规范的 `WWW-Authenticate: Bearer error="invalid_token", resource_metadata="…"` 头部，以便 MCP 客户端可以发现身份验证服务器并启动 OAuth 流。
传入的 JWT 原样转发到 perch-api 作为 `Authorization` 头部 - perch-api 接受相同的受众通过其 `MCP_AUDIENCE` 配置。每个请求没有令牌交换往返。
## 本地开发
```bash
git clone https://github.com/sprout-labs-ai/perch-mcp-server.git
cd perch-mcp-server
npm install
# stdio 模式（默认），针对本地 perch-api
PERCH_API_URL=http://localhost:3000 PERCH_API_TOKEN=pat_… npm run dev
# HTTP 模式，也针对本地 perch-api
HYDRA_ISSUER=… MCP_AUDIENCE=https://mcp.theperch.app \
PORT=3401 PERCH_API_URL=http://localhost:3000 \
npm run dev -- --http
```
通过替换上面的 `command`/`args` 指向开发构建（stdio 模式）：
```json
"command": "node",
"args": ["/absolute/path/to/perch-mcp-server/dist/index.js"]
```
## 许可证
MIT.
