使用说明
Echo框架的MCP包装器
将任何现有的Echo API包裹到MCP工具中，使AI代理能够通过 模型上下文协议.
主要特点
- 零配置：适用于任何现有的Echo API
- 多个架构源：支持Swaggo、原始OpenAPI YAML/JSON和手动模式
- 过滤：包含/排除带有通配符模式的端点
- MCP兼容：可与任何支持MCP的代理配合使用。
安装
go get github.com/BrunoKrugel/echo-mcp
快速开始
package main
import (
"net/http"
server "github.com/BrunoKrugel/echo-mcp"
"github.com/labstack/echo/v4"
)
func main() {
e := echo.New()
// Existing API routes
e.GET("/ping", func(c echo.Context) error {
return c.JSON(http.StatusOK, map[string]string{"message": "pong"})
})
// Add MCP support
mcp := server.New(e)
mcp.Mount("/mcp")
e.Start(":8080")
}
现在API可以访问 http://localhost:8080/mcp
高级用法
自动Swagger模式
如果您已经将Swaggo用于Swagger文档，请启用自动模式生成：
// @Summary Get user by ID
// @Description Retrieve detailed user information
// @Tags users
// @Param id path int true "User ID" minimum(1)
// @Success 200 {object} User
// @Router /users/{id} [get]
func GetUser(c echo.Context) error {
// Your handler code
}
func main() {
e := echo.New()
e.GET("/users/:id", GetUser)
// Enable automatic swagger schema generation
mcp := server.NewWithConfig(e, &server.Config{
BaseURL: "http://localhost:8080",
EnableSwaggerSchemas: true,
})
mcp.Mount("/mcp")
e.Start(":8080")
}
原始OpenAPI模式支持
如果你使用其他OpenAPI库，比如 swaggest/openapi-go，您可以传递一个原始的YAML或JSON模式字符串：
import (
"github.com/swaggest/openapi-go/openapi3"
server "github.com/BrunoKrugel/echo-mcp"
)
func main() {
e := echo.New()
// ... define your routes ...
// Generate OpenAPI schema
reflector := openapi3.Reflector{}
reflector.SpecEns().WithOpenapi("3.0.3")
reflector.SpecEns().Info.WithTitle("My API").WithVersion("1.0.0")
// Add operations to reflector
// ...
// Export to YAML (or JSON)
schema, _ := reflector.Spec.MarshalYAML()
// Pass raw schema to MCP server
// ... you can also embed the schema from an exiting openapi.yaml file
mcp := server.NewWithConfig(e, &server.Config{
OpenAPISchema: string(schema),
})
mcp.Mount("/mcp")
e.Start(":8080")
}
这 OpenAPISchema 字段接受YAML和JSON格式的字符串。提供后，它会自动填充：
- 架构标题中的服务器名称
- 模式描述中的描述
- 版本来自架构版本
- 操作定义中的工具模式
端点筛选
仅向MCP工具公开必要的端点：
mcp := server.New(e)
// Include only specific endpoints
mcp.RegisterEndpoints([]string{
"/api/v1/users/:id",
"/api/v1/orders",
})
// Or exclude internal endpoints
mcp.ExcludeEndpoints([]string{
"/health", // Exclude health checks
})
手动模式注册（WIP）
为了更好地控制，请手动注册模式：
type CreateUserRequest struct {
Name string `json:"name" jsonschema:"required,description=User full name"`
Email string `json:"email" jsonschema:"required,description=User email address"`
Age int `json:"age,omitempty" jsonschema:"minimum=0,maximum=150"`
}
type UserQuery struct {
Page int `form:"page,default=1" jsonschema:"minimum=1"`
Limit int `form:"limit,default=10" jsonschema:"maximum=100"`
Active bool `form:"active" jsonschema:"description=Filter by active status"`
}
mcp := server.New(e, &server.Config{BaseURL: "http://localhost:8080"})
// Register schemas for specific routes
mcp.RegisterSchema("POST", "/users", nil, CreateUserRequest{})
mcp.RegisterSchema("GET", "/users", UserQuery{}, nil)
模式生成方法
Echo MCP支持四种模式生成方法，并具有自动回退功能：
| 方法 | 用例 | 优先级 |
|---|---|---|
| 原始OpenAPI架构 | 使用OpenAPI库，如swaggest/OpenAPI go | First（如果设置了OpenAPISchema） |
| 昂首阔步 | 带有Swaggo注释的生产API | 第一个（如果设置了EnableSwaggerSchemas） |
| 手册 | 细粒度控制，复杂验证 | 第二 |
| 自动 | 快速原型制作，简单的端点 | 回退 |
// Option 1: Using raw OpenAPI schema (swaggest/openapi-go, etc.)
schema, _ := reflector.Spec.MarshalYAML()
mcp := server.New(e, &server.Config{
OpenAPISchema: string(schema), // Use raw schema
})
// Option 2: Using Swaggo
mcp := server.New(e, &server.Config{
EnableSwaggerSchemas: true, // Load from swaggo docs
})
// Option 3: Manual schemas for fine-grained control
mcp.RegisterSchema("POST", "/users", nil, CreateUserRequest{})
// Option 4: Automatic inference (fallback)
// No configuration needed - routes will use basic path/body inference
MCP客户端集成
服务器运行后：
手动配置
{
"mcpServers": {
"echo-api": {
"type": "http",
"url": "http://localhost:8080/mcp",
"timeout": 120
},
}
}
本地测试
对于本地测试，请使用MCP Inspector：
npx @modelcontextprotocol/inspector http://localhost:8080/mcp
致谢
- Swaggo -Swagger文档生成器
- swaggest/openapi go -OpenAPI 3.0 Go工具包
- Echo框架 -高性能Go web框架
- 回声切换器 -Echo的Swagger UI中间件
- 模型上下文协议 -人工智能工具交互通用协议
