Generic Gateway

一个基于 FastMCP + ASGI 的通用智能体网关架构模板。它将"工具能力 (MCP)"、"记忆 / 画像 / 提醒系统"、"多渠道消息接入 (Telegram / QQ)"与"自主生命心跳"整合为一个可独立部署的服务。

本仓库为通用化版本：已移除全部个人化内容 (硬编码密钥、私人域名、人设、ID 等)，所有配置均通过环境变量注入，方便直接复用与二次开发。

---

📐 架构总览

┌─────────────────────────────────────────────────────────────┐
│                        客户端 / 外部平台                        │
│   (Claude / Cursor 等 MCP 客户端、Telegram、QQ、邮件、日历)     │
└───────────────┬──────────────────────────────┬──────────────┘
                │ HTTP / SSE / WS              │
                ▼                              ▼
┌──────────────────────────────┐   ┌──────────────────────────┐
│      gateway.py              │   │     heartbeat.py         │
│  ┌────────────────────────┐  │   │  (后台 daemon 线程池)      │
│  │ HostFixMiddleware      │──┼───┼─► 自主生命循环            │
│  │  • /health 健康检查     │  │   │  • Telegram 轮询         │
│  │  • /api/config 热更新   │  │   │  • 消息总结器            │
│  │  • /api/logs  日志      │  │   │  • 提醒巡视器            │
│  │  • /api/restart 重启    │  │   │  • 日程小秘书            │
│  │  • /qq-ws (反向WS端点)  │  │   │  • 信箱巡视器            │
│  └────────────────────────┘  │   │  • 环境变量热同步          │
└──────────┬───────────────────┘   └──────────────────────────┘
           ▼
┌──────────────────────────────┐   ┌──────────────────────────┐
│      server.py               │   │     napcat.py            │
│  FastMCP("GenericGateway")   │   │  • 反向 WS 接入 QQ        │
│  • echo / save_memory        │   │  • 消息转发给 LLM         │
│  • search_memory             │   │  • 二维码 / 状态管理       │
│  • manage_user_fact          │   │  • 掉线通知 / 自动重连     │
│  • organize_knowledge_base   │   └──────────────────────────┘
│  • manage_reminder           │
│  • send_notification         │   ┌──────────────────────────┐
│  • send_email_via_api        │   │     外部依赖 (可选)        │
│  • web_search                │   │  • Supabase (数据库)      │
│  • check_inbox / read_email  │   │  • Mem0 (长期记忆)        │
│  • add/get/modify_calendar   │   │  • Gmail / Calendar API   │
└──────────────────────────────┘   └──────────────────────────┘

文件职责

文件	角色	说明
server.py	MCP 工具层	注册所有 @mcp.tool 工具，是 LLM 调用的入口
gateway.py	ASGI 中间件层	Host 修正、CORS、管理接口、WS 端点路由
heartbeat.py	后台心跳层	7 个 daemon 线程，驱动"自主生命感"
napcat.py	QQ 接入层	NapCat OneBot 协议接入，反向/正向 WS 双模
.env.example	配置模板	所有可配置项的文档化示例

---

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

cp .env.example .env
# 编辑 .env，填入你的真实配置

最小化配置（只跑通 MCP 工具）只需设置：

• OPENAI_API_KEY — LLM 的 API Key
• OPENAI_MODEL_NAME — 模型名

3. 启动

python server.py

服务默认监听 0.0.0.0:10000。健康检查：GET /health。

4. 接入 MCP 客户端

将 MCP 客户端 (如 Claude Desktop、Cursor) 指向：

http://<你的域名或IP>:10000/sse

---

🧩 MCP 工具清单

网关共注册 30+ 个 MCP 工具，按子系统分组（按需配置即可启用）：

分类	工具	功能
基础	echo	回声测试
记忆	save_memory / search_memory	记忆存取（数据库 + Mem0/Pinecone 向量双写双搜）
记忆	get_latest_diary	加载最新记忆流（长期总结 + 短期对话 + 小屋动态）
画像	manage_user_fact / get_user_profile	用户画像 CRUD
知识库	organize_knowledge_base	通用知识库 CRUD
提醒	manage_reminder	闹钟/提醒 (数据库持久版)
消息	send_notification	多渠道推送 (Telegram)
邮件	send_email_via_api	Resend 发邮件
邮件	check_inbox / read_full_email / reply_external_email	Gmail 收发
日历	add_calendar_event / get_calendar_events / modify_calendar_event	Google 日历
搜索	web_search	网页搜索 (Tavily 优先 + DDG 兜底)
模型	switch_ai_brain	热切换 LLM 角色 (openai/main_chat/silicon1/vision/voice)
生活	manage_memory_house	AI 虚拟生活小屋 (陪伴感)
生活	save_expense / check_expense_report / manage_piggy_bank	记账 + 账单 + 储蓄罐
生活	where_is_user / explore_surroundings	GPS 定位 + 周边探索 (高德)
娱乐	tarot_reading	AI 塔罗占卜
多媒体	render_html_to_image	HTML/CSS 转图片 (HCTI)
多媒体	compose_music / cover_existing_song	AI 作曲 + AI 翻唱 (Replicate)
笔记	list_obsidian_cloud / read_obsidian_cloud / write_obsidian_cloud	WebDAV 云端笔记 (Obsidian)

---

📡 管理 API

路径	方法	功能
/health	GET	健康检查
/api/config	POST	热更新环境变量 (JSON body)
/api/logs	GET	读取最近日志
/api/restart	POST	触发云平台重启 (需配 RESTART_WEBHOOK_URL)
/qq-ws	WS	NapCat 反向 WebSocket 端点

---

💓 后台心跳说明

heartbeat.py 中的协程全部是可选的，按需开启：

协程	启用条件	默认间隔
自主生命循环	配置了 LLM	2 小时
Telegram 轮询	配置了 TG_BOT_TOKEN	长轮询
消息总结器	配置了 LLM + Supabase	30 分钟
提醒巡视器	配置了 Supabase	每分钟
日程小秘书	配置了 GOOGLE_USER_TOKEN_JSON	07:30 / 22:00
信箱巡视器	配置了 GMAIL_BRIDGE_URL (默认注释)	5 分钟
环境变量热同步	配置了 Supabase	10 秒

---

🗄️ 数据库表结构 (Supabase)

通用版需要三张表，字段尽量精简：

-- 记忆表
create table memories (
  id bigint generated always as identity primary key,
  title text,
  content text,
  category text default '流水',          -- 流水/记事/灵感/情感/画像
  mood text default '平静',
  tags text default 'System',
  importance int default 1,              -- 权重 1~10，按 category 自动计算
  created_at text
);

-- 用户画像表
create table user_facts (
  key text primary key,
  value text,
  confidence float default 1.0
);

-- 提醒表
create table reminders (
  id text primary key,
  time_str text,           -- "HH:MM"
  content text,
  is_repeat boolean default false,
  is_paused boolean default false,
  last_fired text default ''
);

-- 记忆小屋 (AI 虚拟生活系统，可选)
create table memory_house (
  id bigint generated always as identity primary key,
  room text,                        -- 卧室/厨房/客厅/书房/阳台
  action_type text,                 -- 看书/做饭/听音乐/发呆
  content text,
  is_locked boolean default false,
  created_at text
);

-- 记账 (可选)
create table expenses (
  id bigint generated always as identity primary key,
  item text,
  amount float,
  type text,                        -- 餐饮/购物/交通/娱乐/日常/其他
  date date
);

-- 设备定位数据 (可选，供 where_is_user / explore_surroundings 使用)
create table device_data (
  id bigint generated always as identity primary key,
  timestamp text,
  location_latitude float,
  location_longitude float,
  location_address text,
  foreground_app text,
  app_usage jsonb
);

可在 user_facts 中插入 key='sys_config'，value 为 JSON 字符串，实现配置的数据库热同步。

---

📦 部署指南

本网关需要长驻进程（后台心跳线程 + WebSocket 连接），因此不支持 Serverless 平台（如 Vercel、Cloudflare Workers）。下面提供 4 种主流部署方案。

方案一：Docker 部署（推荐）

最省心的方式，已内置 Dockerfile 和 Compose 配置。

# 1. 准备配置文件
cp .env.example .env
# 编辑 .env 填入真实配置

# 2. 构建并启动
docker compose up -d

# 3. 查看日志
docker compose logs -f

# 4. 停止 / 重启
docker compose down
docker compose restart

手动 docker 命令（不用 compose）：

# 构建镜像
docker build -t mcp-gateway .

# 运行容器
docker run -d --name mcp-gateway --restart unless-stopped \
  -p 10000:10000 --env-file .env mcp-gateway

💡 Dockerfile 内置了 HEALTHCHECK，K8s、Portainer 等编排平台可直接识别容器健康状态。

---

方案二：云平台 PaaS（Zeabur / Render / Railway / Fly.io）

这类平台支持长驻进程 + 自动 HTTPS，最适合本项目。通用流程：

1. 推送代码到 GitHub
2. 在平台新建项目 → 选择本仓库
3. 配置构建命令：平台一般会自动识别，或手动填写
   • Build Command: pip install -r requirements.txt
   • Start Command: python server.py
4. 注入环境变量：在平台后台把 .env 里的变量逐条填入
   • 必填：OPENAI_API_KEY、OPENAI_MODEL_NAME
   • 端口：平台会自动注入 PORT，无需手动设
5. 暴露端口：设为 10000（或代码读取的 PORT）
6. 绑定域名：平台自动分配 HTTPS 域名，直接用

平台特定提示：

平台	注意事项
Zeabur	原版项目就是跑在 Zeabur 上的，直接部署即可。完整教程见 DEPLOY_ZEABUR.md
Render	选 "Web Service" 类型，不是 "Static Site"
Railway	会自动检测 Python，确认 Start Command 即可
Fly.io	需要 fly.toml（可在平台用 fly launch 自动生成）

部署成功后，MCP 客户端接入地址为：https://<平台分配的域名>/sse

---

方案三：VPS + Nginx 反向代理（阿里云 / 腾讯云 / AWS EC2）

适合需要完全掌控的场景。需要自行处理 HTTPS 和反代。

第 1 步：用 systemd 把网关注册为系统服务

创建 /etc/systemd/system/mcp-gateway.service：

[Unit]
Description=Generic MCP Gateway
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/mcp-gateway
EnvironmentFile=/opt/mcp-gateway/.env
ExecStart=/usr/bin/python3 /opt/mcp-gateway/server.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

# 启用并启动
systemctl daemon-reload
systemctl enable mcp-gateway
systemctl start mcp-gateway
systemctl status mcp-gateway   # 检查状态
journalctl -u mcp-gateway -f   # 查看实时日志

第 2 步：配置 Nginx 反向代理

⚠️ 关键：MCP 的 /sse 是流式响应，必须关闭 buffering，否则客户端会一直卡住收不到数据。

创建 /etc/nginx/conf.d/mcp-gateway.conf：

server {
    listen 80;
    server_name your-domain.com;

    # （可选）HTTP 重定向到 HTTPS
    # return 301 https://$host$request_uri;

    location / {
        proxy_pass http://127.0.0.1:10000;

        # ====== SSE 流式响应关键配置 ======
        proxy_buffering off;              # 关闭缓冲，SSE 必需
        proxy_cache off;                  # 关闭缓存
        proxy_read_timeout 86400s;        # 长连接超时调大
        chunked_transfer_encoding on;

        # ====== WebSocket 关键配置 (/qq-ws 端点) ======
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # ====== 通用反代头 ======
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

nginx -t              # 测试配置
systemctl reload nginx

第 3 步：配置 HTTPS（推荐 certbot）

# Ubuntu/Debian
apt install certbot python3-certbot-nginx
certbot --nginx -d your-domain.com

配置完成后，接入地址：https://your-domain.com/sse

---

方案四：本地开发调试

# 1. 创建虚拟环境
python -m venv venv
source venv/bin/activate        # Linux/Mac
# venv\Scripts\activate         # Windows

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env，至少填入 OPENAI_API_KEY 和 OPENAI_MODEL_NAME

# 4. 运行
python server.py

# 5. 验证
curl http://localhost:10000/health

---

⚠️ 部署常见坑点

问题	原因	解决
MCP 客户端连接后卡住	Nginx 没关 proxy_buffering	加 proxy_buffering off;
QQ 机器人连不上	/qq-ws 反代没配 WebSocket 升级	加 proxy_http_version 1.1 + Upgrade 头
部署到 Vercel 失败	Serverless 不支持长驻进程	换用 Render/Railway/VPS
提醒不触发	时区不对	确认容器/服务器时区为 Asia/Shanghai（Dockerfile 已内置）
Telegram 不推送	没配 TG_BOT_TOKEN / TG_CHAT_ID	检查 .env
Supabase 报错	RLS 权限策略	确认表关闭了 RLS 或配置了 service_role key

---

🔒 安全说明

本通用版本已做到：

• ✅ 零硬编码密钥：所有 API Key、Token、URL 均从环境变量读取
• ✅ 无个人化数据：移除了人设、私人域名、用户 ID 等
• ✅ 统一错误兜底：mcp_error_handler 装饰器防止单个工具崩溃影响整体
• ✅ 可选依赖：Supabase / Mem0 / Pinecone / Gmail 等缺失时优雅降级而非报错
• ✅ 管理接口鉴权：所有 /api/* 接口强制校验 API_SECRET 密钥

---

🛠️ 自定义扩展

• 新增 MCP 工具：在 server.py 中仿照现有工具添加 @mcp.tool() 函数即可
• 新增消息渠道：在 heartbeat.py 中添加新的轮询协程，复用 _get_llm_client / _push_wechat
• 替换 LLM：只需修改 OPENAI_BASE_URL 和 OPENAI_MODEL_NAME（或配置多角色 CHAT_* / VISION_* / VOICE_*）
• 替换数据库：将 server.py 顶部的 supabase = ... 改为你的客户端即可

---

📄 License

MIT — 自由使用、修改、分发。