mcpblade

# MCPBlade MCPBlade 是一款强大的聚合和管理服务，适用于模型控制协议（MCP）服务器。它提供了智能工具发现、语义搜索和智能路由功能，可以与多个 MCP 服务器无缝协作。 ## 功能 - **工具聚合**：将多个 MCP 服务器的工具合并到一个统一的界面 - **语义搜索**：基于向量的搜索，使用自然语言查询查找工具 - **智能路由**：自动将工具调用路由到正确的后端服务器 - **健康监测**：对所有连接的服务器进行持续的健康检查和心跳监测 - **持久和临时服务器**：支持基于持久配置和运行时临时服务器 - **多种传输类型**：支持 stdio、SSE 和可流式 HTTP 传输，用于后端连接 - **NATS 集成**：通过 NATS 消息传递与微服务进行分布式服务通信 - **HTTP API**：RESTful API 和 MCP 兼容的流式端点 - **中间件架构**：支持日志、代理和其他中间件 ## 架构 MCPBlade 由几个关键组件组成： - **核心服务**（[`service.go`](service.go)）：主要的业务逻辑和 MCP 服务器管理 - **向量搜索**（[`vector/`](vector/)）：工具索引和语义搜索功能 - **传输层**： - [`transport/nats/`](transport/nats/)：基于 NATS 的通信 - [`transport/http/`](transport/http/)：HTTP API 端点 - **持久性**（[`persistence/chromem/`](persistence/chromem/)）：向量数据库实现 - **MCP 集成**（[`mcp/`](mcp/)）：MCP 协议端点处理程序 - **代理层**（[`proxy.go`](proxy.go)）：用于分布式部署的服务代理中间件 ## 安装 ```bash go install github.com/flarexio/mcpblade/cmd/mcpblade@latest go install github.com/flarexio/mcpblade/cmd/mcpblade_mcp_server@latest ``` ## 配置 创建配置文件 `config.yaml`（参见 [`config.example.yaml`](config.example.yaml) 作为参考）： ```yaml mcpServers: time: transport: stdio command: uvx args: [ "mcp-server-time", "--local-timezone=Asia/Taipei" ] cacheRefreshTTL: 5m vector: enabled: true persistent: true collection: tools ``` ### 支持的传输类型 - **stdio**：与子进程的标准输入/输出通信 - **sse**：通过 HTTP 的服务器发送事件 - **streamable-http**：HTTP 流协议 ## 使用 ### 运行核心服务 ```bash # 使用默认配置文件路径 (~/.flarex/mcpblade) mcpblade # 使用自定义配置文件路径 mcpblade --path /path/to/config # 启用 HTTP API mcpblade --http --http-addr :8080 # 连接到自定义 NATS 服务器 mcpblade --nats nats://localhost:4222 ``` ### 作为 MCP 服务器运行 ```bash # 连接到共享的 MCPBlade 实例 mcpblade_mcp_server --edge-id your-edge-id # 运行具有特定 MCP 后端的专用服务器 mcpblade_mcp_server --edge-id your-edge-id --server-id my-server --cmd "uvx mcp-server-time" # 连接到自定义 NATS 服务器 mcpblade_mcp_server --edge-id your-edge-id --nats nats://localhost:4222 ``` ## API 参考 ### 核心服务接口 [`Service`](service.go) 接口提供以下方法： - **RegisterMCPServer**：向注册表中添加新的 MCP 服务器 - **UnregisterMCPServer**：从注册表中删除 MCP 服务器 - **ListTools**：从注册的服务器获取所有可用的工具 - **SearchTools**：使用语义查询搜索工具 - **Forward**：将 MCP 请求路由到适当的后端服务器 - **Close**：正常关闭服务 ### HTTP API 端点 启用 HTTP 传输时： ```bash # RESTful API POST /api/mcp/register # 注册 MCP 服务器 DELETE /api/mcp/unregister/:id # 注销 MCP 服务器 GET /api/mcp/tools # 列出所有工具 GET /api/mcp/tools/search # 搜索工具 POST /api/mcp/forward # 转发工具调用 # MCP 协议 POST /mcp/ # MCP JSON-RPC 端点 ``` ### 示例工具搜索 ```go // 语义搜索工具 tools, err := service.SearchTools(ctx, "what's the current time?", 5) if err != nil { return err } for _, tool := range tools { fmt.Printf("Tool: %s - %s\n", tool.Name, tool.Description) } ``` ### 示例工具调用 ```go req := mcp.CallToolRequest{ Request: mcp.Request{Method: "tools/call"}, Params: mcp.CallToolParams{ Name: "get_current_time", Arguments: map[string]any{ "timezone": "Asia/Taipei", }, }, } result, err := service.Forward(ctx, req) if err != nil { return err } // 处理结果 if !result.IsError { for _, content := range result.Content { fmt.Printf("Result: %v\n", content) } } ``` ## 传输架构 ``` [MCP 客户端] ↓ (stdio/nats/http) [MCPBlade 代理/服务] ↓ (stdio/sse/streamable-http) [后端 MCP 服务器] ``` ### 流程描述 1. **入站**：客户端通过以下方式连接到 MCPBlade： - **stdio**：原生 MCP 协议（通过 [`mcpblade_mcp_server`](cmd/mcpblade_mcp_server/main.go)） - **nats**：分布式消息传递（通过 [`transport/nats/`](transport/nats/)） - **http**：RESTful API 和 MCP 流式传输（通过 [`transport/http/`](transport/http/)） 2. **处理**：MCPBlade 使用以下方式聚合、搜索和路由请求： - 工具缓存和去重 - 基于向量的语义搜索 - 健康监测和心跳跟踪 3. **出站**：MCPBlade 作为 MCP 客户端通过以下方式连接到后端服务器： - **stdio**：子进程通信 - **sse**：服务器发送事件 - **streamable-http**：HTTP 流式传输 ## 向量搜索 工具在向量数据库中自动索引，以便进行智能搜索： ```go // 搜索工具使用语义相似性 tools, err := service.SearchTools(ctx, "time and date functions", 10) // 工具索引包含元数据，包括： - 服务器 ID - 工具名称和描述 - 输入模式 - 用于重建的完整工具 JSON ``` 向量实现使用 [ChromeDB](https://github.com/philippgille/chromem-go)，支持： - 内存集合用于开发 - 生产环境中的持久存储 - 自动嵌入生成 - 具有可配置结果限制的相似性搜索 ## 健康监测 服务持续监测所有注册的 MCP 服务器的健康状况： - **定期健康检查**：基于 TTL 的可配置监测 - **心跳跟踪**：每个服务器的原子时间戳跟踪 - **自动恢复**：失败的服务器可以自动重启 - **缓存刷新**：根据健康状态刷新工具缓存 - **优雅降级**：失败的服务器被排除在路由之外 ## 中间件系统 MCPBlade 使用中间件架构处理横切关注点： ### 日志中间件 ```go svc = mcpblade.LoggingMiddleware(logger)(svc) ``` 提供具有 [Zap](https://github.com/uber-go/zap) 的结构化日志记录，用于所有服务操作。 ### 代理中间件 ```go svc = mcpblade.ProxyMiddleware(endpoints)(svc) ``` 通过 NATS 端点启用分布式部署，代理调用。 ## 开发 ### 运行测试 ```bash # 运行所有测试 go test ./... # 使用竞争检测运行 go test -race ./... # 运行特定的测试套件 go test ./service_test.go ``` ### 项目结构 ``` ├── cmd/ │ ├── mcpblade/ # 主服务可执行文件 │ └── mcpblade_mcp_server/ # MCP 服务器实现 ├── transport/ │ ├── nats/ # NATS 传输层 │ │ ├── transport.go # NATS 处理程序 │ │ ├── factory.go # NATS 客户端端点 │ │ └── topic.go # NATS 主题路由 │ └── http/ # HTTP 传输层 │ ├── transport.go # HTTP 处理程序 │ ├── mcp.go # MCP 流式端点 │ └── router.go # 路由配置 ├── persistence/chromem/ # ChromeDB 向量数据库 ├── vector/ # 向量数据库接口 ├── mcp/ # MCP 协议处理程序 │ ├── endpoint.go # MCP 端点实现 │ └── endpoint_test.go # MCP 协议测试 ├── service.go # 核心服务实现 ├── service_test.go # 服务集成测试 ├── model.go # 数据模型和类型 ├── model_test.go # 模型序列化测试 ├── endpoint.go # Go-kit 端点 ├── proxy.go # 代理中间件 ├── logging.go # 日志中间件 └── config.example.yaml # 示例配置 ``` ## 依赖 - [mcp-go](https://github.com/mark3labs/mcp-go)：MCP 协议实现 - [chromem-go](https://github.com/philippgille/chromem-go)：向量数据库 - [nats.go](https://github.com/nats-io/nats.go)：具有微服务的 NATS 消息传递 - [go-kit](https://github.com/go-kit/kit)：端点微服务工具包 - [gin](https://github.com/gin-gonic/gin)：HTTP Web 框架 - [zap](https://github.com/uber-go/zap)：结构化日志记录 - [cli/v3](https://github.com/urfave/cli)：命令行界面 ## 许可证 MIT 许可证 - 有关详细信息，请参见 [LICENSE.md](LICENSE.md)。 该项目是 FlareX 生态系统的一部分。 ## 贡献 欢迎贡献！请确保： 1. 所有测试通过：`go test ./...` 2. 代码遵循 Go 惯例 3. 新功能包括测试 4. 文档已更新 5. 提交消息描述清晰 对于重大更改，请先打开问题讨论提议的更改。