# Lupul Augmentat

MCP (Model Context Protocol) server with SSE transport for remote AI agent communication.

## Features

- **SSE Transport**: HTTP-based Server-Sent Events for remote MCP connections
- **OAuth 2.0 Authentication**: RFC 8414 compliant for Claude Code compatibility
- **NATS Messaging**: Internal pub/sub for module communication
- **Agent Presence**: Track online agents and their capabilities
- **Service Discovery**: List local services via systemctl

## Installation

```bash
git clone git@git.runningwolf.com:sebastian/Lupul-Augmentat.git
cd Lupul-Augmentat
npm install
cp .env.example .env
# Edit .env with your configuration
```

## Configuration

Create a `.env` file:

```env
# MCP Server
MCP_HOST=127.0.0.1
MCP_PORT=19017
MCP_LOG_LEVEL=info

# NATS
NATS_URL=nats://localhost:4222

# Security
API_KEY=your-secure-api-key
AUTH_ENABLED=true
```

## Running

### Development
```bash
npm run dev:sse
```

### Production (systemd)
```bash
sudo systemctl start lupul-augmentat
sudo systemctl enable lupul-augmentat
```

## Connecting from Claude Code

Add to your MCP settings:

```json
{
  "mcpServers": {
    "lupul": {
      "type": "sse",
      "url": "https://your-server.com/sse"
    }
  }
}
```

Claude Code will automatically handle OAuth authentication.

## Available Tools

### Agent Management
- `register_agent` - Register yourself with name, role, and capabilities
- `list_agents` - See all online agents
- `list_services` - List services on this machine

### Messaging
- `send_message` - Send message to another agent
- `receive_messages` - Check your inbox

## API Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /sse` | SSE connection (protected) |
| `POST /message` | Send MCP messages (protected) |
| `GET /health` | Health check |
| `GET /.well-known/oauth-authorization-server` | OAuth metadata |
| `GET /.well-known/oauth-protected-resource` | Protected resource metadata |
| `POST /register` | Dynamic client registration |
| `GET /authorize` | OAuth authorization |
| `POST /token` | Token exchange |

## Nginx Configuration

For SSL termination with nginx:

```nginx
location /sse {
    proxy_pass http://127.0.0.1:19017/sse;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 86400s;
    chunked_transfer_encoding off;
}
```

## Architecture

```
Claude Code (Mac/Linux)
    │
    ▼ HTTPS/SSE
┌─────────────────┐
│  nginx (SSL)    │
└────────┬────────┘
         │ HTTP
┌────────▼────────┐
│   SSE Server    │
│  (sse-server.ts)│
└────────┬────────┘
         │ NATS
┌────────▼────────┐
│  Tool Modules   │
│  (messaging,    │
│   file ops...)  │
└─────────────────┘
```

## License

MIT