# NATS MCP Server

An MCP (Model Context Protocol) server that provides access to [NATS](https://nats.io/), a cloud native messaging system, through the NATS CLI.

## Features

- Publish messages with advanced options (headers, templates, reply subjects)
- Subscribe to subjects with configurable timeouts and message counts
- Request-reply pattern support with headers
- Full NATS CLI integration
- Error handling and cleanup

## Requirements

- Node.js >= 14.0.0
- NATS CLI (nats)

### Installing NATS CLI

#### macOS

Using Homebrew:
```bash
brew tap nats-io/nats-tools
brew install nats-io/nats-tools/nats
```

#### Linux

Using snap:
```bash
snap install nats
```

Using apt (Debian/Ubuntu):
```bash
# First, add the NATS repository
echo "deb https://dl.nats.io/nats-io/repo/deb nats release" | sudo tee /etc/apt/sources.list.d/nats.list
curl -fsSL https://dl.nats.io/nats-io/repo/deb/gpg.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/nats.gpg

# Then install
sudo apt-get update
sudo apt-get install nats-server
```

Using yum (RHEL/CentOS):
```bash
# Add the NATS repository
echo "[nats]
name=NATS Repository
baseurl=https://dl.nats.io/nats-io/repo/rpm/centos/\$releasever/\$basearch
gpgcheck=1
gpgkey=https://dl.nats.io/nats-io/repo/rpm/gpg.key
enabled=1" | sudo tee /etc/yum.repos.d/nats.repo

# Install
sudo yum install nats-server
```

#### Windows

Using Chocolatey:
```powershell
choco install nats-io-client
```

Using Scoop:
```powershell
scoop bucket add nats https://github.com/nats-io/scoop-bucket.git
scoop install nats
```

Manual installation:
1. Download the latest release from [NATS CLI Releases](https://github.com/nats-io/natscli/releases)
2. Extract the archive
3. Add the binary to your system PATH

#### Building from Source

If packages are not available for your system:
```bash
# Requires Go 1.16+
go install github.com/nats-io/natscli/nats@latest
```

### Verifying Installation

After installation, verify the CLI works:
```bash
# Check version
nats --version

# Test connection to default server
nats ping

# List available commands
nats help
```

## Installation

```bash
# Install from npm
npm install @modelcontextprotocol/nats-mcp-server

# Or clone and build from source
git clone https://github.com/bmorphism/nats-mcp-server.git
cd nats-mcp-server
npm install
npm run build
```

## Configuration

The server can be configured using environment variables:

- `NATS_URL`: NATS server URL (default: 'nats://localhost:4222')

## Usage

The server provides the following MCP tools:

### publish

Publish a message to a NATS subject with advanced options.

Parameters:
- `subject` (required): NATS subject to publish to
- `message` (required): Message to publish
- `reply` (optional): Reply subject for request-reply patterns
- `headers` (optional): Array of message headers (key-value pairs)
- `count` (optional): Number of messages to publish
- `sleep` (optional): Sleep duration between messages (e.g., "100ms")
- `template` (optional): Enable Go template processing in message

Example with templates:
```typescript
const result = await mcp.useTool("nats", "publish", {
  subject: "greetings",
  message: "Message {{Count}} @ {{Time}}",
  count: 5,
  sleep: "1s",
  template: true
});
```

Example with headers:
```typescript
const result = await mcp.useTool("nats", "publish", {
  subject: "orders",
  message: "New order received",
  headers: [
    { key: "OrderId", value: "12345" },
    { key: "Priority", value: "high" }
  ]
});
```

### subscribe

Subscribe to a NATS subject and receive messages.

Parameters:
- `subject` (required): NATS subject to subscribe to
- `timeout` (optional): Subscription timeout in milliseconds (default: 5000)
- `count` (optional): Number of messages to receive before exiting
- `raw` (optional): Show only message payload

Example:
```typescript
const result = await mcp.useTool("nats", "subscribe", {
  subject: "greetings",
  timeout: 10000,
  count: 5,
  raw: true
});
```

### request

Send a request message and wait for a reply.

Parameters:
- `subject` (required): NATS subject to send request to
- `message` (required): Request message
- `timeout` (optional): Request timeout in milliseconds (default: 5000)
- `headers` (optional): Array of request headers (key-value pairs)

Example:
```typescript
const result = await mcp.useTool("nats", "request", {
  subject: "service.time",
  message: "What time is it?",
  timeout: 3000,
  headers: [
    { key: "Locale", value: "en-US" }
  ]
});
```

## Template Functions

When using templates (template: true), the following functions are available:

- `Count`: Message number
- `TimeStamp`: RFC3339 format current time
- `Unix`: Seconds since 1970 in UTC
- `UnixNano`: Nano seconds since 1970 in UTC
- `Time`: Current time
- `ID`: Unique ID
- `Random(min, max)`: Random string between min and max length

Example with random strings:
```typescript
const result = await mcp.useTool("nats", "publish", {
  subject: "test",
  message: "Random data: {{ Random 10 100 }}",
  template: true
});
```

## Adding to MCP Configuration

### For Cline (VSCode Extension)

Add to `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`:

```json
{
  "mcpServers": {
    "nats": {
      "command": "node",
      "args": ["/path/to/nats-mcp-server/build/index.js"],
      "env": {
        "NATS_URL": "nats://localhost:4222"
      }
    }
  }
}
```

### For Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "nats": {
      "command": "node",
      "args": ["/path/to/nats-mcp-server/build/index.js"],
      "env": {
        "NATS_URL": "nats://localhost:4222"
      }
    }
  }
}
```

## Error Handling

The server includes robust error handling for:
- Connection failures
- Invalid parameters
- Timeouts
- Network errors
- NATS-specific errors
- CLI execution errors

## Development

To build the project:

```bash
npm run build
```

The build output will be in the `build` directory.

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT

## Acknowledgments

- [NATS.io](https://nats.io/) - For the amazing messaging system
- [NATS CLI](https://github.com/nats-io/natscli) - For the CLI tool
- [Model Context Protocol](https://github.com/modelcontextprotocol) - For the MCP framework