funstat-mcp/docs/QUICK_START_GUIDE.md

# Funstat MCP Server - 快速开始教程

欢迎使用 Funstat MCP Server！本教程将手把手教你如何在 **5 分钟内** 完成配置，让你能够通过 Claude Code 访问 10 亿+ Telegram 用户数据。

---

## 📋 前置要求检查

在开始之前，请确保你已经具备：

- ✅ **macOS** 系统（本教程基于 macOS，其他系统类似）
- ✅ **Python 3.10+** 已安装
- ✅ **Claude Code** 已安装
- ✅ **Session 文件** 已创建（`funstat_bot_session.session`）

### 检查 Python 版本

打开终端，运行：

```bash
python3 --version
```

应该看到类似输出：
```
Python 3.10.0 或更高版本
```

如果 Python 版本过低，请先升级 Python。

---

## 🚀 第一步：安装依赖（2分钟）

### 1.1 打开终端

**方法 1**: 按 `Cmd + Space`，输入 "Terminal"，按回车

**方法 2**: 打开 Finder → 应用程序 → 实用工具 → 终端

### 1.2 进入项目目录

在终端中运行：

```bash
cd /Users/lucas/chat--1003255561049/funstat_mcp
```

### 1.3 安装 Python 依赖

运行以下命令：

```bash
pip3 install -r requirements.txt
```

**预期输出**：
```
Collecting telethon>=1.34.0
  Downloading telethon-1.34.0-py3-none-any.whl
Collecting mcp>=0.9.0
  Downloading mcp-0.9.0-py3-none-any.whl
...
Successfully installed telethon-1.34.0 mcp-0.9.0 pydantic-2.5.0
```

**如果遇到权限错误**，使用：
```bash
pip3 install --user -r requirements.txt
```

### 1.4 验证安装

运行：

```bash
python3 -c "import telethon; import mcp; print('✅ 依赖安装成功！')"
```

应该看到：
```
✅ 依赖安装成功！
```

---

## ⚙️ 第二步：配置 Claude Code（2分钟）

### 2.1 找到 Claude Code 配置文件

Claude Code 的配置文件位于：

```
~/Library/Application Support/Claude/claude_desktop_config.json
```

### 2.2 方法一：使用命令行编辑（推荐）

在终端中运行以下命令：

```bash
# 创建配置文件目录（如果不存在）
mkdir -p ~/Library/Application\ Support/Claude

# 使用 nano 编辑器打开配置文件
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

### 2.3 添加 MCP 配置

**如果文件是空的或不存在**，完整复制以下内容：

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

**如果文件已经有内容**，在 `mcpServers` 部分添加 `"funstat"` 配置：

```json
{
  "mcpServers": {
    "现有的MCP服务器配置": {
      ...
    },
    "funstat": {
      "command": "python3",
      "args": [
        "/Users/lucas/chat--1003255561049/funstat_mcp/server.py"
      ]
    }
  }
}
```

### 2.4 保存并退出

如果使用 nano 编辑器：
1. 按 `Ctrl + O` 保存
2. 按 `Enter` 确认
3. 按 `Ctrl + X` 退出

### 2.5 方法二：使用图形界面编辑（替代方案）

**第 1 步**：在 Finder 中打开配置目录

在终端中运行：
```bash
open ~/Library/Application\ Support/Claude
```

**第 2 步**：找到或创建 `claude_desktop_config.json` 文件

**第 3 步**：用文本编辑器打开，复制上面的配置内容

**第 4 步**：保存文件

### 2.6 验证配置文件格式

运行以下命令验证 JSON 格式是否正确：

```bash
python3 -c "import json; f=open(open('$HOME/Library/Application Support/Claude/claude_desktop_config.json')); json.load(f); print('✅ 配置文件格式正确！')"
```

如果格式错误，会显示具体的错误信息。

---

## 🔄 第三步：重启 Claude Code（30秒）

### 3.1 完全退出 Claude Code

**方法 1**: 右键点击 Dock 中的 Claude Code 图标 → 退出

**方法 2**: 在 Claude Code 中按 `Cmd + Q`

**重要**: 确保完全退出，而不是只关闭窗口！

### 3.2 重新启动 Claude Code

从应用程序文件夹或 Launchpad 启动 Claude Code

### 3.3 检查 MCP 服务器状态

启动后，在 Claude Code 中输入：

```
你好，请告诉我当前有哪些可用的 MCP 工具？
```

Claude 应该会列出包含 `funstat_` 开头的工具，例如：
- funstat_search
- funstat_topchat
- funstat_balance
等

---

## ✅ 第四步：测试功能（1分钟）

### 4.1 测试搜索功能

在 Claude Code 中输入：

```
帮我搜索 Python 相关的 Telegram 群组
```

**预期响应**：

Claude 会自动调用 `funstat_search` 工具，然后返回类似这样的结果：

```
我帮你搜索了 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 成员)
...

这些群组都是关于 Python 编程学习和交流的，你想了解哪个群组的更多信息吗？
```

### 4.2 测试其他功能

试试这些命令：

**查看热门群组**：
```
获取热门 Telegram 群组列表
```

**查询用户信息**：
```
查询这个测试用户 ID: 7745296119
```

**查看积分余额**：
```
我的 funstat 积分还有多少？
```

**搜索消息**：
```
搜索包含 "GPT-4" 的 Telegram 消息
```

---

## 🎯 完整使用示例

### 示例 1：寻找技术交流群

```
你: "我想找一些关于 AI 和机器学习的技术交流群"

Claude: 我帮你搜索了 AI 和机器学习相关的群组：

【AI 相关群组】
1. AI Technology Discussion (500,000+ 成员)
   - 链接: https://t.me/...
   - 简介: AI 技术讨论...

2. Machine Learning 中文社区 (300,000+ 成员)
   - 链接: https://t.me/...
   - 简介: 机器学习中文交流...

【机器学习群组】
3. Deep Learning Researchers (200,000+ 成员)
   ...

你对哪个群组感兴趣？我可以帮你查看更详细的信息。
```

### 示例 2：批量查询

```
你: "帮我同时搜索这几个主题的群组：区块链、Web3、NFT"

Claude: [自动并行搜索三个关键词]

我已经为你搜索了三个主题，这里是结果汇总：

【区块链相关 - TOP 5】
1. Blockchain Technology (800,000 成员)
2. Crypto Trading 中文 (500,000 成员)
...

【Web3 相关 - TOP 5】
1. Web3 Developers (400,000 成员)
2. Decentralized Apps (300,000 成员)
...

【NFT 相关 - TOP 5】
1. NFT Marketplace (600,000 成员)
2. Digital Art Collectors (350,000 成员)
...

需要我提供更详细的信息吗？
```

### 示例 3：深度查询

```
你: "查询用户 @某个用户名 的详细信息"

Claude: [调用 funstat_user_info 工具]

用户信息：
- 用户名: @某个用户名
- 用户 ID: 123456789
- 注册时间: 2020-01-15
- 活跃状态: 活跃
- 加入的群组数: 50+
- 最近活跃: 2 天前

主要活跃群组：
1. Python 编程学习
2. AI 技术讨论
3. 区块链开发者社区
...

需要查看更多信息吗？
```

---

## 🔍 故障排除

### 问题 1：MCP 服务器未连接

**症状**: Claude Code 中看不到 funstat 相关工具

**解决方案**：

1. **检查配置文件路径**
   ```bash
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
   ```

   应该看到包含 `funstat` 的配置

2. **验证 server.py 文件存在**
   ```bash
   ls -l /Users/lucas/chat--1003255561049/funstat_mcp/server.py
   ```

3. **验证 Python 可以运行**
   ```bash
   python3 /Users/lucas/chat--1003255561049/funstat_mcp/server.py --help
   ```

4. **查看 Claude Code 日志**
   - 在 Claude Code 中按 `Cmd + Option + I` 打开开发者工具
   - 查看 Console 标签
   - 查找 `funstat` 或 `MCP` 相关的错误信息

### 问题 2：Session 文件错误

**症状**:
```
FileNotFoundError: Session 文件不存在
```

**解决方案**：

1. **检查 session 文件是否存在**
   ```bash
   ls -l /Users/lucas/chat--1003255561049/funstat_mcp/funstat_bot_session.session
   ```

2. **如果不存在，重新创建**
   ```bash
   cd /Users/lucas/chat--1003255561049
   python3 create_session.py
   cp funstat_bot_session.session funstat_mcp/
   ```

### 问题 3：依赖未安装

**症状**:
```
ModuleNotFoundError: No module named 'telethon'
```

**解决方案**：

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

### 问题 4：响应超时

**症状**:
```
TimeoutError: 等待 BOT 响应超时
```

**可能原因**：
1. 网络连接问题
2. Telegram 服务器繁忙
3. BOT 正在处理大量请求

**解决方案**：
1. 检查网络连接
2. 稍后重试
3. 如果持续出现，增加超时时间（编辑 `server.py`）

### 问题 5：速率限制警告

**症状**:
```
INFO: 速率限制: 等待 0.5 秒
```

**说明**: 这是**正常行为**，不是错误！

MCP 服务器自动管理请求速率，确保不超过 Telegram 的限制（18请求/秒）。稍等片刻即可。

### 问题 6：配置文件格式错误

**症状**:
```
JSONDecodeError: Expecting property name enclosed in double quotes
```

**解决方案**：

1. **使用在线 JSON 验证器检查格式**
   - 访问：https://jsonlint.com/
   - 粘贴配置文件内容
   - 检查错误提示

2. **常见错误**：
   - 缺少逗号
   - 多余的逗号
   - 使用单引号而不是双引号
   - 缺少闭合括号

3. **正确格式示例**：
   ```json
   {
     "mcpServers": {
       "funstat": {
         "command": "python3",
         "args": ["/Users/lucas/chat--1003255561049/funstat_mcp/server.py"]
       }
     }
   }
   ```

---

## 📊 性能优化建议

### 1. 利用缓存

相同的查询在 1 小时内会直接从缓存返回，速度极快（<100ms）。

**示例**：
```
第一次: "搜索 Python 群组" → 1-2秒
第二次: "搜索 Python 群组" → <100ms（缓存）
```

### 2. 批量查询

可以在一次对话中要求 Claude 执行多个查询：

```
你: "帮我同时搜索：Python、JavaScript、Go 这三种编程语言的学习群组"

Claude: [自动并行执行三次搜索，整理结果]
```

### 3. 精确搜索

使用更具体的关键词可以获得更准确的结果：

❌ 不够精确: "编程"
✅ 更精确: "Python 机器学习"
✅ 最精确: "Python TensorFlow 深度学习"

---

## 🔐 安全最佳实践

### 1. Session 文件安全

⚠️ **重要**: Session 文件相当于你的 Telegram 账号密码

**保护措施**：

```bash
# 设置严格的文件权限（只有你能读写）
chmod 600 /Users/lucas/chat--1003255561049/funstat_mcp/funstat_bot_session.session
```

**检查权限**：
```bash
ls -l /Users/lucas/chat--1003255561049/funstat_mcp/funstat_bot_session.session
```

应该看到：
```
-rw------- 1 lucas staff ... funstat_bot_session.session
```

### 2. 定期更换 Session

建议每 3-6 个月更换一次：

```bash
# 删除旧 session
rm /Users/lucas/chat--1003255561049/funstat_mcp/funstat_bot_session.session

# 创建新 session
cd /Users/lucas/chat--1003255561049
python3 create_session.py

# 复制到 MCP 目录
cp funstat_bot_session.session funstat_mcp/

# 重启 Claude Code
```

### 3. 使用独立账号

建议注册一个专门用于此项目的 Telegram 账号，不要使用主账号。

---

## 📈 高级配置

### 调整缓存时间

编辑 `server.py`，找到：

```python
CACHE_TTL = 3600  # 默认 1 小时（秒）
```

修改为你需要的值：

```python
CACHE_TTL = 7200  # 2 小时
# 或
CACHE_TTL = 1800  # 30 分钟
```

### 调整速率限制

编辑 `server.py`，找到：

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

**注意**: 不建议提高此值，可能导致 Telegram 限流。

### 调整超时时间

编辑 `server.py`，在 `send_command_and_wait` 方法中：

```python
async def send_command_and_wait(
    self,
    command: str,
    timeout: int = 10,  # 修改这里：10秒超时
    use_cache: bool = True
):
```

修改为：

```python
timeout: int = 15,  # 15秒超时
```

---

## 🎓 学习资源

### MCP 相关

- **MCP 官方文档**: https://modelcontextprotocol.io/
- **Claude Code 文档**: https://docs.anthropic.com/claude/docs

### Telegram Bot API

- **Telegram Bot API**: https://core.telegram.org/bots/api
- **Telethon 文档**: https://docs.telethon.dev/

### 项目文档

- **本地文档**: `/Users/lucas/chat--1003255561049/funstat_mcp/README.md`
- **MrDoc 文档**: http://202.79.167.23:8081/project-89/

---

## 💡 使用技巧

### 技巧 1：组合查询

```
你: "帮我找 Python 和 AI 相关的群组，要求成员数超过 10 万"

Claude: [自动搜索并筛选]
```

### 技巧 2：定期查询

```
你: "每周帮我查一次我的 funstat 积分余额"

Claude: [可以设置提醒或定期查询]
```

### 技巧 3：数据分析

```
你: "分析一下最近区块链领域最活跃的 10 个群组"

Claude: [搜索并分析数据]
```

---

## 📞 获取帮助

### 自助诊断

运行测试脚本：

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

### 查看日志

```bash
# 查看最近的日志
tail -f ~/.claude_code/logs/mcp.log
```

### 联系支持

- **查看文档**: http://202.79.167.23:8081/project-89/doc-392/
- **GitHub Issues**: (如果有的话)

---

## ✅ 快速检查清单

在使用前，确保：

- [ ] Python 3.10+ 已安装
- [ ] 依赖已安装（`pip3 install -r requirements.txt`）
- [ ] Session 文件存在且有正确权限
- [ ] Claude Code 配置文件已正确修改
- [ ] Claude Code 已完全重启
- [ ] 测试查询成功

---

## 🎉 恭喜！

如果你完成了以上所有步骤，你现在已经可以：

✅ 通过自然语言查询 10 亿+ Telegram 用户数据
✅ 搜索群组、频道、用户
✅ 分析 Telegram 社区趋势
✅ 自动化 Telegram 数据收集

**开始探索吧！** 🚀

---

**文档版本**: 1.0
**最后更新**: 2025-10-26
**适用于**: macOS, Claude Code, Funstat MCP Server v1.0