mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:06:14 +08:00
## Description Adds `examples/mcp_demo/README.md` in the same style as `examples/langchain_demo/README.md`. `examples/mcp_demo` contains three runnable demo scripts plus mock-server generators, but no README — the demo is undiscoverable and its entry points (module invocation with `PYTHONPATH=.`, the `OPENAI_API_KEY` requirement for the eval) are only documented inside script docstrings. ## Type of Change - [x] Documentation update ## Changes Made - Added `examples/mcp_demo/README.md`: overview, prerequisites, how to run each demo script (including `PYTHONPATH=.` module invocation), mock-server generation, and expected output for the eval demo (`OPENAI_API_KEY` requirement noted). ## Testing - [ ] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text # Docs-only change: no Python surface touched, so pytest/ruff/mypy are unaffected. # Manual checks performed: # - every command in the README cross-checked against the scripts' argparse/docstrings # - structure and tone match examples/langchain_demo/README.md # - referenced file paths all exist in examples/mcp_demo/ ``` ## Real Behavior Proof - Environment: local checkout of `main` + branch - Exact command / steps: walked each documented command against the actual scripts in `examples/mcp_demo/`; verified every referenced path exists - Observed result: documented invocations match the scripts' `__main__` entry points and flags; env-var requirements match the code - Not tested: live OpenAI-backed eval run (needs `OPENAI_API_KEY`); mock-server demos were verified by reading the code paths ## Runtime Rollout Safety - Rollout-managed feature(s): none — example documentation only - Minimum rollout channel: N/A - Stable/default behavior changed: none - Kill switch / disable path: N/A - Unsafe override required: none - Qualification impact: none - Rollback path: revert the single-file commit ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] My changes generate no new warnings - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title ## Additional Notes Docs-only PR: pytest/ruff/mypy items intentionally unchecked (no Python code changed). Signed-off-by: LeonSGP43 <LeonSGP43@users.noreply.github.com> Co-authored-by: LeonSGP43 <LeonSGP43@users.noreply.github.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
MCP + Headroom Demo
Real-world demonstration of Headroom compression on MCP (Model Context Protocol) tool outputs.
Quick Start
# Show compression on mock MCP tool outputs (no API key needed)
PYTHONPATH=. python -m examples.mcp_demo.show_compression
# Show the minimal BEFORE/AFTER code change for MCP integration
PYTHONPATH=. python -m examples.mcp_demo.show_before_after
# Run the full agent evaluation (requires OPENAI_API_KEY)
export OPENAI_API_KEY='your-key-here'
PYTHONPATH=. python -m examples.mcp_demo.run_agent_eval
What each script does
| Script | Purpose |
|---|---|
show_compression.py |
Compresses mock MCP tool results (Slack search, database queries, GitHub issues, log analysis) via compress_tool_result_with_metrics and prints before/after sizes. |
show_before_after.py |
Prints the minimal code diff needed to add Headroom compression to MCP tool outputs in your host application. |
run_agent_eval.py |
Simulates an agent with multiple MCP tools and tests whether compression preserves the information needed to answer correctly. Deterministic test-data generators keep the eval reproducible. |
mock_mcp_servers.py |
Test-data generators simulating real MCP server outputs. |
Key imports
from headroom.integrations.mcp import compress_tool_result_with_metrics
from headroom.providers import OpenAIProvider