MCP-Tasks: Logging-Integration (wie mcp-db)

Beschreibung

# Ergänzung zu Task #29 + #30: Logging-Integration

Der MCP-Server mcp-tasks MUSS alle Operationen protokollieren - analog zu mcp-db.

---

## Referenz: mcp-db Logging-Architektur

### 1. LogEntry Contract (`domain/log_contract.py`)
```python
@dataclass
class LogEntry:
client_name: str = "mcp-db" # Server-Identifikation
request: str = "" # Tool-Aufruf (truncated)
status: str = "success" # success | denied | error
duration_ms: int = 0 # Ausführungsdauer
error_message: Optional[str] = None
timestamp: datetime = field(default_factory=datetime.now)
```

### 2. ProtokollLogger (`infrastructure/protokoll_logger.py`)
```python
class ProtokollLogger:
def log(self, entry: LogEntry) -> None:
# Schreibt in ki_protokoll.mcp_log
cursor.execute("""
INSERT INTO mcp_log
(timestamp, client_name, request, status, duration_ms, error_message)
VALUES (%s, %s, %s, %s, %s, %s)
""", (...))
```

### 3. Integration in Tools
```python
def register_tool(mcp):
logger = ProtokollLogger()

@mcp.tool()
def tool_name(...):
# 1. Validierung
valid, error = validate(...)
if not valid:
logger.log(LogEntry(
request=request[:200],
status="denied",
error_message=error
))
return error_response

# 2. Ausführung
start = time.time()
result = execute(...)
duration = int((time.time() - start) * 1000)

# 3. Logging
logger.log(LogEntry(
request=request[:200],
status=result.status,
duration_ms=duration,
error_message=result.error
))

return result
```

---

## Anforderungen für mcp-tasks

### Datenbank-Tabelle: mcp_log
Bereits vorhanden in `ki_protokoll`:
```sql
CREATE TABLE mcp_log (
id INT AUTO_INCREMENT PRIMARY KEY,
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
client_name VARCHAR(50) DEFAULT 'mcp-db',
request TEXT,
status ENUM('success', 'error', 'denied'),
duration_ms INT DEFAULT 0,
error_message TEXT
);
```

### LogEntry für mcp-tasks
```python
@dataclass
class LogEntry:
client_name: str = "mcp-tasks" # <- Unterschied zu mcp-db
tool_name: str = "" # <- NEU: Welches Tool
request: str = ""
status: str = "success"
duration_ms: int = 0
error_message: Optional[str] = None
task_id: Optional[int] = None # <- NEU: Betroffener Task
timestamp: datetime = field(default_factory=datetime.now)
```

### Logging-Pflichten

**Jeder Tool-Aufruf MUSS geloggt werden:**

| Tool | Was loggen |
|------|------------|
| tasks_list | Filter-Parameter, Anzahl Ergebnisse |
| tasks_get | Task-ID |
| tasks_create | Titel (truncated), erstellte Task-ID |
| tasks_update | Task-ID, geänderte Felder |
| tasks_status | Task-ID, alter → neuer Status |
| tasks_assign | Task-ID, Assignee |
| tasks_result | Task-ID, Status (success/error) |
| tasks_execute | Task-ID, Model, Tokens |
| tasks_delete | Task-ID |
| tasks_statistics | - |
| contracts_validate | Contract-Name, Outcome |
| quality_check | Pfad, Checks, Passed/Failed |

### Status-Werte

| Status | Bedeutung |
|--------|-----------|
| success | Operation erfolgreich |
| denied | Validierung fehlgeschlagen (z.B. Task nicht gefunden) |
| error | Technischer Fehler (DB, API, etc.) |

---

## DB-User für Logging

Separater User mit nur INSERT-Rechten (wie bei mcp-db):

```sql
CREATE USER 'mcp_logger'@'localhost' IDENTIFIED BY '<password>';
GRANT INSERT ON ki_protokoll.mcp_log TO 'mcp_logger'@'localhost';
FLUSH PRIVILEGES;
```

Konfiguration in `.env`:
```
LOG_DB_HOST=localhost
LOG_DB_NAME=ki_protokoll
LOG_DB_USER=mcp_logger
LOG_DB_PASSWORD=<password>
```

---

## Fail-Safe Logging

```python
try:
logger.log(entry)
except Exception as e:
# 1. Zu stderr loggen (für MCP wichtig!)
print(f"CRITICAL: Log failed: {e}", file=sys.stderr)
# 2. NICHT an Client weitergeben
# 3. Tool-Operation trotzdem fortsetzen
```

**Wichtig:** Logging-Fehler dürfen NIEMALS die Tool-Ausführung blockieren.

---

## Beispiel-Log-Einträge

```
| timestamp | client_name | tool_name | request | status | duration_ms | task_id |
|---------------------|-------------|----------------|----------------------------------|---------|-------------|---------|
| 2025-12-20 10:00:01 | mcp-tasks | tasks_list | {"status":"pending","type":"ai"} | success | 45 | NULL |
| 2025-12-20 10:00:02 | mcp-tasks | tasks_get | {"id":29} | success | 12 | 29 |
| 2025-12-20 10:00:03 | mcp-tasks | tasks_status | {"id":29,"status":"in_progress"} | success | 23 | 29 |
| 2025-12-20 10:00:10 | mcp-tasks | tasks_result | {"id":29,"executor":"claude"} | success | 156 | 29 |
| 2025-12-20 10:00:11 | mcp-tasks | tasks_get | {"id":999} | denied | 8 | 999 |
| 2025-12-20 10:00:12 | mcp-tasks | quality_check | {"path":"/src","checks":"all"} | error | 5023 | NULL |
```

---

## Deliverables (ergänzt zu #29 + #30)

10. LogEntry Dataclass
11. ProtokollLogger Klasse
12. Integration in alle Tools
13. Separater DB-User mcp_logger
14. Fail-Safe Error Handling

Aktionen

Ergebnisse

Logging-Integration in protokoll_logger.py mit LogEntry und Fail-Safe implementiert

Kommentare

← Zurück zur Task-Liste