MCP-Tasks Tools

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

Detaillierte Dokumentation aller 14 MCP-Tools.

Task-Management Tools

tasks_list

Listet Tasks mit optionalen Filtern auf. Token-optimiert durch Compact-Modus.

Compact-Modus (default)

Reduziert Token-Verbrauch um ~90%. Nur wesentliche Felder:

# Kompakte Ausgabe (default)
tasks_list(status="pending")

# Response (~100 Tokens statt ~1000)
{
  "success": true,
  "tasks": [
    {"id": 47, "title": "Token-Optimierung", "description": "tasks_list Response...", "type": "ai_task", "status": "pending"}
  ],
  "total": 5,
  "limit": 10,
  "offset": 0,
  "compact": true
}

Vollständige Ausgabe

# Alle Felder (für Details)
tasks_list(status="pending", compact=False)

# Response (alle 13 Felder pro Task)
{
  "success": true,
  "tasks": [
    {"id": 47, "uuid": "...", "title": "...", "description": "...",
     "type": "ai_task", "status": "pending", "created_by": "mcp-tasks",
     "created_by_type": "ai", "parent_task_id": null, "due_date": null,
     "created_at": "...", "updated_at": "...", "completed_at": null, "metadata": {}}
  ],
  "total": 5,
  "limit": 10,
  "offset": 0,
  "compact": false
}

tasks_get

Holt Details eines einzelnen Tasks inkl. Assignments und Results.

# Beispiel
tasks_get(id=29)

# Response
{
  "success": true,
  "task": {...},
  "assignments": [...],
  "results": [...]
}

tasks_create

Erstellt einen neuen Task.

# Beispiel
tasks_create(
    title="Code Review für API",
    description="Prüfe die neuen Endpunkte",
    type="ai_task"
)

# Response
{
  "success": true,
  "task": {"id": 45, "title": "...", ...},
  "message": "Task #45 created"
}

tasks_update

Aktualisiert Task-Felder.

tasks_status

Ändert den Status eines Tasks.

# Workflow-Beispiel
tasks_status(id=45, status="in_progress")
# ... Arbeit erledigen ...
tasks_status(id=45, status="completed")

tasks_assign

Weist einen Task einer Person oder KI zu.

# Beispiel
tasks_assign(
    id=45,
    assignee="mistral",
    assignee_type="ollama",
    model_name="mistral:latest"
)

tasks_result

Speichert ein Ergebnis für einen Task.

tasks_execute

Führt einen Task direkt mit lokalem Ollama aus.

# Beispiel
tasks_execute(id=45, model="codellama", auto_complete=True)

# Response
{
  "success": true,
  "result": {
    "response": "...",
    "tokens_input": 245,
    "tokens_output": 512,
    "duration_ms": 3400
  },
  "task_completed": true
}

tasks_delete

Löscht einen Task.

tasks_statistics

Holt Statistiken über alle Tasks.

# Beispiel
tasks_statistics()

# Response
{
  "success": true,
  "statistics": {
    "by_status": {"pending": 25, "completed": 120, ...},
    "by_type": {"ai_task": 100, "human_task": 45},
    "tokens": {"total_input": 50000, "total_output": 120000, "total_cost_usd": 2.50},
    "model_usage": [{"model": "mistral", "count": 80, "tokens": 100000}]
  }
}

Quality & Contract Tools

contracts_list

Listet alle verfügbaren Contracts auf.

# Beispiel
contracts_list()

# Response
{
  "success": true,
  "contracts": [
    {"name": "betriebsdokumentation-pruefung_v1.1", "status": "active"},
    {"name": "layered-architecture-pruefung_v1.0", "status": "active"}
  ]
}

contracts_validate

Führt eine Contract-Validierung aus.

# Beispiel
contracts_validate(contract="layered_architecture")

# Response
{
  "success": true,
  "validation": {
    "contract": "layered_architecture",
    "outcome": "passed",  // oder: revision_required, rejected
    "violations": {"critical": 0, "major": 0, "minor": 2},
    "findings": [...]
  }
}

quality_check

Führt PHP-Quality-Prüfungen aus.

# Beispiel
quality_check(path="/var/www/dev.campus.systemische-tools.de/src", checks="phpstan")

# Response
{
  "success": true,
  "passed": true,
  "results": {
    "phpstan": {"passed": true, "issues": 0}
  }
}

quality_report

Erstellt einen vollständigen Qualitätsbericht.

# Beispiel
quality_report(format="markdown")

# Response (Markdown)
# Quality Report
Generated: 2025-12-20 10:00:00

## Overall Status: PASSED

## Quality Checks
- ✓ phpstan: 0 issues
- ✓ cs-fixer: 0 issues
- ✓ semgrep: 0 issues

## Contract Validations
- betriebsdokumentation: passed
- layered_architecture: passed

Error Responses

Alle Tools geben bei Fehlern ein einheitliches Format zurück:

{
  "success": false,
  "error": "Task 999 not found"
}

Logging

Jeder Tool-Aufruf wird automatisch geloggt:

Verwandte Themen

• MCP-Tasks Übersicht
• Architektur
• Ollama - für tasks_execute

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:

Infrastructure Layer

Datenbankzugriff in infrastructure/task_repository.py:

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:

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

Verwandte Themen

• MCP-Tasks Übersicht
• Tools im Detail
• MCP-DB Architektur (Vergleich)

MCP-Tasks Installation

Aktualisiert: 2025-12-31

Setup, Registrierung und Test des MCP-Tasks Servers.

Voraussetzungen

• Python 3.10+
• MariaDB/MySQL
• Claude Code CLI
• Ollama (optional, für tasks_execute)

1. Verzeichnis erstellen

mkdir -p /var/www/mcp-servers/mcp_tasks
cd /var/www/mcp-servers/mcp_tasks

2. Virtual Environment

python3 -m venv venv
source venv/bin/activate
pip install mcp pymysql python-dotenv requests pyyaml

3. Dateien erstellen

Siehe Architektur für vollständige Verzeichnisstruktur.

# Struktur
/var/www/mcp-servers/mcp_tasks/
├── server.py               # Hauptdatei
├── config.py               # Konfiguration
├── requirements.txt
├── venv/
├── domain/
│   ├── __init__.py
│   └── contracts.py        # Dataclasses
├── infrastructure/
│   ├── __init__.py
│   └── task_repository.py  # CRUD-Operationen
├── tools/
│   ├── __init__.py
│   ├── task_tools.py
│   └── quality_tools.py
└── validators/
    ├── __init__.py
    └── workflow_validator.py

4. Datenbank vorbereiten (ki_dev)

Task-Tabellen erstellen

-- Haupttabelle
CREATE TABLE IF NOT EXISTS tasks (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    uuid VARCHAR(36) NOT NULL,
    title VARCHAR(255) NOT NULL,
    description TEXT DEFAULT NULL,
    type ENUM('human_task', 'ai_task', 'mixed') NOT NULL DEFAULT 'human_task',
    status ENUM('pending', 'in_progress', 'completed', 'failed', 'cancelled') NOT NULL DEFAULT 'pending',
    created_by VARCHAR(100) NOT NULL,
    created_by_type ENUM('human', 'ai') NOT NULL DEFAULT 'human',
    parent_task_id BIGINT UNSIGNED DEFAULT NULL,
    due_date DATETIME DEFAULT NULL,
    created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
    updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
    completed_at DATETIME(6) DEFAULT NULL,
    metadata LONGTEXT CHECK (JSON_VALID(metadata)),
    UNIQUE KEY uk_uuid (uuid),
    INDEX idx_status (status),
    INDEX idx_created_by (created_by),
    INDEX idx_type (type),
    INDEX idx_parent_task (parent_task_id),
    INDEX idx_created_at (created_at),
    INDEX idx_status_created (status, created_at),
    CONSTRAINT fk_parent_task FOREIGN KEY (parent_task_id) REFERENCES tasks(id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- Zuweisungen
CREATE TABLE IF NOT EXISTS task_assignments (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    task_id BIGINT UNSIGNED NOT NULL,
    assignee VARCHAR(100) NOT NULL,
    assignee_type ENUM('human', 'ollama', 'claude', 'anthropic_api') NOT NULL,
    model_name VARCHAR(100) DEFAULT NULL,
    assigned_by VARCHAR(100) NOT NULL,
    assigned_by_type ENUM('human', 'ai') NOT NULL DEFAULT 'human',
    status ENUM('pending', 'accepted', 'rejected', 'in_progress', 'completed') NOT NULL DEFAULT 'pending',
    assigned_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
    accepted_at DATETIME(6) DEFAULT NULL,
    completed_at DATETIME(6) DEFAULT NULL,
    notes TEXT DEFAULT NULL,
    INDEX idx_task_id (task_id),
    INDEX idx_assignee (assignee),
    INDEX idx_assignee_type (assignee_type),
    INDEX idx_status (status),
    INDEX idx_assigned_at (assigned_at),
    CONSTRAINT fk_assignment_task FOREIGN KEY (task_id) REFERENCES tasks(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- Ergebnisse
CREATE TABLE IF NOT EXISTS task_results (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    task_id BIGINT UNSIGNED NOT NULL,
    assignment_id BIGINT UNSIGNED DEFAULT NULL,
    executor VARCHAR(100) NOT NULL,
    executor_type ENUM('human', 'ollama', 'claude', 'anthropic_api') NOT NULL,
    model_name VARCHAR(100) DEFAULT NULL,
    request TEXT DEFAULT NULL,
    response LONGTEXT DEFAULT NULL,
    request_timestamp DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
    response_timestamp DATETIME(6) DEFAULT NULL,
    duration_ms INT UNSIGNED DEFAULT NULL,
    tokens_input INT UNSIGNED DEFAULT NULL,
    tokens_output INT UNSIGNED DEFAULT NULL,
    tokens_total INT UNSIGNED DEFAULT NULL,
    cost_usd DECIMAL(10,6) DEFAULT NULL,
    status ENUM('success', 'error', 'partial') NOT NULL DEFAULT 'success',
    error_message TEXT DEFAULT NULL,
    created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
    INDEX idx_task_id (task_id),
    INDEX idx_assignment_id (assignment_id),
    INDEX idx_executor (executor),
    INDEX idx_executor_type (executor_type),
    INDEX idx_model (model_name),
    INDEX idx_status (status),
    INDEX idx_created_at (created_at),
    CONSTRAINT fk_result_task FOREIGN KEY (task_id) REFERENCES tasks(id) ON DELETE CASCADE,
    CONSTRAINT fk_result_assignment FOREIGN KEY (assignment_id) REFERENCES task_assignments(id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

5. In Claude Code registrieren

User-Scope (Global)

Registrierung für alle Projekte:

claude mcp add mcp-tasks \
  /var/www/mcp-servers/mcp_tasks/venv/bin/python \
  /var/www/mcp-servers/mcp_tasks/server.py

Projekt-Scope (Lokal)

Registrierung nur für ein bestimmtes Projekt:

cd /var/www
claude mcp add mcp-tasks \
  /var/www/mcp-servers/mcp_tasks/venv/bin/python \
  /var/www/mcp-servers/mcp_tasks/server.py

6. Registrierung prüfen

# Liste aller MCP Server
claude mcp list

# Erwartete Ausgabe:
# mcp-tasks: connected

# In Claude Code Session
/mcp

7. Tools testen

# Task-Management
tasks_list()
tasks_statistics()

# Task erstellen und ausführen
tasks_create(title="Test-Task", type="ai_task")
tasks_execute(id=1, model="mistral")

# Quality-Checks
contracts_list()
quality_check(path="/var/www/dev.campus.systemische-tools.de/src")

Ollama-Integration

Für tasks_execute muss Ollama laufen:

# Ollama Status prüfen
ollama list

# Modell laden (falls nicht vorhanden)
ollama pull mistral

# Test
curl http://localhost:11434/api/tags

Troubleshooting

Server startet nicht

# Dependencies prüfen
pip list | grep -E "mcp|pymysql|dotenv"

# Python Version
python --version  # Muss 3.10+ sein

# Import-Fehler finden
python -c "from tools.task_tools import register_task_tools"

Verbindungsfehler

# DB-Verbindung testen (über MCP)
tasks_list(limit=1)

Ollama-Fehler

# Ollama Status
systemctl status ollama

# API erreichbar?
curl http://localhost:11434/api/tags

# Modell vorhanden?
ollama list | grep mistral

Updates

# Dependencies aktualisieren
cd /var/www/mcp-servers/mcp_tasks
source venv/bin/activate
pip install --upgrade mcp pymysql python-dotenv requests pyyaml

# Server wird beim nächsten Claude Code Start neu geladen

Deinstallation

# Aus Claude Code entfernen
claude mcp remove mcp-tasks

# Verzeichnis löschen (optional)
rm -rf /var/www/mcp-servers/mcp_tasks

# Tabellen behalten oder löschen (optional)
DROP TABLE task_results;
DROP TABLE task_assignments;
DROP TABLE tasks;

Verwandte Themen

• MCP-Tasks Übersicht
• Architektur
• Tools im Detail
• Ollama - Lokale KI-Modelle