chore: initial commit

docs/QUICK_REFERENCE.md

@@ -0,0 +1,111 @@
+# 🚀 Funstat MCP 快速参考
+
+## 📍 关键文件位置
+
+| 文件 | 路径 |
+|------|------|
+| **MCP 服务器** | `/Users/lucas/chat--1003255561049/funstat_mcp/server.py` |
+| **Session 文件** | `~/telegram_sessions/funstat_bot.session` |
+| **AgentAPI 配置** | `/Users/lucas/牛马/config.json` |
+| **测试客户端** | `/Users/lucas/chat--1003255561049/test_mcp_client.py` |
+| **重启指南** | `/Users/lucas/chat--1003255561049/RESTART_AGENTAPI_GUIDE.md` |
+| **完整报告** | `/Users/lucas/chat--1003255561049/FUNSTAT_MCP_DEPLOYMENT_REPORT.md` |
+
+---
+
+## ⚡ 快速命令
+
+### 测试 Funstat MCP（立即可用）
+```bash
+python3 /Users/lucas/chat--1003255561049/test_mcp_client.py
+```
+
+### 重启 AgentAPI
+```bash
+# 停止
+pkill -f "agentapi mcp"
+
+# 启动
+cd /Users/lucas/牛马 && ./agentapi mcp -c config.json
+```
+
+### 检查配置
+```bash
+# 查看 funstat 配置
+cat /Users/lucas/牛马/config.json | grep -A 5 "funstat"
+
+# 验证 JSON 格式
+python3 -m json.tool /Users/lucas/牛马/config.json > /dev/null && echo "✅" || echo "❌"
+```
+
+---
+
+## 🎯 8个 Funstat MCP 工具
+
+| 工具 | 命令 | 功能 | 测试状态 |
+|------|------|------|---------|
+| funstat_start | `/start` | 欢迎消息 | ✅ 成功 |
+| funstat_search | `/search <关键词>` | 搜索群组/频道 | ✅ 成功 |
+| funstat_topchat | `/topchat` | 热门聊天 | ✅ 成功 |
+| funstat_menu | `/menu` | 显示菜单 | ✅ 成功 |
+| funstat_balance | `/余额` | 查询积分 | ⚠️ 需调整 |
+| funstat_text | `/text <文本>` | 文本搜索 | ⏳ 未测试 |
+| funstat_human | `/human <姓名>` | 姓名搜索 | ⏳ 未测试 |
+| funstat_user_info | `@username` | 用户详情 | ⏳ 未测试 |
+
+---
+
+## 📊 项目状态
+
+### ✅ 已完成
+- 完整的 MCP 服务器实现（8个工具）
+- Session 文件创建和安全管理
+- AgentAPI 配置添加
+- 速率限制（18 req/s）和缓存（1小时）
+- 独立测试客户端
+- 完整文档和指南
+- Docker 部署方案
+
+### 🎯 核心测试结果
+- ✅ Telegram 连接正常
+- ✅ BOT 通信正常（@openaiw_bot）
+- ✅ 5个工具测试通过
+- ✅ 独立运行验证成功
+
+### ⏳ 待确认
+- AgentAPI 是否能识别并加载 funstat 配置
+- 需要重启 AgentAPI 后验证
+
+---
+
+## 🔧 故障排查一行命令
+
+```bash
+# 全面检查
+echo "Session:" && ls -lh ~/telegram_sessions/funstat_bot.session && \
+echo "\nConfig:" && cat /Users/lucas/牛马/config.json | grep -A 3 "funstat" && \
+echo "\nMCP Test:" && python3 /Users/lucas/chat--1003255561049/test_mcp_client.py
+```
+
+---
+
+## 📞 联系信息
+
+- **项目目录**: `/Users/lucas/chat--1003255561049/`
+- **AgentAPI 目录**: `/Users/lucas/牛马/`
+- **BOT**: @openaiw_bot (KT超级数据)
+- **账号**: @xiaobai_80 (ID: 7363537082)
+
+---
+
+## 🎓 技术栈
+
+- **Telethon**: Telegram MTProto 客户端
+- **MCP**: Model Context Protocol
+- **Python 3**: 异步编程（asyncio）
+- **AgentAPI**: 自定义 MCP 服务器管理器
+
+---
+
+**最后更新**: 2025-10-26 20:58
+**状态**: ✅ 配置完成，等待重启验证