591 lines
11 KiB
Markdown
591 lines
11 KiB
Markdown
# 为其他用户部署 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 工具。
|