MCP-Tasks Architektur

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

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

Verzeichnisstruktur

/var/www/mcp-servers/mcp_tasks/
├── server.py               # Hauptdatei, MCP-Server
├── config.py               # Zentrale Konfiguration
├── requirements.txt        # Python Dependencies
├── venv/                   # Virtual Environment
│
├── domain/                 # Domain Layer
│   ├── __init__.py
│   └── contracts.py        # Dataclasses: Task, TaskAssignment, TaskResult
│
├── infrastructure/         # Infrastructure Layer
│   ├── __init__.py
│   └── task_repository.py  # CRUD-Operationen
│
├── tools/                  # MCP Tools
│   ├── __init__.py
│   ├── task_tools.py       # Task-Management Tools
│   └── quality_tools.py    # Quality/Contract Tools
│
└── validators/             # Input-Validierung
    ├── __init__.py
    └── workflow_validator.py  # Workflow-Validierung

Layer-Architektur

Domain Layer

Enthält die Datenstrukturen in domain/contracts.py:

Klasse	Beschreibung
`Task`	Task-Entity mit allen Feldern
`TaskAssignment`	Zuweisung an Person/KI
`TaskResult`	Ergebnis mit Token-Tracking
`TaskStatus`	Enum: pending, in_progress, completed, failed, cancelled
`TaskType`	Enum: human_task, ai_task, mixed
`ExecutorType`	Enum: human, ollama, claude, anthropic_api

Infrastructure Layer

Datenbankzugriff in infrastructure/task_repository.py:

Klasse	Beschreibung
`TaskRepository`	CRUD für tasks, assignments, results

Hinweis: Die Datenbankverbindung wird inline via shared config erstellt. Logging erfolgt direkt in mcp_log ohne separate Logger-Klasse.

Validators Layer

Input-Validierung in validators/workflow_validator.py:

Workflow-Status-Übergänge validieren
Task-Typ-Validierung

Tools Layer

MCP-Tool-Definitionen:

Modul	Tools
`task_tools.py`	tasks_list, tasks_get, tasks_create, tasks_update, tasks_status, tasks_assign, tasks_result, tasks_execute, tasks_delete, tasks_statistics
`quality_tools.py`	contracts_list, contracts_validate, quality_check, quality_report

Datenfluss

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

Konfiguration (config.py)

class Config:
    # Datenbank für Task-Operationen (ki_dev)
    DB_HOST = os.getenv("DB_HOST", "localhost")
    DB_PORT = int(os.getenv("DB_PORT", "3306"))
    DB_NAME = os.getenv("DB_NAME", "ki_dev")
    DB_USER = os.getenv("DB_USER", "claude_code")
    DB_PASSWORD = os.getenv("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"]

Datenbank (ki_dev)

Task-Tabellen befinden sich in der Datenbank ki_dev:

tasks - Haupttabelle mit uuid, title, description, type, status
task_assignments - Zuweisungen an Personen/KI
task_results - Ergebnisse mit Token-Tracking

Logging erfolgt in ki_dev.mcp_log.

Design-Prinzipien

Single Responsibility (SRP)

Repository: Nur Datenbankzugriff
Tools: Nur MCP-Interface
Validators: Nur Input-Validierung

Fail-Safe Logging

try:
    # Log direkt in mcp_log einfügen
    cursor.execute("INSERT INTO mcp_log ...")
except Exception as e:
    # Nur zu stderr, NICHT an Client
    print(f"Log failed: {e}", file=sys.stderr)
    # Tool-Operation fortsetzen!

Dependencies

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