funstat BOT MCP 封装 - 系统架构规划

# funstat BOT MCP 封装 - 系统架构规划

## 项目目标

将 Telegram BOT `@openaiw_bot` (funstat | infostat) 封装成 MCP (Model Context Protocol) 工具，使 Claude Code 能够直接调用该 BOT 的所有功能。

---

## 核心架构设计

### 1. 技术栈选择

**✅ 选择方案: 基于 Telegram Bot API**

- **原因**: 
  - 没有请求限制
  - API 稳定可靠
  - 易于集成和维护
  - 支持长轮询(long polling)和 Webhook

- **替代方案**: 
  - ❌ Telegram Web 自动化 (限制多，不稳定)
  - ❌ MTProto API (过于复杂)

### 2. 系统组件

```
┌─────────────┐      MCP Protocol      ┌──────────────────┐
│             │◄─────────────────────►│                  │
│ Claude Code │                       │   MCP Server     │
│             │                       │  (Python)        │
└─────────────┘                       └──────────────────┘
                                              │
                                              │ Telegram Bot API
                                              │ (getUpdates + sendMessage)
                                              ▼
                                      ┌──────────────────┐
                                      │                  │
                                      │  Telegram Bot    │
                                      │  (自己的BOT)     │
                                      │                  │
                                      └──────────────────┘
                                              │
                                              │ 用户消息
                                              │ 命令交互
                                              ▼
                                      ┌──────────────────┐
                                      │                  │
                                      │  @openaiw_bot    │
                                      │  (funstat)       │
                                      │                  │
                                      └──────────────────┘
```

### 3. 数据流程

1. **Claude Code 调用 MCP 工具**
   - 用户向 Claude 发出指令
   - Claude 选择合适的 MCP 工具
   - 发送工具调用请求

2. **MCP Server 处理请求**
   - 解析工具名称和参数
   - 构造 Telegram 命令
   - 通过 Bot API 发送消息

3. **Telegram Bot 转发消息**
   - 我们的 BOT 发送消息给 @openaiw_bot
   - 消息内容可以是命令、查询、用户ID等

4. **funstat BOT 响应**
   - @openaiw_bot 处理请求
   - 返回结果（文本、图片、按钮等）

5. **MCP Server 接收响应**
   - 通过 getUpdates 轮询获取消息
   - 过滤出 @openaiw_bot 的响应
   - 格式化响应内容

6. **返回给 Claude Code**
   - 将格式化后的内容返回
   - Claude 向用户展示结果

---

## MCP 工具设计

### 核心工具列表

| 工具名 | 功能 | 参数 | Telegram 命令 |
|--------|------|------|---------------|
| `openaiw_start` | 启动 BOT | 无 | `/start` |
| `openaiw_menu` | 显示菜单和状态 | 无 | `/menu` |
| `openaiw_balance` | 查询积分 | 无 | `/balance` |
| `openaiw_search_groups` | 搜索群组 | query | `/search {query}` |
| `openaiw_search_by_text` | 搜索消息文本 | text | `/text {text}` |
| `openaiw_search_by_name` | 搜索用户名 | name | `/human {name}` |
| `openaiw_query_user` | 查询用户信息 | user_id | `{user_id}` |
| `openaiw_top_chats` | 热门群组榜 | 无 | `/topchat` |
| `openaiw_custom_command` | 自定义命令 | command | `{command}` |

### 扩展工具（未来）

- `openaiw_buy` - 购买积分
- `openaiw_hide_data` - 隐藏数据
- `openaiw_tracked_users` - 查看追踪用户
- `openaiw_set_language` - 设置语言

---

## 技术实现细节

### 1. 消息发送机制

```python
def send_message(text: str) -> bool:
    """发送消息给 BOT"""
    url = f"{BASE_URL}/sendMessage"
    data = {
        "chat_id": MY_CHAT_ID,  # 我的聊天 ID
        "text": text
    }
    response = requests.post(url, json=data)
    return response.json().get('ok', False)
```

### 2. 消息接收机制

**方案: Long Polling (getUpdates)**

```python
def wait_for_response(timeout=20) -> List[Message]:
    """等待 BOT 响应"""
    start_time = time.time()
    responses = []
    
    while time.time() - start_time < timeout:
        updates = get_updates(offset=last_update_id)
        
        for update in updates['result']:
            msg = update['message']
            
            # 过滤: 只要 BOT 发送的消息
            if msg['from']['is_bot'] and msg['chat']['id'] == MY_CHAT_ID:
                responses.append(msg)
        
        if responses:
            break
        
        time.sleep(0.5)
    
    return responses
```

### 3. 响应格式化

支持的消息类型：
- ✅ 文本消息
- ✅ 图片消息（带说明）
- ✅ 文档消息
- ✅ 内联键盘按钮
- ✅ 回复键盘

---

## 配置管理

### 环境变量

```bash
OPENAIW_BOT_TOKEN=8410096573:AAFLJbWUp2Xog0oeoe7hfBlVqR7ChoSl9Pg
OPENAIW_CHAT_ID=7363537082
```

### 配置文件 (config.json)

```json
{
  "bot_token": "8410096573:AAFLJbWUp2Xog0oeoe7hfBlVqR7ChoSl9Pg",
  "chat_id": 7363537082,
  "response_timeout": 20,
  "max_retries": 3
}
```

---

## 错误处理策略

### 1. 超时处理
- 默认等待 20 秒
- 超时返回友好提示
- 可配置超时时间

### 2. 网络错误
- 自动重试（最多 3 次）
- 指数退避策略
- 记录错误日志

### 3. BOT 无响应
- 返回明确提示
- 建议用户检查积分余额
- 提供替代方案

---

## 部署方案

### 方式 1: 本地运行

```bash
# 安装依赖
pip install mcp requests

# 运行服务器
python server.py
```

### 方式 2: Docker 容器

```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY server.py .
CMD ["python", "server.py"]
```

### 方式 3: Claude Code 集成

在 `claude_desktop_config.json` 中配置：

```json
{
  "mcpServers": {
    "openaiw-bot": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}
```

---

## 测试计划

### 1. 单元测试
- ✅ 消息发送功能
- ✅ 消息接收功能
- ✅ 响应格式化功能

### 2. 集成测试
- ✅ 每个 MCP 工具
- ✅ 错误处理流程
- ✅ 超时处理

### 3. 端到端测试
- ✅ Claude Code 调用测试
- ✅ 实际查询功能验证

---

## 性能优化

### 1. 缓存机制
- 缓存 BOT 状态（积分、用户信息）
- 设置合理的过期时间

### 2. 并发处理
- 支持多个并发请求
- 使用异步 I/O

### 3. 轮询优化
- 使用 long polling
- 减少不必要的 API 调用

---

## 安全考虑

### 1. Token 安全
- ✅ 不要硬编码 Token
- ✅ 使用环境变量或配置文件
- ✅ 不要提交到 Git

### 2. 权限控制
- 只允许特定用户使用
- 验证 chat_id

### 3. 日志脱敏
- 隐藏敏感信息
- 安全地记录错误

---

## 下一步行动

1. ✅ 完成架构设计
2. ⏳ 绘制流程图
3. ⏳ 实现 MCP 服务器
4. ⏳ 创建配置文件
5. ⏳ 编写测试用例
6. ⏳ 部署和集成测试

---

**创建时间**: 2025-10-26  
**状态**: 🔄 架构设计完成，待实现