echo-mcp

Convierte automáticamente cualquier API de Echo en una herramienta MCP

GitHub
12

Documentación

Wrapper MCP para Echo Framework

Build Status Codecov branch Go Report Card Release

Envuelve cualquier API Echo existente en herramientas MCP y permite que los agentes de IA interactúen con tu API a través del Protocolo de Contexto de Modelo.

Inspirado en gin-mcp pero para el framework Echo.

Características Principales

  • Configuración Cero: Funciona con cualquier API Echo existente
  • Múltiples Fuentes de Esquema: Soporte para Swaggo, OpenAPI YAML/JSON sin procesar y esquemas manuales
  • Filtrado: Incluir/excluir endpoints con patrones comodín
  • Compatible con MCP: Funciona con cualquier agente que soporte MCP.

Instalación

go get github.com/BrunoKrugel/echo-mcp

Inicio Rápido

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")
}

Ahora la API es accesible en http://localhost:8080/mcp

Uso Avanzado

Esquemas Swagger Automáticos

Si ya usas Swaggo para la documentación Swagger, habilita la generación automática de esquemas:

// @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")
}

Soporte de Esquema OpenAPI sin Procesar

Si usas otras librerías OpenAPI como swaggest/openapi-go, puedes pasar una cadena de esquema YAML o JSON sin procesar:

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")
}

El campo OpenAPISchema acepta cadenas con formato YAML y JSON. Cuando se proporciona, completa automáticamente:

  • Nombre del servidor a partir del título del esquema
  • Descripción a partir de la descripción del esquema
  • Versión a partir de la versión del esquema
  • Esquemas de herramientas a partir de las definiciones de operaciones

Filtrado de Endpoints

Expón solo los endpoints necesarios a las herramientas 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
})

Registro Manual de Esquemas (WIP)

Para un mejor control, registra esquemas manualmente:

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)

Métodos de Generación de Esquemas

Echo-MCP soporta cuatro enfoques de generación de esquemas, con respaldo automático:

MétodoCaso de UsoPrioridad
Esquema OpenAPI sin ProcesarUsando librerías OpenAPI como swaggest/openapi-goPrimero (si OpenAPISchema está configurado)
SwaggerAPIs de producción con anotaciones SwaggoPrimero (si EnableSwaggerSchemas está configurado)
ManualControl detallado, validación complejaSegundo
AutomáticoPrototipado rápido, endpoints simplesRespaldo
// 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

Integración con Cliente MCP

Una vez que tu servidor esté en ejecución:

Configuración manual

{
  "mcpServers": {
    "echo-api": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "timeout": 120
    },
  }
}

Pruebas Locales

Para pruebas locales, usa MCP Inspector:

npx @modelcontextprotocol/inspector http://localhost:8080/mcp

Agradecimientos