README.md•6.68 kB
# 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.