DevTools MCP

Ein kleiner MCP-Server mit Entwickler-Hilfsfunktionen, erstellt, um das Model Context Protocol end-to-end zu lernen: Serverimplementierung, lokales Testen, die Verwendung eines vorhandenen MCP, öffentliche Bereitstellung und Smithery-Publishing.

1. Überblick

DevTools MCP stellt über das Model Context Protocol vier kleine Entwickler-Tools bereit: Erklären einer Fehlermeldung, Validieren/Formatieren von JSON, Erzeugen eines regulären Ausdrucks aus einer Beschreibung und das Zusammenfassen von Text mit einem LLM (Groq). Ein minimales TypeScript/Vite-Dashboard ermöglicht es, die Tools in einem Browser auszuprobieren, wobei es sich als echter MCP-Client verbindet.

Related MCP server: Log Analyzer MCP

2. Warum MCP

MCP standardisiert, wie ein LLM-Host (Claude Desktop, eine IDE, ein Agent) Tools entdeckt und aufruft, statt dass jedes Projekt eine eigene, maßgeschneiderte Tool-Aufruf-API erfindet. Einen echten MCP-Server zu bauen – nicht eine REST API mit einem aufgesetzten MCP-Label – war das primäre Lernziel dieses Projekts.

3. Architektur

MCP Client
    |
MCP Protocol
    |
DevTools MCP Server
    |-- explain_error    (local/deterministic)
    |-- format_json      (local/deterministic)
    |-- generate_regex   (local/deterministic)
    `-- summarize_text
            |
        Groq API
            |
        GPT-OSS 120B

Der Server (server/server.py) ist eine mcp.server.MCPServer-Instanz (MCP Python SDK v2). Er läuft über stdio für lokale Tests (MCP Inspector, Client(mcp)) und über Streamable HTTP (/mcp) für den Fern- bzw. Browserzugriff. Das TypeScript-Frontend (frontend/) ist ein echter MCP-Client: Es nutzt Client und StreamableHTTPClientTransport aus @modelcontextprotocol/sdk, um direkt über Streamable HTTP mit dem Server zu sprechen (CORS ist serverseitig aktiviert) – nicht über eine handgebaute REST-Brücke.

4. Tools

5. Projektstruktur

devtools-mcp/
├── server/
│   ├── server.py               # MCPServer + tool registration + ASGI app
│   ├── tools.py                # explain_error / format_json / generate_regex logic
│   ├── ai.py                   # Groq-backed summarize_text logic
│   └── tests/
│       └── test_server.py      # pytest suite using the SDK's in-memory Client
├── frontend/
│   ├── index.html
│   ├── src/
│   │   ├── main.ts             # real MCP client (StreamableHTTPClientTransport)
│   │   └── style.css
│   ├── package.json
│   ├── tsconfig.json
│   └── vite.config.ts
├── .env.example
├── .gitignore
├── requirements.txt
├── render.yaml                 # optional Render Blueprint
├── README.md
└── EXISTING_MCP_EXPERIENCE.md

6. Voraussetzungen

• Python 3.10+

• Node.js 18+ und npm (für das Frontend und zum Ausführen des MCP Inspector über npx)

• Ein Groq-API-Schlüssel (nur für summarize_text erforderlich)

• (Optional, für das Deployment) Ein Render-Konto und ein Smithery-Konto

7. Installation

git clone <this-repo>
cd devtools-mcp
python3 -m venv .venv
. .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

8. Umgebungsvariablen

Kopiere .env.example als .env und fülle aus, was du brauchst:

GROQ_API_KEY=            # required for summarize_text
GROQ_MODEL=openai/gpt-oss-120b
MCP_ALLOWED_HOSTS=        # only needed when deployed behind a real hostname
MCP_ALLOWED_ORIGINS=      # comma-separated browser origins allowed via CORS

.env wird von git ignoriert. Übe niemals echte Geheimnisse in ein Commit ein.

9. Lokale Einrichtung

Stdio (Standard, für lokale MCP-Clients):

python -m server.server

Streamable HTTP (für das Frontend oder jeden HTTP-basierenden MCP-Client), nur lokal:

uvicorn server.server:app --host 127.0.0.1 --port 8000

MCP_ALLOWED_HOSTS kann bei lokalem Betrieb ungesetzt bleiben – die im SDK eingebaute DNS-Rebinding-Bounded Allowlist für localhost deckt 127.0.0.1/localhost automatisch passend ab. Health-Check: curl http://127.0.0.1:8000/health.

10. MCP Inspector Tests

# Against stdio:
uv run mcp dev server/server.py     # requires uv; or: npx @modelcontextprotocol/inspector
# Against a running Streamable HTTP server:
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8000/mcp --method tools/list

In der Entwicklung wurde dies gegen den lokalen Streamable-HTTP-Server ausgeführt und bestätigt, dass alle vier Tools mit korrekten Ein-/Ausgabe-Schemas auffindbar sind (siehe unten unter „Tests“ die genauen Ergebnisse).

11. Frontend-Einrichtung

cd frontend
npm install
npm run dev          # http://localhost:5173

Setze im laufenden Dashboard das Feld Server-URL auf den /mcp-Endpunkt deines MCP-Servers (Standard http://localhost:8000/mcp), klicke auf Connect, wähle ein Tool aus, fülle das Formular aus und klicke auf Run. Für die lokale Benutzung startet das Backend mit MCP_ALLOWED_ORIGINS=http://localhost:5173, damit es CORS erlaubt ist.

Produktions-Build: npm run build (Ausgabe nach frontend/dist/).

12. Groq-Einrichtung

1. Erstelle einen API-Schlüssel unter console.groq.com.

2. Setze GROQ_API_KEY (optional zusätzlich GROQ_MODEL, Standardwert openai/gpt-oss-120b) in .env oder in den Umgebungsvariablen deiner Deployment-Plattform.

3. In keiner anderen Komponente dieses Projekts wird ein anderer LLM-Provider verwendet.

13. Vorhandene MCP-Erfahrung

Sieh für die geforderte Demonstration der Verwendung eines vorhandenen MCP-Servers (Context7) in EXISTING_MCP_EXPERIENCE.md nach – was er ist, wie die Verbindung hergestellt wurde, welche konkrete Anfrage gestellt wurde und was du gelernt hast.

14. Deployment mit Render

Für das Deployment wird die nativen Laufzeit von Render für Python verwendet (kein Docker nötig.

Einrichtung über das Dashboard:

1. Pushe dieses Repo nach GitHub.

2. In Render: New → Web Service → Repo verbinden.

3. Laufzeit: Python 3. Build-Befehl: pip install -r requirements.txt. Startbefehl: uvicorn server.server:app --host 0.0.0.0 --port $PORT.

4. Setze die Umgebungsvariablen: GROQ_API_KEY, GROQ_MODEL, MCP_ALLOWED_HOSTS=<your-service>.onrender.com,<your-service>.onrender.com:* sowie MCP_ALLOWED_ORIGINS=<your-frontend-origin> (wenn du das Frontend mit bereitstellst). du bereitstellst).

5. Deployen. Der MCP-Endpoint lautet dann https://<your-service>.onrender.com/mcp.

Ein render.yaml-Blueprint ist als Komfort für dieselbe Konfiguration beigefügt.

Manueller Prüfschritt nötig: Ein echtes Deployment erfordert ein Render-Konto und wurde nicht im Rahmen dieser Leistung ausgeführt – siehe im Abschlussbericht, welche Schritte manuell bleiben.

15. Smithery-Publishing

Die aktuelle Smithery-CLI unterstützt die direkte Veröffentlichung einer bereits gehosteten Remote-MCP-Server-URL (für diesen Weg ist keine Docker/Container-Verpackung einzupacken):

npm install -g smithery
smithery auth login
smithery mcp publish "https://<your-service>.onrender.com/mcp" -n "<your-org>/devtools-mcp"

Nach der Veröffentlichung prüfe, ob die vier Tools bereitgestellt sind:

smithery mcp add "https://<your-service>.onrender.com/mcp" --id devtools-mcp
smithery tool list devtools-mcp

Mit anzulegendem Schritt: Dafür brauchte man erst ein Smithery-Konto und ein aktives, öffentlich erreichbares Render-Deployment; das wurde im Rahmen hier nicht ausgeführt.

16. Öffentliche MCP-Nutzung

Nach dem Deployment lässt sich von jedem Streamable-HTTP-MCP-Client eine Verbindung herstellen zu:

https://<your-service>.onrender.com/mcp

Beispiel mit dem Client des SDK:

from mcp import Client
from mcp.client.streamable_http import streamable_http_client

async with streamable_http_client("https://<your-service>.onrender.com/mcp") as (r, w, _):
    async with Client(r, w) as client:
        await client.initialize()
        print(await client.list_tools())

17. Tests

Hier in dieser Umgebung wirklich ausgeführt:

pytest server/tests/ -v

Ergebnis: 11 bestanden – Tool-Erkennung; gültige, fehlerhafte und leere format_json-Eingaben; übereinstimmende und nicht übereinstimmende explain_error-Muster (einschließlich leerer Eingabe); generate_regex für ein bekanntes Muster (mit Live-Regex-Abgleich) und eine nicht zugeordnete Beschreibung; summarize_text ohne GROQ_API_KEY und mit leerer Eingabe.

Zusätzlich manuell (außerhalb von pytest) ausgeführt:

• uvicorn server.server:app startete erfolgreich; /health gab {"status":"ok",...} zurück.

• Ein roher initialize-JSON-RPC-POST an /mcp antwortete mit 200.

• Echtes MCP Inspector CLI (npx @modelcontextprotocol/inspector --cli) verband sich über Streamable HTTP, listete alle vier Tools mit korrekten Schemas auf und rief erfolgreich generate_regex, explain_error und format_json (gültige und ungültige JSON) und summarize_text auf (das die fehlenden API-Schlüssel-Fehler korrekt meldete, da in dieser Liste kein echter Groq-Schlüssel verfügbar war).

• Transportsicherheit geprüft: Eine Anfrage mit mitgefälschtem Host-Header erhielt korrekt 421 Misdirected Request.

• CORS-Preflight geprüft: Eine OPTIONS /mcp-Anfrage mit Origin: http://localhost:5173 lieferte 200 mit den korrekten access-control-*-Headern, sobald MCP_ALLOWED_ORIGINS gesetzt war.

• Frontend: npx tsc --noEmit lief ohne Fehler; npm run build war erfolgreich und erzeugte frontend/dist/.

Nicht überprüft (erforderlich sind externe Konten/Zugangsdaten, die in dieser Umgebung nicht verfügbar sind): Ein echter summarize_text-Aufruf mit einem live-Groq-API-Key, das Render-Deployment selbst sowie Smithery-Publishing/Listing.

18. Einschränkungen

• summarize_text wurde nur end-to-end auf seinen Fehlerpfaden getestet; ein Aufruf mit echten Groq-Zugangsdaten fehlt.

• Das Render-Deployment und das Smithery-Publishing sind manuelle Schritte mit eigenen Konten (siehe Teile 14-15) und wurden hier nicht durchgeführt.

• explain_error und generate_regex verwenden kleine, handgeschriebene Musterbibliotheken statt eines LLM – bewusst einfach/deterministisch, passend zum Umfang des Projekts. Sie erkennen daher sind nicht jede nur denkbare Fehlermeldung bzw. jede Musterbeschreibung.

• Das Frontend hat keine Authentifizierung und ist dem gemäß Projektumfang („no accounts/auth“) für lokale bzw. Demo-Zwecke gedacht.

19. Lernergebnisse

• Was MCP ist: Ein standardisiertes Protokoll, das „LLM with Kontext/Aktionen zu versorgen“ von „der LLM-Interaktion selbst“ trennt – so dass ein einmal gebauter Server (wie dieser) mit jedem kompatiblen Client funktioniert.

• Host / Client / Server: Der Host ist die LLM-Anwendung (Claude Desktop oder die Anwendung hinter dem Browser-Dashboard); der Client ist die Komponente, die MCP verwendet (der SDK-Client bzw. der auf StreamableHTTPClientTransport basierte Client unsers Frontend); der Server ist das, was wir gebaut haben – er spricht nie direkt mit einem Model.

• Tools vs. Ressourcen vs. Prompts: Tools sind Modellgesteuert (das LLM entscheidet z. B. format_json zu call); Ressourcen sind anwendungsgesteuerte Datenladevorgänge; Prompts sind von Nutzern aufgerufene Vorlagen. Für dieses Projekt waren nur Tools nötig.

• Tool-Entdeckung und -Aufruf: Ein Client ruft tools/list auf, um zu erfahren, was verfügbar ist (Name, Beschreibung, JSON-Schema inputs/outputs, alles automatisch aus Python-Typhinweisen und Docstrings generiert) und ruft danach tools/call auf, um ein Tool mit Argumenten auszuführen.

• Warum MCP statt einer einfachen REST API: Für eine REST API braucht man je Client eine maßgeschneiderte Integration; ein MCP-Server beschreibt seine eigenen Fähigkeiten / seine Schemas selbst, sodass jeder MCP-fähige Host–ohne benutzerdefinierte Kleber–loslegen kann. Das wurde in direkter Form gezeigt, indem derselbe Server mit MCP Inspector und mit der selbstgebauten Frontend-Client ohne serverseitige Änderung verbunden wurde.

• Wo das LLM ins Spiel kommt: Nur innerhalb von summarize_text, das Groq aufruft. Alles andere Grundserver ist schlichter deterministischer Code – eine gute Erinnerung daran, dass „MCP-Server“ und „KI-Anwendung“ nicht dasselbe sind.

• Deployment-Realität: Streamable-HTTP-Server gehen aus Sicherheit standardmäßig von localhost-only Host-/Origin-Allowlisten aus, und das muss hinter realem Hostnamen explizit geöffnet werden (TransportSecuritySettings) – das wurde hands-on bestätigt, indem ein 421 erzeugt und dann behoben wurde.