MCP-DB Architektur

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

Aufbau und Struktur des MCP-DB Servers nach OOP, SRP, KISS, YAGNI Prinzipien.

Verzeichnisstruktur

/var/www/mcp-servers/mcp_db/
├── server.py              # MCP Server Entrypoint
├── config.py              # Zentrale Konfiguration
├── .env                   # Credentials (chmod 600)
├── .env.example           # Template
├── requirements.txt       # Dependencies
├── requirements-test.txt  # Test Dependencies
├── ruff.toml              # Linter Config
├── pytest.ini             # Test Config
├── run_tests.sh           # Test Runner
├── venv/                  # Virtual Environment
├── tests/                 # Unit Tests
│
├── domain/                # Contracts (Dataclasses)
│   ├── __init__.py
│   ├── query_contract.py  # QueryRequest, QueryResponse
│   └── execute_contract.py # ExecuteContract für DDL
│
├── validators/            # SRP: Separate Validierung
│   ├── __init__.py
│   ├── query_validator.py    # SELECT Validierung
│   └── execute_validator.py  # DDL Validierung (ALTER, CREATE, DROP, TRUNCATE)
│
├── infrastructure/        # Implementierungen
│   ├── __init__.py
│   └── db_connection.py   # MariaDB Connection Pool
│
└── tools/                 # MCP Tools (10 Dateien)
    ├── __init__.py
    ├── select_tool.py     # db_select
    ├── schema_tool.py     # db_schema
    ├── stats_tool.py      # db_stats
    ├── databases_tool.py  # db_databases
    ├── tables_tool.py     # db_tables
    ├── describe_tool.py   # db_describe
    ├── insert_tool.py     # db_insert
    ├── update_tool.py     # db_update
    ├── delete_tool.py     # db_delete
    └── execute_tool.py    # db_execute (DDL)

Komponenten-Diagramm

┌─────────────────────────────────────────────────────────────┐
│                     Claude Code                              │
│                         │                                    │
│                    MCP Protocol                              │
│                         │                                    │
│                         ▼                                    │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                   server.py                           │   │
│  │                 (Entrypoint)                          │   │
│  └──────────────────────┬───────────────────────────────┘   │
│                         │                                    │
│           ┌─────────────┼─────────────┐                      │
│           ▼             ▼             ▼                      │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐               │
│  │ 6 Read     │ │ 3 Write    │ │ 1 DDL      │               │
│  │ Tools      │ │ Tools      │ │ Tool       │               │
│  └─────┬──────┘ └─────┬──────┘ └─────┬──────┘               │
│        │              │              │                       │
│        └──────────────┼──────────────┘                       │
│                       ▼                                      │
│  ┌──────────────────────────────────────────────────────┐   │
│  │       QueryValidator / ExecuteValidator               │   │
│  │   (Blocklist, Allowlist, Limits, DDL-Prüfung)        │   │
│  └──────────────────────┬───────────────────────────────┘   │
│                         │                                    │
│                         ▼                                    │
│  ┌────────────────────────────────────────────────────┐     │
│  │  DatabaseConnection (Connection Pool)               │     │
│  └─────────────────────┬──────────────────────────────┘     │
│                        │                                     │
│                        ▼                                     │
│           ┌────────────────────────┐                         │
│           │   MariaDB (ki_dev,     │                         │
│           │   ki_content, mcp_log) │                         │
│           └────────────────────────┘                         │
└─────────────────────────────────────────────────────────────┘

Design-Prinzipien

PrinzipUmsetzung
SRP Jede Klasse hat eine Verantwortung: Validator validiert, Tool führt aus
OOP Klassen mit klarer Kapselung, keine globalen Funktionen
KISS Minimale Komplexität, kein Over-Engineering
Immutability QueryRequest ist frozen (unveränderlich)
Fail-Safe Exceptions statt silent failures

Datenfluss

1. Claude Code ruft db_select(query, database, max_rows, params)
2. Tool empfängt Request
3. QueryValidator.validate_query() prüft:
   - SELECT-Only
   - Keyword-Blocklist
   - Database-Allowlist
   - Table-Allowlist
   - Query-Länge
   - Max-Rows
4. Bei Fehler: DENIED Response + Log
5. Bei Erfolg: Tool führt Query aus
   - Connection aus Pool
   - SET max_statement_time (MariaDB)
   - cursor.execute(query, params)
   - fetchmany(max_rows)
6. Logging in ki_dev.mcp_log
7. Response zurück an Claude Code

Validators

ValidatorPrüftVerwendet von
QueryValidator SELECT-Queries, Blocklist, Allowlist db_select
ExecuteValidator DDL-Statements (ALTER, CREATE, DROP, TRUNCATE) db_execute

Logging

Alle Operationen werden in ki_dev.mcp_log protokolliert:

Verwandte Kapitel