feat: add deferred MCP provider registration

[Aaron ("AJ") Steers (aaronsteers)]

Summary

Adds mcp_provider(annotations=...) as a deferred-registration companion to mcp_tool() for FastMCP providers. Provider factories are collected by module, registered through the existing register_mcp_tools(app, mcp_module=...) flow, and receive a transform that fills missing tool annotations without overwriting annotations already declared by the provider’s tools.

Example:

@mcp_provider(annotations={"interactive-ui": True})
def prefab_provider() -> Provider:
    return GenerativeUI(...)

register_mcp_tools(app, mcp_module="interactive")

Tests cover decorator collection and provider tool annotation merging/registration.

Link to Devin session: https://app.devin.ai/sessions/f1992546281649c585688348e5774812
Requested by: Aaron ("AJ") Steers (@aaronsteers)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

🎉 Thanks for opening this pull request!

Your contribution is appreciated. Here are some helpful commands you can use:

Quick Commands

• /autofix - Auto-format and fix linting issues (ruff format + ruff check --fix)
• /lock - Update the uv.lock file with latest dependencies

Available Poe Tasks

You can run any of these tasks using the slash command: /poe <task-name>

Core Tasks

• /poe test - Run all tests
• /poe test-fast - Run tests with fast exit on first failure
• /poe lint - Check code style and quality
• /poe format - Format code with ruff
• /poe deps - Check for unused and missing dependencies
• /poe check - Run format check, linting, dependency check, and tests

Quick Fixes

• /poe fix - Auto-format and fix linting issues
• /poe clean - Clean up build artifacts and cache

Build & Install

• /poe build - Build the package
• /poe install - Install with development dependencies

Other Commands

• /poe version - Show package version
• /poe pre-commit - Run pre-commit style checks

The CI will automatically run tests when you push commits. Happy coding! 🚀

[Copilot]

Pull request overview

Adds deferred registration support for FastMCP providers (parallel to the existing deferred mcp_tool / mcp_prompt / mcp_resource patterns), and wires provider registration into the existing register_mcp_tools(app, mcp_module=...) flow with annotation merging for provider-sourced tools.

Changes:

• Added @mcp_provider(annotations=...) decorator and a _REGISTERED_PROVIDERS registry for deferred provider factory collection.
• Extended register_mcp_tools(...) to instantiate/register matching providers and attach a transform that merges provider-level annotations into provider tool annotations without overwriting tool-declared annotations.
• Added unit tests covering provider decorator collection and annotation merge behavior via register_mcp_tools.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
tests/test_fastmcp_extensions.py	Adds unit tests for provider registration and provider-tool annotation merging.
src/fastmcp_extensions/registration.py	Registers deferred providers during register_mcp_tools and applies an annotations-merging transform to provider tools.
src/fastmcp_extensions/decorators.py	Introduces mcp_provider decorator + provider registry and clears it in _clear_registrations().
src/fastmcp_extensions/__init__.py	Exposes mcp_provider from the package public API (__all__).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.