Files
14a4b54302 docs: add README for examples/mcp_demo (#3045)
## 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>
2026-10-01 12:28:12 -05:00
..

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