mcp-asia-time v1.1.0

MCP Asia Time

A Modern Control Protocol (MCP) server implementation focused on providing time-related tools for Asian timezones, with a particular emphasis on Bali/Makassar time. This package provides both a CLI interface and an HTTP server that can be integrated with various MCP clients.

Features

• Get current time in Asia/Makassar timezone
• Flexible date/time formatting options
• Full MCP protocol support
• Command-line interface for direct usage
• Extensible tool registration system

Installation

Global Installation (recommended for CLI usage)

npm install -g mcp-asia-time

Local Installation (for programmatic usage)

npm install mcp-asia-time

Usage

CLI Commands

1. Get current time:

# Basic usage
mcp-asia-time gettime

# Custom format
mcp-asia-time gettime -f "DD MMM YYYY HH:mm:ss"

# Different timezone
mcp-asia-time gettime -z "Asia/Jakarta"

2. List available tools:

mcp-asia-time list

3. Start HTTP server:

mcp-asia-time serve

# Custom port
mcp-asia-time serve -p 8080

MCP Protocol Integration

The server implements the Model Context Protocol (MCP), providing standardized endpoints for tool discovery and execution:

1. Health Check (GET /health)

Verify server status:

curl http://localhost:3000/health

Response:

{
    "status": "ok"
}

2. Tool Discovery (GET /tools)

Get metadata for all available tools:

curl http://localhost:3000/tools

Response:

[
    {
        "name": "gettime",
        "description": "Returns the current date and time in the specified timezone (default: Asia/Makassar)",
        "parameters": {
            "format": {
                "type": "string",
                "description": "Format string according to moment.js",
                "default": "YYYY-MM-DD HH:mm:ss"
            },
            "timezone": {
                "type": "string",
                "description": "Timezone string (e.g. Asia/Makassar, Europe/London)",
                "default": "Asia/Makassar"
            }
        }
    }
]

3. Tool Execution (POST /tool/:name)

Execute a specific tool with parameters:

curl -X POST http://localhost:3000/tool/gettime \
  -H "Content-Type: application/json" \
  -d '{
    "format": "DD MMM YYYY HH:mm:ss",
    "timezone": "Asia/Jakarta"
  }'

Response:

{
    "success": true,
    "result": "21 Feb 2024 15:30:45 (Asia/Jakarta)"
}

Error Response:

{
    "success": false,
    "error": "Invalid timezone or format: Unknown timezone"
}

Integration with MCP Clients

To integrate with MCP clients (like Claude for Desktop):

1. Start the HTTP server:

mcp-asia-time serve

2. Configure your MCP client with:
   • Base URL: http://localhost:3000
   • The client will automatically discover available tools through the /tools endpoint
   • Tools can be executed via POST requests to /tool/:name

Development

Project Structure

/
├── src/
│   ├── index.js        # Main entry point
│   ├── mcpServer.js    # MCP server implementation
│   └── tools/
│       └── getTime.js  # Time tool implementation
├── test/               # Test files
├── cli.js             # CLI implementation
└── server.js          # HTTP server entry point

Adding New Tools

To add a new tool that's compatible with the MCP protocol:

1. Create a new tool file in src/tools/:

export function myTool(params = {}) {
    const {
        param1 = 'default1',
        param2 = 'default2'
    } = params;
    
    // Tool implementation
    return result;
}

export default {
    name: 'mytool',
    description: 'Description of what the tool does',
    parameters: {
        param1: {
            type: 'string',
            description: 'Description of param1',
            default: 'default1'
        },
        param2: {
            type: 'string',
            description: 'Description of param2',
            default: 'default2'
        }
    },
    execute: myTool
};

2. Register the tool in src/index.js:

import myTool from './tools/myTool.js';
server.registerTool(myTool);

Configuration

The following environment variables are supported:

• PORT - HTTP server port (default: 3000)

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request