git@:/.git git remote set-url origin git@github-thecodelogs:thecodelogs/bonaire-mcp-server.git

MCP Itinerary Server (Go) — Detailed Documentation

📌 Overview

This project implements a minimal Model Context Protocol (MCP) server in Go for an itinerary system.

The goal is to:

• Expose backend functionality as AI-callable tools
• Follow proper JSON-RPC over stdio
• Maintain clean architecture (no circular dependencies)

🧠 High-Level Architecture

          ┌───────────────┐
          │   AI Client   │ (Inspector / LLM)
          └──────┬────────┘
                 │ JSON-RPC (stdio)
                 ▼
        ┌────────────────────┐
        │     MCP Layer      │ (protocol handling)
        └────────┬───────────┘
                 ▼
        ┌────────────────────┐
        │    Tools Layer     │ (MCP adapters)
        └────────┬───────────┘
                 ▼
        ┌────────────────────┐
        │   Service Layer    │ (business logic)
        └────────────────────┘

📂 Project Structure

mcp-itinerary/
├── main.go
├── mcp/
│   ├── server.go
│   └── types.go
├── tools/
│   ├── router.go
│   └── itinerary.go
├── service/
│   └── itinerary_service.go

🔍 File-by-File Breakdown

1. main.go — Entry Point

🎯 Purpose

• Bootstraps the MCP server
• Injects the request handler (dependency injection)

🧩 Code Responsibility

server := mcp.Server{
    Handler: tools.HandleMCPRequest,
}

💡 Key Concept

• Dependency Injection
• mcp package does NOT know about tools
• Avoids circular dependency

2. mcp/types.go — Protocol Models

🎯 Purpose

Defines JSON-RPC structures.

🧩 Structures

Request

type Request struct {
    ID     interface{}
    Method string
    Params map[string]interface{}
}

Response

type Response struct {
    JSONRPC string
    ID      interface{}
    Result  interface{}
    Error   interface{}
}

💡 Key Concept

• Mirrors JSON-RPC 2.0 spec
• Keeps protocol logic isolated

3. mcp/server.go — Core MCP Engine

🎯 Purpose

• Handles stdio communication
• Runs infinite loop
• Converts raw input → structured request → response

🔁 Flow

stdin → read → parse JSON → call handler → write stdout

🧩 Key Function

func (s *Server) Start()

🔍 Internals

Step 1: Read input

line, err := reader.ReadBytes('\n')

Step 2: Parse JSON

json.Unmarshal(line, &req)

Step 3: Call handler

resp := s.Handler(req)

Step 4: Return response

fmt.Println(string(bytes))

⚠️ Important Rules

• NEVER log to stdout ❌
• Use stderr for debugging ✅
• Must run continuously (no exit)

4. tools/router.go — MCP Method Router

🎯 Purpose

Routes incoming MCP methods:

• initialize
• tools/list
• tools/call

🔁 Flow

Request.Method → switch → appropriate handler

🧩 Handled Methods

✅ initialize

case "initialize":

Purpose:

• First handshake with client

Returns:

{
  "protocolVersion": "2024-11-05",
  "capabilities": {
    "tools": {}
  },
  "serverInfo": {
    "name": "itinerary-mcp",
    "version": "1.0.0"
  }
}

✅ tools/list

case "tools/list":

Purpose:

• Tell AI what tools are available

Calls:

ListTools()

✅ tools/call

case "tools/call":

Purpose:

• Execute a tool

Calls:

HandleToolCall(req)

5. tools/itinerary.go — Tool Definitions

🎯 Purpose

• Define tools (metadata)
• Execute tool logic

🧩 Function 1: ListTools()

Returns:

[
  {
    "name": "create_itinerary",
    "description": "...",
    "input_schema": { ... }
  }
]

🧩 Function 2: HandleToolCall()

name := req.Params["name"]
args := req.Params["arguments"]

🔁 Flo

... View full README on GitHub