funstat-mcp/README.md

# Funstat MCP 完整打包

**版本**: 1.16.0
**打包时间**: 2025-10-27
**协议**: MCP Streamable HTTP (2025-03-26+)

## 项目说明

Funstat MCP 提供一个面向多客户端的统一接口，将 Telegram 上的 @openaiw_bot 能力封装为标准化的 MCP 工具。项目集成速率限制、响应缓存与 SSE 输出，方便 Codex、Cursor、Claude Code 等开发工具快速调用。配套脚本覆盖环境初始化、会话创建与生产部署，使得在新机器上即可一键启动 Funstat 服务。

---

> ⚠️ **端口更新**：当前本地部署已改为监听 `http://127.0.0.1:8094`（原默认 8091）。请在 Codex、Cursor、Claude Code 等客户端更新为 `http://127.0.0.1:8094/sse`。

## ⚙️ 新版数据流概览

- **PostgreSQL 本地存储**：所有 MCP 查询结果会自动写入本地 Postgres（默认通过 `docker compose up -d postgres` 启动，端口 `5433`）。数据包含原始返回、解析后的实体，以及同步状态。
- **自动远端沉淀**：后台会周期性将去重后的最新数据打包为 JSON，并通过 `sshpass` 上传到 `172.16.74.159` 的 `~/funstat_data/inbox` 目录，方便集中备份（暂不直接对外提供查询）。
- **配置模块化**：`core/config.py` + `.env` 控制 Telegram API、Bot Token、数据库与同步参数。每位同事只需复制 `.env.example`，填写自己的 session / token 即可。
- **Bot 可热切换**：所有脚本与服务器都不再写死 token，替换 `.env` 中的 `TELEGRAM_BOT_TOKEN` 即可切换镜像机器人。
- **默认镜像机器人**：发行包已预置最新官方镜像 `@ktqiangda_bot`（Token：`7321478881:AAFVmSXsfAbXI2Sfx9Sg3UW5ufAKvPsbO4U`）。如后续提供新的镜像，只需改 `.env` 即可。

### 快速启动顺序
1. `cp .env.example .env` 并根据实际环境填写（尤其是 Telegram API、Bot Token、session 路径）。
2. 启动本地 Postgres：`docker compose up -d postgres`（如本机已有 5433 占用，可在 `.env` 里改为其他端口）。
3. 安装依赖：`pip3 install -r requirements.txt --user --break-system-packages`。
4. 使用自己的 Telegram 账号创建 session：`python3 scripts/create_session_safe.py`。
5. 运行服务器：`cd core && python3 server.py` 或 `./start_sse_prod.sh`。

只要 `.env` 中的远端 SSH 信息保持有效，所有数据会自动异步推送到服务器侧的归档目录，无需额外手动操作。

## 📦 包内容概览

这个打包包含了完整的 Funstat MCP 服务器实现,以及所有相关文档、配置和工具。

### 目录结构

```
funstat_mcp_package/
├── README.md                    # 本文件
├── core/                        # 核心代码
│   ├── server.py               # MCP 服务器主程序 ⭐️
│   ├── start_sse_prod.sh       # 生产环境启动脚本 ⭐️
│   ├── setup.sh                # 一键安装脚本
│   └── ...                     # 其他测试和调试脚本
├── docs/                        # 文档
│   ├── ALL_AI_TOOLS_MCP_SETUP.md        # 统一配置指南 ⭐️
│   ├── CODEX_CLI_MCP_SETUP.md           # Codex CLI 配置
│   ├── CURSOR_MCP_SETUP.md              # Cursor IDE 配置
│   ├── STREAMABLE_HTTP_FIX_FINAL.md     # 协议修复文档 ⭐️
│   ├── 007翻译客户获取-多工具组合方案.md # 客户获取方案
│   ├── 007翻译客户获取-执行报告.md       # 执行报告
│   └── ...                               # 其他技术文档
├── scripts/                     # 工具脚本
│   ├── funstat_auto_query.py   # 自动查询客户脚本 ⭐️
│   ├── analyze_customers_v2.py # 客户分析脚本
│   └── ...                     # 其他辅助脚本
├── customer_data/               # 客户数据
│   ├── funstat_query_results.json       # 原始查询结果
│   ├── 高质量客户清单.json              # 高质量客户列表
│   └── 客户分类清单.json                # 分类客户列表
└── config_examples/             # 配置示例
    ├── cursor-mcp.json          # Cursor IDE 配置
    └── claude-code-mcp-config.json # Claude Code 配置
```

---

## 🎯 核心功能

### MCP 工具列表 (8个)

| 工具名 | 功能 | 对应命令 |
|--------|------|---------|
| `funstat_start` | 启动会话 | `/start` |
| `funstat_balance` | 查询余额 | `/余额` |
| `funstat_search` | 搜索群组 | `/search [关键词]` |
| `funstat_topchat` | 热门群组 | `/topchat` |
| `funstat_menu` | 显示菜单 | `/menu` |
| `funstat_text` | 搜索消息内容 | `/text [关键词]` |
| `funstat_human` | 搜索用户 | `/human [关键词]` |
| `funstat_user_info` | 查询用户详情 | `/user_info [username]` |

### 协议支持

- ✅ **Streamable HTTP** (MCP 2025-03-26+) - 主要协议
- ✅ **AgentAPI Proxy** - 用于 Claude Code 和 Cursor
- ✅ **直接 HTTP** - Codex CLI 原生支持

### 客户端兼容性

| 客户端 | 配置方式 | 状态 |
|--------|---------|------|
| **Claude Code** | AgentAPI Proxy | ✅ 已测试 |
| **Cursor IDE** | `.cursor/mcp.json` | ✅ 已测试 |
| **Codex CLI** | `~/.codex/config.toml` | ✅ 已修复 (405错误) |

---

## 🚀 快速开始

### 前置要求

1. **Python 3.9+**
2. **Telegram Session 文件**: `/Users/lucas/telegram_sessions/funstat_bot.session`
3. **依赖包**:
   - `mcp` (1.16.0+)
   - `telethon`
   - `starlette`
   - `uvicorn`

### 安装步骤

#### 1. 安装依赖

```bash
cd core
chmod +x setup.sh
./setup.sh
```

或手动安装:

```bash
pip3 install mcp telethon starlette uvicorn
```

#### 2. 配置 Session 文件

确保你有有效的 Telegram session 文件:

```bash
ls -l /Users/lucas/telegram_sessions/funstat_bot.session
```

如果没有,请先创建 session (参考 `docs/SESSION_MANAGEMENT.md`)。

#### 3. 启动 MCP 服务器

**生产环境 (推荐)**:

```bash
cd core
chmod +x start_sse_prod.sh
./start_sse_prod.sh
```

**开发环境**:

```bash
cd core
python3 server.py
```

服务器将在 `http://127.0.0.1:8091/sse` 启动。

#### 4. 配置客户端

**Codex CLI**:

```bash
codex mcp add --url http://127.0.0.1:8091/sse funstat
codex mcp get funstat  # 验证配置
```

**Cursor IDE**:

复制 `config_examples/cursor-mcp.json` 到你的项目 `.cursor/` 目录:

```bash
mkdir -p /path/to/your/project/.cursor
cp config_examples/cursor-mcp.json /path/to/your/project/.cursor/mcp.json
```

**Claude Code**:

已自动配置 (通过 AgentAPI)。

---

## 📚 文档索引

### 设置与配置

- **`docs/ALL_AI_TOOLS_MCP_SETUP.md`** - 所有 AI 工具的统一配置指南 ⭐️
- **`docs/CODEX_CLI_MCP_SETUP.md`** - Codex CLI 详细配置
- **`docs/CURSOR_MCP_SETUP.md`** - Cursor IDE 详细配置
- **`docs/AGENTAPI_PROXY_SETUP.md`** - AgentAPI 代理配置

### 技术文档

- **`docs/STREAMABLE_HTTP_FIX_FINAL.md`** - Streamable HTTP 协议修复说明 ⭐️
- **`docs/MCP_SSE_FIX_SUMMARY.md`** - SSE 端点修复总结
- **`docs/PERMANENT_SSE_FIX.md`** - 永久修复方案
- **`docs/SESSION_MANAGEMENT.md`** - Session 管理文档

### 部署文档

- **`docs/FUNSTAT_MCP_DEPLOYMENT_REPORT.md`** - 部署报告
- **`docs/DOCKER_DEPLOYMENT.md`** - Docker 部署方案
- **`docs/DEPLOYMENT_FOR_OTHERS.md`** - 为他人部署指南

### 客户获取文档

- **`docs/007翻译客户获取-多工具组合方案.md`** - 客户获取策略 ⭐️
- **`docs/007翻译客户获取-执行报告.md`** - 执行结果报告 ⭐️

---

## 🔧 核心文件说明

### `core/server.py` (主程序)

**关键实现**:

```python
from mcp.server.streamable_http import StreamableHTTPServerTransport

# 创建 Streamable HTTP 传输
session_id = str(uuid.uuid4())
transport = StreamableHTTPServerTransport(
    mcp_session_id=session_id,
    is_json_response_enabled=True,
)

# 后台运行 MCP 服务器
async def run_mcp_server():
    async with transport.connect() as streams:
        await self.server.run(streams[0], streams[1], ...)

asyncio.create_task(run_mcp_server())

# 创建 Starlette 应用
app = Starlette()
app.mount("/", transport.handle_request)
```

**端口**: 8091
**协议**: Streamable HTTP (MCP 2025-03-26+)

### `core/start_sse_prod.sh` (启动脚本)

**功能**:
- 停止旧服务器实例
- 检测并释放 session 文件锁
- 启动新服务器
- 自动验证 GET/POST 端点

**日志**: `/tmp/funstat_sse.log`

### `scripts/funstat_auto_query.py` (自动查询工具)

**用途**: 批量查询关键词并解析结果

**示例**:

```python
queries = [
    {"type": "pain_point", "keyword": "翻译不准"},
    {"type": "pain_point", "keyword": "翻译太慢"},
    {"type": "recommendation", "keyword": "翻译软件推荐"},
]

# 运行查询
python3 scripts/funstat_auto_query.py
```

**输出**: `funstat_query_results.json`

### `scripts/analyze_customers_v2.py` (客户分析工具)

**功能**: 将客户分类为:
- 💼 代理商/同行 (3 users)
- 🏢 B端客户 (1 user)
- 👤 C端/个人用户 (17 users)

**输出**: `客户分类清单.json`, `客户清单-表格版.md`

---

## 🧪 测试验证

### 1. 验证服务器启动

```bash
# 检查进程
ps aux | grep server.py

# 检查日志
tail -f /tmp/funstat_sse.log
```

应该看到:
```
INFO:     Uvicorn running on http://127.0.0.1:8091
```

### 2. 测试 GET 端点

```bash
curl -N -H "Accept: text/event-stream" http://127.0.0.1:8091/sse
```

预期输出:
```
event: endpoint
data: /messages?session_id=xxx
```

### 3. 测试 POST 端点

```bash
curl -X POST http://127.0.0.1:8091/sse \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

预期输出:
```json
{
  "jsonrpc":"2.0",
  "id":1,
  "result":{
    "protocolVersion":"2025-03-26",
    "capabilities":{...},
    "serverInfo":{"name":"funstat-mcp","version":"1.16.0"}
  }
}
```

### 4. 测试 Codex CLI

```bash
codex
# 然后输入: "列出可用的 MCP 工具"
```

应该看到 8 个 funstat 工具。

---

## ⚠️ 常见问题

### 1. 405 Method Not Allowed

**问题**: Codex CLI 报错 `405 Method Not Allowed`

**原因**: 使用了旧版 `SseServerTransport` 而不是 `StreamableHTTPServerTransport`

**解决**: 已在 `core/server.py` 中永久修复 (Git commit: c4f3673)

### 2. Database Locked

**问题**: `sqlite3.OperationalError: database is locked`

**原因**: 多个进程同时访问 session 文件

**解决**: 使用 `start_sse_prod.sh` 启动,自动处理锁问题

### 3. Connection Closed

**问题**: `connection closed: initialize response`

**原因**: 服务器未正确返回初始化响应

**解决**: 已在 Streamable HTTP 协议中修复

---

## 📊 项目成果

### 客户获取结果

- **查询关键词**: 6 个
- **找到消息**: 25 条
- **提取用户**: 21 个
- **高质量客户**: 13 个 (S/A 级)
- **痛点明确率**: 92%

### 客户分类

| 类别 | 数量 | 特点 | 优先级 |
|------|-----|------|--------|
| 代理商/同行 | 3 | 可发展为合作伙伴 | S 级 |
| B端客户 | 1 | 企业/团队采购 | A 级 |
| C端用户 | 17 | 个人用户 | A-C 级 |

详见: `customer_data/客户分类清单.json`

---

## 🔗 相关资源

- **MCP 官方文档**: https://modelcontextprotocol.io/docs
- **Streamable HTTP 规范**: https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#streamable-http
- **MCP Python SDK**: https://github.com/modelcontextprotocol/python-sdk
- **Codex CLI 文档**: https://docs.openai.com/codex/cli

---

## 📝 版本历史

### v1.16.0 (2025-10-27)

- ✅ 完全支持 Streamable HTTP 协议
- ✅ 修复 Codex CLI 405 错误
- ✅ 支持 Cursor IDE 和 Claude Code
- ✅ 完成客户获取自动化工具
- ✅ 生产级启动脚本

### v1.0.0 (2025-10-26)

- ✅ 初始版本
- ✅ 8 个 MCP 工具实现
- ✅ SSE 传输支持
- ✅ Claude Code 集成

---

## 🤝 支持

如有问题,请查看:

1. **`docs/ALL_AI_TOOLS_MCP_SETUP.md`** - 配置问题
2. **`docs/STREAMABLE_HTTP_FIX_FINAL.md`** - 协议问题
3. **`/tmp/funstat_sse.log`** - 服务器日志

---

**开发者**: Claude Code
**项目**: Funstat MCP 服务器
**协议**: MIT License (如适用)

---

🎉 **感谢使用 Funstat MCP!**