mcp-context-engineering

Небольшой запускаемый проект, демонстрирующий контекстную инженерию для MCP-серверов: сохранение небольшого следа сервера Model Context Protocol в контекстном окне модели, чтобы агенты были дешевле и точнее.

Проблема

Когда MCP-клиент (Claude Desktop, Cursor, SDK-приложение) подключается к MCP-серверу, он тянет каждое объявляемое определение инструмента — имя, описание и полную схему входных данных — в контекст модели. Сервер с 30–60+ инструментами может сжечь более 10 000 токенов на определениях, прежде чем агент вообще что-то сделает. Это приводит к двум проблемам:

• Впустую потраченные токены. Вы платите за определения инструментов, которые агент никогда не вызовет.

• Снижение точности. Модель отвлекается на нерелевантные инструменты и с большей вероятностью выберет неправильный или выдумает параметры.

Два приёма

Этот проект реализует обе половины решения на каталоге из 33 имитационных инструментов «web-data» (Amazon, LinkedIn, TikTok, GitHub, Zillow, автоматизация браузера, пакетный скрапинг, ...), организованных в логические группы.

1. Ограничьте набор объявляемых инструментов. Загружайте только те возможности, которые нужны агенту, — либо целой группой (GROUPS=social), либо выборочно отдельными инструментами (TOOLS=web_data_amazon_product,...). Только эти определения когда-либо попадают в контекст.

2. Оптимизируйте вывод, который возвращают эти инструменты. Удаляйте из соскрапленных страниц Markdown, тратящий токены (жирный/курсив, синтаксис изображений, маркеры заголовков, ограждения кода, URL ссылок), прежде чем они попадут в контекст, сохраняя каждое слово, которое модель реально читает.

Измеренный эффект (из прилагаемого офлайн-отчёта)

Полный каталог = 33 инструмента ≈ 4 556 токенов определений при загрузке без ограничений.

Очистка Markdown на соскрапленной странице: 243 → 149 токенов (~39% меньше).

Числа получены встроенным эвристическим оценщиком токенов; передайте --tiktoken в отчёт для точных подсчётов, если установлен tiktoken. Смысл в соотношениях, которые стабильны.

Паттерн в одной фразе

Ограничьте набор загружаемых инструментов, сократите их вывод и позвольте MCP-серверу делать сложную работу.

Карта кода

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

Как части сочетаются

tool_groups.py определяет, какие имена инструментов относятся к какой группе. tool_catalog.py задаёт каждому имени полное определение (описание + схему) и имитационный обработчик. context_config.py читает окружение и решает, какое именно подмножество имён предоставлять. server.py запрашивает у context_config это подмножество, объявляет только эти определения через tools/list и — когда вызывается инструмент MARKDOWN_TOOLS — прогоняет его вывод через strip_markdown.py перед возвратом. token_utils.py обеспечивает работу офлайн-отчёта token_report.py, который количественно оценивает оба выигрыша, не обращаясь к сети.

Поток данных

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

Быстрый старт

# 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

Запуск MCP-сервера

Сервер общается по MCP через stdio и настраивается полностью через переменные окружения:

# 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

Допустимые идентификаторы групп: ecommerce, social, business, research, finance, app_stores, browser, advanced_scraping. Полный список переменных см. в .env.example.

Подключение к MCP-клиенту

Скопируйте один из файлов в examples/ в конфигурацию серверов вашего клиента (для Claude Desktop это claude_desktop_config.json), замените /ABSOLUTE/PATH на путь к вашей копии репозитория и перезапустите клиент. Три примера показывают ограниченную группу, набор, отобранный вручную, и базовый вариант с загрузкой всего.

Примечания об инструментах

Каждый обработчик инструмента в этом проекте возвращает готовые офлайн-примеры данных. Нигде нет API-ключей и доступа к сети — цель состоит в демонстрации паттерна контекстной инженерии, а не в скрапинге живых сайтов. Чтобы сделать проект реальным, замените обработчики в tool_catalog.py на вызовы настоящего web-data бэкенда и читайте его учётные данные из переменной окружения (заглушка WEB_DATA_API_KEY описана в .env.example).

Основано на / вдохновлено

• Model Context Protocol Python SDK — официальный SDK, который использует этот сервер: https://github.com/modelcontextprotocol/python-sdk

• Документация и спецификация протокола: https://modelcontextprotocol.io

• Bright Data MCP server — MCP-сервер с открытым исходным кодом, который популяризировал ограничение набора инструментов по группам и оптимизацию вывода с очисткой Markdown, воспроизведённые здесь: https://github.com/brightdata/brightdata-mcp

Лицензия

MIT (см. LICENSE, если он присутствует, или считайте пример кода лицензированным по MIT).