# 为其他用户部署 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 工具。