chore: initial commit
This commit is contained in:
你的用户名
421
docs/CURSOR_MCP_SETUP.md
Normal file
421
docs/CURSOR_MCP_SETUP.md
Normal file
@@ -0,0 +1,421 @@
|
||||
# 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 工具了!** 🎉
|
||||
Reference in New Issue
Block a user