Gird-MCP服务器管理器
用于部署和管理MCP(模型上下文协议)服务器的统一管理系统,具有API密钥认证、访问控制、多策略支持和多种部署选项。
中文文档 |英语
特性
核心能力
- 统一的API网关:所有具有承载令牌身份验证的MCP服务器的单一入口点
- API密钥管理:使用以下项创建和管理API密钥:
- 基于Bcrypt的安全散列
- 服务器特定权限
- IP白名单支持
- 到期日期
- 多种部署方法:
- 本地进程管理(带自动重启)
- Docker编写支持
- 具有自动恢复功能的健康检查
- 多租户:租户隔离和配额管理
- 实时事件:基于SSE的部署状态事件流
管理接口
- HTTP REST API:服务器和API密钥的完整CRUD操作
- 命令行界面(CLI):
gird-mcp服务器和密钥管理命令 - Web仪表板:基于React的用户界面,包括:
- 服务器管理和监控
- API密钥管理
- 实时日志查看
- 受保护的身份验证
建筑亮点
- 服务层:将业务逻辑与HTTP处理彻底分离
- API标准化响应:一致
{ data, success }格式 - 分页:内置分页、过滤和排序
- 请求日志记录:使用相关ID进行全面的请求/响应日志记录
- 超时处理:所有外部请求都有可配置的超时
- 连接限制:SSE连接限制,以防止资源耗尽
项目结构```
gird/
├── packages/
│ ├── core/ # Shared types, utilities, logger, config, env validation
│ ├── server/ # HTTP REST API server with service layer
│ ├── cli/ # Command-line interface
│ └── dashboard/ # Web dashboard (React + Vite + TanStack Query)
├── apps/
│ └── agent/ # MCP proxy server with auth and deployment management
├── prisma/
│ ├── schema.prisma # Database schema (User, Role, Server, ApiKey, Webhook, etc.)
│ └── seed.ts # Default roles seed data
├── .claude/
│ └── plans/ # Implementation plans
└── package.json # Monorepo root
## 入门指南
### 先决条件
- Node.js>=20.0.0
- pnpm>=9.0.0
- Docker(可选,用于Docker Compose部署)
### 安装```bash
# Clone the repository
git clone
cd gird
# Install dependencies
pnpm install
# Generate Prisma client
pnpm db:generate
# Push database schema
pnpm db:push
# Seed default roles (ADMIN, USER, READ_ONLY)
pnpm db:seed
# Set up environment variables
cp .env.example .env
# Edit .env with your settings (API_KEY_SECRET must be 32+ chars)
发展```bash
Start all services in development mode
pnpm dev
Or start individually:
API server (port 3000)
cd packages/server && pnpm dev
Agent proxy server (port 3001)
cd apps/agent && pnpm dev
Web Dashboard (port 5173)
cd packages/dashboard && pnpm dev
### 建筑```bash
# Build all packages
pnpm build
# Typecheck all packages
pnpm -r typecheck
# Lint all packages
pnpm lint
用法
CLI命令```bash
Link CLI globally (first time only)
cd packages/cli && pnpm link --global
Server management
gird-mcp server list # List all servers
gird-mcp server create my-server # Create a new server
gird-mcp server start my-server # Start a server
gird-mcp server stop my-server # Stop a server
gird-mcp server delete my-server -f # Delete a server (with --force flag)
API Key management
gird-mcp key list # List all API keys
gird-mcp key create my-key # Create a new API key
gird-mcp key create my-key --servers all # Create key with access to all servers
gird-mcp key delete my-key -f # Delete an API key (with --force flag)
### HTTP API
API服务器运行于 `http://localhost:3000` 默认情况下。
**认证**:所有端点都需要 `Authorization: Bearer gird_sk_XXX` 头球
#### 服务器端点
|方法|路径|描述|
|--------|------|-------------|
|得到| `/api/servers` |列出服务器(分页,支持过滤)|
|职位| `/api/servers` |创建新服务器|
|得到| `/api/servers/:id` |获取服务器详细信息|
|PUT| `/api/servers/:id` |更新服务器|
|删除| `/api/servers/:id` |删除服务器|
|职位| `/api/servers/:id/start` |启动服务器部署|
|职位| `/api/servers/:id/stop` |停止服务器部署|
|得到| `/api/servers/:id/logs` |获取服务器日志|
**查询参数** (对于列表端点):
- `page` (默认值:1)
- `pageSize` (默认值:20,最大值:100)
- `type` (STDIO、SSE、AWS_LAMBDA、可执行文件)
- `status` (活动、停止、错误)
- `search` (按名称/描述搜索)
- `sortBy` (名称、createdAt、updatedAt)
- `sortOrder` (上升,下降)
#### API关键终结点
|方法|路径|描述|
|--------|------|-------------|
|得到| `/api/keys` |列出API密钥(已分页)|
|职位| `/api/keys` |创建新的API密钥|
|得到| `/api/keys/:id` |获取API密钥详细信息|
|删除| `/api/keys/:id` |删除API密钥|
**响应格式:**```json
{
"data": { ... },
"success": true
}
代理服务器
代理代理服务器运行在 http://localhost:3001 默认情况下。
终点:
GET /health-健康检查GET /metrics-普罗米修斯指标GET /events-SSE事件流(已验证)ALL /mcp/:serverId/*-MCP代理到后端服务器(经过身份验证)
MCP请求示例:```bash
curl -X POST http://localhost:3001/mcp/YOUR_SERVER_ID/tools/list \
-H "Authorization: Bearer gird_sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
### Web仪表板
打开 `http://localhost:5173` 在浏览器中访问web仪表板。
**特征:**
- **仪表板概述**:快速统计和导航
- **服务器页面**:列出、创建、查看详细信息、启动/停止服务器
- **服务器详细信息**:完整的服务器信息、部署控制、实时日志
- **API密钥页**:列出、创建、删除API密钥
- **认证**:API基于密钥的登录
## 配置
配置通过环境变量进行管理(`.env` 文件):```env
# Database (SQLite default, can use PostgreSQL)
DATABASE_URL="file:./dev.db"
# Agent Server (Proxy)
AGENT_PORT=3001
AGENT_HOST=127.0.0.1
# API Server
API_PORT=3000
API_HOST=0.0.0.0
# Dashboard
DASHBOARD_PORT=5173
# Secret for API key hashing (MUST be 32+ characters in production)
API_KEY_SECRET="change-this-to-a-secure-random-string-min-32-chars-long"
# Environment
NODE_ENV="development"
环境变量引用
| 变量 | 默认值 | 描述 |
|---|---|---|
DATABASE_URL |
file:./dev.db |
数据库连接字符串 |
API_KEY_SECRET |
必需的 | API密钥哈希的秘密(至少32个字符) |
AGENT_HOST |
127.0.0.1 |
代理服务器绑定地址 |
AGENT_PORT |
3001 |
代理服务器端口 |
API_HOST |
0.0.0.0 |
API服务器绑定地址 |
API_PORT |
3000 |
API服务器端口 |
DASHBOARD_PORT |
5173 |
仪表板端口 |
NODE_ENV |
development |
环境(开发/生产/测试) |
数据库模式
该项目使用Prisma和SQLite(默认情况下,兼容PostgreSQL)。
核心型号
- 用户:具有电子邮件/密码身份验证的用户帐户
- 会话:web仪表板的用户会话
- 角色:具有JSON权限的RBAC角色
- 用户角色:用户角色关联
- 租户:多租户隔离
- 服务器:MCP服务器配置(STDIO、SSE、AWS_LAMBDA、可执行)
- 部署:具有状态跟踪的部署记录
- ApiKey:具有权限和IP白名单的API密钥
- 使用记录:计费/配额的使用情况跟踪
- 网络钩子:事件通知的Webhook配置
- 健康检查:部署的健康检查记录
- 指标:Prometheus指标存储
- 审计:运营审计跟踪
发展
类型安全
该项目是用TypeScript编写的,启用了严格模式。```bash
Typecheck all packages
pnpm -r typecheck
```
代码组织
- 服务层:业务逻辑
packages/server/src/services/ - 中间件:身份验证、登录
packages/server/src/middleware/ - 防护类型:安全型缩窄
packages/core/src/type-guards.ts - React 钩子:TanStack查询挂钩
packages/dashboard/src/hooks/
添加新功能
- 添加数据库模型:更新
prisma/schema.prisma - 运行迁移:
pnpm db:generate && pnpm db:push - 添加类型:更新
packages/core/src/types.ts - 添加服务:创建于
packages/server/src/services/ - 添加路线:创建于
packages/server/src/routes/ - 更新仪表板:添加挂钩和页面
许可证
麻省理工学院
贡献
欢迎投稿!请阅读我们的投稿指南和行为准则。