内容
# 简单AI — 开源MCP网关
> **个人AI代理的多模型MCP网关.**
> 通过标准模型上下文协议在DeepSeek、Gemini和Claude之间路由任务.
> 使用Go构建. 自主托管. 生产就绪.
[](https://modelcontextprotocol.io)
[](https://go.dev)
[](LICENSE)
**[mcpgate.org](https://mcpgate.org)** · [快速开始](#setup) · [添加技能](#adding-a-new-skill)
---
## 什么是简单AI?
一个开源的MCP（模型上下文协议）网关，暴露个人AI代理工具给任何兼容MCP的客户端（Claude Code等）。
**多模型路由：**
- **DeepSeek** — 普通任务（预算跟踪，搜索）
- **Gemini** — 备用
- **Claude** — 代理规划，推理密集的工作流，MCP工具调用
只需通过SSE连接一次，即可访问所有技能：
```json
{
"mcpServers": {
"simpleai": { "type": "http", "url": "http://your-host:8080/sse" }
}
}
```
---
## 架构
```
用户
│
├─── Telegram 消息
│ ↓
│ Telegram 机器人 (cmd/telegram)
│ ↓
│ agent.Service ←── plugin.Registry ──┬── RAGSearchSkill
│ ↓ ├── BudgetSkill
│ LLM（DeepSeek 主要，Gemini 备用，Claude 用于代理）
│
└─── Claude Code / 外部代理
↓ HTTP/SSE :8080
MCP 服务器 (cmd/mcp)
↓
plugin.Registry（共享）
```
**关键设计：** `plugin.Registry` 是可用工具的单一来源。
两个入口点（Telegram 和 MCP）使用相同的注册表 — 只需添加一次技能，即可在任何地方使用。
---
## 功能
- **MCP 服务器** — HTTP/SSE 网关在 `:8080` 用于Claude Code和其他MCP客户端
- **多模型路由** — DeepSeek → Gemini → Claude 管道
- **预算跟踪器** — 支出，收入，目标，债务，多币种
- **支出预测** — 类别级别预测与趋势分析
- **定期付款** — 按计划自动交易与通知
- **RAG 搜索** — 知识库搜索文档通过 pgvector
- **邮件摘要** — Gmail/IMAP 集成
- **每日提醒** — 按时间和时区配置
- **CI/CD** — GitHub Actions → SSH → Docker Compose → systemd（~2 分钟部署）
---
## 项目结构
```
cmd/
app/ — 主入口：运行 Telegram 机器人 + MCP 服务器 + 工作线程
agent/ — CLI 代理：读取 stdin，响应 LLM（例如 git diff → 代码审查）
embeddings/ — 为 rag_document 记录生成嵌入
ingest/ — 从 JSON 加载收据到 DB + rag_document
mcp/ — MCP HTTP/SSE 服务器在 :8080
rag-query/ — 用于手动 RAG 搜索测试的 CLI
telegram/ — Telegram 机器人（独立）
worker/ — 后台工作线程
internal/
agent/ — agent.Service：用于 Telegram 的工具调用循环
plugin/ — 注册表，技能接口，清单
skills/ — RAGSearchSkill，BudgetSkill（在此添加更多）
rag/ — pgvector 存储，检索器，提示构建器
budget/ — 预算模型和 CRUD 存储
mail/ — Gmail/IMAP 集成
mcp/ — plugin.Registry → mcp-go 适配器
notify/ — 来自后台任务的 Telegram 通知
adapters/ — LLM 工厂（OpenAI，Ollama，自动备用），Telegram 包装器
```
---
## 工作原理
### 工具调用循环（Telegram）
1. 使用可用的技能列表构建系统提示
2. 发送给 LLM → 获取 JSON `{"skill": "...", "input": {...}}`
3. 执行技能，将结果传回 LLM
4. 将最终答案返回给用户
### RAG 搜索示例
```
用户： "查找一月份的收据"
→ LLM → {"skill":"rag_search","input":{"query":"收据 一月份"}}
→ 嵌入查询 → pgvector 搜索 → 构建提示 → LLM → 答案
```
### 预算跟踪器示例
```
用户： "花费 1500 美元购买杂货"
→ LLM → {"skill":"budget","input":{"action":"add_expense","amount":1500,"category":"food"}}
→ BudgetSkill → 添加交易 → 获取摘要 → 答案
```
---
## 添加新技能
1. 创建 `internal/skills/my_skill.go`，实现 `plugin.Skill`：
```go
func (s *MySkill) Manifest() plugin.Manifest { ... }
func (s *MySkill) Run(ctx context.Context, input string) (string, error) { ... }
```
2. 在 `cmd/app/main.go` → `buildRegistry()` 中注册。
3. 更新 README。
参见 `rag_search.go`（简单）和 `budget_skill.go`（基于操作）作为示例。
---
## 设置
### 先决条件
- Go 1.24+
- Docker（用于 PostgreSQL + pgvector）
### 运行
```bash
cp .env.example .env # 填写必填值
docker compose up -d # 启动 Postgres
make migrate-up # 应用迁移
make run-all # 启动所有
```
`make run-all` 在一个进程中启动：
- Telegram 机器人
- MCP SSE 服务器在 `:8080`
- 邮件工作线程（如果设置了 `MAIL_ACCOUNTS_JSON`）
### MCP 服务器（用于 Claude Code）
```bash
make run-mcp
```
`.mcp.json` 已在根目录：
```json
{
"mcpServers": {
"simpleai": { "type": "http", "url": "http://localhost:8080/sse" }
}
}
```
在 Claude Code 中验证： `/mcp` → 应该显示 `rag_search` 工具。
### 通过 CLI 进行代码审查
```bash
git diff | go run cmd/agent/main.go
# 或：
make run-diff
```
---
## 环境变量
```env
# LLM
LLM_PROVIDER=openai # openai | ollama
LLM_CHAT_MODEL=gpt-4.1-mini
EMBEDDING_MODEL=text-embedding-3-small
API_KEY=sk-...
# Ollama（如果 LLM_PROVIDER=ollama）
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5:7b-instruct-q4_K_M
OLLAMA_EMBED_MODEL=nomic-embed-text
# 数据库
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=simpleai
POSTGRES_USER=simpleai
POSTGRES_PASSWORD=simpleai
# Telegram
TELEGRAM_BOT_TOKEN=...
TELEGRAM_ALLOWED_CHATS=123456789
TELEGRAM_WORKERS=4
# 系统
SYS_PROMPT=你是一个有用的助手...
LOG_LEVEL=info # debug | info | warn | error
LOG_FORMAT=text # text | json
# 可观察性（Langfuse，可选 — 留空以禁用）
LANGFUSE_HOST=http://localhost:3001
LANGFUSE_PUBLIC_KEY=pk-lf-rag-mm-dr-local
LANGFUSE_SECRET_KEY=sk-lf-...
```
---
## 可观察性（Langfuse）
自我托管的 Langfuse 通过单独的 `deploy/langfuse/` 中的 compose 启动。代理发送跟踪（trace 到请求 → 每个 LLM 调用生成 → 每个工具调用的 span）到 http://localhost:3001/project/rag-mm/traces。
详情： [deploy/langfuse/README.md](deploy/langfuse/README.md).
如果未设置 `LANGFUSE_*` 变量 — 跟踪功能关闭，代理按原样工作。
---
## Make 目标
| 命令 | 描述 |
|---------|-------------|
| `make run-all` | **启动所有** — Telegram + MCP + 工作线程 |
| `make db-up` | 在 Docker 中启动 Postgres |
| `make migrate-up` | 应用 SQL 迁移 |
| `make migrate-down` | 回滚最后一次迁移 |
| `make run-mcp` | 仅在 :8080 上启动 MCP SSE 服务器 |
| `make run-diff` | git diff → 代码审查代理 |
| `make lint` | 运行 golangci-lint |
---
## 技术栈
Go · PostgreSQL · pgvector · Docker · GitHub Actions · DeepSeek · Gemini · Claude (Bedrock) · goose · slog
