# basic-mcp

MCP server providing deterministic tools for operations that LLMs commonly struggle with: time, math, counting, randomness, and validation.

## Installation

```bash
bun install
```

## Usage

### With Claude Code

Add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "basic-tools": {
      "command": "bun",
      "args": ["run", "/path/to/basic-mcp/index.ts"]
    }
  }
}
```

### Standalone

```bash
bun run index.ts
```

## Tools

### Time
| Tool | Description |
|------|-------------|
| `now` | Get current date/time with timezone support |
| `date_diff` | Calculate difference between two dates |
| `date_add` | Add/subtract time from a date |
| `unix_timestamp` | Convert between Unix timestamps and dates |

### Math
| Tool | Description |
|------|-------------|
| `calculate` | Evaluate math expressions (supports "15% of 200", sqrt, trig, etc.) |
| `convert_units` | Convert between units (km to miles, celsius to fahrenheit, etc.) |
| `statistics` | Calculate mean, median, mode, std dev, min, max, sum |

### Strings
| Tool | Description |
|------|-------------|
| `count` | Count characters, words, lines, bytes, sentences, paragraphs |
| `hash` | Generate MD5, SHA1, SHA256, SHA512 hashes |
| `uuid` | Generate UUID v4 |
| `base64` | Encode/decode base64 |
| `regex_test` | Test strings against regex patterns |

### Random
| Tool | Description |
|------|-------------|
| `random_int` | Cryptographically secure random integer |
| `random_float` | Cryptographically secure random float |
| `random_choice` | Select random item(s) from a list |
| `shuffle` | Randomly shuffle an array (Fisher-Yates) |

### Validation
| Tool | Description |
|------|-------------|
| `validate` | Validate email, URL, IPv4, IPv6, UUID, JSON, credit card (Luhn) |
| `json_parse` | Parse JSON with optional path extraction |
| `url_parse` | Parse URL into components |
| `dns_lookup` | DNS lookup (A, AAAA, MX, TXT, NS, CNAME records) |

## License

MIT