ProfRandom92/comptext-mcp-server

🚀 CompText MCP Server

Ein hochperformanter MCP (Model Context Protocol) Server für CompText DSL mit REST API Wrapper - deployed auf Render.com.

📋 Features

• ✅ CompText DSL Support - Vollständiger Zugriff auf den CompText Codex
• ✅ MCP Protocol - Native MCP-Server-Implementierung für Claude Desktop
• ✅ REST API - FastAPI HTTP Wrapper für universellen Zugriff
• ✅ Caching & Performance - LRU-Cache mit automatischem Retry-Mechanismus
• ✅ Type Safety - Vollständige Type Hints und Validierung
• ✅ Error Handling - Exponential Backoff und umfassende Fehlerbehandlung
• ✅ Security - Input-Validierung und Sanitization
• ✅ Production Ready - Docker, Health Checks, Monitoring

🏗️ Architektur

comptext-mcp-server/
├── src/comptext_mcp/         # Hauptpaket
│   ├── server.py              # MCP Server Implementierung
│   ├── notion_client.py       # Notion API Client mit Retry-Logik
│   ├── constants.py           # Zentrale Konstanten
│   └── utils.py               # Validierungs- und Hilfsfunktionen
├── rest_api_wrapper.py        # REST API Wrapper
├── mcp_server.py              # Einfacher Server für Render.com
└── tests/                     # Test Suite

🔧 Installation & Verwendung

Voraussetzungen

• Python 3.10+
• Notion API Token
• CompText Database ID

Lokale Entwicklung

# 1. Repository klonen
git clone https://github.com/ProfRandom92/comptext-mcp-server.git
cd comptext-mcp-server

# 2. Abhängigkeiten installieren
pip install -r requirements.txt

# 3. Umgebungsvariablen setzen
cp .env.example .env
# Bearbeite .env und füge deine Notion Credentials ein

# 4. MCP Server starten
python -m comptext_mcp.server

# Oder REST API starten
python rest_api_wrapper.py

MCP Server (für Claude Desktop)

# Server im stdio-Modus starten
python -m comptext_mcp.server

Konfiguration in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "comptext": {
      "command": "python",
      "args": ["-m", "comptext_mcp.server"],
      "env": {
        "NOTION_API_TOKEN": "your_token_here",
        "COMPTEXT_DATABASE_ID": "your_db_id"
      }
    }
  }
}

REST API Server

# Mit uvicorn
uvicorn rest_api_wrapper:app --reload

# Oder direkt
python rest_api_wrapper.py

Server läuft auf http://localhost:8000

📊 API Endpoints

REST API

MCP Tools

Der MCP Server bietet folgende Tools:

• list_modules - Liste aller Module (A-M)
• get_module - Lade spezifisches Modul
• get_command - Lade Seiteninhalt
• search - Durchsuche Codex
• get_by_tag - Filter nach Tag
• get_by_type - Filter nach Typ
• get_statistics - Codex Statistiken

🐳 Docker Deployment

# REST API Image bauen
docker build -f Dockerfile.rest -t comptext-api .

# Container starten
docker run -p 8000:8000 --env-file .env comptext-api

# Mit Docker Compose
docker-compose up -d

🚀 Deployment auf Render.com

Automatisches Deployment

1. Push zu GitHub
2. Gehe zu render.com/deploy
3. Verbinde Repository
4. Render erkennt automatisch render.yaml
5. Setze Environment Variables:
   • NOTION_API_TOKEN
   • COMPTEXT_DATABASE_ID (optional)
6. Click "Apply" → Fertig! ✅

Nach dem Deployment

Du erhältst eine URL wie: https://comptext-mcp.onrender.com

API Docs: https://comptext-mcp.onrender.com/docs

🔑 Umgebungsvariablen

# Erforderlich
NOTION_API_TOKEN=your_notion_token_here

# Optional
COMPTEXT_DATABASE_ID=0e038c9b52c5466694dbac288280dd93  # Standard-DB
LOG_LEVEL=INFO
HOST=0.0.0.0
PORT=8000

📖 Verwendungsbeispiele

Python Client

from comptext_mcp import get_all_modules, search_codex, get_module_by_name

# Alle Module laden
modules = get_all_modules()
print(f"Gefunden: {len(modules)} Einträge")

# Suche durchführen
results = search_codex("docker", max_results=5)
for result in results:
    print(f"- {result['titel']}")

# Spezifisches Modul laden
modul_b = get_module_by_name("Modul B: Programmierung")

REST API

# Alle Module
curl http://localhost:8000/api/modules

# Suche
curl "http://localhost:8000/api/search?query=docker&max_results=5"

# Modul B laden
curl http://localhost:8000/api/modules/B

# Statistiken
curl http://localhost:8000/api/statistics

JavaScript/TypeScript

// Suche durchführen
const response = await fetch(
  'https://comptext-mcp.onrender.com/api/search?query=docker'
);
const data = await response.json();
console.log(`Gefunden: ${data.count} Ergebnisse`);

🧪 Testing

# Tests ausführen
make test

# Mit Coverage
make test-cov

# Linting
make lint

# Code formatieren
make format

⚡ Performance-Hinweise

• Caching: get_all_modules() ist gecached (LRU, 128 Einträge)
• Retry-Logik: Automatische Wiederholung bei API-Fehlern (3x, exponential backoff)
• Free Tier Sleep: Render.com schläft nach 15 Min Inaktivität
  • Erste Anfrage nach Pause: ~30 Sek (Cold Start)
  • Lösung: Verwende Render's Cron Jobs für Keep-Alive Pings

🛡️ Security Features

• ✅ Input-Validierung für alle User-Eingaben
• ✅ Page ID Format-Validierung
• ✅ Query String Sanitization
• ✅ Text Output Sanitization
• ✅ CORS-Konfiguration
• ✅ Error Message Sanitization

🔧 Entwicklung

# Dev-Dependencies installieren
make install-dev

# Pre-commit hooks einrichten
pre-commit install

# Code formatieren
black src/ tests/
isort src/ tests/

# Type checking
mypy src/

📚 Module Übersicht

🤝 Contributing

Siehe für Richtlinien.

📄 Lizenz

MIT License - siehe für Details.

🔗 Links

• Notion Documentation
• MCP Protocol
• Render.com
• GitHub Repository