MCP-Docs Architektur

Verzeichnisstruktur und Komponenten des MCP-Docs Servers.

Verzeichnisstruktur

/opt/mcp-servers/mcp-docs/
├── server.py              # Entry Point (FastMCP)
├── config.py              # Konfiguration
├── .env                   # Credentials (DB_HOST, DB_USER, etc.)
├── requirements.txt       # Dependencies (mcp, pymysql, python-dotenv)
├── venv/                  # Python Virtual Environment
│
├── domain/
│   ├── __init__.py
│   └── dokumentation.py   # Entities (Dokumentation, DocStatus, LogEntry)
│
├── infrastructure/
│   ├── __init__.py
│   ├── db_connection.py   # Datenbankverbindung (ki_system)
│   ├── protokoll_logger.py # Logging nach ki_protokoll.mcp_log
│   └── docs_repository.py # CRUD-Operationen
│
└── tools/
    ├── __init__.py
    └── docs_tools.py      # 9 MCP-Tools

Layer-Architektur

Komponenten

server.py

Entry Point mit FastMCP-Initialisierung:

from mcp.server.fastmcp import FastMCP
from tools.docs_tools import register_docs_tools

mcp = FastMCP("mcp-docs", instructions="...")
register_docs_tools(mcp)

if __name__ == "__main__":
    mcp.run(transport="stdio")

domain/dokumentation.py

Dataclasses für Dokumentations-Entities:

@dataclass
class Dokumentation:
    id: int
    parent_id: Optional[int]
    slug: str
    path: str
    title: str
    description: Optional[str]
    content: str
    status: str  # draft, published, archived
    sort_order: int
    depth: int
    created_at: datetime
    updated_at: datetime

    def to_dict(self) -> dict
    def to_dict_compact(self) -> dict  # ohne content

infrastructure/docs_repository.py

CRUD-Operationen auf ki_system.dokumentation:

• find_by_id(), find_by_path()
• find_all() mit Filtern
• find_children() - Kind-Dokumente
• get_hierarchy() - Vollständiger Baum
• get_breadcrumb() - Pfad zum Dokument
• create(), update(), delete()
• move() - Parent ändern
• get_statistics()

infrastructure/db_connection.py

Verbindung zur ki_system Datenbank:

def get_connection():
    return pymysql.connect(
        host=os.getenv("DB_HOST"),
        database="ki_system",
        user=os.getenv("DB_USER"),
        password=os.getenv("DB_PASSWORD"),
        cursorclass=pymysql.cursors.DictCursor
    )

infrastructure/protokoll_logger.py

Logging nach ki_protokoll.mcp_log:

def log_operation(tool: str, params: dict, result: dict):
    # INSERT INTO mcp_log ...

Datenbank-Schema

-- ki_system.dokumentation
CREATE TABLE dokumentation (
    id INT AUTO_INCREMENT PRIMARY KEY,
    parent_id INT DEFAULT NULL,
    slug VARCHAR(100) NOT NULL,
    path VARCHAR(500) NOT NULL,
    title VARCHAR(255) NOT NULL,
    description TEXT,
    content LONGTEXT,
    status ENUM('draft','published','archived') DEFAULT 'draft',
    sort_order INT DEFAULT 0,
    depth INT DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    
    UNIQUE KEY (path),
    FOREIGN KEY (parent_id) REFERENCES dokumentation(id) ON DELETE SET NULL
);

Hierarchie-Konzept

Datenfluss

Claude Code
    ↓ MCP Tool Call
FastMCP (server.py)
    ↓ docs_get()
docs_tools.py
    ↓ Repository
docs_repository.py
    ↓ SQL + Logging
ki_system.dokumentation + ki_protokoll.mcp_log

Besonderheiten

• Zwei Datenbanken: Daten in ki_system, Logging in ki_protokoll
• Pfad-Berechnung: Automatisch aus Parent-Pfad + Slug
• Depth-Berechnung: Parent-Depth + 1
• Token-Optimierung: to_dict_compact() ohne Content