[jpsiddharth2008]

Summary

Closes #73.

Adds an application-owned widget registry and a widget://examples MCP resource so tooling can discover registered widgets, their metadata, and example inputs and outputs.

The registry is built from tools registered during application startup, including helper-generated @widget options. It does not scan source files or execute tools.

Changes

• Add WidgetRegistry, WidgetManifest, WidgetMetadata, and WidgetExample.
• Expose registry access through app.widget_registry and get_widget_registry(app).
• Publish widget routes, resource URIs, MIME types, metadata, associated tool names, and declared examples through widget://examples.
• Deduplicate shared routes and sort entries deterministically, retaining examples from every associated tool.
• Keep registries isolated between applications and return detached copies from read APIs.
• Reuse existing MCP resource handlers and mode-aware widget metadata helpers.
• Preserve existing widget HTML rendering and resource behavior.
• Leave resource listings unchanged for applications without widgets.
• Reject conflicting widget://examples registrations in applications containing widgets.
• Add usage documentation, implementation details, and verification results.

Acceptance criteria

• Verified all three official templates through actual application bootstrapping:
  • python-starter: 1 unique widget.
  • python-pizzaz: 3 unique widgets.
  • python-oauth / flight-booking: 6 unique widgets.
• Confirmed helper-generated Pizzaz options retain their metadata and examples.
• Confirmed shared routes such as order-summary appear once.
• Confirmed applications without widgets receive no additional MCP resource.

Testing

Added 22 tests covering:

• Supported decorator forms and helper-generated options.
• Metadata, MIME types, and preservation of example values.
• Duplicate routes, deterministic ordering, and merged examples.
• Application isolation and protection against mutation through returned data.
• Empty applications and reserved-URI collisions.
• Additional configured MCP server instances.
• Modern/sessionless and legacy/sessionful HTTP.
• Real stdio resource discovery and reading with uncontaminated protocol output.
• Isolated bootstrapping of all three templates with networking blocked.

Complete test collection succeeds: 847 tests.

Validated locally with official MCP 2.3.0:

Platform	Python	Full-suite result	Coverage
Linux — WSL Ubuntu	3.10.21	847 passed	86.44%
Linux — WSL Ubuntu	3.11.16	847 passed	86.42%
Linux — WSL Ubuntu	3.12.14	847 passed	86.42%
Windows	3.10.21	847 passed	86.44%
Windows	3.11.16	847 passed	86.42%
Windows	3.12.14	846 passed, 1 failed	86.42%

The new registry module has 100% statement coverage. No test exclusions, new skips, or xfail markers were added.

Windows 3.12 limitation

An existing OAuth localhost HTTP test intermittently raises WinError 10053. The same test and error were reproduced on unchanged upstream develop (63ecd924) using the same Python and MCP versions.

All new widget tests pass. No OAuth implementation or tests were modified to suppress the failure.

Validation

python -m pytest tests --collect-only -o addopts= -q
python -m pytest tests/test_widget_registry.py -o addopts=--timeout=60 -q
python -m pytest tests --cov=nitrostack --cov-report=term-missing --timeout=60 --tb=short -o addopts= -q
git diff --check

[AadarshM07]

The core implementation looks good to me. however the repo does not maintain a doc/ folder. Also issue#73-verfication.md looks more like developer reference. the minimal documentation can be added on the readme.md itself and the additional doc folder can be removed i think.