mcp

README

MCP Module

Model Context Protocol (MCP) module, manages the unified MCP server with stdio and Streamable HTTP transports.

Directory Structure

internal/modules/mcp/
├── module.go                      # MCP module core
├── module_http_contract_test.go   # HTTP interface contract tests
├── dto.go                         # Data transfer objects
├── utils.go                       # Utility functions
└── README.md                      # This document

cmd/mcp/
└── main.go                        # Unified MCP server entry (stdio mode)

Transports

Transport	Endpoint	Use Case
Streamable HTTP	POST/GET/DELETE /api/v1/mcp/sse	Web apps, remote access, multi-client
stdio	./bin/mcp	Local CLI tools, Claude Desktop

---

Streamable HTTP Interface

The unified endpoint /api/v1/mcp/sse supports three HTTP methods per the MCP Streamable HTTP spec:

Method	Purpose	When
POST	Send JSON-RPC messages (initialize, tools/list, tools/call, notifications)	All client-to-server communication
GET	Open SSE stream for server-to-client messages	After initialize, for server-initiated messages
DELETE	Close a session	When done

Required Headers

Header	Required	Description
Content-Type: application/json	POST	JSON-RPC payload
Accept: application/json, text/event-stream	POST/GET	Required by spec
Mcp-Session-Id	After initialize	Session ID from initialize response
Mcp-Protocol-Version	After initialize	e.g. 2025-06-18

Protocol Flow

1. POST  /api/v1/mcp/sse  {"method":"initialize","params":{"protocolVersion":"2025-06-18"}}
   <- 200 OK + Mcp-Session-Id header + InitializeResult JSON

2. POST  /api/v1/mcp/sse  {"method":"notifications/initialized"}
   (with Mcp-Session-Id + Mcp-Protocol-Version headers)
   <- 202 Accepted

3. POST  /api/v1/mcp/sse  {"method":"tools/list"}
   (with Mcp-Session-Id + Mcp-Protocol-Version headers)
   <- 200 OK + tools catalog JSON

4. POST  /api/v1/mcp/sse  {"method":"tools/call","params":{"name":"list_schemas"}}
   <- 200 OK + tool result JSON

5. DELETE /api/v1/mcp/sse
   (with Mcp-Session-Id header)
   <- 204 No Content

Quick Test

# Start the server
cd backend && make dev

# Initialize a session
curl -i -X POST http://localhost:8080/api/v1/mcp/sse \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

---

Discovery & Health

# List available servers
curl http://localhost:8080/api/v1/mcp/servers | jq

# Health check
curl http://localhost:8080/api/v1/mcp/health | jq

---

Client Configuration

Claude Desktop (Streamable HTTP)

{
  "mcpServers": {
    "leeforge": {
      "url": "http://localhost:8080/api/v1/mcp/sse"
    }
  }
}

Claude Desktop (stdio)

{
  "mcpServers": {
    "leeforge": {
      "command": "/path/to/backend/bin/mcp",
      "args": [],
      "env": {}
    }
  }
}

Go SDK Client

client := mcp.NewClient(&mcp.Implementation{
    Name:    "my-client",
    Version: "1.0.0",
}, nil)

transport := &mcp.StreamableClientTransport{
    Endpoint: "http://localhost:8080/api/v1/mcp/sse",
}

session, err := client.Connect(context.Background(), transport, nil)

---

Available Tools

All tools are exposed through the unified server:

Tool	Module	Description
list_schemas	schema	List all entity schemas
get_schema_by_module	schema	Get schemas by module name
get_schema_by_name	schema	Get schema by entity name
validate_schema	schema	Validate a schema definition
create_menu	menu	Create a menu item
batch_create_menus	menu	Create multiple menu items
get_menu_tree	menu	Get the menu tree
delete_menu	menu	Delete a menu item

---

Version: 3.0.0 Last Updated: 2026-02-15 Transport: Streamable HTTP (MCP spec 2025-06-18)

Documentation

Index

• Variables
• func NewMCPModule(logger logging.Logger, deps *core.Dependencies) core.Module
• type ErrorResponse
• type HealthResponse
• type MCPCapabilities
• type MCPExamples
• type MCPModule
  • func (m *MCPModule) GetUnifiedServer() *mcp.Server
  • func (m *MCPModule) Name() string
  • func (m *MCPModule) RegisterPrivateRoutes(r chi.Router)
  • func (m *MCPModule) RegisterPublicRoutes(r chi.Router)
  • func (m *MCPModule) RunMCPServer(ctx context.Context, serverName string) error
• type MCPServerInfo
• type ServerHealth
• type ServersResponse

Variables

var (
	ErrServerNotFound = errors.New("MCP server not found")
)

Errors

Functions

func NewMCPModule

func NewMCPModule(logger logging.Logger, deps *core.Dependencies) core.Module

NewMCPModule creates a new MCP module

Types

type ErrorResponse

type ErrorResponse struct {
	Error   string `json:"error"`
	Message string `json:"message"`
}

ErrorResponse is the standard error response

type HealthResponse

type HealthResponse struct {
	Status  string                  `json:"status"`
	Servers map[string]ServerHealth `json:"servers"`
}

HealthResponse is the response for health check

type MCPCapabilities

type MCPCapabilities struct {
	Resources []string `json:"resources"`
	Tools     []string `json:"tools"`
}

MCPCapabilities describes what an MCP server can do

type MCPExamples

type MCPExamples struct {
	StdioUsage          []string       `json:"stdioUsage,omitempty"`
	HTTPUsage           []string       `json:"httpUsage,omitempty"`
	ClaudeDesktopConfig map[string]any `json:"claudeDesktopConfig,omitempty"`
}

MCPExamples provides usage examples

type MCPModule

type MCPModule struct {
	// contains filtered or unexported fields
}

MCPModule represents the MCP module that manages all MCP servers

func (*MCPModule) GetUnifiedServer

func (m *MCPModule) GetUnifiedServer() *mcp.Server

GetUnifiedServer returns the unified MCP server

func (*MCPModule) Name

func (m *MCPModule) Name() string

Name returns the module name

func (*MCPModule) RegisterPrivateRoutes

func (m *MCPModule) RegisterPrivateRoutes(r chi.Router)

RegisterPrivateRoutes registers MCP endpoints (requires JWT or API-key authentication)

func (*MCPModule) RegisterPublicRoutes

func (m *MCPModule) RegisterPublicRoutes(r chi.Router)

RegisterPublicRoutes - MCP module has no public routes

func (*MCPModule) RunMCPServer

func (m *MCPModule) RunMCPServer(ctx context.Context, serverName string) error

RunMCPServer runs a specific MCP server by name (for command-line use)

type MCPServerInfo

type MCPServerInfo struct {
	Name         string          `json:"name"`
	Description  string          `json:"description"`
	Version      string          `json:"version"`
	Status       string          `json:"status"` // running, stopped, error
	Transports   []string        `json:"transports"`
	HTTPEndpoint string          `json:"httpEndpoint,omitempty"`
	StdioCommand string          `json:"stdioCommand,omitempty"`
	Capabilities MCPCapabilities `json:"capabilities"`
	Examples     *MCPExamples    `json:"examples,omitempty"`
}

MCPServerInfo contains information about an MCP server

type ServerHealth

type ServerHealth struct {
	Status     string            `json:"status"`
	Transports map[string]string `json:"transports,omitempty"`
}

ServerHealth contains health information for a server

type ServersResponse

type ServersResponse struct {
	Servers []MCPServerInfo `json:"servers"`
	Count   int             `json:"count"`
}

ServersResponse is the response for listing servers