# Coin Flip MCP Server

An MCP server that provides true random coin flips using random.org's randomness API. This server demonstrates the Model Context Protocol by providing a tool for generating random outcomes with configurable sides.

## Features

### Tools
- `flip_coin` - Flip a coin with configurable number of sides
  - Optional `sides` parameter (default: 2)
  - Uses true randomness from random.org
  - Special handling for edge cases (0, 1, or negative sides)
  - For 2 sides: Returns "Heads" or "Tails"
  - For 3 sides: Returns "Heads", "Tails", or "_"
  - For n>3 sides: Returns "It landed on side X"

## Development

Install dependencies:
```bash
npm install
```

Build the server:
```bash
npm run build
```

For development with auto-rebuild:
```bash
npm run watch
```

## Installation

To use with Claude Desktop, add the server config:

On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`  
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "coin-flip": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-coin-flip"]
    }
  }
}
```

## Example Usage

Once connected to an MCP client like Claude Desktop, you can use natural language to interact with the coin flip tool. For example:

- "Flip a coin"
- "Roll a 6-sided die"
- "Give me a random number between 1 and 20"

The server will use true randomness from random.org to generate the result.

## Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector node build/index.js
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT