Samurai MCP Super Server

Samurai MCP Super Server

一款功能全面的模型上下文协议（MCP）超级服务，具备插件架构、安全保险库集成和实时 Web 仪表板。

🚀 功能

核心功能

• 基于插件的架构：适用于不同服务的模块化 MCP 实例（通过 Twilio 发送 SMS 等）
• 大模型提供商管理：支持多个大模型提供商，并管理 API 密钥
• 安全保险库集成：采用行业标准的 API 密钥存储与加密
• 实时 Web 仪表板：提供实时监控与管理界面
• 速率限制与节流：按提供商和插件控制请求
• 全面的日志记录：提供可查询历史记录的请求/响应分析

高级功能

• 插件市场：由社区贡献的插件
• A/B 测试框架：测试不同的大模型配置
• 成本跟踪：按用户/组织进行预算管理
• 响应缓存：通过智能缓存降低 API 成本
• 插件沙箱：为插件提供安全隔离
• 指标与可观测性：集成 Prometheus/Grafana

开发者体验

• 插件 SDK/CLI：易于使用的插件开发工具
• 热重载：开发期间重新加载插件
• OpenAPI 文档：自动生成 API 文档
• 测试框架：用于插件测试的模拟服务

📁 项目结构

├── README.md
├── go.mod
├── go.sum
├── samurai.go                 # Development CLI tool
├── docker-compose.yml         # Database services
├── .env.example              # Environment template
├── backend/
│   ├── cmd/
│   │   └── server/
│   │       └── main.go       # Application entry point
│   └── internal/
│       ├── api/
│       │   ├── handlers/     # HTTP request handlers
│       │   ├── middleware/   # HTTP middleware
│       │   └── routes/       # Route definitions
│       ├── config/           # Configuration management
│       ├── database/         # Database connection & models
│       └── utils/            # Utilities (logging, etc.)
├── config/
│   └── development.json      # Development configuration
├── logs/                     # Application logs
├── bin/                      # Compiled binaries
└── data/                     # Database data

🛠️ 先决条件

• Go 1.21+：下载 Go
• Docker Desktop：下载 Docker
• Git：下载 Git

⚡ 快速开始

1. 克隆仓库

git clone https://github.com/exprays/samurai
cd exprays-samurai

2. 设置开发环境

go run samurai.go setup

这将：

• 创建所需目录
• 将 .env.example 复制到 .env
• 下载 Go 依赖项
• 拉取所需的 Docker 镜像

3. 启动开发环境

go run samurai.go dev

这将：

• 启动 PostgreSQL 数据库
• 启动后端服务
• 显示服务 URL 和状态

4. 验证安装

go run samurai.go status

🔧 开发命令

命令	说明
go run samurai.go dev	启动完整的开发环境
go run samurai.go setup	设置开发环境
go run samurai.go build	构建应用程序
go run samurai.go test	运行所有测试
go run samurai.go status	显示服务状态
go run samurai.go logs	显示服务日志
go run samurai.go stop	停止所有服务
go run samurai.go clean	清理构建产物

🌐 服务端点

服务	URL	说明
健康检查	http://localhost:8080/health	服务健康状态
就绪检查	http://localhost:8080/health/ready	数据库就绪状态
API 基础路径	http://localhost:8080/api/v1	REST API 端点
数据库	localhost:5432	PostgreSQL 数据库

📊 日志记录

应用程序使用结构化日志记录，并将日志分别写入不同的文件：

• 应用程序日志：logs/app.log - 主要应用事件
• 访问日志：logs/access.log - HTTP 请求/响应日志
• 数据库日志：logs/database.log - 数据库查询和操作

日志配置

日志通过环境变量进行配置：

• LOG_LEVEL：debug、info、warn、error（默认值：info）
• LOG_FORMAT：json、console（默认值：json）

🔒 环境配置

将 .env.example 复制到 .env 并进行配置：

# Server Configuration
SERVER_PORT=8080
SERVER_HOST=localhost
SERVER_ENVIRONMENT=development

# Database Configuration
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=samurai
DATABASE_PASSWORD=samurai_password
DATABASE_NAME=samurai_db
DATABASE_SSL_MODE=disable

# Authentication
JWT_SECRET=your-jwt-secret-here
JWT_EXPIRY=24h

# Logging
LOG_LEVEL=info
LOG_FORMAT=json

🏗️ 架构

当前实现（阶段 1）

• ✅ Go 项目结构与模块管理
• ✅ 使用 Gin 框架的 HTTP 服务
• ✅ 配置管理系统
• ✅ 使用 GORM 的 PostgreSQL 数据库
• ✅ 结构化日志基础设施
• ✅ 基于 JWT 的身份验证
• ✅ 用户注册和登录 API
• ✅ 基于角色的访问控制（RBAC）
• ✅ API 中间件（身份验证、CORS、日志记录、恢复）

即将推出的功能（第 2 阶段及后续）

• 🔄 MCP 协议实现
• 🔄 大模型提供商集成
• 🔄 插件系统架构
• 🔄 Vault 集成
• 🔄 前端仪表板
• 🔄 监控与可观测性

🧪 测试

# Run all tests
go run samurai.go test

# Run specific package tests
cd backend && go test ./internal/...

# Run tests with coverage
cd backend && go test -cover ./...

📦 构建

# Build for current platform
go run samurai.go build

# Build for specific platform
cd backend && GOOS=linux GOARCH=amd64 go build -o ../bin/mcp-server-linux ./cmd/server

🔍 监控

健康检查

• GET /health - 基本服务健康状态
• GET /health/ready - 数据库连通性检查

日志

查看实时日志：

# Application logs
tail -f logs/app.log

# Access logs
tail -f logs/access.log

# Database logs
tail -f logs/database.log

🤝 贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 运行测试并确保通过
6. 提交拉取请求

📋 开发阶段

第 1 阶段：基础建设（已完成）

• 项目设置与基础后端
• 身份验证与安全基础
• 数据库模型和连接
• 日志基础设施
• 基础 API 文档

第 2 阶段：核心 MCP 集成（进行中）

• MCP 协议实现
• 大模型提供商集成
• 插件-MCP 桥接
• API 密钥管理

第 3 阶段及后续：高级功能

• Vault 集成
• 前端仪表板
• 监控与可观测性
• 插件市场
• 企业功能

📞 支持

如需支持或有任何疑问：

• 在仓库中创建问题
• 查看 API 文档
• 查阅 开发指南

📄 许可证

[待添加许可证信息]