# 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
