# websocat-mcp

An MCP (Model Context Protocol) server for WebSocket operations, providing tools to connect, send, receive, and manage WebSocket connections.

## Installation

### From GitHub

```bash
git clone https://github.com/shivam-jainn/websocat-mcp.git
cd websocat-mcp
bun install
bun run build
```

### From npm (when published)

```bash
npm install -g websocat-mcp
```

Or locally:

```bash
npm install websocat-mcp
```

## Build

```bash
bun run build
```

## Usage

This MCP server provides the following tools:

### `websocket_connect`
Connect to a WebSocket server.

**Parameters:**
- `url` (required): WebSocket URL (e.g., `ws://localhost:8080` or `wss://example.com`)
- `connectionId` (optional): Unique identifier for this connection (auto-generated if not provided)

**Example:**
```json
{
  "url": "ws://localhost:8080",
  "connectionId": "my-connection"
}
```

### `websocket_send`
Send a message through a WebSocket connection.

**Parameters:**
- `connectionId` (required): Connection ID to send the message through
- `message` (required): Message to send

**Example:**
```json
{
  "connectionId": "my-connection",
  "message": "Hello, WebSocket!"
}
```

### `websocket_receive`
Receive messages from a WebSocket connection (waits for messages).

**Parameters:**
- `connectionId` (required): Connection ID to receive messages from
- `timeout` (optional): Timeout in milliseconds (default: 5000)
- `maxMessages` (optional): Maximum number of messages to receive (default: 1)

**Example:**
```json
{
  "connectionId": "my-connection",
  "timeout": 10000,
  "maxMessages": 5
}
```

### `websocket_close`
Close a WebSocket connection.

**Parameters:**
- `connectionId` (required): Connection ID to close
- `code` (optional): Close code (default: 1000)
- `reason` (optional): Close reason

**Example:**
```json
{
  "connectionId": "my-connection",
  "code": 1000,
  "reason": "Done"
}
```

### `websocket_list`
List all active WebSocket connections.

**Parameters:** None

### `websocket_create_server`
Create a WebSocket server.

**Parameters:**
- `port` (optional): Port to listen on (default: 8080)
- `hostname` (optional): Hostname to bind to (default: localhost)

**Example:**
```json
{
  "port": 8080,
  "hostname": "localhost"
}
```

## MCP Configuration

To use this MCP server with Cursor or other MCP clients, add it to your MCP configuration:

### Local Installation

```json
{
  "mcpServers": {
    "websocat-mcp": {
      "command": "bun",
      "args": ["/path/to/websocat-mcp/build/index.js"]
    }
  }
}
```

### Global Installation (npm)

```json
{
  "mcpServers": {
    "websocat-mcp": {
      "command": "websocat-mcp"
    }
  }
}
```

### Using bunx (no installation needed)

```json
{
  "mcpServers": {
    "websocat-mcp": {
      "command": "bunx",
      "args": ["--bun", "websocat-mcp"]
    }
  }
}
```

## Features

- ✅ Connect to WebSocket servers
- ✅ Send messages through WebSocket connections
- ✅ Receive messages with timeout support
- ✅ Close connections gracefully
- ✅ List all active connections
- ✅ Create WebSocket servers
- ✅ Connection state management
- ✅ Error handling

## Development

This project uses:
- [Bun](https://bun.com) - Fast JavaScript runtime
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk) - MCP server implementation
- TypeScript - Type safety

## License

MIT