# Beagle Security MCP Server

This is a Model Context Protocol (MCP) server that provides integration with the Beagle Security API. It allows you to manage projects, applications, and automated security testing through the Beagle Security platform.

## Features

- **Project Management**: Create, modify, list, and delete projects
- **Application Management**: Create, get, modify, list, and delete applications
- **Domain Verification**: Get verification signatures and verify domain ownership with multiple signature types
- **Security Testing**: Start, monitor, stop, and retrieve results from automated penetration tests
- **Team Support**: Work with team projects and tests

## Installation

### Option 1: Docker (Recommended)

1. Clone this repository
2. Set up your environment variables:
   ```bash
   cp .env.example .env
   # Edit .env with your API token
   ```
3. Build and run with Docker:
   ```bash
   npm run docker:build
   npm run docker:run
   ```

Or use Docker Compose:
```bash
docker-compose up -d
```

### Option 2: Local Installation

1. Clone this repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Build the project:
   ```bash
   npm run build
   ```

## Configuration

### Environment Variables

Set your Beagle Security API token as an environment variable:

```bash
export BEAGLE_SECURITY_API_TOKEN=your_api_token_here
```

You can obtain an API token from your Beagle Security account settings (Profile → Personal access token).

### MCP Configuration

#### Docker Configuration

Add the server to your MCP configuration file:

```json
{
  "mcpServers": {
    "beagle-security": {
      "command": "docker",
      "args": [
        "run", 
        "--rm", 
        "-i", 
        "--env", "BEAGLE_SECURITY_API_TOKEN=your_api_token_here",
        "--env", "NODE_ENV=production",
        "mcp/beagle-security-mcp-server"
      ]
    }
  }
}
```

#### Local Configuration

For local installations:

```json
{
  "mcpServers": {
    "beagle-security": {
      "command": "node",
      "args": ["path/to/beagle-security-mcp-server/build/index.js"],
      "env": {
        "BEAGLE_SECURITY_API_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

## Available Tools (18 Total)

### Project Management (4 tools)

- `beagle_create_project`: Create a new project
- `beagle_modify_project`: Modify an existing project
- `beagle_list_projects`: List all projects and applications
- `beagle_delete_project`: Delete a project

### Application Management (5 tools)

- `beagle_create_application`: Create a new application in a project
- `beagle_get_application`: Get application details by token
- `beagle_modify_application`: Modify an existing application
- `beagle_list_applications`: List all applications under a project
- `beagle_delete_application`: Delete an application

### Domain Verification (2 tools)

- `beagle_get_domain_signature`: Get domain verification signature
- `beagle_verify_domain`: Complete domain verification with FILE, DNS, or API signature types

### Security Testing (7 tools)

- `beagle_start_test`: Start an automated penetration test
- `beagle_get_test_status`: Get the status of a running test
- `beagle_stop_test`: Stop a running test
- `beagle_get_test_result`: Get detailed test results in JSON format
- `beagle_list_test_sessions`: List all test sessions for an application
- `beagle_list_running_tests`: List all running tests for user or team (supports team filtering)


## Testing

### Comprehensive Test Suite

Run all tests to validate functionality:

```bash
# Run complete test suite (recommended)
npm run test:all

# Test individual components
npm run test:tools          # Test all 18 MCP tools
npm run test:integration    # Integration & API tests
npm run test                # Unit tests

# Test with real API (requires token)
BEAGLE_SECURITY_API_TOKEN=your_token npm run test:all
```

### Test Features

- **Tool Validation**: Tests all 18 tools with proper parameters
- **API Integration**: Live API testing when credentials provided
- **Error Handling**: Validates error scenarios and edge cases
- **Cross-Platform**: Works on Linux, macOS, and Windows
- **Docker Testing**: Validates container functionality

For detailed testing information, see [TESTING.md](./TESTING.md).

## Development

### Docker Development

```bash
# Build Docker image
npm run docker:build

# Run with Docker
npm run docker:run

# Use Docker Compose
npm run docker:compose:up

# View logs
npm run docker:compose:logs

# Stop services
npm run docker:compose:down
```

### Local Development

```bash
# Running in Development Mode
npm run dev

# Building
npm run build

# Starting the Server
npm start
```

## API Reference

This server implements the Beagle Security API v2.0. For detailed API documentation, visit:
https://beaglesecurity.com/developer/apidoc

## API Compatibility

This server implements **Beagle Security API v2.0** with:
- ✅ **All endpoints verified** against official documentation
- ✅ **Correct parameter naming** (camelCase format)
- ✅ **Proper error handling** for all API response codes
- ✅ **Latest API features** including domain verification types

## Error Handling

The server includes comprehensive error handling for:
- Authentication errors (invalid API tokens)
- HTTP errors (network issues, server errors)  
- Validation errors (missing required parameters)
- API-specific errors (returned by Beagle Security)
- Cross-platform compatibility issues

## Security Considerations

- Keep your API token secure and never commit it to version control
- Use environment variables or secure configuration management
- Ensure proper scopes are set when generating API tokens
- Monitor API usage to detect unauthorized access

## Troubleshooting

### Common Issues

1. **Server won't start**: Run `npm run build` to check for build errors
2. **API calls failing**: Verify your `BEAGLE_SECURITY_API_TOKEN` is valid
3. **Docker issues**: Ensure Docker is installed and running
4. **macOS timeout errors**: Install with `brew install coreutils` or tests will auto-fallback

### Getting Help

- Run the test suite: `npm run test:all`
- Check the logs in development mode: `NODE_ENV=development npm start`
- Review [TESTING.md](./TESTING.md) for detailed troubleshooting

## API Reference

Complete API documentation: https://beaglesecurity.com/developer/apidoc

## License

MIT License