419 lines
8.7 KiB
Markdown
419 lines
8.7 KiB
Markdown
# 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:8094/sse funstat
|
|
```
|
|
|
|
**输出**:
|
|
```
|
|
Added global MCP server 'funstat'.
|
|
```
|
|
|
|
### 2. 配置验证 ✅
|
|
|
|
**配置详情**:
|
|
```
|
|
Name: funstat
|
|
URL: http://127.0.0.1:8094/sse
|
|
Transport: streamable_http
|
|
Status: enabled
|
|
Auth: Unsupported
|
|
```
|
|
|
|
### 3. 配置文件更新 ✅
|
|
|
|
**文件位置**: `~/.codex/config.toml`
|
|
|
|
**新增内容**:
|
|
```toml
|
|
[mcp_servers.funstat]
|
|
url = "http://127.0.0.1:8094/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:8094/sse - enabled Unsupported
|
|
```
|
|
|
|
### 查看服务器详情
|
|
|
|
```bash
|
|
codex mcp get funstat
|
|
```
|
|
|
|
**输出**:
|
|
```
|
|
funstat
|
|
enabled: true
|
|
transport: streamable_http
|
|
url: http://127.0.0.1:8094/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:8094/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:8094/sse
|
|
│
|
|
┌─────────────▼──────────────────┐
|
|
│ Funstat MCP Server (SSE) │
|
|
│ funstat_mcp/server.py │
|
|
│ 端口: 8094 │
|
|
└─────────────┬──────────────────┘
|
|
│
|
|
│ 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:8094/sse \
|
|
--bearer-token-env-var FUNSTAT_TOKEN \
|
|
funstat
|
|
```
|
|
|
|
### 手动编辑配置文件
|
|
|
|
**文件**: `~/.codex/config.toml`
|
|
|
|
```toml
|
|
[mcp_servers.funstat]
|
|
url = "http://127.0.0.1:8094/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:8094/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 支持自然语言交互,你可以用中文或英文与它对话!
|