Demo: add a lightweight visual MCP simulator for non-technical users

[itprodirect]

Objective

Add a lightweight visual simulator that helps non-technical users understand the MCP flow without requiring a full desktop-client setup.

Context

A demo website or visual simulator can make MCP intuitive. Start small: a local/static simulator that shows the message flow and sample tool results is more appropriate than a full production Next.js app at this stage.

Scope

Add one lightweight demo path, such as one of these:

docs/demo-simulator.html

or

demo/streamlit_app.py

Pick the simplest option that fits the existing repo and dependencies.

Simulator concept

The user should be able to click through steps like:

1. Discover tools
2. Select a sample business question
3. Call sample MCP tool
4. Show result
5. Explain what happened

The visual should reinforce:

AI Host -> MCP Client -> MCP Server -> Sample Data -> Tool Result

Acceptance criteria

• A non-technical user can understand the simulator without reading Python source code.
• Demo uses only tracked sample data or hardcoded safe sample results.
• README links to the simulator.
• The simulator explains that it is a teaching aid, not a production MCP host.
• No secrets, API keys, or real client data are required.
• Existing tests still pass.

Non-goals

• Do not build a full hosted web app yet.
• Do not add authentication.
• Do not add claims triage automation.
• Do not add a database unless absolutely necessary.

Validation

ruff check .
mypy --strict .
pytest -q

Manual validation:

• Open or run the simulator from a clean clone.
• Confirm the flow is understandable in under 2 minutes.