mcp-context-engineering

Ein kleines, ausführbares Projekt, das Context Engineering für MCP-Server demonstriert: den Fußabdruck eines Model Context Protocol-Servers im Kontextfenster des Modells klein zu halten, damit Agenten günstiger und genauer arbeiten.

Das Problem

Wenn ein MCP-Client (Claude Desktop, Cursor, eine SDK-App) eine Verbindung zu einem MCP-Server herstellt, zieht er jede beworbene Tool-Definition – Name, Beschreibung und vollständiges Eingabeschema – in den Kontext des Modells. Ein Server mit 30–60+ Tools kann weit über 10.000 Tokens für Definitionen verbrauchen, bevor der Agent überhaupt etwas tut. Das verursacht zwei Probleme:

• Verschwendete Tokens. Du bezahlst für Tool-Definitionen, die der Agent nie aufruft.

• Reduzierte Genauigkeit. Das Modell wird durch irrelevante Tools abgelenkt und wählt eher das falsche aus oder halluziniert Parameter.

Die zwei Techniken

Dieses Projekt implementiert beide Hälften der Lösung anhand eines Katalogs von 33 Mock-„Web-Data“-Tools (Amazon, LinkedIn, TikTok, GitHub, Zillow, Browser-Automatisierung, Batch-Scraping, ...), die in logische Gruppen organisiert sind.

1. Begrenze die Tools, die du bewirbst. Lade nur die Fähigkeiten, die ein Agent benötigt – entweder als ganze Gruppe (GROUPS=social) oder durch manuelles Auswählen einzelner Tools (TOOLS=web_data_amazon_product,...). Nur diese Definitionen erreichen jemals den Kontext.

2. Optimiere die Ausgabe, die diese Tools zurückgeben. Entferne tokenverschwendendes Markdown (fett/kursiv, Bildsyntax, Überschriftenmarkierungen, Codeblöcke, Link-URLs) aus gescrapten Seiten, bevor sie in den Kontext gelangen, und behalte jedes Wort, das das Modell tatsächlich liest.

Gemessene Auswirkung (aus dem beiliegenden Offline-Bericht)

Vollständiger Katalog = 33 Tools ≈ 4.556 Tokens an Definitionen, wenn ohne Begrenzung geladen.

Strip-Markdown auf einer gescrapten Seite: 243 → 149 Tokens (~39 % weniger).

Die Zahlen verwenden einen eingebauten heuristischen Token-Schätzer; übergib --tiktoken an den Bericht für exakte Zählungen, falls tiktoken installiert ist. Der Punkt sind die Verhältnisse, die stabil sind.

Das Muster in einem Satz

Begrenze die Tools, die du lädst, trimme die Ausgabe, die sie zurückgeben, und lass den MCP-Server die schwierigen Teile übernehmen.

Code-Übersicht

mcp-context-engineering/
├── src/mcp_context_engineering/
│   ├── __init__.py          # Public API re-exports + version.
│   ├── tool_groups.py       # Source of truth for groups: BASE_TOOLS + 8 logical
│   │                        #   groups (ecommerce, social, business, research,
│   │                        #   finance, app_stores, browser, advanced_scraping)
│   │                        #   and helpers (all_tool_names, total_tool_count).
│   ├── tool_catalog.py      # Full catalog of 33 ToolSpecs: name, description,
│   │                        #   JSON input schema, and an OFFLINE mock handler
│   │                        #   each. Also MARKDOWN_TOOLS (which outputs to strip)
│   │                        #   and a SAMPLE_MARKDOWN_PAGE for the demo.
│   ├── context_config.py    # The scoping brain. Reads PRO_MODE / GROUPS / TOOLS,
│   │                        #   resolves the exact tool set (resolve_context),
│   │                        #   and defines named PRESETS.
│   ├── strip_markdown.py    # Dependency-free output optimiser: strips Markdown
│   │                        #   formatting, keeps words + code, links optional.
│   ├── token_utils.py       # Lightweight offline token estimator + tool-def
│   │                        #   token counting (tiktoken optional).
│   └── server.py            # The MCP server (official SDK low-level Server,
│   │                        #   stdio). Advertises only scoped tools; strips
│   │                        #   Markdown output. build_server() for tests.
├── scripts/
│   ├── run_server.py        # Launch the server over stdio (what a client runs).
│   └── token_report.py      # Offline demo: prints the savings tables above.
├── examples/
│   ├── claude_desktop_social_agent.json   # config: one group
│   ├── claude_desktop_price_monitor.json  # config: hand-picked tools
│   └── claude_desktop_pro_mode.json       # config: everything (baseline)
├── tests/
│   └── test_context_engineering.py        # 23 offline tests (unittest)
├── requirements.txt         # Just the official `mcp` SDK (tiktoken optional).
├── .env.example             # All config vars, documented.
└── .gitignore

Wie die Teile zusammenpassen

tool_groups.py definiert, welche Tool-Namen zu welcher Gruppe gehören. tool_catalog.py gibt jedem Namen eine vollständige Definition (Beschreibung + Schema) und einen Mock-Handler. context_config.py liest die Umgebung und entscheidet die genaue Teilmenge der Namen, die exponiert werden. server.py fragt context_config nach dieser Teilmenge, bewirbt nur diese Definitionen über tools/list und – wenn ein MARKDOWN_TOOLS-Tool aufgerufen wird – führt dessen Ausgabe durch strip_markdown.py, bevor sie zurückgegeben wird. token_utils.py versorgt den Offline-token_report.py, der beide Gewinne quantifiziert, ohne das Netzwerk zu berühren.

Datenfluss

flowchart TD
    subgraph Config["Configuration (env vars)"]
        E["PRO_MODE / GROUPS / TOOLS<br/>STRIP_MARKDOWN"]
    end

    E --> RC["context_config.resolve_context()"]
    TG["tool_groups.py<br/>(group -> tool names)"] --> RC
    RC -->|"scoped list of tool names"| SRV["server.py (MCP Server)"]
    TC["tool_catalog.py<br/>(name -> description, schema, handler)"] --> SRV

    subgraph MCP["MCP session (stdio)"]
        CLIENT["MCP client / LLM agent"]
        SRV
    end

    SRV -->|"tools/list: ONLY scoped definitions"| CLIENT
    CLIENT -->|"tools/call(name, args)"| SRV
    SRV -->|"handler() output"| STRIP["strip_markdown.py<br/>(markdown tools only)"]
    STRIP -->|"trimmed text"| CLIENT

    RC -.offline.-> REPORT["scripts/token_report.py"]
    TC -.offline.-> REPORT
    TU["token_utils.py"] -.-> REPORT
    REPORT -.-> OUT["savings tables"]

Schnellstart

# 1. (optional) create a virtualenv
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate

# 2. install the one dependency
pip install -r requirements.txt

# 3. see the token savings - fully offline, no key, no network
python scripts/token_report.py
python scripts/token_report.py --json      # machine-readable

# 4. run the tests
python -m unittest discover -s tests -v

Den MCP-Server ausführen

Der Server spricht MCP über stdio und wird vollständig über Umgebungsvariablen konfiguriert:

# default: just the small base tool set
python scripts/run_server.py

# a focused social-media agent
GROUPS=social python scripts/run_server.py

# hand-pick exactly the tools a price monitor needs
TOOLS=web_data_amazon_product,web_data_ebay_product,web_data_google_shopping \
    python scripts/run_server.py

# the un-scoped baseline (loads everything)
PRO_MODE=true python scripts/run_server.py

# disable output trimming
STRIP_MARKDOWN=false GROUPS=social python scripts/run_server.py

Gültige Gruppen-IDs: ecommerce, social, business, research, finance, app_stores, browser, advanced_scraping. Siehe .env.example für die vollständige Liste der Variablen.

Einbinden in einen MCP-Client

Kopiere eine der Dateien in examples/ in die Server-Konfiguration deines Clients (für Claude Desktop ist das claude_desktop_config.json), ersetze /ABSOLUTE/PATH durch den Pfad zu deinem Checkout und starte den Client neu. Die drei Beispiele zeigen eine begrenzte Gruppe, eine manuell ausgewählte Menge und die Alles-laden-Basislinie.

Hinweise zu den Tools

Jeder Tool-Handler in diesem Projekt gibt vorgefertigte, offline-Beispieldaten zurück. Es gibt keinen API-Schlüssel und keinen Netzwerkzugriff – das Ziel ist es, das Context-Engineering-Muster zu demonstrieren, nicht Live-Seiten zu scrapen. Um es real zu machen, ersetze die Handler in tool_catalog.py durch Aufrufe an ein echtes Web-Data-Backend und lies dessen Anmeldedaten aus einer Umgebungsvariable (ein Platzhalter, WEB_DATA_API_KEY, ist in .env.example dokumentiert).

Basierend auf / inspiriert von

• Model Context Protocol Python SDK – das offizielle SDK, das dieser Server verwendet: https://github.com/modelcontextprotocol/python-sdk

• Protokoll-Dokumentation & Spezifikation: https://modelcontextprotocol.io

• Bright Data MCP-Server – ein Open-Source-MCP-Server, der die hier modellierte Tool-Gruppen-Begrenzung und Strip-Markdown-Ausgabeoptimierung populär gemacht hat: https://github.com/brightdata/brightdata-mcp

Lizenz

MIT (siehe LICENSE, falls vorhanden, oder behandle den Beispielcode als MIT-lizenziert).