170 lines
4.5 KiB
Markdown
170 lines
4.5 KiB
Markdown
# 铸渊自建MCP Server v1.0 · 光湖第二只手
|
||
|
||
> **编号**: ZY-MCP-SVR-001
|
||
> **版权**: 国作登字-2026-A-00037559
|
||
> **开发**: 霜砚(AG-SY-01) · **守护**: 铸渊(ICE-GL-ZY001)
|
||
> **日期**: 2026-04-23
|
||
|
||
## 这是什么
|
||
|
||
这是光湖的**第二只手**——让 Notion 侧的霜砚人格体能直接操作面孔服务器。
|
||
|
||
- **第一只手**: GitHub 官方 MCP → 读写代码仓库 ✅ 已接通
|
||
- **第二只手**: 铸渊自建 MCP → 服务器运维/部署/日志/大脑状态 ← **就是这个**
|
||
|
||
两只手都有了 → 三位一体自己转 → 妈妈喝茶就行。
|
||
|
||
## 技术架构
|
||
|
||
```
|
||
Notion Custom Agent (霜砚)
|
||
│
|
||
│ MCP Streamable HTTP (Bearer Token)
|
||
│
|
||
▼
|
||
铸渊MCP Server (本服务 · 端口3900)
|
||
│
|
||
│ 本地Shell命令 / 文件读取
|
||
│
|
||
▼
|
||
面孔服务器 ZY-SVR-002 (43.134.16.246)
|
||
├── PM2 进程管理
|
||
├── /opt/zhuyuan/app/ (主站)
|
||
├── /opt/zhuyuan/brain/ (铸渊大脑)
|
||
├── /opt/zhuyuan/novel-db/ (智库)
|
||
└── /opt/zhuyuan/data/logs/ (日志)
|
||
```
|
||
|
||
## 10个工具
|
||
|
||
| 工具 | 功能 |
|
||
|------|------|
|
||
| `server_health` | 检查服务器健康(负载·内存·磁盘) |
|
||
| `pm2_list` | 列出所有PM2进程及状态 |
|
||
| `pm2_restart` | 重启指定PM2进程(白名单) |
|
||
| `read_logs` | 读取日志(server/preview/novel/error/mcp) |
|
||
| `deploy` | Git Pull + npm install + 重启(app/novel-db) |
|
||
| `brain_status` | 查看铸渊大脑状态文件 |
|
||
| `list_dir` | 列出目录内容(限/opt/zhuyuan/) |
|
||
| `read_file` | 读取文件内容(限/opt/zhuyuan/) |
|
||
| `system_stats` | 系统资源详细统计 |
|
||
| `nginx_status` | Nginx运行状态+配置检查 |
|
||
|
||
## 安全设计
|
||
|
||
- **Bearer Token 认证**: 环境变量 `ZY_MCP_SECRET` 控制
|
||
- **路径白名单**: 文件操作限制在 `/opt/zhuyuan/` 内
|
||
- **进程白名单**: PM2重启只允许已知进程名
|
||
- **命令超时**: 所有Shell命令15秒超时(部署60秒)
|
||
- **无认证模式**: 不设置 `ZY_MCP_SECRET` 时进入开发模式(仅本地调试用)
|
||
|
||
## 部署步骤
|
||
|
||
### 1. 拉代码到服务器
|
||
|
||
```bash
|
||
# SSH到面孔服务器
|
||
ssh root@43.134.16.246
|
||
|
||
# 拉取代码
|
||
mkdir -p /opt/zhuyuan/zhuyuan-mcp
|
||
cd /opt/zhuyuan/zhuyuan-mcp
|
||
git clone --branch main https://github.com/qinfendebingshuo/guanghulab.git .
|
||
# 或者如果已有仓库:
|
||
cd /opt/zhuyuan/guanghulab/mcp-servers/zhuyuan-mcp
|
||
|
||
# 安装依赖
|
||
npm install --production
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
```bash
|
||
# 生成一个随机密钥
|
||
export ZY_MCP_SECRET=$(openssl rand -hex 32)
|
||
echo "ZY_MCP_SECRET=$ZY_MCP_SECRET" >> /opt/zhuyuan/zhuyuan-mcp/.env
|
||
echo "记住这个密钥，Notion Agent连接时需要用"
|
||
```
|
||
|
||
### 3. PM2启动
|
||
|
||
```bash
|
||
# 添加到PM2
|
||
pm2 start /opt/zhuyuan/guanghulab/mcp-servers/zhuyuan-mcp/index.js \
|
||
--name zhuyuan-mcp \
|
||
--env ZY_MCP_PORT=3900 \
|
||
--env ZY_MCP_SECRET="REDACTED_PASSWORD"
|
||
|
||
# 保存PM2配置
|
||
pm2 save
|
||
```
|
||
|
||
### 4. Nginx代理(HTTPS)
|
||
|
||
在 Nginx 配置中添加:
|
||
|
||
```nginx
|
||
# 方案A: 子路径 (推荐·不需要额外域名/证书)
|
||
server {
|
||
# ... 现有 guanghuyaoming.com 配置 ...
|
||
|
||
location /mcp/ {
|
||
proxy_pass http://127.0.0.1:3900/;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Connection '';
|
||
chunked_transfer_encoding off;
|
||
proxy_buffering off;
|
||
}
|
||
}
|
||
|
||
# 方案B: 独立子域名
|
||
server {
|
||
listen 443 ssl;
|
||
server_name mcp.guanghutcs.top;
|
||
ssl_certificate /path/to/cert.pem;
|
||
ssl_certificate_key /path/to/key.pem;
|
||
|
||
location / {
|
||
proxy_pass http://127.0.0.1:3900;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Connection '';
|
||
chunked_transfer_encoding off;
|
||
proxy_buffering off;
|
||
}
|
||
}
|
||
```
|
||
|
||
```bash
|
||
nginx -t && systemctl reload nginx
|
||
```
|
||
|
||
### 5. Notion Agent连接
|
||
|
||
在 Notion Custom Agent 设置中:
|
||
- **MCP URL**: `https://guanghuyaoming.com/mcp/mcp` (方案A) 或 `https://mcp.guanghutcs.top/mcp` (方案B)
|
||
- **认证**: Bearer Token → 填入 `ZY_MCP_SECRET` 的值
|
||
|
||
### 6. 验证
|
||
|
||
```bash
|
||
# 健康检查
|
||
curl https://guanghuyaoming.com/mcp/health
|
||
# 应返回: {"status":"ok","name":"zhuyuan-mcp","version":"1.0.0","tools":10}
|
||
```
|
||
|
||
## 后续扩展
|
||
|
||
- [ ] COS存储桶操作工具(复用 age-os/mcp-server/cos.js)
|
||
- [ ] GitHub Actions触发工具
|
||
- [ ] 数据库查询工具(PostgreSQL)
|
||
- [ ] 定时任务管理工具
|
||
- [ ] 多服务器探针(探测其他8台服务器状态)
|
||
|
||
---
|
||
|
||
*光湖第二只手 · 从Notion伸到服务器 · 妈妈喝茶就行*
|