chore: initial commit

2025-11-01 21:58:03 +08:00
commit a05a7dd40e
65 changed files with 16590 additions and 0 deletions
--- a/docs/QUICK_START_GUIDE.md
+++ b/docs/QUICK_START_GUIDE.md
@@ -0,0 +1,694 @@
+# 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