[DOCS]: Developer guide for fast-time-server via JSON-RPC

## 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

```bash
# 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):

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

## HTTP Transport Usage

### Health Check

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

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

### Version Information

```bash
# 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

```bash
# 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:**
```json
{
  "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

```bash
# 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

```bash
# 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:**
```json
{
  "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:**
```bash
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:**
```bash
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:**
```json
{
  "jsonrpc":"2.0",
  "id":4,
  "result":{
    "content":[
      {
        "type":"text",
        "text":"2025-07-08T15:41:01-04:00"
      }
    ],
    "isError":false
  }
}
```

**Convert Time Between Timezones:**
```bash
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:**
```json
{
  "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

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
#!/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:

```json
{
  "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:

```json
{
  "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:**
```json
{
  "jsonrpc":"2.0",
  "id":3,
  "result":{
    "content":[{
      "type":"text",
      "text":"invalid timezone \"Invalid/Zone\": unknown time zone Invalid/Zone"
    }],
    "isError":true
  }
}
```

**Missing required parameter:**
```json
{
  "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](https://modelcontextprotocol.io/)
- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
- [IANA Time Zone Database](https://www.iana.org/time-zones)
- [Go time package documentation](https://pkg.go.dev/time)

[DOCS]: Developer guide for fast-time-server via JSON-RPC #323

Description

Overview

Available Tools

Transport Modes

Quick Start

Running the Server

Endpoint URLs

DUAL Transport (default Docker)

HTTP Transport Only

SSE Transport Only

Authentication

HTTP Transport Usage

Health Check

Version Information

MCP Protocol Flow

1. Initialize Connection

2. Send Initialized Notification

3. List Available Tools

4. Call Tools

SSE Transport Usage

Establishing SSE Connection

Sending Messages via SSE

Common Use Cases

Get Time in Multiple Timezones

Time Zone Conversion

Complete Example Session

Integration with Claude Desktop

Troubleshooting

Common Issues

Error Examples

Valid Timezone Examples

Performance Notes

Further Reading

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions