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

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: aaronsteers

README.md

@@ -4,12 +4,13 @@ Unofficial extension library for FastMCP 2.0 with patterns, practices, and utili
 
 ## Features
 
+- MCP Server Factory: `mcp_server()` helper that creates FastMCP instances with built-in server info resources, MCP asset discovery (optional), and credential resolution.
 - MCP Annotation Constants: Standard annotation hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) following the FastMCP 2.2.7+ specification
-- Deferred Registration Decorators: `@mcp_tool`, `@mcp_prompt`, `@mcp_resource` decorators for organizing tools by domain with automatic domain detection
-- Registration Utilities: Functions to register tools, prompts, and resources with a FastMCP app, filtered by domain
-- Tool Testing Utilities: Helpers for testing MCP tools directly with JSON arguments (stdio and HTTP transports)
-- Tool List Measurement: Utilities for measuring tool list size to track context truncation issues
-- Prompt Helpers: Generic `get_prompt_text` helper for agents that cannot access prompt assets directly
+- Deferred Registration Decorators: `@mcp_tool`, `@mcp_prompt`, `@mcp_resource` decorators for organizing tools by domain with automatic domain detection.
+- Registration Utilities: Functions to register tools, prompts, and resources with a FastMCP app, filtered by domain.
+- Tool Testing Utilities: Helpers for testing MCP tools directly with JSON arguments (stdio and HTTP transports).
+- Tool List Measurement: Utilities for measuring tool list size to track context truncation issues.
+- Prompt Helpers: Generic `get_prompt_text` helper for agents that cannot access prompt assets directly.
 
 ## Installation
 
@@ -25,6 +26,37 @@ uv add fastmcp-extensions
 
 ## Quick Start
 
+### Using the MCP Server Factory
+
+The `mcp_server` function creates a FastMCP instance with built-in server info resources and optional credential resolution:
+
+```python
+from fastmcp_extensions import mcp_server, MCPServerConfigArg
+
+app = mcp_server(
+    name="my-mcp-server",
+    package_name="my-package",
+    advertised_properties={
+        "docs_url": "https://github.com/org/repo",
+        "release_history_url": "https://github.com/org/repo/releases",
+    },
+    server_config_args=[
+        MCPServerConfigArg(
+            name="api_key",
+            http_header_key="X-API-Key",
+            env_var="MY_API_KEY",
+            required=True,
+            sensitive=True,
+        ),
+    ],
+)
+
+# Server info resource is automatically registered at {name}://server/info
+# Get credentials from HTTP headers or environment variables
+from fastmcp_extensions import get_mcp_config
+api_key = get_mcp_config(app, "api_key")
+```
+
 ### Using Annotation Constants
 
 ```python
@@ -132,10 +164,16 @@ cmd = "python bin/measure_mcp_tool_list.py"
 
 ## API Reference
 
+### Server Factory
+
+- `mcp_server` - Create a FastMCP instance with built-in server info resource and auto-registration of decorated tools and assets.
+- `MCPServerConfigArg` - Configuration for credential resolution and other server settings.
+- `get_mcp_config` - Get a credential from HTTP headers or environment variables.
+
 ### Annotations
 
 | Constant | Description | FastMCP Default |
-|----------|-------------|-----------------|
+| -------- | ----------- | --------------- |
 | `READ_ONLY_HINT` | Tool only reads data | `False` |
 | `DESTRUCTIVE_HINT` | Tool modifies/deletes data | `True` |
 | `IDEMPOTENT_HINT` | Repeated calls have same effect | `False` |

src/fastmcp_extensions/__init__.py

@@ -18,10 +18,6 @@
     READ_ONLY_HINT,
 )
 from fastmcp_extensions.decorators import (
-    clear_registrations,
-    get_registered_prompts,
-    get_registered_resources,
-    get_registered_tools,
     mcp_prompt,
     mcp_resource,
     mcp_tool,
@@ -33,20 +29,26 @@
     register_mcp_resources,
     register_mcp_tools,
 )
+from fastmcp_extensions.server import (
+    MCPServerConfig,
+    MCPServerConfigArg,
+    get_mcp_config,
+    mcp_server,
+)
 
 __all__ = [
     "DESTRUCTIVE_HINT",
     "IDEMPOTENT_HINT",
     "OPEN_WORLD_HINT",
     "READ_ONLY_HINT",
+    "MCPServerConfig",
+    "MCPServerConfigArg",
     "PromptDef",
     "ResourceDef",
-    "clear_registrations",
-    "get_registered_prompts",
-    "get_registered_resources",
-    "get_registered_tools",
+    "get_mcp_config",
     "mcp_prompt",
     "mcp_resource",
+    "mcp_server",
     "mcp_tool",
     "register_mcp_prompts",
     "register_mcp_resources",

src/fastmcp_extensions/decorators.py

@@ -186,34 +186,7 @@ def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
     return decorator
 
 
-def get_registered_tools() -> list[tuple[Callable[..., Any], dict[str, Any]]]:
-    """Get all registered tools.
-
-    Returns:
-        List of (function, annotations) tuples for all registered tools.
-    """
-    return _REGISTERED_TOOLS.copy()
-
-
-def get_registered_prompts() -> list[tuple[Callable[..., Any], dict[str, Any]]]:
-    """Get all registered prompts.
-
-    Returns:
-        List of (function, annotations) tuples for all registered prompts.
-    """
-    return _REGISTERED_PROMPTS.copy()
-
-
-def get_registered_resources() -> list[tuple[Callable[..., Any], dict[str, Any]]]:
-    """Get all registered resources.
-
-    Returns:
-        List of (function, annotations) tuples for all registered resources.
-    """
-    return _REGISTERED_RESOURCES.copy()
-
-
-def clear_registrations() -> None:
+def _clear_registrations() -> None:
     """Clear all registered tools, prompts, and resources.
 
     This is primarily useful for testing.

src/fastmcp_extensions/registration.py

@@ -191,30 +191,3 @@ def _register_fn(
         resource_list=_REGISTERED_RESOURCES,
         register_fn=_register_fn,
     )
-
-
-def get_registered_tools() -> list[tuple[Callable[..., Any], dict[str, Any]]]:
-    """Get all registered tools.
-
-    Returns:
-        List of (function, annotations) tuples for all registered tools.
-    """
-    return _REGISTERED_TOOLS.copy()
-
-
-def get_registered_prompts() -> list[tuple[Callable[..., Any], dict[str, Any]]]:
-    """Get all registered prompts.
-
-    Returns:
-        List of (function, annotations) tuples for all registered prompts.
-    """
-    return _REGISTERED_PROMPTS.copy()
-
-
-def get_registered_resources() -> list[tuple[Callable[..., Any], dict[str, Any]]]:
-    """Get all registered resources.
-
-    Returns:
-        List of (function, annotations) tuples for all registered resources.
-    """
-    return _REGISTERED_RESOURCES.copy()