MCP-Tasks Architektur

Verzeichnisstruktur, Komponenten und Design-Prinzipien des MCP-Tasks Servers.

Verzeichnisstruktur

/opt/mcp-servers/mcp-tasks/
├── server.py               # Hauptdatei, MCP-Server
├── config.py               # Zentrale Konfiguration
├── .env                    # Credentials (chmod 600)
├── requirements.txt        # Python Dependencies
├── venv/                   # Virtual Environment
│
├── domain/                 # Domain Layer
│   ├── __init__.py
│   └── contracts.py        # Dataclasses: Task, LogEntry, etc.
│
├── infrastructure/         # Infrastructure Layer
│   ├── __init__.py
│   ├── db_connection.py    # Database Connection Pool
│   ├── protokoll_logger.py # Logging in mcp_log
│   └── task_repository.py  # CRUD-Operationen
│
├── tools/                  # MCP Tools
│   ├── __init__.py
│   ├── task_tools.py       # 10 Task-Management Tools
│   └── quality_tools.py    # 4 Quality/Contract Tools
│
└── validators/             # (Optional) Input-Validierung
    └── __init__.py

Layer-Architektur

Domain Layer

Enthält die Datenstrukturen und Business-Logik:

KlasseBeschreibung
TaskTask-Entity mit allen Feldern
TaskAssignmentZuweisung an Person/KI
TaskResultErgebnis mit Token-Tracking
LogEntryLog-Eintrag für mcp_log
TaskStatusEnum: pending, in_progress, completed, failed, cancelled
TaskTypeEnum: human_task, ai_task, mixed
ExecutorTypeEnum: human, ollama, claude, anthropic_api

Infrastructure Layer

Datenbankzugriff und externe Dienste:

KlasseBeschreibung
DatabaseConnectionContext Manager für DB-Verbindungen
ProtokollLoggerFail-Safe Logging in mcp_log
TaskRepositoryCRUD für tasks, assignments, results

Tools Layer

MCP-Tool-Definitionen:

ModulTools
task_tools.pytasks_list, tasks_get, tasks_create, tasks_update, tasks_status, tasks_assign, tasks_result, tasks_execute, tasks_delete, tasks_statistics
quality_tools.pycontracts_list, contracts_validate, quality_check, quality_report

Datenfluss

Claude Code
    │
    ▼
┌─────────────────────────────────────────┐
│  MCP-Tasks Server (stdio)               │
│  ┌────────────────────────────────────┐ │
│  │ Tools                               │ │
│  │  - tasks_list()                     │ │
│  │  - tasks_create()                   │ │
│  │  - quality_check()                  │ │
│  └──────────────┬─────────────────────┘ │
│                 │                        │
│  ┌──────────────▼─────────────────────┐ │
│  │ Infrastructure                      │ │
│  │  - TaskRepository                   │ │
│  │  - ProtokollLogger                  │ │
│  └──────────────┬─────────────────────┘ │
│                 │                        │
└─────────────────┼───────────────────────┘
                  │
    ┌─────────────┼─────────────┐
    │             │             │
    ▼             ▼             ▼
┌────────┐  ┌────────┐    ┌─────────┐
│ tasks  │  │mcp_log │    │ Ollama  │
│ (CRUD) │  │(INSERT)│    │ (API)   │
└────────┘  └────────┘    └─────────┘

Konfiguration (config.py)

class Config:
    # Datenbank für Task-Operationen
    DB_HOST = os.getenv("DB_HOST", "localhost")
    DB_PORT = int(os.getenv("DB_PORT", "3306"))
    DB_NAME = os.getenv("DB_NAME", "ki_protokoll")
    DB_USER = os.getenv("DB_USER", "claude_code")
    DB_PASSWORD = os.getenv("DB_PASSWORD", "")

    # Datenbank für Logging (separater User)
    LOG_DB_USER = os.getenv("LOG_DB_USER", "mcp_logger")
    LOG_DB_PASSWORD = os.getenv("LOG_DB_PASSWORD", "")

    # Ollama
    OLLAMA_HOST = os.getenv("OLLAMA_HOST", "http://localhost:11434")
    OLLAMA_DEFAULT_MODEL = os.getenv("OLLAMA_MODEL", "mistral")

    # Limits
    MAX_RESULTS = 100
    MAX_DESCRIPTION_LENGTH = 50000

    # Gültige Werte
    VALID_STATUSES = ["pending", "in_progress", "completed", "failed", "cancelled"]
    VALID_TYPES = ["human_task", "ai_task", "mixed"]
    VALID_EXECUTOR_TYPES = ["human", "ollama", "claude", "anthropic_api"]

Environment Variables (.env)

# Datenbank für Task-Operationen
DB_HOST=localhost
DB_PORT=3306
DB_NAME=ki_protokoll
DB_USER=claude_code
DB_PASSWORD=****

# Datenbank für Logging
LOG_DB_HOST=localhost
LOG_DB_NAME=ki_protokoll
LOG_DB_USER=mcp_logger
LOG_DB_PASSWORD=****

# Ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=mistral

Design-Prinzipien

Single Responsibility (SRP)

Fail-Safe Logging

try:
    logger.log(entry)
except Exception as e:
    # Nur zu stderr, NICHT an Client
    print(f"Log failed: {e}", file=sys.stderr)
    # Tool-Operation fortsetzen!

Separation of Concerns

Dependencies

# requirements.txt
mcp>=1.0.0
pymysql>=1.1.0
python-dotenv>=1.0.0
requests>=2.31.0
pyyaml>=6.0.0

Verwandte Themen