mcp-context-engineering

A small, runnable project that demonstrates context engineering for MCP servers: keeping a Model Context Protocol server's footprint in the model's context window small, so agents are cheaper and more accurate.

The problem

When an MCP client (Claude Desktop, Cursor, an SDK app) connects to an MCP server, it pulls every advertised tool definition - name, description and full input schema - into the model's context. A server with 30-60+ tools can burn well over 10k tokens on definitions before the agent does anything. That causes two problems:

• Wasted tokens. You pay for tool definitions the agent will never call.
• Reduced accuracy. The model gets distracted by irrelevant tools and is more likely to pick the wrong one or hallucinate parameters.

The two techniques

This project implements both halves of the fix on a catalog of 33 mock "web-data" tools (Amazon, LinkedIn, TikTok, GitHub, Zillow, browser automation, batch scraping, ...) organised into logical groups.

1. Scope the tools you advertise. Load only the capabilities an agent needs - either by whole group (GROUPS=social) or by hand-picking individual tools (TOOLS=web_data_amazon_product,...). Only those definitions ever reach the context.
2. Optimise the output those tools return. Strip token-wasting Markdown (bold/italic, image syntax, heading markers, code fences, link URLs) from scraped pages before they enter the context, keeping every word the model actually reads.

Measured impact (from the bundled offline report)

Full catalog = 33 tools ≈ 4,556 tokens of definitions if loaded un-scoped.

Configuration	Tools	Def. tokens	Saved vs. all
default (base tools only)	3	506	89%
GROUPS=ecommerce	9	1,318	71%
GROUPS=social	11	1,566	66%
GROUPS=social,business	14	1,973	57%
TOOLS= amazon,ebay,google_shopping	3	416	91%
GROUPS=research + 1 custom tool	6	917	80%
PRO_MODE=true (load everything)	33	4,556	0%

Strip-markdown on a scraped page: 243 → 149 tokens (~39% fewer).

Numbers use a built-in heuristic token estimator; pass --tiktoken to the report for exact counts if tiktoken is installed. The point is the ratios, which are stable.

The pattern in one sentence

Scope the tools you load, trim the output they return, and let the MCP server handle the hard parts.

Code map

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

How the pieces fit

tool_groups.py defines which tool names belong to which group. tool_catalog.py gives each name a full definition (description + schema) and a mock handler. context_config.py reads the environment and decides the exact subset of names to expose. server.py asks context_config for that subset, advertises only those definitions via tools/list, and - when a MARKDOWN_TOOLS tool is called - runs its output through strip_markdown.py before returning it. token_utils.py powers the offline token_report.py, which quantifies both wins without touching the network.

Data flow

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

Quick start

# 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

Running the MCP server

The server speaks MCP over stdio and is configured entirely through environment variables:

# 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

Valid group ids: ecommerce, social, business, research, finance, app_stores, browser, advanced_scraping. See .env.example for the full list of variables.

Wiring into an MCP client

Copy one of the files in examples/ into your client's server config (for Claude Desktop that is claude_desktop_config.json), replace /ABSOLUTE/PATH with the path to your checkout, and restart the client. The three examples show a scoped group, a hand-picked set, and the load-everything baseline.

Notes on the tools

Every tool handler in this project returns canned, offline sample data. There is no API key and no network access anywhere - the goal is to demonstrate the context-engineering pattern, not to scrape live sites. To make it real, swap the handlers in tool_catalog.py for calls to an actual web-data backend and read its credentials from an environment variable (a placeholder, WEB_DATA_API_KEY, is documented in .env.example).

Built on / inspired by

• Model Context Protocol Python SDK - the official SDK this server uses: https://github.com/modelcontextprotocol/python-sdk
• Protocol docs & spec: https://modelcontextprotocol.io
• Bright Data MCP server - an open-source MCP server that popularised the tool-group scoping and strip-markdown output optimisation modelled here: https://github.com/brightdata/brightdata-mcp

License

MIT (see LICENSE if present, or treat the sample code as MIT-licensed).