# MCP Server

A custom [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides Claude Code and other MCP clients with secure access to filesystem, system information, Obsidian vault, SQLite database, and UniFi network controller tools.

## Features

- **Filesystem Tools** - Read, write, list, and search files within allowed paths
- **System Tools** - Get system info, run whitelisted commands, view processes and disk usage
- **Obsidian Tools** - List notes, read content, search text, and find backlinks in your vault
- **Database Tools** - Query SQLite databases with read-only access
- **UniFi Tools** - Query and manage UniFi Dream Machine networks, including Threat Management (CyberSecure)

## Security

- HTTPS with TLS certificates (Let's Encrypt supported)
- Bearer token authentication for all MCP requests
- Path restrictions for filesystem operations
- Command whitelist for system operations
- Read-only database access with query filtering
- API key authentication for UniFi integration

## Requirements

- Node.js 18+ (for native fetch support)
- npm or yarn
- TLS certificates (self-signed for development, Let's Encrypt for production)
- Optional: UniFi Dream Machine with API key

## Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/your-username/mcp-server.git
   cd mcp-server
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Configure environment:
   ```bash
   cp .env.example .env
   # Edit .env with your settings
   ```

4. Generate TLS certificates (for development):
   ```bash
   mkdir -p certs
   openssl req -x509 -newkey rsa:4096 -keyout certs/server.key -out certs/server.crt -days 365 -nodes -subj "/CN=localhost"
   ```

5. Build and run:
   ```bash
   npm run build
   npm start
   ```

## Configuration

Copy `.env.example` to `.env` and configure:

| Variable | Required | Description |
|----------|----------|-------------|
| `MCP_TOKEN` | Yes | Authentication token for MCP clients |
| `MCP_PORT` | No | Server port (default: 8443) |
| `USE_HTTPS` | No | Use HTTPS (default: true) |
| `SSL_CERT_PATH` | No | Path to SSL certificate |
| `SSL_KEY_PATH` | No | Path to SSL private key |
| `ALLOWED_PATHS` | No | Comma-separated paths for filesystem access |
| `OBSIDIAN_VAULT_PATH` | No | Path to Obsidian vault |
| `DB_PATH` | No | Path to SQLite database |
| `UNIFI_HOST` | No | UniFi controller IP/hostname |
| `UNIFI_API_KEY` | No | UniFi API key |
| `UNIFI_SITE` | No | UniFi site name (default: "default") |

## Usage

### Development

```bash
npm run dev    # Run with tsx (hot reload)
```

### Production

```bash
npm run build  # Compile TypeScript
npm start      # Run compiled server
```

### Systemd Service

Create `/etc/systemd/system/mcp-server.service`:

```ini
[Unit]
Description=MCP Server
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/mcp-server
ExecStart=/usr/bin/npm start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Then:
```bash
sudo systemctl daemon-reload
sudo systemctl enable mcp-server
sudo systemctl start mcp-server
```

## Connecting Clients

### Claude Code (CLI)

```bash
claude mcp add --transport http my-mcp https://your-server.example.com:8443/mcp \
  --header "Authorization: Bearer YOUR_MCP_TOKEN"
```

Or add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "my-mcp": {
      "url": "https://your-server.example.com:8443/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "my-mcp": {
      "url": "https://your-server.example.com:8443/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

## Available Tools

See [docs/tools-reference.md](docs/tools-reference.md) for complete tool documentation.

### Tool Categories

| Category | Tools | Description |
|----------|-------|-------------|
| Filesystem | 4 | File read/write/list/search |
| System | 4 | System info and commands |
| Obsidian | 4 | Vault notes and search |
| Database | 3 | SQLite queries |
| UniFi | 19 | Network management and security |

**Total: 34 tools**

## Project Structure

```
mcp-server/
├── src/
│   ├── index.ts          # Entry point
│   ├── server.ts         # Express + MCP setup
│   ├── auth.ts           # Token authentication
│   └── tools/
│       ├── index.ts      # Tool registry
│       ├── filesystem.ts # File operations
│       ├── system.ts     # System commands
│       ├── obsidian.ts   # Obsidian vault
│       ├── database.ts   # SQLite queries
│       └── unifi.ts      # UniFi controller
├── docs/                 # Documentation
├── certs/                # TLS certificates (not in repo)
├── dist/                 # Compiled output (not in repo)
├── .env                  # Configuration (not in repo)
└── .env.example          # Example configuration
```

## API Endpoints

The server provides two ways to access tools:

### REST API (Simple)

Direct tool access without MCP protocol handshake. Best for scripts, automation, and testing.

| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| `/health` | GET | No | Health check |
| `/api/tools` | GET | Yes | List all available tools with schemas |
| `/api/tools/:name` | GET | Yes | Get info for a specific tool |
| `/api/tools/:name` | POST | Yes | Execute a tool (args in request body) |

**Example - Single request to call a tool:**
```bash
curl -X POST https://your-server.example.com:8443/api/tools/unifi_get_network_health \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Response format:**
```json
{
  "success": true,
  "tool": "unifi_get_network_health",
  "data": { ... }
}
```

### MCP Protocol (Full)

Standard MCP protocol with session management. Required for Claude Code and Claude Desktop.

| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| `/mcp` | GET | Yes | Server info |
| `/mcp` | POST | Yes | MCP protocol messages |
| `/mcp` | DELETE | Yes | Close session |

## License

ISC

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.