422 lines
10 KiB
Markdown
422 lines
10 KiB
Markdown
# Cursor IDE - Funstat MCP 配置指南
|
|
|
|
**配置时间**: 2025-10-27
|
|
**状态**: ✅ 已配置完成
|
|
**Cursor版本要求**: 0.47.x 或更高
|
|
|
|
---
|
|
|
|
## 📋 配置概述
|
|
|
|
本指南将帮助你在 **Cursor IDE** 中配置 Funstat MCP 服务器,使 Cursor 的AI助手可以调用 Funstat 的翻页搜索功能。
|
|
|
|
---
|
|
|
|
## ✅ 已完成的配置
|
|
|
|
### 1. MCP 配置文件创建 ✅
|
|
|
|
**文件位置**: `/Users/lucas/chat--1003255561049/.cursor/mcp.json`
|
|
|
|
**配置内容**:
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"funstat": {
|
|
"command": "/Users/lucas/牛马/agentapi",
|
|
"args": ["proxy", "http://127.0.0.1:8091/sse"],
|
|
"env": {}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. SSE 服务器启动 ✅
|
|
|
|
**服务地址**: `http://127.0.0.1:8091`
|
|
**SSE 端点**: `http://127.0.0.1:8091/sse`
|
|
**消息端点**: `http://127.0.0.1:8091/messages`
|
|
**进程ID**: 3783
|
|
**日志文件**: `/tmp/funstat_sse.log`
|
|
|
|
---
|
|
|
|
## 🚀 使用方法
|
|
|
|
### 方式1: 项目级配置 (当前方式) ✅
|
|
|
|
**配置文件**: `.cursor/mcp.json` (仅在此项目中生效)
|
|
|
|
**优点**:
|
|
- ✅ 项目特定,不影响其他项目
|
|
- ✅ 可以随项目分享配置
|
|
- ✅ 适合团队协作
|
|
|
|
**激活方法**:
|
|
1. 在 Cursor 中打开项目: `/Users/lucas/chat--1003255561049`
|
|
2. Cursor 自动读取 `.cursor/mcp.json`
|
|
3. Funstat MCP 工具自动可用
|
|
|
|
### 方式2: 全局配置 (可选)
|
|
|
|
如果希望在所有项目中都能使用 Funstat MCP:
|
|
|
|
**macOS 全局配置位置**:
|
|
```bash
|
|
~/Library/Application Support/Cursor/User/globalStorage/anysphere.cursor-mcp/mcp.json
|
|
```
|
|
|
|
或者
|
|
|
|
```bash
|
|
~/.cursor-mcp/mcp.json
|
|
```
|
|
|
|
**配置内容** (与项目级相同):
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"funstat": {
|
|
"command": "/Users/lucas/牛马/agentapi",
|
|
"args": ["proxy", "http://127.0.0.1:8091/sse"],
|
|
"env": {}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 SSE 服务器管理
|
|
|
|
### 启动服务器
|
|
|
|
```bash
|
|
# 方式1: 前台运行 (可看到日志)
|
|
cd /Users/lucas/chat--1003255561049/funstat_mcp
|
|
python3 server.py
|
|
|
|
# 方式2: 后台运行 (推荐)
|
|
cd /Users/lucas/chat--1003255561049/funstat_mcp
|
|
nohup python3 server.py > /tmp/funstat_sse.log 2>&1 &
|
|
|
|
# 方式3: 使用启动脚本
|
|
cd /Users/lucas/chat--1003255561049/funstat_mcp
|
|
./start_sse.sh
|
|
```
|
|
|
|
### 检查服务器状态
|
|
|
|
```bash
|
|
# 检查进程是否运行
|
|
ps aux | grep "server.py" | grep -v grep
|
|
|
|
# 查看日志
|
|
tail -f /tmp/funstat_sse.log
|
|
|
|
# 测试连接
|
|
curl http://127.0.0.1:8091/sse
|
|
```
|
|
|
|
### 停止服务器
|
|
|
|
```bash
|
|
# 查找进程ID
|
|
ps aux | grep "server.py" | grep -v grep
|
|
|
|
# 停止进程 (替换 PID 为实际进程ID)
|
|
kill <PID>
|
|
|
|
# 或强制停止
|
|
pkill -f "server.py"
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠️ 在 Cursor 中使用 Funstat 工具
|
|
|
|
### 可用的 MCP 工具
|
|
|
|
在 Cursor 的 AI Chat 中,你可以使用以下工具:
|
|
|
|
| 工具名 | 功能 | 示例 |
|
|
|--------|------|------|
|
|
| `send_command` | 发送命令到 funstat BOT | "发送 /search 翻译" |
|
|
| `search_users` | 搜索用户/群组 | "搜索翻译相关用户" |
|
|
| `get_user_info` | 获取用户详情 | "查询用户 @username 的信息" |
|
|
| `get_group_info` | 获取群组详情 | "查询群组 123456 的信息" |
|
|
| `get_message_stats` | 消息统计 | "获取群组消息统计" |
|
|
| `list_recent_chats` | 最近对话列表 | "列出最近的对话" |
|
|
| `get_help` | 获取帮助 | "显示 Funstat 帮助" |
|
|
| `get_status` | 服务器状态 | "检查服务器状态" |
|
|
|
|
### 使用示例
|
|
|
|
在 Cursor 的 AI Chat 中输入:
|
|
|
|
```
|
|
请帮我搜索所有包含"翻译"关键词的Telegram用户
|
|
```
|
|
|
|
Cursor 的 AI 会自动调用 Funstat MCP 的 `search_users` 工具。
|
|
|
|
---
|
|
|
|
## 🎯 验证配置
|
|
|
|
### 1. 检查配置文件
|
|
|
|
```bash
|
|
cat /Users/lucas/chat--1003255561049/.cursor/mcp.json
|
|
```
|
|
|
|
应该看到:
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"funstat": {
|
|
"command": "/Users/lucas/牛马/agentapi",
|
|
"args": ["proxy", "http://127.0.0.1:8091/sse"],
|
|
"env": {}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. 检查 SSE 服务器
|
|
|
|
```bash
|
|
# 检查进程
|
|
ps aux | grep server.py
|
|
|
|
# 测试连接
|
|
curl -i http://127.0.0.1:8091/sse
|
|
```
|
|
|
|
应该返回 SSE 响应头。
|
|
|
|
### 3. 在 Cursor 中验证
|
|
|
|
1. 打开 Cursor
|
|
2. 打开项目: `/Users/lucas/chat--1003255561049`
|
|
3. 打开 AI Chat (Cmd+L)
|
|
4. 输入: "列出可用的 MCP 工具"
|
|
5. 应该看到 Funstat 相关工具
|
|
|
|
---
|
|
|
|
## 📊 架构图
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Cursor IDE │
|
|
│ ┌───────────────────────────────────────────────────────┐ │
|
|
│ │ AI Chat / Composer │ │
|
|
│ │ (使用 Claude 或其他 AI 模型) │ │
|
|
│ └───────────────────┬───────────────────────────────────┘ │
|
|
│ │ MCP Protocol │
|
|
│ │ │
|
|
│ ┌───────────────────▼───────────────────────────────────┐ │
|
|
│ │ MCP Client (Cursor 内置) │ │
|
|
│ │ 读取: .cursor/mcp.json │ │
|
|
│ └───────────────────┬───────────────────────────────────┘ │
|
|
└────────────────────────┼────────────────────────────────────┘
|
|
│
|
|
│ 调用 agentapi proxy
|
|
│
|
|
┌────────────▼────────────┐
|
|
│ AgentAPI Proxy │
|
|
│ /Users/lucas/牛马/ │
|
|
│ agentapi │
|
|
└────────────┬────────────┘
|
|
│
|
|
│ SSE 连接
|
|
│ http://127.0.0.1:8091/sse
|
|
│
|
|
┌────────────────▼────────────────┐
|
|
│ Funstat MCP Server (SSE) │
|
|
│ funstat_mcp/server.py │
|
|
│ 端口: 8091 │
|
|
└────────────────┬────────────────┘
|
|
│
|
|
│ Telethon
|
|
│ (Telegram MTProto)
|
|
│
|
|
┌────────────▼────────────┐
|
|
│ Telegram BOT │
|
|
│ @openaiw_bot │
|
|
│ (KT超级数据) │
|
|
└─────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🔒 安全注意事项
|
|
|
|
### 1. Session 文件保护
|
|
|
|
Session 文件包含登录凭据,已被 .gitignore 保护:
|
|
|
|
```bash
|
|
# .gitignore 中已配置
|
|
*.session
|
|
*.session-journal
|
|
```
|
|
|
|
### 2. API 密钥
|
|
|
|
Funstat MCP 使用的 Telegram API 密钥存储在:
|
|
- `/Users/lucas/牛马/config.json` (AgentAPI 配置)
|
|
- 环境变量 (可选)
|
|
|
|
**不要将这些文件提交到公共仓库!**
|
|
|
|
### 3. 本地服务器
|
|
|
|
SSE 服务器仅监听 `127.0.0.1`,不对外网开放:
|
|
|
|
```python
|
|
host = os.getenv("FUNSTAT_HOST", "127.0.0.1") # 仅本地
|
|
port = int(os.getenv("FUNSTAT_PORT", "8091"))
|
|
```
|
|
|
|
---
|
|
|
|
## 🐛 故障排除
|
|
|
|
### 问题1: Cursor 无法识别 MCP 工具
|
|
|
|
**可能原因**:
|
|
- Cursor 版本过低 (需要 0.47.x+)
|
|
- .cursor/mcp.json 文件格式错误
|
|
- SSE 服务器未运行
|
|
|
|
**解决方法**:
|
|
```bash
|
|
# 1. 检查 Cursor 版本
|
|
# Cursor -> About Cursor
|
|
|
|
# 2. 验证 JSON 格式
|
|
cat .cursor/mcp.json | python3 -m json.tool
|
|
|
|
# 3. 检查 SSE 服务器
|
|
ps aux | grep server.py
|
|
curl http://127.0.0.1:8091/sse
|
|
|
|
# 4. 重启 Cursor
|
|
# Cursor -> Quit Cursor (完全退出)
|
|
# 重新打开
|
|
```
|
|
|
|
### 问题2: SSE 服务器连接失败
|
|
|
|
**可能原因**:
|
|
- 服务器未启动
|
|
- 端口被占用
|
|
- Session 文件被锁定
|
|
|
|
**解决方法**:
|
|
```bash
|
|
# 1. 检查端口占用
|
|
lsof -i :8091
|
|
|
|
# 2. 杀死占用进程
|
|
kill <PID>
|
|
|
|
# 3. 重启 SSE 服务器
|
|
cd /Users/lucas/chat--1003255561049/funstat_mcp
|
|
python3 server.py
|
|
```
|
|
|
|
### 问题3: AgentAPI Proxy 失败
|
|
|
|
**可能原因**:
|
|
- AgentAPI 二进制文件不存在
|
|
- 权限问题
|
|
|
|
**解决方法**:
|
|
```bash
|
|
# 1. 检查 AgentAPI 是否存在
|
|
ls -la /Users/lucas/牛马/agentapi
|
|
|
|
# 2. 添加执行权限
|
|
chmod +x /Users/lucas/牛马/agentapi
|
|
|
|
# 3. 测试 AgentAPI
|
|
/Users/lucas/牛马/agentapi --help
|
|
```
|
|
|
|
---
|
|
|
|
## 📖 相关文档
|
|
|
|
### Cursor MCP 文档
|
|
|
|
- [Cursor 官方 MCP 文档](https://docs.cursor.com/context/model-context-protocol)
|
|
- [MCP 配置示例](https://mcpconfig.com/cursor-mcp/)
|
|
|
|
### Funstat MCP 文档
|
|
|
|
- [README.md](README.md) - 项目主文档
|
|
- [PAGINATION_SUCCESS_REPORT.md](PAGINATION_SUCCESS_REPORT.md) - 翻页功能
|
|
- [SSE_CONVERSION_COMPLETE.md](SSE_CONVERSION_COMPLETE.md) - SSE 转换
|
|
- [GIT_VERSION_CONTROL.md](GIT_VERSION_CONTROL.md) - Git 版本管理
|
|
|
|
---
|
|
|
|
## 🎊 配置完成!
|
|
|
|
### ✅ 当前状态
|
|
|
|
```
|
|
✅ .cursor/mcp.json 已创建
|
|
✅ SSE 服务器已启动 (PID: 3783)
|
|
✅ AgentAPI Proxy 已配置
|
|
✅ Funstat MCP 工具已可用
|
|
```
|
|
|
|
### 🚀 下一步
|
|
|
|
1. **打开 Cursor**: 在 Cursor 中打开此项目
|
|
2. **验证工具**: 在 AI Chat 中询问可用的 MCP 工具
|
|
3. **开始使用**: 让 Cursor AI 帮你搜索 Telegram 用户!
|
|
|
|
### 📝 快速命令
|
|
|
|
```bash
|
|
# 启动 SSE 服务器
|
|
cd /Users/lucas/chat--1003255561049/funstat_mcp && python3 server.py
|
|
|
|
# 检查服务器状态
|
|
ps aux | grep server.py
|
|
|
|
# 查看日志
|
|
tail -f /tmp/funstat_sse.log
|
|
|
|
# 停止服务器
|
|
pkill -f server.py
|
|
```
|
|
|
|
---
|
|
|
|
## 💡 使用示例
|
|
|
|
### 在 Cursor AI Chat 中:
|
|
|
|
**用户**: 帮我搜索所有与"翻译"相关的 Telegram 用户,并自动翻页获取完整数据
|
|
|
|
**Cursor AI** 会:
|
|
1. 调用 `search_users` MCP 工具
|
|
2. 使用 Funstat 的自动翻页功能
|
|
3. 返回完整的搜索结果 (可能有数百条)
|
|
|
|
**结果**: 你会得到完整的用户列表,包括 ID、用户名、来源关键词和页码!
|
|
|
|
---
|
|
|
|
**配置完成时间**: 2025-10-27
|
|
**SSE 服务器**: ✅ 运行中
|
|
**Cursor MCP**: ✅ 已配置
|
|
|
|
🎉 **Cursor 现在可以使用 Funstat MCP 工具了!** 🎉
|