doudou/funstat-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: initial commit

Browse Source
This commit is contained in:
你的用户名
2025-11-01 21:58:03 +08:00
commit a05a7dd40e
65 changed files with 16590 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

418
docs/CODEX_CLI_MCP_SETUP.md Normal file
View File

@@ -0,0 +1,418 @@
# Codex CLI - Funstat MCP 配置指南
**配置时间**: 2025-10-27
**状态**: ✅ 已配置完成
**Codex CLI 版本**: 0.49.0
---
## 📋 配置概述
本指南说明如何在 **Codex CLI** (OpenAI 的命令行 AI 助手) 中配置 Funstat MCP 服务器,使 Codex 可以调用 Funstat 的翻页搜索功能。
---
## ✅ 已完成的配置
### 1. MCP 服务器添加 ✅
**命令**:
```bash
codex mcp add --url http://127.0.0.1:8091/sse funstat
```
**输出**:
```
Added global MCP server 'funstat'.
```
### 2. 配置验证 ✅
**配置详情**:
```
Name: funstat
URL: http://127.0.0.1:8091/sse
Transport: streamable_http
Status: enabled
Auth: Unsupported
```
### 3. 配置文件更新 ✅
**文件位置**: `~/.codex/config.toml`
**新增内容**:
```toml
[mcp_servers.funstat]
url = "http://127.0.0.1:8091/sse"
```
---
## 🚀 使用方法
### 在 Codex CLI 中使用
```bash
# 启动 Codex 交互式会话
codex
# 在 Codex 中输入你的请求
> 帮我搜索所有包含"翻译"关键词的Telegram用户,并自动翻页获取完整数据
```
Codex 会自动:
- ✅ 连接到 Funstat MCP 服务器
- ✅ 调用 `search_users` 工具
- ✅ 使用自动翻页功能
- ✅ 返回完整的搜索结果
---
## 🛠️ MCP 服务器管理
### 列出所有 MCP 服务器
```bash
codex mcp list
```
**输出**:
```
Name Url Bearer Token Env Var Status Auth
funstat http://127.0.0.1:8091/sse - enabled Unsupported
```
### 查看服务器详情
```bash
codex mcp get funstat
```
**输出**:
```
funstat
enabled: true
transport: streamable_http
url: http://127.0.0.1:8091/sse
bearer_token_env_var: -
http_headers: -
env_http_headers: -
remove: codex mcp remove funstat
```
### 删除 MCP 服务器
```bash
codex mcp remove funstat
```
### 重新添加
```bash
codex mcp add --url http://127.0.0.1:8091/sse funstat
```
---
## 🔧 SSE 服务器管理
### 确保 SSE 服务器运行
**检查状态**:
```bash
ps aux | grep server.py | grep -v grep
```
**如果未运行,启动服务器**:
```bash
cd /Users/lucas/chat--1003255561049/funstat_mcp
nohup python3 server.py > /tmp/funstat_sse.log 2>&1 &
```
**查看日志**:
```bash
tail -f /tmp/funstat_sse.log
```
---
## 🎯 可用的 MCP 工具
Codex 可以调用以下 Funstat MCP 工具:
| 工具名 | 功能 | 示例提示 |
|--------|------|----------|
| `search_users` | 搜索用户/群组 | "搜索翻译相关用户" |
| `send_command` | 发送命令到 BOT | "发送 /search subtitle" |
| `get_user_info` | 获取用户详情 | "查询用户 @username" |
| `get_group_info` | 获取群组详情 | "查询群组 123456" |
| `get_message_stats` | 消息统计 | "获取消息统计" |
| `list_recent_chats` | 最近对话列表 | "列出最近对话" |
| `get_help` | 获取帮助 | "显示 Funstat 帮助" |
| `get_status` | 服务器状态 | "检查服务器状态" |
---
## 📖 使用示例
### 示例 1: 交互式搜索
```bash
$ codex
Codex> 请帮我搜索包含"翻译"的Telegram用户,并自动翻页获取所有结果
[Codex 调用 Funstat MCP 的 search_users 工具]
[自动翻页,获取完整数据]
[返回结果: 890条记录,包括ID、用户名、来源页码]
```
### 示例 2: 一次性命令
```bash
codex exec "搜索所有包含'subtitle'关键词的Telegram群组"
```
### 示例 3: 带图片的搜索
```bash
codex -i screenshot.png "这个截图中的Telegram用户名是什么?帮我搜索相关信息"
```
---
## 📊 架构图
```
┌─────────────────────────────────────────────┐
│ Codex CLI (命令行) │
│ codex / codex exec │
└─────────────────┬───────────────────────────┘
│
│ 读取配置
│ ~/.codex/config.toml
│
┌─────────────▼──────────────┐
│ MCP Client (Codex内置) │
│ [mcp_servers.funstat] │
│ url = http://... │
└─────────────┬──────────────┘
│
│ 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超级数据) │
└────────────────────────────┘
```
---
## 🔧 高级配置
### 添加环境变量认证 (可选)
如果需要 Bearer Token 认证:
```bash
# 设置环境变量
export FUNSTAT_TOKEN="your-token-here"
# 添加 MCP 服务器时指定
codex mcp add \
--url http://127.0.0.1:8091/sse \
--bearer-token-env-var FUNSTAT_TOKEN \
funstat
```
### 手动编辑配置文件
**文件**: `~/.codex/config.toml`
```toml
[mcp_servers.funstat]
url = "http://127.0.0.1:8091/sse"
# bearer_token_env_var = "FUNSTAT_TOKEN" # 可选
```
---
## 🐛 故障排除
### 问题 1: Codex 无法连接到 MCP 服务器
**可能原因**:
- SSE 服务器未运行
- URL 配置错误
- 端口被占用
**解决方法**:
```bash
# 1. 检查 SSE 服务器状态
ps aux | grep server.py
# 2. 测试 SSE 端点
curl -i http://127.0.0.1:8091/sse
# 3. 重启 SSE 服务器
cd /Users/lucas/chat--1003255561049/funstat_mcp
python3 server.py
# 4. 验证 MCP 配置
codex mcp get funstat
```
### 问题 2: MCP 工具不可用
**可能原因**:
- MCP 服务器未启用
- Codex 版本过低
**解决方法**:
```bash
# 1. 检查 Codex 版本 (需要 0.40.0+)
codex --version
# 2. 更新 Codex
brew upgrade codex-cli
# 3. 验证 MCP 服务器状态
codex mcp list
```
### 问题 3: Session 文件锁定
**解决方法**:
```bash
# 停止所有使用 session 的进程
pkill -f server.py
# 重启 SSE 服务器
cd /Users/lucas/chat--1003255561049/funstat_mcp
python3 server.py
```
---
## 📖 相关文档
### Codex CLI 文档
- [Codex CLI GitHub](https://github.com/openai/codex-cli)
- [MCP 官方文档](https://modelcontextprotocol.io)
### Funstat MCP 文档
- [README.md](README.md) - 项目主文档
- [PAGINATION_SUCCESS_REPORT.md](PAGINATION_SUCCESS_REPORT.md) - 翻页功能
- [CURSOR_MCP_SETUP.md](CURSOR_MCP_SETUP.md) - Cursor IDE 配置
- [SSE_CONVERSION_COMPLETE.md](SSE_CONVERSION_COMPLETE.md) - SSE 转换
---
## 🎊 配置完成!
### ✅ 当前状态
```
✅ Codex MCP 配置已添加
✅ 配置文件已更新 (~/.codex/config.toml)
✅ SSE 服务器运行中
✅ Funstat MCP 工具已可用
```
### 🚀 验证步骤
1. **检查配置**:
```bash
codex mcp list
```
2. **启动 Codex**:
```bash
codex
```
3. **测试搜索**:
```
Codex> 列出可用的 MCP 工具
Codex> 搜索包含"翻译"的Telegram用户
```
### 📝 快速命令
```bash
# 查看 MCP 服务器
codex mcp list
# 启动 Codex
codex
# 一次性命令
codex exec "搜索翻译相关用户"
# 检查 SSE 服务器
ps aux | grep server.py
```
---
## 💡 使用技巧
### 1. 组合多个工具
```bash
codex exec "先搜索'翻译'相关用户,然后查询前5个用户的详细信息"
```
### 2. 批量处理
```bash
codex exec "搜索以下关键词并汇总结果: 翻译, subtitle, fansub"
```
### 3. 导出结果
```bash
codex exec "搜索翻译用户并导出为JSON格式"
```
---
## ✨ 现在支持的 AI 工具
| AI 工具 | 配置方式 | 配置文件 | 状态 |
|---------|---------|----------|------|
| **Claude Code** | 项目配置 | `claude-code-mcp-config.json` | ✅ |
| **Cursor IDE** | 项目配置 | `.cursor/mcp.json` | ✅ |
| **Codex CLI** | 全局配置 | `~/.codex/config.toml` | ✅ |
---
**配置完成时间**: 2025-10-27
**SSE 服务器**: ✅ 运行中
**Codex MCP**: ✅ 已配置
🎉 **Codex CLI 现在可以使用 Funstat MCP 工具了!** 🎉
---
## 🎯 下一步
1. **启动 Codex**: `codex`
2. **测试工具**: 让 Codex 搜索 Telegram 用户
3. **探索功能**: 尝试不同的搜索关键词和翻页功能
**提示**: Codex 支持自然语言交互,你可以用中文或英文与它对话!