mcp-context-engineering

Un pequeño proyecto ejecutable que demuestra ingeniería de contexto para servidores MCP: mantener la huella de un servidor del Model Context Protocol en la ventana de contexto del modelo pequeña, para que los agentes sean más baratos y precisos.

El problema

Cuando un cliente MCP (Claude Desktop, Cursor, una aplicación SDK) se conecta a un servidor MCP, extrae todas las definiciones de herramientas anunciadas (nombre, descripción y esquema de entrada completo) a la ventana de contexto del modelo. Un servidor con 30-60+ herramientas puede quemar más de 10k tokens en definiciones antes de que el agente haga nada. Eso causa dos problemas:

• Tokens desperdiciados. Pagas por definiciones de herramientas que el agente nunca llamará.

• Precisión reducida. El modelo se distrae con herramientas irrelevantes y es más probable que elija la incorrecta o alucine parámetros.

Las dos técnicas

Este proyecto implementa ambas partes de la solución en un catálogo de 33 herramientas simuladas de "datos web" (Amazon, LinkedIn, TikTok, GitHub, Zillow, automatización de navegador, scraping por lotes, ...) organizadas en grupos lógicos.

1. Limita las herramientas que anuncias. Carga solo las capacidades que un agente necesita, ya sea por grupo completo (GROUPS=social) o seleccionando herramientas individuales (TOOLS=web_data_amazon_product,...). Solo esas definiciones llegan al contexto.

2. Optimiza la salida que devuelven esas herramientas. Elimina el Markdown que desperdicia tokens (negrita/cursiva, sintaxis de imágenes, marcadores de encabezado, bloques de código, URLs de enlaces) de las páginas raspadas antes de que entren al contexto, conservando cada palabra que el modelo realmente lee.

Impacto medido (del informe offline incluido)

Catálogo completo = 33 herramientas ≈ 4,556 tokens de definiciones si se cargan sin limitar.

Strip-markdown en una página raspada: 243 → 149 tokens (~39% menos).

Los números usan un estimador de tokens heurístico integrado; pasa --tiktoken al informe para obtener recuentos exactos si tiktoken está instalado. El punto son las proporciones, que son estables.

El patrón en una frase

Limita las herramientas que cargas, recorta la salida que devuelven y deja que el servidor MCP maneje las partes difíciles.

Mapa del código

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

Cómo encajan las piezas

tool_groups.py define qué nombres de herramientas pertenecen a qué grupo. tool_catalog.py da a cada nombre una definición completa (descripción + esquema) y un manejador simulado. context_config.py lee el entorno y decide el subconjunto exacto de nombres a exponer. server.py pregunta a context_config por ese subconjunto, anuncia solo esas definiciones a través de tools/list y, cuando se llama a una herramienta MARKDOWN_TOOLS, ejecuta su salida a través de strip_markdown.py antes de devolverla. token_utils.py alimenta el informe offline token_report.py, que cuantifica ambas ventajas sin tocar la red.

Flujo de datos

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"]

Inicio rápido

# 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

Ejecutar el servidor MCP

El servidor habla MCP sobre stdio y se configura completamente a través de variables de entorno:

# 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

IDs de grupo válidos: ecommerce, social, business, research, finance, app_stores, browser, advanced_scraping. Consulta .env.example para la lista completa de variables.

Conexión a un cliente MCP

Copia uno de los archivos en examples/ a la configuración de servidor de tu cliente (para Claude Desktop es claude_desktop_config.json), reemplaza /ABSOLUTE/PATH con la ruta a tu checkout y reinicia el cliente. Los tres ejemplos muestran un grupo limitado, un conjunto seleccionado a mano y la línea base de cargar todo.

Notas sobre las herramientas

Cada manejador de herramientas en este proyecto devuelve datos de muestra simulados y offline. No hay clave API ni acceso a red en ningún lugar: el objetivo es demostrar el patrón de ingeniería de contexto, no raspar sitios en vivo. Para hacerlo real, reemplaza los manejadores en tool_catalog.py por llamadas a un backend real de datos web y lee sus credenciales de una variable de entorno (un marcador de posición, WEB_DATA_API_KEY, está documentado en .env.example).

Construido sobre / inspirado por

• Model Context Protocol Python SDK - el SDK oficial que usa este servidor: https://github.com/modelcontextprotocol/python-sdk

• Documentación y especificación del protocolo: https://modelcontextprotocol.io

• Servidor MCP de Bright Data - un servidor MCP de código abierto que popularizó el limitado de grupos de herramientas y la optimización de salida strip-markdown modelados aquí: https://github.com/brightdata/brightdata-mcp

Licencia

MIT (consulta LICENSE si existe, o trata el código de muestra como licenciado bajo MIT).