gomcp

README

gomcp

A clean Go library for building Model Context Protocol (MCP) servers on top of mcp-go.

Features

• Three ways to register tools: inline struct, function helper, or JSON file on disk
• Built-in argument extraction helpers (ArgString, ArgFloat, ArgBool, …)
• Result builders (ResultText, ResultJSON, ResultError, …)
• Both SSE (HTTP) and Stdio transports — pick at runtime

---

Installation

go get github.com/raykavin/gomcp

---

Quick start

package main

import (
	"context"

	mcpserver "github.com/raykavin/gomcp/server"
)

func main() {

	srv := mcpserver.NewMCPServer("my-agent", "1.0.0")

	// Register a tool
	srv.AddToolFunc(
		"echo",
		"Returns the input message",
		mcpserver.JSONSchema{
			Type: "object",
			Required: []string{"message"},
			Properties: map[string]mcpserver.JSONSchemaProperty{
				"message": {Type: "string", Description: "Message to echo"},
			},
		},
		func(ctx context.Context, req mcpproto.CallToolRequest) (*mcpproto.CallToolResult, error) {
			msg, errResult := mcpserver.ArgStringRequired(req, "message")
			if errResult != nil {
				return errResult, nil
			}
			return mcpserver.ResultText("echo: " + msg), nil
		},
	)

	// Start SSE transport
	srv.Start(ctx, ":8080")
}

---

Tool registration methods

1. AddToolFunc: inline, all fields explicit

Best for tools defined entirely in Go code.

err := srv.AddToolFunc(
    "search",                   // name
    "Search the web",           // description
    mcpserver.JSONSchema{...},  // schema
    myHandler,
)

2. AddTool: using a ToolDefinition struct

Useful when building definitions programmatically or receiving them from external sources.

def := mcpserver.ToolDefinition{
    Name:        "add",
    Description: "Adds two numbers",
    Schema:      mcpserver.JSONSchema{...},
}
err := srv.AddTool(def, myHandler)

3. AddToolFromFile: load from a JSON file on disk

Keeps tool metadata outside Go code. Ideal for config-driven agents or tools shared across projects.

err := srv.AddToolFromFile("tools/search.json", myHandler)

JSON file format:

{
  "name": "search",
  "description": "Search the web and return relevant results",
  "schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "The search query" },
      "max_results": { "type": "number", "description": "Max results" }
    },
    "required": ["query"]
  }
}

4. AddToolFromJSON: load from raw []byte

For tools fetched from a database, remote config, etc.

data := []byte(`{...}`)
err := srv.AddToolFromJSON(data, myHandler)

---

Argument helpers

Inside a handler, use the helpers to safely extract typed arguments:

// String (returns error result if missing)
msg, errResult := mcpserver.ArgStringRequired(req, "message")
if errResult != nil {
    return errResult, nil
}

// Optional string
if q, ok := mcpserver.ArgString(req, "query"); ok { ... }

// Number
if n, ok := mcpserver.ArgFloat(req, "count"); ok { ... }

// Bool
if verbose, ok := mcpserver.ArgBool(req, "verbose"); ok { ... }

---

Result helpers

mcpserver.ResultText("plain string response")
mcpserver.ResultJSON(map[string]any{"key": "value"})
mcpserver.ResultError("something broke", err)
mcpserver.ResultErrorMsg("missing argument: query")

---

Transports

SSE (HTTP): default

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()

if err := srv.Start(ctx, ":8080"); err != nil {
    log.Fatal(err)
}

Clients connect via http://localhost:8080/sse.

Stdio: For Claude Desktop and local agents

if err := srv.StartStdio(ctx); err != nil {
    log.Fatal(err)
}

Graceful shutdown (SSE only)

srv.Shutdown(ctx)

---

Project structure

github.com/raykavin/gomcp/
├── server.go     # MCPServer, Start, StartStdio, Shutdown
├── tool.go       # ToolDefinition, JSONSchema, ParseToolDefinition
├── helpers.go    # ResultText/JSON/Error, ArgString/Float/Bool helpers
├── go.mod
└── example/
    ├── main.go
    └── tools/
        └── search.json

---

Tests

go test ./server

---

Contributing

Contributions to gomcp are welcome! Here are some ways you can help improve the project:

• Report bugs and suggest features by opening issues on GitHub
• Submit pull requests with bug fixes or new features
• Improve documentation to help other users and developers
• Share your custom strategies with the community

License

gomcp is distributed under the MIT License.
For complete license terms and conditions, see the LICENSE file in the repository.

---

Contact

For support, collaboration, or questions about gomcp:

Email: raykavin.meireles@gmail.com
GitHub: @raykavin