# 在 Claude Code 中配置 Funstat MCP Server

## 快速配置（3 步完成）

### 第 1 步：安装依赖

```bash
cd /Users/lucas/chat--1003255561049/funstat_mcp
pip install -r requirements.txt
```

### 第 2 步：配置 Claude Code

打开 Claude Code 配置文件并添加 MCP 服务器配置：

**macOS 配置文件位置**:
- 方法 1: 在 Claude Code 中按 `Cmd+,` 打开设置，搜索 "MCP"
- 方法 2: 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`

**配置内容**:

```json
{
  "mcpServers": {
    "funstat": {
      "command": "python3",
      "args": [
        "/Users/lucas/chat--1003255561049/funstat_mcp/server.py"
      ]
    }
  }
}
```

### 第 3 步：重启 Claude Code

- 完全退出 Claude Code
- 重新启动

## 验证安装

启动 Claude Code 后，你应该能看到 MCP 服务器已连接。试试这些命令：

```
你: "帮我搜索 Python 相关的群组"
Claude: [自动调用 funstat_search 工具]
```

## 可用功能

### 1. 搜索群组/频道

```
你: "搜索区块链相关的群组"
你: "帮我找 AI 技术交流群"
你: "查找 Python 学习频道"
```

### 2. 热门排行

```
你: "获取热门群组列表"
你: "查看最活跃的频道"
```

### 3. 消息搜索

```
你: "搜索包含 'GPT-4' 的消息"
你: "查找讨论比特币的对话"
```

### 4. 用户查询

```
你: "查询用户 @username 的信息"
你: "查看用户 ID 123456789 的资料"
```

### 5. 积分管理

```
你: "我的积分还有多少？"
你: "查看我的使用统计"
```

## 工作原理

```
你的请求
    ↓
Claude Code 理解意图
    ↓
自动选择并调用 MCP 工具
    ↓
MCP Server → Telethon → @openaiw_bot
    ↓
返回结果给 Claude
    ↓
Claude 用自然语言呈现结果给你
```

## 性能特性

- ⚡ **智能缓存**: 相同查询 1 小时内立即返回（<100ms）
- 🚀 **速率管理**: 自动管理请求速率（18/秒）
- 💾 **低延迟**: 首次查询 1-2 秒，缓存命中 <100ms
- 🔄 **自动重试**: 失败请求自动重试

## 故障排除

### MCP 服务器未连接

1. 检查配置文件路径是否正确
2. 确保 Python 3 已安装：`python3 --version`
3. 确保依赖已安装：`pip list | grep telethon`

### Session 文件错误

```bash
cd /Users/lucas/chat--1003255561049
python3 create_session.py
```

然后复制生成的 session 文件到 funstat_mcp 目录。

### 查看日志

MCP 服务器会输出日志到 stderr，你可以在 Claude Code 的开发者工具中查看：

1. 打开 Claude Code
2. 按 `Cmd+Option+I` 打开开发者工具
3. 查看 Console 标签

## 示例对话

### 示例 1：搜索技术群组

```
你: "帮我找几个 Python 编程学习群组"

Claude: 我帮你搜索了 Python 相关的群组，找到了以下热门群组：

1. Python 编程学习 (152,441 成员)
2. Простой Python | Программирование (143,192 成员)
3. Learn Python (116,063 成员)
4. PythonNotes (109,769 成员)
5. Hacking Python Course Coding (100,134 成员)

你想了解哪个群组的更多信息吗？
```

### 示例 2：查询用户信息

```
你: "查询一下这个用户 ID: 7745296119"

Claude: [返回用户的详细信息，包括用户名、加入时间、活跃群组等]
```

### 示例 3：批量查询

```
你: "帮我搜索以下主题的群组：AI、区块链、Python"

Claude: [同时搜索多个关键词并整理结果]
```

## 高级配置

### 调整缓存时间

编辑 `server.py` 中的 `CACHE_TTL` 变量：

```python
CACHE_TTL = 3600  # 默认 1 小时，单位：秒
```

### 调整速率限制

编辑 `server.py` 中的速率限制配置：

```python
RATE_LIMIT_PER_SECOND = 18  # 每秒最多请求数
```

### 调整超时时间

在调用工具时可以调整超时：

```python
# 在 call_tool 方法中
response = await self.send_command_and_wait(command, timeout=15)  # 15 秒超时
```

## 数据库规模

Funstat BOT 数据库包含：

- 👥 **1,012,339,264** 用户
- 📱 **50,704,308** 群组/频道
- 💬 **91,122,802,688** 消息

## 安全提示

⚠️ **Session 文件安全**:
- Session 文件相当于你的 Telegram 账号密码
- 不要分享给他人
- 不要上传到公开的 Git 仓库
- 建议定期更换（删除旧 session，重新创建）

## 更多文档

- 完整功能列表: http://202.79.167.23:8081/project-89/doc-384/
- 架构设计: http://202.79.167.23:8081/project-89/doc-385/
- 流程图: http://202.79.167.23:8081/project-89/doc-391/

---

**🎉 享受通过 Claude Code 访问 10 亿+ Telegram 用户数据的便利吧！**