# MCMod MCP Server — Setup & Usage Guide

## 1. Local Node Setup (Recommended For Development)

Docker is not required. Node.js 18 or newer is sufficient.

```powershell
git clone https://github.com/kankrittapon/MCP-BRPG.git
cd MCP-BRPG
npm install
Copy-Item .env.example .env
npm run audit:all
npm start
```

The local defaults bind to `127.0.0.1:3001` and load data from `./data`. Leave `MCP_API_KEY`
empty only for local development. Useful endpoints:

- Health: `http://127.0.0.1:3001/`
- SSE: `http://127.0.0.1:3001/sse`
- Tools: `http://127.0.0.1:3001/tools`

Run `npm run check` in CI when the Wizard source catalog is expected to be complete. It exits with
an error while records remain partial or missing.

## 2. Optional Server/Docker Setup

```bash
# 1. Copy the MCMod folder to your server or clone it
# 2. Navigate to the mcp-server directory
cd /path/to/MCMod/mcp-server

# 3. Install dependencies
npm install

# 4. Create your .env file (DO NOT share this file)
cp .env.example .env
nano .env   # or use any text editor
```

Inside `.env`, fill in:
```
SERVER_HOST=0.0.0.0
SERVER_PORT=3001
MCP_API_KEY=your_random_secret_key
MOD_DATA_ROOT=/path/to/MCMod
```

Generate a random API key:
```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

```bash
# 5. Start the server
npm start
```

The server will be available at: **http://192.168.1.248:3001**

---

## 3. Connect from Gemini CLI

Add to your Gemini CLI config (`~/.gemini/config.json` or `settings.json`):

```json
{
  "mcpServers": {
    "mcmod": {
      "transport": "sse",
      "url": "http://192.168.1.248:3001/sse",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}
```

---

## 4. Connect from Claude CLI

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "mcmod": {
      "transport": "sse",
      "url": "http://192.168.1.248:3001/sse",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}
```

---

## 5. Connect from Codex CLI (OpenAI)

Add to your Codex CLI config:

```json
{
  "mcp_servers": [
    {
      "name": "mcmod",
      "transport": "sse",
      "url": "http://192.168.1.248:3001/sse",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  ]
}
```

---

## 6. Available MCP Tools

| Tool | Description |
|---|---|
| `list_classes` | List all classes (Wizard, Ninja) |
| `list_skills` | List skills by class + tree (Main/Succession/Awakening) |
| `get_skill` | Get full skill data by ID or name |
| `search_skills` | Search by CC type, special damage, keyword |
| `get_skill_icon` | Get pixel icon as base64 PNG |
| `get_world_core` | Get combat ruleset (stats/offensive/special/defensive) |
| `get_data_audit` | Inspect Wizard/Ninja source completeness, missing fields, and conflicts |

Audit commands:

```bash
npm run audit:wizard
npm run audit:ninja
npm run audit:all
```

`get_data_audit` accepts `class` (`Wizard`, `Ninja`, or `all`), plus optional
`tree` and `status` filters. A skill remains `partial` until its rank fields and
source manifest are complete; skills without ranks are reported as `missing`.

---

## 7. Quick Test (curl)

```bash
# Health check
curl http://192.168.1.248:3001/

# Direct tool call (no SSE, just REST)
curl -X POST http://192.168.1.248:3001/call/get_skill \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{"id": "wizard_fireball"}'

# Search by CC effect
curl -X POST http://192.168.1.248:3001/call/search_skills \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{"cc_effect": "Floating", "class": "Ninja"}'

# Get World Core
curl -X POST http://192.168.1.248:3001/call/get_world_core \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{"section": "offensive"}'
```

---

## 8. Auto-start on Boot (Linux systemd)

```bash
# Create service file
sudo nano /etc/systemd/system/mcmod-mcp.service
```

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

[Service]
Type=simple
User=kanfullbuster
WorkingDirectory=/home/kanfullbuster/MCMod/mcp-server
ExecStart=/usr/bin/node server.js
Restart=on-failure
EnvironmentFile=/home/kanfullbuster/MCMod/mcp-server/.env

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

```bash
sudo systemctl enable mcmod-mcp
sudo systemctl start mcmod-mcp
sudo systemctl status mcmod-mcp
```