[Docs]: Add Developer Guide for using fast-time-server via JSON-RPC commands using curl or stdio

[crivetimihai]

Overview

This guide demonstrates how to interact with the fast-time-server MCP server using raw JSON-RPC commands via curl. The fast-time-server is an ultra-fast Go-based MCP server that provides time-related tools for LLM applications.

Available Tools

• get_system_time: Returns current time in any IANA timezone
• convert_time: Converts time between different timezones

Transport Modes

The fast-time-server supports multiple transport modes:

• stdio: For desktop clients like Claude Desktop (default)
• sse: Server-Sent Events for web-based MCP clients
• http: HTTP streaming for REST-like interactions
• dual: Both SSE and HTTP on the same port (SSE at /sse, HTTP at /http)

Quick Start

Running the Server

# Docker - DUAL mode (both SSE and HTTP)
docker run --rm -it -p 8888:8080 ghcr.io/ibm/fast-time-server:latest

# Docker - HTTP only
docker run --rm -it -p 8888:8080 ghcr.io/ibm/fast-time-server:latest -transport=http

# Docker - SSE only
docker run --rm -it -p 8888:8080 ghcr.io/ibm/fast-time-server:latest -transport=sse

# Docker - STDIO (for testing)
docker run --rm -it ghcr.io/ibm/fast-time-server:latest -transport=stdio

# Docker - With authentication
docker run --rm -it -p 8888:8080 ghcr.io/ibm/fast-time-server:latest -auth-token=secret123

# Binary download (if available)
./fast-time-server -transport=dual -port=8080
./fast-time-server -transport=http -port=8080
./fast-time-server -transport=sse -port=8080 -auth-token=secret123

Endpoint URLs

DUAL Transport (default Docker)

• SSE Events: http://localhost:8888/sse
• SSE Messages: http://localhost:8888/messages
• HTTP MCP: http://localhost:8888/http
• Health: http://localhost:8888/health
• Version: http://localhost:8888/version

HTTP Transport Only

• MCP: http://localhost:8888/
• Health: http://localhost:8888/health
• Version: http://localhost:8888/version

SSE Transport Only

• Events: http://localhost:8888/sse
• Messages: http://localhost:8888/messages
• Health: http://localhost:8888/health
• Version: http://localhost:8888/version

Authentication

When using authentication (via -auth-token flag or AUTH_TOKEN environment variable):

# Include Bearer token in requests
curl -H "Authorization: Bearer secret123" http://localhost:8888/sse

HTTP Transport Usage

Health Check

# Check server health
curl http://localhost:8888/health

# Expected response:
# {"status":"healthy","uptime_seconds":123}

Version Information

# Get server version
curl http://localhost:8888/version

# Expected response:
# {"name":"fast-time-server","version":"1.5.0","mcp_version":"1.0"}

MCP Protocol Flow

1. Initialize Connection

# Initialize the MCP connection
curl -X POST http://localhost:8888/http \
     -H "Content-Type: application/json" \
     -d '{
           "jsonrpc":"2.0",
           "method":"initialize",
           "params":{
             "protocolVersion":"2025-03-26",
             "capabilities":{},
             "clientInfo":{"name":"test-client","version":"1.0"}
           },
           "id":1
         }'

Expected Response:

{
  "jsonrpc":"2.0",
  "id":1,
  "result":{
    "protocolVersion":"2025-03-26",
    "capabilities":{
      "tools":{"listChanged":false}
    },
    "serverInfo":{
      "name":"fast-time-server",
      "version":"1.5.0"
    }
  }
}

2. Send Initialized Notification

# Send initialized notification
curl -X POST http://localhost:8888/http \
     -H "Content-Type: application/json" \
     -d '{
           "jsonrpc":"2.0",
           "method":"notifications/initialized",
           "params":{}
         }'

3. List Available Tools

# List all available tools
curl -X POST http://localhost:8888/http \
     -H "Content-Type: application/json" \
     -d '{
           "jsonrpc":"2.0",
           "method":"tools/list",
           "id":2
         }'

Expected Response:

{
  "jsonrpc":"2.0",
  "id":2,
  "result":{
    "tools":[
      {
        "name":"get_system_time",
        "description":"Get current system time in specified timezone",
        "inputSchema":{
          "type":"object",
          "properties":{
            "timezone":{
              "type":"string",
              "description":"IANA timezone name (e.g., 'America/New_York', 'Europe/London'). Defaults to UTC"
            }
          }
        }
      },
      {
        "name":"convert_time",
        "description":"Convert time between different timezones",
        "inputSchema":{
          "type":"object",
          "properties":{
            "time":{
              "type":"string",
              "description":"Time to convert in RFC3339 format or common formats like '2006-01-02 15:04:05'"
            },
            "source_timezone":{
              "type":"string",
              "description":"Source IANA timezone name"
            },
            "target_timezone":{
              "type":"string",
              "description":"Target IANA timezone name"
            }
          },
          "required":["time","source_timezone","target_timezone"]
        }
      }
    ]
  }
}

4. Call Tools

Get Current Time in UTC:

curl -X POST http://localhost:8888/http \
     -H "Content-Type: application/json" \
     -d '{
           "jsonrpc":"2.0",
           "method":"tools/call",
           "params":{
             "name":"get_system_time",
             "arguments":{}
           },
           "id":3
         }'

Get Current Time in Specific Timezone:

curl -X POST http://localhost:8888/http \
     -H "Content-Type: application/json" \
     -d '{
           "jsonrpc":"2.0",
           "method":"tools/call",
           "params":{
             "name":"get_system_time",
             "arguments":{"timezone":"America/New_York"}
           },
           "id":4
         }'

Expected Response:

{
  "jsonrpc":"2.0",
  "id":4,
  "result":{
    "content":[
      {
        "type":"text",
        "text":"2025-07-08T15:41:01-04:00"
      }
    ],
    "isError":false
  }
}

Convert Time Between Timezones:

curl -X POST http://localhost:8888/http \
     -H "Content-Type: application/json" \
     -d '{
           "jsonrpc":"2.0",
           "method":"tools/call",
           "params":{
             "name":"convert_time",
             "arguments":{
               "time":"2025-07-08T15:41:01-04:00",
               "source_timezone":"America/New_York",
               "target_timezone":"Europe/Dublin"
             }
           },
           "id":5
         }'

Expected Response:

{
  "jsonrpc":"2.0",
  "id":5,
  "result":{
    "content":[
      {
        "type":"text",
        "text":"2025-07-08T20:41:01+01:00"
      }
    ],
    "isError":false
  }
}

SSE Transport Usage

Establishing SSE Connection

# Terminal 1: Start SSE connection (keeps connection open)
curl -N http://localhost:8888/sse

This will establish a persistent connection and you'll see responses in real-time.

Sending Messages via SSE

In a separate terminal, send JSON-RPC messages:

# Initialize
curl -X POST http://localhost:8888/messages \
     -H "Content-Type: application/json" \
     -d '{
           "jsonrpc":"2.0",
           "id":1,
           "method":"initialize",
           "params":{
             "protocolVersion":"2025-03-26",
             "capabilities":{},
             "clientInfo":{"name":"sse-client","version":"1.0"}
           }
         }'

# List tools
curl -X POST http://localhost:8888/messages \
     -H "Content-Type: application/json" \
     -d '{
           "jsonrpc":"2.0",
           "id":2,
           "method":"tools/list"
         }'

# Get current time in Dublin
curl -X POST http://localhost:8888/messages \
     -H "Content-Type: application/json" \
     -d '{
           "jsonrpc":"2.0",
           "id":3,
           "method":"tools/call",
           "params":{
             "name":"get_system_time",
             "arguments":{"timezone":"Europe/Dublin"}
           }
         }'

Common Use Cases

Get Time in Multiple Timezones

# Create a script to get times in multiple zones
#!/bin/bash

SERVER="http://localhost:8888/http"

# Function to get time in timezone
get_time() {
    local tz=$1
    curl -s -X POST $SERVER \
         -H "Content-Type: application/json" \
         -d "{
               \"jsonrpc\":\"2.0\",
               \"method\":\"tools/call\",
               \"params\":{
                 \"name\":\"get_system_time\",
                 \"arguments\":{\"timezone\":\"$tz\"}
               },
               \"id\":$(date +%s)
             }" | jq -r '.result.content[0].text'
}

echo "Current times around the world:"
echo "UTC:         $(get_time 'UTC')"
echo "New York:    $(get_time 'America/New_York')"
echo "London:      $(get_time 'Europe/London')"
echo "Dublin:      $(get_time 'Europe/Dublin')"
echo "Tokyo:       $(get_time 'Asia/Tokyo')"
echo "Sydney:      $(get_time 'Australia/Sydney')"

Time Zone Conversion

# Convert a meeting time from Dublin to various timezones
MEETING_TIME="2025-07-08T14:00:00"
SOURCE_TZ="Europe/Dublin"

convert_time() {
    local target_tz=$1
    curl -s -X POST http://localhost:8888/http \
         -H "Content-Type: application/json" \
         -d "{
               \"jsonrpc\":\"2.0\",
               \"method\":\"tools/call\",
               \"params\":{
                 \"name\":\"convert_time\",
                 \"arguments\":{
                   \"time\":\"$MEETING_TIME\",
                   \"source_timezone\":\"$SOURCE_TZ\",
                   \"target_timezone\":\"$target_tz\"
                 }
               },
               \"id\":$(date +%s)
             }" | jq -r '.result.content[0].text'
}

echo "Meeting at $MEETING_TIME Dublin time:"
echo "New York:  $(convert_time 'America/New_York')"
echo "Los Angeles: $(convert_time 'America/Los_Angeles')"
echo "Tokyo:     $(convert_time 'Asia/Tokyo')"
echo "Sydney:    $(convert_time 'Australia/Sydney')"

Complete Example Session

#!/bin/bash

# fast-time-server complete session example
SERVER="http://localhost:8888/http"

# Function to make JSON-RPC calls
make_call() {
    curl -s -X POST $SERVER \
         -H "Content-Type: application/json" \
         -d "$1" | jq
}

echo "=== Fast Time Server Example Session ==="

# 1. Health check
echo "=== Health Check ==="
curl -s http://localhost:8888/health | jq

# 2. Version info
echo "=== Version Info ==="
curl -s http://localhost:8888/version | jq

# 3. Initialize connection
echo "=== Initializing ==="
make_call '{
  "jsonrpc":"2.0",
  "method":"initialize",
  "params":{
    "protocolVersion":"2025-03-26",
    "capabilities":{},
    "clientInfo":{"name":"example-client","version":"1.0"}
  },
  "id":1
}'

# 4. Send initialized notification
echo "=== Sending initialized notification ==="
make_call '{
  "jsonrpc":"2.0",
  "method":"notifications/initialized",
  "params":{}
}'

# 5. List tools
echo "=== Listing Tools ==="
make_call '{
  "jsonrpc":"2.0",
  "method":"tools/list",
  "id":2
}'

# 6. Get current time (UTC)
echo "=== Getting UTC Time ==="
make_call '{
  "jsonrpc":"2.0",
  "method":"tools/call",
  "params":{
    "name":"get_system_time",
    "arguments":{}
  },
  "id":3
}'

# 7. Get current time (Dublin)
echo "=== Getting Dublin Time ==="
make_call '{
  "jsonrpc":"2.0",
  "method":"tools/call",
  "params":{
    "name":"get_system_time",
    "arguments":{"timezone":"Europe/Dublin"}
  },
  "id":4
}'

# 8. Convert time
echo "=== Converting Time ==="
make_call '{
  "jsonrpc":"2.0",
  "method":"tools/call",
  "params":{
    "name":"convert_time",
    "arguments":{
      "time":"2025-07-08T14:00:00",
      "source_timezone":"Europe/Dublin",
      "target_timezone":"America/New_York"
    }
  },
  "id":5
}'

echo "=== Session Complete ==="

Integration with Claude Desktop

To use this with Claude Desktop, create a configuration that points to the STDIO mode:

{
  "mcpServers": {
    "fast-time": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/ibm/fast-time-server:latest",
        "-transport=stdio",
        "-log-level=error"
      ]
    }
  }
}

Or if you have the binary locally:

{
  "mcpServers": {
    "fast-time": {
      "command": "./fast-time-server",
      "args": ["-transport=stdio", "-log-level=error"]
    }
  }
}

Troubleshooting

Common Issues

1. Connection refused: Ensure the server is running and port is correct
2. Authentication errors: Include Bearer token when server is configured with auth
3. Invalid timezone: Use valid IANA timezone names (e.g., 'America/New_York', not 'EST')
4. Time format errors: Use RFC3339 format or common formats like '2006-01-02 15:04:05'

Error Examples

Invalid timezone:

{
  "jsonrpc":"2.0",
  "id":3,
  "result":{
    "content":[{
      "type":"text",
      "text":"invalid timezone \"Invalid/Zone\": unknown time zone Invalid/Zone"
    }],
    "isError":true
  }
}

Missing required parameter:

{
  "jsonrpc":"2.0",
  "id":4,
  "result":{
    "content":[{
      "type":"text",
      "text":"time parameter is required"
    }],
    "isError":true
  }
}

Valid Timezone Examples

• US: America/New_York, America/Chicago, America/Denver, America/Los_Angeles
• Europe: Europe/London, Europe/Dublin, Europe/Paris, Europe/Berlin
• Asia: Asia/Tokyo, Asia/Shanghai, Asia/Mumbai, Asia/Dubai
• Australia: Australia/Sydney, Australia/Melbourne, Australia/Perth
• UTC: UTC

Performance Notes

The fast-time-server is written in Go and optimized for performance:

• Timezone caching: Loaded timezones are cached for faster subsequent calls
• Concurrent requests: Can handle multiple simultaneous requests
• Low memory footprint: Minimal resource usage
• Fast startup: Quick initialization time

Further Reading

• MCP Specification
• JSON-RPC 2.0 Specification
• IANA Time Zone Database
• Go time package documentation

[cassiasamp]

Hi @crivetimihai, I'm thinking about working on this..do you have an example of how the developer guide should be? Would this be similar to issue #46?