doudou/funstat-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: initial commit

Browse Source
This commit is contained in:
你的用户名
2025-11-01 21:58:03 +08:00
commit a05a7dd40e
65 changed files with 16590 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

590
docs/DEPLOYMENT_FOR_OTHERS.md Normal file
View File

@@ -0,0 +1,590 @@
# 为其他用户部署 Funstat MCP 工具
## 📝 概述
这个文档说明如何让其他人（你的团队成员、朋友等）在他们自己的电脑上使用 Funstat MCP 工具。
---
## 🎯 三种部署方案
### 方案 1：完全独立部署（推荐）✅
**适用场景**：
- 每个人有自己的电脑
- 每个人有自己的 Telegram 账号
- 需要各自独立使用
**优势**：
- ✅ 完全独立，互不影响
- ✅ 每人有自己的积分和配额
- ✅ 安全性最高
- ✅ 可以使用不同的 Telegram 账号
**缺点**：
- ❌ 每人需要申请自己的 API 凭证
- ❌ 每人需要自己配置
---
### 方案 2：共享 Session（不推荐）⚠️
**适用场景**：
- 临时测试
- 演示使用
**优势**：
- ✅ 部署快速
**缺点**：
- ❌ 安全风险：所有人使用同一个 Telegram 账号
- ❌ 并发问题：可能导致 session 冲突
- ❌ 配额共享：积分被所有人共用
- ❌ **不推荐用于生产环境**
---
### 方案 3：中心化 API 服务（未来扩展）
**适用场景**：
- 大规模团队使用
- 需要统一管理
**架构**：
```
多个用户 → 中心 API 服务器 → MCP Server → @openaiw_bot
```
**说明**：这需要额外开发，当前版本不支持。
---
## 🚀 方案 1：完全独立部署指南
### 前置要求
每个用户需要：
- ✅ macOS / Linux / Windows（带 WSL）
- ✅ Python 3.10+
- ✅ Claude Code 已安装
- ✅ 一个 Telegram 账号（可以是新注册的）
### 步骤 1：分享项目文件
#### 方法 A：GitHub（推荐）
如果你的项目在 GitHub：
```bash
# 其他用户克隆仓库
git clone https://github.com/your-username/funstat-mcp.git
cd funstat-mcp
```
#### 方法 B：直接分享文件
打包项目文件夹：
```bash
# 在你的电脑上
cd /Users/lucas/chat--1003255561049
tar -czf funstat-mcp.tar.gz \
funstat_mcp/ \
create_session_safe.py \
mermaid_diagrams.md \
*.md
# 发送 funstat-mcp.tar.gz 给其他用户
```
其他用户解压：
```bash
tar -xzf funstat-mcp.tar.gz
cd funstat_mcp
```
### 步骤 2：申请 Telegram API 凭证
**重要**：每个用户需要申请自己的 API 凭证！
1. 访问：https://my.telegram.org/apps
2. 登录他们自己的 Telegram 账号
3. 创建新应用
4. 获取 `api_id` 和 `api_hash`
### 步骤 3：配置 API 凭证
编辑 `server.py` 和 `create_session_safe.py`，替换 API 凭证：
```python
# server.py 和 create_session_safe.py 中
API_ID = 你的_api_id # 替换这里
API_HASH = "你的_api_hash" # 替换这里
```
**更好的方法**：使用环境变量（推荐）
创建 `.env` 文件：
```bash
# .env
TELEGRAM_API_ID=你的_api_id
TELEGRAM_API_HASH=你的_api_hash
```
然后修改代码读取环境变量：
```python
import os
from dotenv import load_dotenv
load_dotenv()
API_ID = int(os.getenv('TELEGRAM_API_ID'))
API_HASH = os.getenv('TELEGRAM_API_HASH')
```
### 步骤 4：安装依赖
```bash
cd funstat_mcp
pip3 install -r requirements.txt
# 如果使用 .env
pip3 install python-dotenv
```
### 步骤 5：创建 Session 文件
```bash
cd ..
python3 create_session_safe.py
```
按照提示：
1. 输入手机号
2. 输入验证码
3. 如果有两步验证，输入密码
### 步骤 6：配置 Claude Code
编辑 Claude Code 配置文件：
**macOS**:
```bash
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
**Linux**:
```bash
nano ~/.config/claude-code/config.json
```
添加配置（**注意修改路径**）：
```json
{
"mcpServers": {
"funstat": {
"command": "python3",
"args": [
"/完整路径/到/funstat_mcp/server.py"
]
}
}
}
```
### 步骤 7：测试
```bash
cd funstat_mcp
python3 test_server.py
```
应该看到：
```
✅ 登录成功
✅ 已连接到: KT超级数据
✅ 当前账号: @你的用户名
```
### 步骤 8：重启 Claude Code 并使用
完全退出并重启 Claude Code，然后测试：
```
你: "帮我搜索 Python 学习群组"
```
---
## 🔐 安全配置指南
### 敏感信息管理
**不要在代码中硬编码 API 凭证！**
#### 方法 1：使用 .env 文件（推荐）
```bash
# .env
TELEGRAM_API_ID=你的api_id
TELEGRAM_API_HASH=你的api_hash
```
```python
# server.py
import os
from dotenv import load_dotenv
load_dotenv()
API_ID = int(os.getenv('TELEGRAM_API_ID'))
API_HASH = os.getenv('TELEGRAM_API_HASH')
```
**记得添加到 .gitignore**：
```bash
echo ".env" >> .gitignore
echo "*.session" >> .gitignore
```
#### 方法 2：使用配置文件
创建 `config.json`（不提交到 Git）：
```json
{
"api_id": 你的_api_id,
"api_hash": "你的_api_hash"
}
```
```python
# server.py
import json
with open('config.json') as f:
config = json.load(f)
API_ID = config['api_id']
API_HASH = config['api_hash']
```
---
## 👥 多用户部署示例
### 场景：团队 3 人使用
**用户 A**（你）：
- API ID: 24660516
- Session: ~/telegram_sessions/funstat_bot.session
- 账号: @xiaobai_80
**用户 B**（同事）：
- API ID: 12345678（他自己申请的）
- Session: ~/telegram_sessions/funstat_bot.session
- 账号: @colleague_account
**用户 C**（朋友）：
- API ID: 87654321（他自己申请的）
- Session: ~/telegram_sessions/funstat_bot.session
- 账号: @friend_account
**每个人完全独立，互不影响**。
---
## 📦 创建分发包
### 自动化部署脚本
创建一个 `setup.sh` 脚本：
```bash
#!/bin/bash
#
# Funstat MCP 自动部署脚本
#
echo "=================================="
echo "Funstat MCP 工具部署向导"
echo "=================================="
echo ""
# 检查 Python
if ! command -v python3 &> /dev/null; then
echo "❌ 未找到 Python 3"
echo "请先安装 Python 3.10 或更高版本"
exit 1
fi
echo "✅ Python 版本: $(python3 --version)"
echo ""
# 安装依赖
echo "📦 安装依赖..."
pip3 install -r requirements.txt
echo ""
# 检查 API 凭证
echo "=================================="
echo "配置 Telegram API 凭证"
echo "=================================="
echo ""
echo "请访问 https://my.telegram.org/apps"
echo "获取你的 API ID 和 API Hash"
echo ""
read -p "请输入你的 API ID: " api_id
read -p "请输入你的 API Hash: " api_hash
# 创建 .env 文件
cat > .env << EOF
TELEGRAM_API_ID=$api_id
TELEGRAM_API_HASH=$api_hash
EOF
echo "✅ API 凭证已保存到 .env 文件"
echo ""
# 创建 session
echo "=================================="
echo "创建 Telegram Session"
echo "=================================="
echo ""
echo "现在将引导你登录 Telegram 账号..."
echo ""
python3 create_session_safe.py
echo ""
echo "=================================="
echo "✅ 部署完成！"
echo "=================================="
echo ""
echo "下一步："
echo "1. 配置 Claude Code（参考文档）"
echo "2. 重启 Claude Code"
echo "3. 测试: python3 test_server.py"
echo ""
```
使用：
```bash
chmod +x setup.sh
./setup.sh
```
---
## 🌐 Web 界面部署（高级）
如果需要提供 Web 界面供多人使用，可以创建 API 服务：
### 架构
```
多个用户浏览器
↓
Web 界面 (FastAPI/Flask)
↓
认证层 (JWT)
↓
MCP Server Pool
↓
@openaiw_bot
```
### 示例代码框架
```python
# api_server.py
from fastapi import FastAPI, Depends, HTTPException
from fastapi.security import HTTPBearer
from server import FunstatMCPServer
app = FastAPI()
security = HTTPBearer()
# 用户认证（简化版本）
async def verify_token(credentials = Depends(security)):
# 实现你的认证逻辑
if credentials.credentials != "你的密钥":
raise HTTPException(status_code=401)
return credentials
@app.post("/search")
async def search(
query: str,
credentials = Depends(verify_token)
):
server = FunstatMCPServer()
await server.initialize()
result = await server.call_tool("funstat_search", {"query": query})
await server.client.disconnect()
return {"result": result}
```
**注意**：这需要额外的开发和安全配置。
---
## 🔒 安全检查清单
在分享给其他人之前，确保：
- [ ] **移除所有个人 API 凭证**
- [ ] **移除所有 session 文件**
- [ ] **添加 .gitignore**
```
.env
config.json
*.session
*.session-journal
__pycache__/
```
- [ ] **提供清晰的文档**
- [ ] **说明数据隐私政策**
- [ ] **说明使用限制**
---
## 📄 提供给用户的文档模板
创建一个 `README_FOR_USERS.md`：
```markdown
# Funstat MCP 工具 - 用户指南
## 快速开始
1. 申请 Telegram API 凭证
访问：https://my.telegram.org/apps
2. 安装依赖
```bash
pip3 install -r requirements.txt
```
3. 配置 API 凭证
编辑 `server.py` 替换 API_ID 和 API_HASH
4. 创建 Session
```bash
python3 create_session_safe.py
```
5. 配置 Claude Code
添加配置到 Claude Code 配置文件
6. 测试
```bash
python3 test_server.py
```
## 支持
如有问题，请联系：[你的联系方式]
```
---
## 🎯 最佳实践总结
### 推荐做法 ✅
1. **每个用户独立部署**
- 各自申请 API 凭证
- 各自创建 session
- 各自配置 Claude Code
2. **使用环境变量**
- 不在代码中硬编码凭证
- 使用 .env 文件
- 添加到 .gitignore
3. **提供自动化脚本**
- setup.sh 一键部署
- 详细的使用文档
- 故障排除指南
### 避免做法 ❌
1. **不要共享 session 文件**
- 安全风险
- 并发冲突
- 积分混乱
2. **不要在 Git 中提交敏感信息**
- API 凭证
- Session 文件
- 配置文件
3. **不要使用同一个 API 凭证**
- 可能违反 Telegram ToS
- 配额限制问题
---
## 💡 常见问题
### Q: 多个用户会互相影响吗？
A: 不会。只要每个用户：
- 使用自己的 API 凭证
- 创建自己的 session
- 在自己的电脑上运行
就完全独立，互不影响。
### Q: 需要购买服务器吗？
A: 不需要。每个用户在自己的电脑上运行 MCP 服务器即可。
### Q: 可以共享一个 Telegram 账号吗？
A: 技术上可以，但**强烈不推荐**：
- 安全风险
- Session 冲突
- 积分共享问题
### Q: 如何限制使用次数？
A: 可以在 MCP 服务器中添加使用计数：
```python
# server.py
class FunstatMCPServer:
def __init__(self):
self.usage_count = 0
self.usage_limit = 100 # 每天限制
async def call_tool(self, name, arguments):
if self.usage_count >= self.usage_limit:
raise Exception("今日使用次数已达上限")
self.usage_count += 1
# ... 原有逻辑
```
---
## 📞 支持和帮助
如果其他用户在部署时遇到问题：
1. 查看文档：`QUICK_START_GUIDE.md`
2. 运行诊断：`python3 test_server.py`
3. 检查 session：`~/telegram_sessions/check_session.sh`
4. 联系你获取支持
---
**部署给其他用户？完全可以！** ✅
只要每个人按照这个指南独立部署，就可以安全、稳定地使用 Funstat MCP 工具。