gird (Hengistchan)

Gird-MCP服务器管理器

用于部署和管理MCP（模型上下文协议）服务器的统一管理系统，具有API密钥认证、访问控制、多策略支持和多种部署选项。

 ](https://nodejs.org/) 

中文文档 |英语

特性

核心能力

• 统一的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部署）

安装

# 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)

发展

# 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

建筑

# Build all packages
pnpm build

# Typecheck all packages
pnpm -r typecheck

# Lint all packages
pnpm lint

用法

CLI命令

# 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 头球

服务器端点

查询参数 （对于列表端点）：

• page （默认值：1）
• pageSize （默认值：20，最大值：100）
• type （STDIO、SSE、AWS_LAMBDA、可执行文件）
• status （活动、停止、错误）
• search （按名称/描述搜索）
• sortBy （名称、createdAt、updatedAt）
• sortOrder （上升，下降）

API关键终结点

响应格式：

{
  "data": { ... },
  "success": true
}

代理服务器

代理代理服务器运行在 http://localhost:3001 默认情况下。

终点：

• GET /health -健康检查
• GET /metrics -普罗米修斯指标
• GET /events -SSE事件流（已验证）
• ALL /mcp/:serverId/* -MCP代理到后端服务器（经过身份验证）

MCP请求示例：

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 文件）：

# 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"

环境变量引用

数据库模式

该项目使用Prisma和SQLite（默认情况下，兼容PostgreSQL）。

核心型号

• 用户：具有电子邮件/密码身份验证的用户帐户
• 会话：web仪表板的用户会话
• 角色：具有JSON权限的RBAC角色
• 用户角色：用户角色关联
• 租户：多租户隔离
• 服务器：MCP服务器配置（STDIO、SSE、AWS_LAMBDA、可执行）
• 部署：具有状态跟踪的部署记录
• ApiKey：具有权限和IP白名单的API密钥
• 使用记录：计费/配额的使用情况跟踪
• 网络钩子：事件通知的Webhook配置
• 健康检查：部署的健康检查记录
• 指标：Prometheus指标存储
• 审计：运营审计跟踪

发展

类型安全

该项目是用TypeScript编写的，启用了严格模式。

# 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/

添加新功能

1. 添加数据库模型：更新 prisma/schema.prisma
2. 运行迁移: pnpm db:generate && pnpm db:push
3. 添加类型：更新 packages/core/src/types.ts
4. 添加服务：创建于 packages/server/src/services/
5. 添加路线：创建于 packages/server/src/routes/
6. 更新仪表板：添加挂钩和页面

许可证

麻省理工学院

贡献

欢迎投稿！请阅读我们的投稿指南和行为准则。