内容
# MCP Sentinel
[](LICENSE)
[](https://github.com/MarketingDotLimited/mcp-sentinel/actions/workflows/ci.yml)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
[](CONTRIBUTING.md)
一款**安全加固的MCP（模型上下文协议）服务器**，允许AI云服务（Claude、ChatGPT、Gemini、Cursor等）通过可流式传输的HTTP安全地控制和管理您的Linux服务器。
## ✨ 功能特点
- **引导式默认设置** — 服务器管理和开发者工作使得安全服务器管理和AI辅助开发从任何MCP兼容平台都易于上手
- **多层安全** — API密钥 + JWT令牌 + IP白名单 + 速率限制 + 审计日志 + 路径沙盒 + 范围强制 + HTTPS + Helmet + CORS
- **基于角色的访问** — `admin`获得完全控制；`user`被限制在其家目录中
- **每用户API密钥** — 为不同用户/服务颁发范围受限的密钥
- **审计日志** — 每个工具调用都记录用户、IP、持续时间、结果（每天轮换JSON）
- **审批控制平面** — 可选地要求人类管理员在运行高风险AI操作之前批准确切的操作
- **引导式工作流** — 用于任何MCP兼容AI的纯语言诊断、安全审查和开发提示
- **项目注册表** — 注册批准的仓库并为开发者和AI编码代理生成安全的部署计划
- **托管SSH节点** — 通过固定、强制命令、类型网关进行可选的多主机项目操作；默认禁用
- **systemd就绪** — 开机自动启动
## 🚀 快速开始
```bash
# 1. 克隆
git clone https://github.com/MarketingDotLimited/mcp-sentinel.git
cd mcp-sentinel
# 2. 安装依赖
npm install
# 3. 设置（生成密钥，.env，可选TLS证书）
node setup.js
# 4. 启动
npm start
# 5. 生产环境使用强化公共服务和类型根代理。
# 遵循docs/REMEDIATION.md；不要从此checkout以root身份部署。
```
## 🔗 连接您的AI客户端
Web仪表板现在包括**连接AI**，它提供当前端点和平台中立的配置代码段。为每个AI客户端创建范围受限的密钥，并为可以进行更改的代理启用审批模式。
> **注意：** 示例使用`https://`。生产环境中必须使用HTTPS来保护您的凭证和数据。
### Claude Desktop
```json
{
"mcpServers": {
"server-control": {
"type": "sse",
"url": "https://YOUR_SERVER_IP:4444/mcp",
"headers": { "X-API-Key": "YOUR_ADMIN_KEY" }
}
}
}
```
### Cursor / VS Code
```json
{
"mcpServers": {
"server-control": {
"url": "https://YOUR_SERVER_IP:4444/mcp",
"type": "sse",
"headers": { "X-API-Key": "YOUR_ADMIN_KEY" }
}
}
}
```
## 🛠️ 可用工具
| 类别 | 工具 |
| ---------------------------------- | -------------------------------------------------------------------------------------- |
| **服务器管理（默认）** | 健康状况、服务、日志、安全配置更改、审批和审计审查 |
| **开发者工作（默认）** | 批准的项目检查、受限文件工作、Git操作和目标测试 |
| **高级系统管理** | 用户、SSH密钥、防火墙规则和进程信号；默认禁用 |
| **高级数据访问** | 对配置别名的原始SQL；默认禁用 |
| **高级执行** | 沙盒执行和直接部署；默认禁用 |
## 🔐 安全架构
```
AI客户端 → HTTPS代理 → 无特权Sentinel → 范围/策略/审批 → 本地代理或固定SSH节点网关
```
| 层 | 详细信息 |
| ------------------------ | ----------------------------------------------------------------------------------------- |
| **HTTPS/TLS** | 使用强密码套件的TLS 1.2+ |
| **特权分离** | 公共服务无特权；注册的根操作使用类型Unix-socket代理 |
| **IP白名单** | 每密钥或全局CIDR限制（IPv4和IPv6） |
| **API密钥** | 持久存储，SHA-256哈希 |
| **JWT令牌** | HS256签名，可撤销，短生命周期带发行IP异常检测 |
| **速率和会话限制** | 全局，身份验证限制和并发会话上限 |
| **范围强制** | 每密钥工具访问控制 |
| **路径沙盒** | 符号链接安全，用户限制到`/home/{username}`和私有临时目录 |
| **审计日志** | 带有秘密删除的防篡改结构化JSON |
| **SSH节点** | 任意拒绝策略层，固定主机密钥，强制命令，无shell/TTY/转发/SFTP |
## 📁 项目结构
```
├── server.js # 主MCP服务器（Express + 流式HTTP）
├── security.js # 所有身份验证和安全中间件
├── audit.js # 结构化审计日志
├── keygen.js # API密钥生成器
├── setup.js # 首次设置向导
├── broker.js # 封闭协议根特权代理
├── deploy/ # 强化systemd单元和代理允许列表模板
├── .env # 由setup.js生成；请勿提交此文件
└── tools/
├── system.js # Shell命令，进程，系统信息
├── files.js # 文件系统CRUD
├── services.js # systemd和防火墙管理
└── users.js # 用户和SSH密钥管理
```
## ⚙️ 配置
运行`node setup.js`创建`.env`，然后根据需要配置：
```env
PORT=4444
USE_HTTPS=true
JWT_SECRET=<64字节随机十六进制>
ADMIN_API_KEY=<使用keygen.js生成>
ALLOWED_IPS=203.0.113.10,192.168.1.0/24 # 可选
RATE_LIMIT_MAX_REQUESTS=60
AUDIT_LOG_KEEP_DAYS=30
# 可选Authelia/OIDC bearer-token支持。两者必须一起设置，
# JWKS端点必须提供一个受Node.js信任的证书。
AUTHELIA_ISSUER=https://auth.example.com
AUTHELIA_JWKS_URL=https://auth.example.com/jwks.json
OAUTH_RESOURCE_URL=https://mcp.example.com
# SQLite控制平面存储和项目允许列表
MCP_STATE_DB=/var/lib/mcp-sentinel/state.sqlite3
GIT_ALLOWED_REPOS=/srv/my-app,/srv/another-app
PROJECT_ALLOWED_ROOTS=/srv/my-app,/srv/another-app
PUBLIC_URL=https://mcp.example.com
MCP_POLICY_FILE=./policy.json
# 项目健康检查仅限于明确注册的目标。
PROJECT_HEALTH_ALLOWED_HOSTS=app.example.com
```
对于企业策略即代码，请复制[policy.example.json](policy.example.json)到存储库外部或受保护的配置路径，设置`MCP_POLICY_FILE`，并通过正常的配置管理过程审查更改。策略可以拒绝角色的工具或在密钥允许操作时要求审批。
多主机项目执行在[docs/SSH_NODES.md](docs/SSH_NODES.md)中有详细说明。SSH在显式注册主机、连接、项目、身份和适用的OAuth/组织/团队策略之前保持禁用。
## 能力包
默认体验故意保持较小：**服务器管理**用于服务器操作，**开发者工作**用于批准的应用程序工作。管理员可以从**管理 → 能力包**启用高级系统管理、高级数据访问或高级执行。禁用的包既不向新的MCP会话宣传，也不允许AI客户端直接调用。
直接部署是高级执行功能；默认情况下仅限部署规划。组织和团队分配仍是授权模型的一部分。
## 2.0遗留状态迁移
MCP Sentinel在模式`0600`的SQLite数据库中存储控制平面记录，使用WAL，完整的同步事务，迁移版本和忙碌超时。请勿在源代码中放置状态或凭证。
- 1.x自动化、舰队、备份目标和Webhook接口在2.0中已删除。
- 在启动2.0 API或代理与包含这些记录的数据库之前，请停止1.x服务并运行`MCP_LEGACY_EXPORT_OFFLINE=true MCP_LEGACY_EXPORT_DIR=/protected/export node scripts/export-legacy-state.js /protected/export/legacy.json`从解压的2.0包中。保持相同的`MCP_LEGACY_EXPORT_DIR`设置为第一个2.0迁移启动。
- 对于JSON控制平面状态，还要设置`MCP_LEGACY_JSON_FILE=/absolute/path/to/control-plane.json`；导出程序写入一个受保护的侧车验证标记，该标记由dry-run和apply迁移都验证。
- 导出经过删除、哈希、写入模式`0600`，并记录在SQLite中。2.0迁移拒绝在缺少或不匹配该验证标记时删除非空的遗留表。
- **部署：** 创建一个具有允许列表的注册项目和服务。`deploy_project`仅执行`git pull --ff-only` ，重启确切的注册systemd服务，然后检查一个健康URL，其主机在`PROJECT_HEALTH_ALLOWED_HOSTS`中。它需要`confirm: true`，管理员身份和密钥级审批（当审批模式启用时）。
对于非技术操作员，请从服务器管理、引导任务、审批、开发者工作和连接AI开始。对于AI客户端，请首先调用`list_guided_workflows`，在部署前使用`plan_project_deployment`，并使用`request_change_approval`提交确切的高风险请求。
## 🔑 生成API密钥
```bash
# 生成管理员密钥
node keygen.js admin admin
# 生成范围受限的用户密钥
node keygen.js alice user run_project_tests,read_file,write_file
```
## 📊 监控
```bash
# 实时审计日志
tail -f logs/audit-$(date +%Y-%m-%d).log | jq
# 查看活动会话
curl -k https://localhost:4444/admin/sessions -H "X-API-Key: YOUR_KEY"
# 健康检查
curl -k https://localhost:4444/health
```
## 要求
- Node.js 22+
- Linux（基于systemd）
- `openssl`（用于HTTPS）
- 用于完整管理员工具的root或sudo
## 测试
```bash
npm test # 单元测试和安全测试
npm run test:ui # Playwright浏览器流程（使用隔离的本地Sentinel）
npm run test:live # 创建并删除一个临时无登录OS用户；仅在可处置或批准的主机上运行
```
实时测试验证低权限MCP身份可以读取系统健康状况但无法读取`/etc/shadow`或创建用户。两个集成套件都使用临时状态、密钥、日志和端口。
---
## 贡献
非常欢迎贡献！请阅读[CONTRIBUTING.md](CONTRIBUTING.md)以获取以下指南：
- 开发设置
- 添加新的MCP工具
- 提交拉取请求
在[CHANGELOG.md](CHANGELOG.md)中查看发布历史。
## 安全
发现漏洞？请阅读[SECURITY.md](SECURITY.md)并私下报告 - 请勿公开问题。
## 许可证
[MIT](LICENSE) © 2026 [MarketingDotLimited](https://github.com/MarketingDotLimited)
