# Scoring Engine MCP Server

An MCP (Model Context Protocol) server for [Scoring Engine](https://github.com/scoringengine/scoringengine) - an open-source platform for running Red/White/Blue team cybersecurity competitions.

## Features

This MCP server provides programmatic access to all Scoring Engine API functionality:

### Scoreboard
- Get bar chart data (team scores)
- Get line chart data (score progression over rounds)

### Overview
- Get current round data
- Get overview status for all teams and services
- Get column headers
- Get detailed competition data

### Team Management
- Get team statistics (placement, score)
- Get team services with status and check history
- Get current service status

### Service Management
- Get check history for services
- Update service account credentials (blue team)
- Update service host/port (blue team)

### Statistics
- Get round statistics with up/down counts

### Flags (Red/White team)
- Get active flags
- Get flag solve status
- Get flag scoring totals

### Injects
- List team injects
- Get inject details
- Submit injects
- View/add comments
- List inject files

### Notifications
- List all notifications
- Get unread notifications

### Admin (White team only)
- Team/user management
- Engine control (pause/resume)
- Service configuration
- Inject template management
- Scoring and grading
- Settings management

## Installation

```bash
npm install
npm run build
```

## Configuration

Set the following environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `SCORING_ENGINE_URL` | Base URL of your Scoring Engine instance | `http://localhost` |
| `SCORING_ENGINE_SESSION` | Session cookie value for authentication | (empty) |

### Getting the Session Cookie

1. Log in to your Scoring Engine instance in a web browser
2. Open Developer Tools (F12)
3. Go to Application > Cookies
4. Copy the value of the `session` cookie

## Usage with Claude Desktop

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

```json
{
  "mcpServers": {
    "scoringengine": {
      "command": "node",
      "args": ["/path/to/scoringengine-mcp/dist/index.js"],
      "env": {
        "SCORING_ENGINE_URL": "https://your-scoring-engine.example.com",
        "SCORING_ENGINE_SESSION": "your-session-cookie-value"
      }
    }
  }
}
```

## Usage with Claude Code

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "scoringengine": {
      "command": "node",
      "args": ["/path/to/scoringengine-mcp/dist/index.js"],
      "env": {
        "SCORING_ENGINE_URL": "https://your-scoring-engine.example.com",
        "SCORING_ENGINE_SESSION": "your-session-cookie-value"
      }
    }
  }
}
```

## Available Tools

### Scoreboard Tools
- `scoreboard_get_bar_data` - Get team bar chart data
- `scoreboard_get_line_data` - Get team line chart data

### Overview Tools
- `overview_get_round_data` - Get current round info
- `overview_get_data` - Get team/service overview
- `overview_get_columns` - Get column headers
- `overview_get_detailed_data` - Get detailed data for display

### Team Tools
- `team_get_stats` - Get team placement and score
- `team_get_services` - Get team's services with details
- `team_get_services_status` - Get current service status

### Service Tools
- `service_get_checks` - Get check history
- `service_update_account` - Update account credentials
- `service_update_host` - Update service hostname
- `service_update_port` - Update service port

### Stats Tools
- `stats_get_rounds` - Get round statistics

### Flags Tools (Red/White team)
- `flags_get_active` - Get active flags
- `flags_get_solves` - Get solve status
- `flags_get_totals` - Get scoring totals

### Injects Tools
- `injects_list` - List team injects
- `inject_get` - Get inject details
- `inject_submit` - Submit an inject
- `inject_get_comments` - Get inject comments
- `inject_add_comment` - Add a comment
- `inject_get_files` - List inject files

### Notifications Tools
- `notifications_list` - List all notifications
- `notifications_unread` - Get unread notifications

### Admin Tools (White team only)
- `admin_get_teams` - List all teams
- `admin_add_user` - Create user
- `admin_add_team` - Create team
- `admin_update_password` - Change user password
- `admin_toggle_engine` - Pause/resume engine
- `admin_get_engine_status` - Check if paused
- `admin_get_engine_stats` - Get engine statistics
- `admin_get_worker_stats` - Get worker stats
- `admin_get_queue_stats` - Get queue stats
- `admin_get_round_progress` - Get round progress
- `admin_update_check` - Modify check results
- `admin_update_host` - Change service host
- `admin_update_port` - Change service port
- `admin_update_points` - Update point values
- `admin_update_worker_queue` - Assign worker queue
- `admin_update_target_round_time` - Set round duration
- `admin_update_worker_refresh_time` - Set refresh interval
- `admin_injects_get_templates` - List inject templates
- `admin_injects_get_template` - Get template details
- `admin_injects_create_template` - Create template
- `admin_injects_update_template` - Update template
- `admin_injects_delete_template` - Delete template
- `admin_inject_grade` - Grade an inject
- `admin_injects_get_scores` - Get inject scores
- `admin_injects_get_bar_chart` - Get inject chart data
- `admin_update_setting` - Update settings
- `admin_update_environment_info` - Update environment
- `admin_update_property` - Update properties

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Run directly with ts-node
npm run dev
```

## License

MIT