carljmosca/mcp-golang-wasm-example

MCP Go WASM Server

A Model Context Protocol (MCP) server implementation in Go that runs in the browser via WebAssembly. This project demonstrates how to build an MCP server that can be executed client-side using WASM, enabling streamable HTTP communication without external dependencies.

🌟 Features

• Pure Go Implementation: Built using Go's standard library with no external dependencies
• WebAssembly Support: Runs entirely in the browser via WASM
• MCP Protocol Compliant: Implements the Model Context Protocol specification (version 2024-11-05)

1. Go WASM Module: Compiles to WebAssembly and exposes JavaScript functions
2. JavaScript Bridge: Handles communication between the browser and WASM
3. JSON-RPC Protocol: Standard request/response pattern for tool invocation
4. MCP Compliance: Follows the Model Context Protocol specification

🚀 Quick Start

Prerequisites

• Go 1.21 or higher
• Python 3 (for local HTTP server)
• Modern web browser with WebAssembly support
• Or use the included Dev Container for a pre-configured environment

Using Dev Container (Recommended)

This project includes a Dev Container configuration for VS Code. You do not need to install Go or Python locally.

Steps:

1. Open the project in VS Code.
2. If prompted, "Reopen in Container" (or use the Command Palette: Dev Containers: Reopen in Container).
3. The container will build with Go and Python pre-installed, and VS Code extensions for Go and Python enabled.
4. Use the integrated terminal to run make build and make serve as described below.

This ensures a consistent development environment for all contributors.

Build and Run

# Build the WASM binary
make build

# Serve the application (builds automatically)
make serve

# Or combine both steps
make run

Then open your browser to http://localhost:8080

Manual Build

# Build WASM
GOOS=js GOARCH=wasm go build -o main.wasm main.go

# Copy the Go WASM runtime
cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" .

# Serve with any HTTP server
python3 -m http.server 8080

📖 Usage

Using the Web Interface

1. Initialize Server: Click "Initialize Server" to establish the MCP connection
2. List Tools: View all available tools and their schemas
3. Call Tool: Select a tool from the dropdown, enter parameters (space-separated), and execute the tool. For example, use add 2 3 to get the sum of 2 and 3, or select getCurrentTime with no parameters.

Programmatic Usage

// Send a JSON-RPC request to the MCP server
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "add",
        arguments: { a: 2, b: 3 }
    }
};

const responseJSON = mcpHandleRequest(JSON.stringify(request));
const response = JSON.parse(responseJSON);
console.log(response.result);

🛠️ MCP Protocol Implementation

Supported Methods

Example Tools

getCurrentTime

{
    "name": "getCurrentTime",
    "description": "Returns the current time in RFC3339 format",
    "inputSchema": {
        "type": "object",
        "properties": {},
        "required": []
    }
}

add

{
    "name": "add",
    "description": "Returns the sum of two numbers (a + b)",
    "inputSchema": {
        "type": "object",
        "properties": {
            "a": { "type": "number" },
            "b": { "type": "number" }
        },
        "required": ["a", "b"]
    }
}

🔧 Adding New Tools

🔧 Adding or Using Tools

To use a tool, select it from the dropdown in the UI and enter its parameters (space-separated). For example:

• For add, enter: 2 3 (returns 5)
• For getCurrentTime, no parameters are needed

To add a new tool to the server, define it in NewMCPServer() and implement its handler in handleToolCall(), then rebuild the WASM binary.

📁 Project Structure

.
├── main.go           # MCP server implementation
├── index.html        # Web interface
├── go.mod           # Go module definition
├── Makefile         # Build automation
└── README.md        # This file

🎨 Design Philosophy

This implementation prioritizes:

• Simplicity: No external dependencies, pure Go standard library
• Efficiency: Minimal overhead, direct JavaScript bridge
• Idiomatic Go: Follows Go best practices and conventions
• Browser-First: Designed specifically for WASM/browser environments
• MCP Compliance: Adheres to the Model Context Protocol specification

🔍 Technical Details

WASM Bridge

The Go code exposes a single function to JavaScript:

js.Global().Set("mcpHandleRequest", js.FuncOf(func(this js.Value, args []js.Value) interface{} {
    requestJSON := args[0].String()
    response := server.HandleRequest(requestJSON)
    return response
}))

JSON-RPC 2.0

All communication follows the JSON-RPC 2.0 specification:

• Request: { jsonrpc, id, method, params }
• Response: { jsonrpc, id, result } or { jsonrpc, id, error }

Error Codes

Standard JSON-RPC error codes:

• -32700: Parse error
• -32601: Method not found
• -32602: Invalid params

🧪 Testing

Test the server using the web interface or browser console:

// Initialize
mcpHandleRequest('{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}')

// List tools
mcpHandleRequest('{"jsonrpc":"2.0","id":2,"method":"tools/list"}')

// Call tool
mcpHandleRequest('{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"getCurrentTime"}}')

📝 License

MIT License - feel free to use this in your own projects!

🤝 Contributing

Contributions are welcome! Feel free to:

• Add new example tools
• Improve the UI
• Enhance error handling
• Add tests
• Improve documentation

🔗 Resources

• Model Context Protocol Specification
• Go WebAssembly Documentation
• JSON-RPC 2.0 Specification

Built with ❤️ using Go and WebAssembly