gustavofagundes/mcp-server-generic

MCP Tools Server

A Model Context Protocol (MCP) server written in Go that provides three useful tools: sum numbers, multiply numbers, and count letters in a sentence.

Features

• Sum Numbers: Add multiple numbers together
• Multiply Numbers: Multiply multiple numbers together
• Count Letters: Count the number of letters in a sentence

Quick Start

Prerequisites

• Go 1.21 or higher
• Git (optional, for cloning)

Installation & Running

1. Install dependencies:

   go mod tidy
   

2. Run the server:

   go run .
   

   The server will start on port 8084 by default. You should see:

   MCP Server starting on port 8084
   Health check available at: http://localhost:8084/health
   MCP endpoint available at: http://localhost:8084/mcp
   Available tools: sum_numbers, multiply_numbers, count_letters
   

3. Health Check: Visit http://localhost:8084/health to verify the server is running.

API Usage

The server implements the MCP (Model Context Protocol) specification. All requests should be sent as POST to /mcp with JSON-RPC 2.0 format.

Initialize the Connection

curl -X POST http://localhost:8084/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }'

List Available Tools

curl -X POST http://localhost:8084/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Tool Examples

Sum Numbers

curl -X POST http://localhost:8084/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "sum_numbers",
      "arguments": {
        "numbers": [1, 2, 3, 4, 5]
      }
    }
  }'

Multiply Numbers

curl -X POST http://localhost:8084/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "multiply_numbers",
      "arguments": {
        "numbers": [2, 3, 4]
      }
    }
  }'

Count Letters

curl -X POST http://localhost:8084/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "count_letters",
      "arguments": {
        "sentence": "Hello, World! 123"
      }
    }
  }'

Configuration

Environment Variables

• PORT: Server port (default: 8084)

Example:

PORT=9000 go run .

Project Structure

mcp-server/
├── go.mod          # Go module file
├── main.go         # Server entry point
├── server.go       # MCP server implementation
├── tools.go        # Tool implementations
├── types.go        # MCP protocol types
└── README.md       # This file

Development

Building

go build -o mcp-server
./mcp-server

Testing Tools

Use the curl examples above or any HTTP client that supports JSON-RPC 2.0.

MCP Protocol Support

This server implements the Model Context Protocol (MCP) specification with support for:

• initialize - Initialize the MCP connection
• tools/list - List available tools
• tools/call - Execute a tool with arguments

Error Handling

The server provides detailed error messages for:

• Invalid JSON-RPC requests
• Missing or invalid parameters
• Tool execution errors
• Unknown methods or tools

License

This project is open source and available under the MIT License.