内容
# MCP AUVP
本地MCP服务器，用于通过聊天（Cursor、Claude Desktop等）查询AUVP产品。
**仓库：** [github.com/rod-moraes/mcp-auvp](https://github.com/rod-moraes/mcp-auvp)
| 产品 | 基础 | 文档 |
|---------|------|--------------|
| **金融** | `https://financas-api.auvp.com.br` | **[src/financas/README.md](src/financas/README.md)** — 32 tools (账户，交易，仪表盘，预算) |
| **分析** | `https://analitica.auvp.com.br` | **[src/analitica/README.md](src/analitica/README.md)** — 44 tools (排名，基本面，市场，比较) |
| **社区** | `https://comunidade.auvp.com.br` | **[src/comunidade/README.md](src/comunidade/README.md)** — 8 tools (搜索，论坛，主题，通知，排名) |
服务器使用`stdio`传输，可以直接从GitHub使用`npx`安装，无需克隆仓库。
---
## 安装（公共仓库在GitHub）
### 前置条件
- **Node.js** ≥ 20.18 ([nodejs.org](https://nodejs.org/))
- AUVP账户（`sso.auvp.com.br`上的SSO登录）
- **Cursor**（或另一个兼容`stdio`的MCP客户端）
### 步骤 1 — 在Cursor上配置MCP
创建或编辑`~/.cursor/mcp.json`（全局）或`.cursor/mcp.json`（仅限当前项目）：
```json
{
"mcpServers": {
"mcp-auvp": {
"command": "npx",
"args": ["-y", "github:rod-moraes/mcp-auvp"]
}
}
}
```
令牌和cookie会自动保存到`~/.auvp-financas/` — 无需在`mcp.json`中配置`env`。
示例：[.cursor/mcp.json.example](.cursor/mcp.json.example)。
**私人仓库？** 在URL中使用令牌：
```json
"args": ["-y", "git+https://TOKEN@github.com/rod-moraes/mcp-auvp.git"]
```
**固定版本**（避免自动获取`main`）：
```json
"args": ["-y", "github:rod-moraes/mcp-auvp#main"]
```
### 步骤 2 — 重启Cursor上的MCP
打开**设置 → MCP → 重启**（或重启Cursor）。
首次执行时，`npx`会下载仓库，运行`npm install`并自动编译（准备）。无需手动克隆或运行`npm run build`。
### 步骤 3 — 认证
在Cursor的聊天中，向代理发出请求：
> 调用`auvp_ensure_auth`登录AUVP。
MCP：
1. 如果令牌仍然有效，则重用它。
2. 尝试静默续期保存的浏览器配置文件。
3. 仅当需要登录时，才打开可见的Chrome。
第一次（或会话过期时），浏览器会打开供您登录SSO。之后，续期通常是自动的。
### 步骤 4 — Playwright的Chromium（仅限首次）
如果登录因缺少嵌入式浏览器而失败，请在终端中运行**一次**：
```bash
npx -y --package=github:rod-moraes/mcp-auvp -c "playwright install chromium"
```
如果您克隆了仓库：
```bash
cd mcp-auvp
npm run playwright:install
```
### 步骤 5 — 测试
在聊天中，请求类似：
- 金融：*"使用`auvp_financas_list_accounts`列出我的账户"*
- 分析：*"使用`auvp_analitica_get_ranking`搜索股息收益率排名"*
- 社区：*"使用`auvp_comunidade_get_topic`阅读主题X"*
使用`auvp_get_auth_status`确认状态。
---
## 磁盘上保存的内容
| 文件 | 内容 |
|---------|----------|
| `~/.auvp-financas/access-token` | 金融API的Bearer令牌 |
| `~/.auvp-financas/analitica-cookie` | 分析的会话cookie |
| `~/.auvp-financas/comunidade-cookie` | 社区的IPS会话cookie |
| `~/.auvp-financas/browser-profile/` | Playwright浏览器配置文件（SSO会话） |
| `~/.auvp-financas/storage-state.json` | cookie的额外备份 |
**不以明文保存密码** — 仅保存浏览器在配置文件中保存的内容。要切换帐户或清除会话：使用`fresh: true`调用`auvp_ensure_auth`。
MCP会自动从磁盘重新加载令牌和cookie；仅当服务器停止时才需要重启。
### 启动MCP时的登录
激活/重启MCP时，它会自动检查身份验证（有效令牌 → 静默续期 → 如果需要可见的Chrome）。要禁用：
```bash
export AUVP_FINANCAS_AUTO_LOGIN_ON_START=0
```
---
## 开发（本地克隆）
要贡献或在不使用GitHub的`npx`的情况下运行：
```bash
git clone https://github.com/rod-moraes/mcp-auvp.git
cd mcp-auvp
npm install # 已经触发构建（准备）
npm run playwright:install # 首次运行，需要登录
npm test
```
MCP配置指向克隆：
```json
{
"mcpServers": {
"mcp-auvp": {
"command": "npx",
"args": ["-y", "mcp-auvp"],
"cwd": "/path/to/mcp-auvp"
}
}
}
```
无需编译的开发模式：
```bash
npm run dev
```
---
## 环境变量
可选 — 默认值无需在`mcp.json`中配置。仅当需要**自定义路径**用于令牌/cookie或**内联值**（无磁盘文件）时声明为`env`：
```json
"env": {
"AUVP_FINANCAS_ACCESS_TOKEN_FILE": "/custom/path/access-token",
"AUVP_ANALITICA_COOKIE_FILE": "/custom/path/analitica-cookie",
"AUVP_COMUNIDADE_COOKIE_FILE": "/custom/path/comunidade-cookie"
}
```
内联替代（无文件）：`AUVP_FINANCAS_ACCESS_TOKEN`，`AUVP_ANALITICA_COOKIE`，`AUVP_COMUNIDADE_COOKIE`。
| 变量 | 默认值 | 描述 |
|----------|---------|-----------|
| `AUVP_FINANCAS_API_BASE_URL` | `https://financas-api.auvp.com.br` | 金融API |
| `AUVP_FINANCAS_ORIGIN` | `https://financas.auvp.com.br` | 金融源/引用 |
| `AUVP_ANALITICA_BASE_URL` | `https://analitica.auvp.com.br` | 分析API |
| `AUVP_ANALITICA_ORIGIN` | `https://analitica.auvp.com.br` | 分析源/引用 |
| `AUVP_FINANCAS_TIMEOUT_MS` | `30000` | 请求超时（毫秒） |
| `AUVP_FINANCAS_ACCESS_TOKEN_FILE` | `~/.auvp-financas/access-token` | Bearer令牌文件 |
| `AUVP_FINANCAS_ACCESS_TOKEN` | — | 内联令牌（文件替代） |
| `AUVP_ANALITICA_COOKIE_FILE` | `~/.auvp-financas/analitica-cookie` | 分析cookie |
| `AUVP_ANALITICA_COOKIE` | — | 内联cookie（文件替代） |
| `AUVP_COMUNIDADE_COOKIE_FILE` | `~/.auvp-financas/comunidade-cookie` | 社区IPS cookie |
| `AUVP_COMUNIDADE_COOKIE` | — | 内联cookie（文件替代） |
| `AUVP_FINANCAS_BROWSER_PROFILE_DIR` | `~/.auvp-financas/browser-profile` | Playwright配置文件 |
| `AUVP_FINANCAS_STORAGE_STATE_FILE` | `~/.auvp-financas/storage-state.json` | 会话备份 |
| `AUVP_FINANCAS_LOGIN_FRESH` | — | `1`强制从零开始登录 |
| `AUVP_FINANCAS_AUTO_LOGIN_ON_START` | `1` | `0`禁用启动时的自动登录 |
| `AUVP_FINANCAS_EXTRA_HEADERS` | — | 额外的JSON头 |
SSO（可选）：
| 变量 | 默认值 |
|----------|---------|
| `AUVP_FINANCAS_SSO_BASE_URL` | `https://sso.auvp.com.br` |
| `AUVP_FINANCAS_SSO_REALM` | `AUVP` |
| `AUVP_FINANCAS_SSO_CLIENT_ID` | `financas` |
| `AUVP_FINANCAS_SSO_REDIRECT_URI` | `https://financas-api.auvp.com.br/auth/auvp/callback` |
| `AUVP_FINANCAS_SSO_SCOPE` | `email profile openid` |
---
## 工具
### 认证（横向）
| 工具 | 用途 |
|------|-----|
| `auvp_ensure_auth` | 自动登录/续期（推荐） |
| `auvp_get_auth_status` | 检查Bearer、分析/社区cookie和会话 |
| `auvp_create_sso_login_url` | SSO登录URL（手动流程） |
| `auvp_complete_sso_login` | 使用`callbackUrl`完成登录 |
### 金融 — `auvp_financas_*`
文档： **[src/financas/README.md](src/financas/README.md)**
账户、交易、仪表盘、预算、类别、标签和Pluggy的读写。实时扫描：`npm run scan:financas`。
### 分析 — `auvp_analitica_*`
文档： **[src/analitica/README.md](src/analitica/README.md)**
会话、排名、资产基本面、市场、新闻和模拟器。仅读。扫描：`npm run scan:analitica`；审计：`npm run audit:analitica`。
### 社区 — `auvp_comunidade_*`
文档： **[src/comunidade/README.md](src/comunidade/README.md)**
搜索、论坛/主题列表、帖子和评论的读取、通知和IPS排名。仅读。扫描：`npm run scan:comunidade`.
---
## 手动SSO流程（替代方案）
优先使用`auvp_ensure_auth`，它会自动打开浏览器并保存令牌。
1. 调用`auvp_create_sso_login_url`（具有有效`state`的API URL）。
2. 在浏览器中打开URL并完成登录。
3. 如果重定向太快：DevTools → Network → **保留日志** → 过滤`callback` → 复制URL。
4. 调用`auvp_complete_sso_login`并在同一MCP会话中使用`callbackUrl`。
5. Bearer令牌自动保存到磁盘。
不要手动生成登录URL：API验证它创建的`state`。
---
## 验证
```bash
npm test
npm run build
npm run scan:financas # 需要认证
npm run scan:analitica # 需要认证（Bearer + cookie）
npm run scan:comunidade # 需要IPS cookie
```
---
## 目录来源
从HAR和Scrapling探针中提取的初始合同，来自三个产品。新路由可以使用技能[auvp-scrapling](.cursor/skills/auvp-scrapling/SKILL.md)发现 — 查看每个模块的README：
- [金融](src/financas/README.md)
- [分析](src/analitica/README.md)
- [社区](src/comunidade/README.md)
