README - nunu-layout-mcp by go-nunu

🚀 Quickly Build a High-Performance Go MCP Server

This project is a sample MCP Server built using the Nunu framework and MCP-GO. It allows you to rapidly set up a Golang-based MCP Server and test/debug it using the MCP Inspector tool.

🚀 Quick Start: Run the MCP Server in 3 Minutes

1. Create a Project

Option 1: Clone the Template Repository

git clone https://github.com/go-nunu/nunu-layout-mcp.git
# Note: The default project name is nunu-layout-mcp

Option 2: Create a New Project via Nunu CLI (Recommended)

go install github.com/go-nunu/nunu@latest

nunu new mcp-demo -r https://github.com/go-nunu/nunu-layout-mcp.git

2. Build and Start

Build the MCP Server

cd mcp-demo

go build -ldflags="-s -w" -o ./bin/server ./cmd/server

Start MCP Inspector

MCP Inspector is an interactive developer tool provided by the MCP community for testing and debugging:

npx -y @modelcontextprotocol/inspector ./bin/server
# Requires Node.js to be installed

3. Test the Service

Open your browser: http://127.0.0.1:6274 to test different transport protocols.

Transport Type	Address / Parameter	Use Case	Pros	Cons
STDIO	`./bin/server`	CLI tools, desktop apps	Simple, secure, no network needed	Local only, single client
SSE	`http://localhost:3001/sse`	Web real-time comm.	Multi-client, real-time, browser friendly	HTTP overhead, server-to-client only
StreamableHTTP	`http://localhost:3002/mcp`	Web services, APIs	Standard protocol, caching & load balancing	No real-time support, slightly complex
In-Process	(no external address)	Embedded, testing	No serialization, ultra-fast	In-process only

🛠️ Development Guide

As this project is built on the Nunu architecture, it’s recommended to understand the framework before development.

📡 MCP Server Development

See the MCP-GO Server Docs

This project enables three protocols by default: STDIO, SSE, StreamableHTTP. You can modify or disable them as needed:

// File: internal/server/mcp.go

func setupSrv(logger *log.Logger) *servermcp.Server {
	mcpServer := server.NewMCPServer(
		"example-servers/everything",
		"1.0.0",
		server.WithResourceCapabilities(true, true),
		server.WithPromptCapabilities(true),
		server.WithToolCapabilities(true),
		server.WithLogging(),
		server.WithHooks(newHooks(logger)),
	)

	return servermcp.NewServer(logger,
		servermcp.WithMCPSrv(mcpServer),

		// STDIO
		servermcp.WithStdioSrv(true),

		// SSE
		servermcp.WithSSESrv(":3001", server.NewSSEServer(
			mcpServer,
			server.WithSSEEndpoint("/sse"),
		)),

		// StreamableHTTP
		servermcp.WithStreamableHTTPSrv(":3002", server.NewStreamableHTTPServer(
			mcpServer,
			server.WithEndpointPath("/mcp"),
		)),
	)
}

Call Flow Diagram

client
  ↓
internal/server/mcp.go
  ↓
internal/handler/example.go
  ↓
internal/service/example.go
  ↓
internal/repository/example.go
  ↓
DB / Third-party services

Note:

If MCP STDIO is enabled, no logs should be printed to the terminal, or the communication will break. You must configure logs to write only to a file:

# File: config/local.yml
log:
  log_level: debug
  mode: file               # file, console, or both
  encoding: console        # json or console
  log_file_name: "./storage/logs/server.log"
  max_backups: 30
  max_age: 7
  max_size: 1024
  compress: true

To view logs in Unix systems:

tail -f storage/logs/server.log

🤝 Integrating MCP Client

See MCP-GO Client Docs

You can register a client in internal/repository/repository.go, for example:

func NewStdioMCPClient() *client.Client {
	c, err := client.NewStdioMCPClient(
		"go", []string{}, "run", "/path/to/server/main.go",
	)
	if err != nil {
		panic(err)
	}
	defer c.Close()
	return c
}

To integrate other protocols or clients, follow similar patterns used in redis, gorm, etc.

📚 Resources

Final Notes

Currently, there is no official Golang SDK provided by the MCP organization. The most mature open-source project is mark3labs/mcp-go.

We’re looking forward to an official Golang SDK, and this project will be updated accordingly once it’s released.

Official Go MCP SDK: https://github.com/golang/tools/tree/master/internal/mcp

📄 License

Nunu is released under the — free to use and contribute!