# Skraak MCP Server

A production-ready Model Context Protocol (MCP) server implemented in Go that provides time-related tools for AI assistants.

## Overview

This MCP server implements the `get_current_time` tool, allowing AI assistants to query the current system time with timezone information. Built using the official MCP Go SDK, it follows best practices for extensibility and maintainability.

## Features

- **get_current_time**: Returns current system time in RFC3339 format with timezone and Unix timestamp
- Full MCP protocol compliance via stdio transport
- Type-safe tool handlers with automatic JSON schema generation
- Extensible architecture for adding new tools

## Requirements

- Go 1.25.6 or later
- MCP-compatible client (Claude Desktop, etc.)

## Installation

```bash
# Clone or navigate to the project directory
cd /home/david/go/src/skraak_mcp

# Download dependencies
go mod download

# Build the server
go build -o skraak_mcp
```

## Usage

### Running the Server

The server communicates over stdio (standard input/output) as per MCP specification and requires a DuckDB database path as an argument:

```bash
./skraak_mcp /path/to/database.duckdb
```

Example:
```bash
./skraak_mcp ./test.duckdb
```

### Configuring with Claude Desktop

Add to your Claude Desktop MCP configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "skraak_mcp": {
      "command": "/home/david/go/src/skraak_mcp/skraak_mcp",
      "args": ["/path/to/database.duckdb"]
    }
  }
}
```

## Available Tools

### get_current_time

Returns the current system time with comprehensive timezone information.

**Input**: None

**Output**:
```json
{
  "time": "2024-01-25T10:30:45Z",
  "timezone": "UTC",
  "unix": 1706181045
}
```

**Fields**:
- `time`: Current system time in RFC3339 format (ISO 8601 compatible)
- `timezone`: System timezone identifier
- `unix`: Unix timestamp in seconds since epoch

## Development

### Project Structure

```
skraak_mcp/
├── go.mod              # Go module definition
├── go.sum              # Dependency checksums
├── main.go             # Server entry point
├── tools/              # Tool implementations
│   └── time.go        # Time-related tools
└── README.md          # This file
```

### Adding New Tools

1. **Create tool file** in the `tools/` package (e.g., `tools/calculator.go`)

2. **Define input/output structures** with jsonschema tags:
```go
type CalculateInput struct {
    Expression string `json:"expression" jsonschema:"Mathematical expression to evaluate"`
}

type CalculateOutput struct {
    Result float64 `json:"result" jsonschema:"Calculated result"`
}
```

3. **Implement handler function**:
```go
func Calculate(ctx context.Context, req *mcp.CallToolRequest, input CalculateInput) (
    *mcp.CallToolResult,
    CalculateOutput,
    error,
) {
    // Implementation
    return &mcp.CallToolResult{}, output, nil
}
```

4. **Register in main.go**:
```go
err := mcp.AddTool(
    server,
    "calculate",
    "Evaluate mathematical expressions",
    tools.Calculate,
)
```

### Testing

Build and test the server:

```bash
# Build
go build -o skraak_mcp

# Run (will wait for MCP protocol messages on stdin)
./skraak_mcp ./test.duckdb

# In another terminal, you can test with an MCP client
# or manually send JSON-RPC messages
```

Unit tests can be added in .......

## Dependencies

- [MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk) v1.2.0+
- [DuckDB Go SDK](https://github.com/duckdb/duckdb-go) v2

## Protocol Compliance

This server implements:
- MCP Protocol version: Latest
- Transport: stdio (JSON-RPC 2.0)
- Capabilities: Tools
- Future support: Resources, Prompts

## License

MIT

## Contributing

Contributions welcome! Please ensure:
- Code follows Go best practices
- Tools include comprehensive descriptions
- JSON schema tags document all fields
- Error handling is robust

## Troubleshooting

**Server won't start**:
- Check Go version: `go version`
- Rebuild: `go build -o skraak_mcp`
- Check logs in stderr

**Tool not appearing in client**:
- Verify MCP configuration path
- Restart Claude Desktop
- Check server binary path is correct

**Time format issues**:
- Output uses RFC3339 (ISO 8601) format
- Timezone reflects system configuration
- Unix timestamp is in seconds (not milliseconds)