# Sectional MCP Panel Documentation

## Overview

The Sectional MCP Panel is a comprehensive management service designed to orchestrate and monitor multiple server processes organized into logical sections. It provides a centralized control panel for starting, stopping, and monitoring servers, with support for containerization and resource management.

## Architecture

The Sectional MCP Panel is built with a modular architecture consisting of the following components:

1. **Database Layer**: Handles persistence of panel configuration, sections, servers, tasks, and audit logs
2. **Configuration System**: Manages hierarchical configuration with inheritance (global → section → server)
3. **Runtime Engine**: Manages container lifecycle using Docker
4. **Orchestration Engine**: Coordinates operations across servers and sections
5. **API Layer**: Provides RESTful endpoints for all operations
6. **Web UI**: Offers a user-friendly interface for management

## Installation

### Prerequisites

- Docker and Docker Compose
- Access to Docker socket for container management

### Using Docker Compose

1. Clone the repository:
   ```
   git clone https://github.com/your-org/mcp-panel.git
   cd mcp-panel
   ```

2. Configure the application:
   ```
   mkdir -p config data
   cp config/default_config.json config/
   ```

3. Start the application:
   ```
   docker-compose up -d
   ```

4. Access the UI:
   ```
   http://localhost:8000/ui
   ```

### Manual Installation

1. Clone the repository:
   ```
   git clone https://github.com/your-org/mcp-panel.git
   cd mcp-panel
   ```

2. Create a virtual environment:
   ```
   python -m venv venv
   source venv/bin/activate
   ```

3. Install dependencies:
   ```
   pip install -r requirements.txt
   ```

4. Configure the application:
   ```
   mkdir -p config data
   cp config/default_config.json config/
   ```

5. Start the application:
   ```
   ./start.sh
   ```

## Configuration

The Sectional MCP Panel uses a JSON-based configuration system with a hierarchical structure:

- **Global Defaults**: Applied to all servers
- **Section Settings**: Override global defaults for servers in a section
- **Server Settings**: Override section and global settings for a specific server

### Configuration Schema

```json
{
  "configSchemaVersion": "1.0.0",
  "panelName": "Sectional MCP Panel",
  "globalDefaults": {
    "settings": {
      "environmentVars": {},
      "resourceLimits": {},
      "runtimeOptions": {},
      "securityContext": {}
    }
  },
  "sections": [
    {
      "sectionName": "Example Section",
      "description": "Description",
      "settings": {},
      "servers": [
        {
          "serverName": "Example Server",
          "description": "Description",
          "runtimeDefinition": {
            "type": "docker_image",
            "command": "image:tag",
            "args": [],
            "ports": []
          },
          "settings": {}
        }
      ]
    }
  ]
}
```

## API Reference

The Sectional MCP Panel provides a RESTful API for all operations.

### Panel Endpoints

- `GET /api/v1/panel`: Get panel configuration
- `PUT /api/v1/panel`: Update panel configuration
- `GET /api/v1/panel/schema`: Get configuration schema
- `GET /api/v1/panel/health`: Health check

### Section Endpoints

- `GET /api/v1/sections`: Get all sections
- `GET /api/v1/sections/{section_id}`: Get section by ID
- `POST /api/v1/sections`: Create a new section
- `PUT /api/v1/sections/{section_id}`: Update a section
- `DELETE /api/v1/sections/{section_id}`: Delete a section
- `POST /api/v1/sections/{section_id}/{action}`: Perform action on section (start, stop, restart)

### Server Endpoints

- `GET /api/v1/servers`: Get all servers
- `GET /api/v1/servers/{server_id}`: Get server by ID
- `POST /api/v1/servers`: Create a new server
- `PUT /api/v1/servers/{server_id}`: Update a server
- `DELETE /api/v1/servers/{server_id}`: Delete a server
- `POST /api/v1/servers/{server_id}/{action}`: Perform action on server (start, stop, restart)

### Task Endpoints

- `GET /api/v1/tasks`: Get all tasks
- `GET /api/v1/tasks/{task_id}`: Get task by ID

## User Interface

The Sectional MCP Panel provides a web-based user interface for managing sections and servers. The UI is accessible at `http://localhost:8000/ui` and includes the following features:

- Dashboard with overview of all sections and servers
- Section management (add, edit, delete)
- Server management (add, edit, delete, start, stop, restart)
- Task monitoring
- Panel configuration

## Runtime Types

The Sectional MCP Panel supports the following runtime types:

- `docker_image`: Run a Docker container from an image
- `npx_command`: Run an NPX command in a Node.js container

## Security Considerations

- The Sectional MCP Panel requires access to the Docker socket, which has security implications
- In production environments, consider implementing authentication and authorization
- Restrict access to the API and UI using network controls
- Use secure environment variables for sensitive information

## Troubleshooting

### Common Issues

1. **Docker not available**: Ensure Docker is installed and the Docker socket is accessible
2. **Permission denied**: Ensure the user running the application has permission to access the Docker socket
3. **Database errors**: Check that the data directory is writable
4. **Configuration errors**: Validate your configuration against the schema

### Logs

Logs are written to stdout/stderr and can be viewed using:

```
docker-compose logs -f
```

## Development

### Project Structure

```
mcp_panel_project/
├── config/                 # Configuration files
├── data/                   # Database and state files
├── src/                    # Source code
│   ├── api/                # API endpoints
│   ├── config/             # Configuration system
│   ├── database/           # Database models and operations
│   ├── orchestration/      # Orchestration engine
│   ├── runtime/            # Runtime engine
│   └── ui/                 # Web UI
├── tests/                  # Test scripts
├── Dockerfile              # Docker build file
├── docker-compose.yml      # Docker Compose configuration
├── requirements.txt        # Python dependencies
└── start.sh                # Startup script
```

### Running Tests

```
cd mcp_panel_project
python -m tests.test_database
python -m tests.test_config
python -m tests.test_runtime
python -m tests.test_orchestration
python -m tests.test_api
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.