feat: add mcp_server() helper with built-in server info and credential resolution

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

Summary

Adds a new mcp_server() factory function that creates FastMCP instances with common patterns built-in:

• Automatic server info resource - Registers a {name}://server/info resource with package version, git SHA, FastMCP version, and custom advertised properties
• HTTP header credential resolution - MCPServerConfigArg allows defining credentials that resolve from HTTP headers first, then fall back to environment variables, then to default values
• MCP module auto-discovery - Optional auto_discover_assets parameter discovers sibling non-private modules in the caller's package
• Passthrough to FastMCP - All additional kwargs are passed to the FastMCP constructor

Example usage:

from fastmcp_extensions import mcp_server, MCPServerConfigArg, get_mcp_config

app = mcp_server(
    name="my-server",
    package_name="my-package",
    advertised_properties={"docs_url": "..."},
    server_config_args=[
        MCPServerConfigArg(
            name="api_key",
            http_header_key="X-API-Key",
            env_var="MY_API_KEY",
            default="fallback-value",  # Can also be a callable
        ),
    ],
)
api_key = get_mcp_config(app, "api_key")

Updates since last revision

Based on PR feedback:

• Renamed resolve_config to get_mcp_config ("get" is more accurate since values may be cached, and "mcp" prefix makes the purpose clearer)
• Made get_registered_tools, get_registered_prompts, get_registered_resources private (internal implementation details now that mcp_server() handles registration)
• Made clear_registrations private (_clear_registrations) - only used for testing
• Added comprehensive module docstring with usage examples and backtick cross-links to key components
• Added normalize_fn parameter to MCPServerConfigArg for transforming resolved values
• Updated get_mcp_config to accept either Context or FastMCP for session-aware resolution
• Renamed _mcp_server_config to x_mcp_server_config to distinguish from FastMCP's private properties
• Moved package_name to a top-level parameter
• Implemented _discover_mcp_module_names() using inspect and pkgutil
• Made http_header_key and env_var optional/nullable
• Added default field (string or callable)
• 29 tests total

Review & Testing Checklist for Human

• Test _discover_mcp_module_names() with a real package - The implementation uses stack inspection (inspect.currentframe()) which can be fragile. Verify it works correctly when called from a real MCP server package.
• Test normalize_fn behavior - Verify that returning None from normalize_fn triggers fallback to next source, and that exceptions propagate correctly without leaking sensitive values.
• Test get_mcp_config with Context - Verify session-aware resolution works when passing a Context object from an MCP tool function.
• Verify sensitive attribute behavior - MCPServerConfigArg.sensitive is defined but not used for masking. Confirm this is intentional for future use.

Suggested test plan:

1. Create a simple MCP server package with multiple modules using mcp_server(auto_discover_assets=True)
2. Verify _discover_mcp_module_names() returns the expected module list
3. Start the server and query the {name}://server/info resource
4. Test credential resolution with HTTP headers, env vars, default values, and normalize_fn

Notes

Closes #6

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

[devin-ai-integration]

Original prompt from AJ Steers

@Devin - <https://github.com/airbytehq/fastmcp-extensions/issues/6>
Thread URL: https://airbytehq-team.slack.com/archives/D089P0UPVT4/p1768687993204549

[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 and CI 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]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.