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 即可。

快速启动顺序

cp .env.example .env 并根据实际环境填写（尤其是 Telegram API、Bot Token、session 路径）。
启动本地 Postgres：docker compose up -d postgres（如本机已有 5433 占用，可在 .env 里改为其他端口）。
安装依赖：pip3 install -r requirements.txt --user --break-system-packages。
使用自己的 Telegram 账号创建 session：python3 scripts/create_session_safe.py。
运行服务器：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错误)

🚀 快速开始

前置要求

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

安装步骤

1. 安装依赖

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

或手动安装:

pip3 install mcp telethon starlette uvicorn

2. 配置 Session 文件

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

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

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

3. 启动 MCP 服务器

生产环境 (推荐):

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

开发环境:

cd core
python3 server.py

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

4. 配置客户端

Codex CLI:

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

Cursor IDE:

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

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` (主程序)

关键实现:

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` (自动查询工具)

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

示例:

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. 验证服务器启动

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

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

应该看到:

INFO:     Uvicorn running on http://127.0.0.1:8091

2. 测试 GET 端点

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

预期输出:

event: endpoint
data: /messages?session_id=xxx

3. 测试 POST 端点

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"}}}'

预期输出:

{
  "jsonrpc":"2.0",
  "id":1,
  "result":{
    "protocolVersion":"2025-03-26",
    "capabilities":{...},
    "serverInfo":{"name":"funstat-mcp","version":"1.16.0"}
  }
}

4. 测试 Codex CLI

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 集成

🤝 支持

如有问题,请查看:

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

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

🎉 感谢使用 Funstat MCP!

README.md Unescape Escape

Funstat MCP 完整打包

项目说明