modern-di-fastmcp 4.0.1

modern-di integration for FastMCP.

Full guide: FastMCP integration docs

Usage example: examples/

Installation

uv add modern-di-fastmcp      # or: pip install modern-di-fastmcp

Usage

setup_di attaches the root container to the server and adds a middleware that builds a request container for every MCP request. FromDI, used as a parameter's default value, resolves a provider (or type) from it and keeps the parameter out of the tool schema.

import dataclasses

import fastmcp
from modern_di import Container, Group, Scope, providers
from modern_di_fastmcp import FromDI, setup_di


@dataclasses.dataclass(kw_only=True)
class Settings:
    greeting: str = "Hello"


@dataclasses.dataclass(kw_only=True)
class GreetingService:
    settings: Settings  # auto-injected by type


class Dependencies(Group):
    settings = providers.Factory(scope=Scope.APP, creator=Settings)
    service = providers.Factory(scope=Scope.REQUEST, creator=GreetingService)


mcp = fastmcp.FastMCP("greeter")
container = Container(groups=[Dependencies])
setup_di(mcp, container)
container.validate()  # optional fail-fast; must come after setup_di registers its providers


@mcp.tool
def greet(name: str, service: GreetingService = FromDI(Dependencies.service)) -> str:  # noqa: B008
    return f"{service.settings.greeting}, {name}!"

FromDI must be the default value, not Annotated metadata: FastMCP keeps an Annotated parameter in the schema and asks the client for it. When the parameter's type has no schema, as with a plain class, FastMCP itself refuses the tool when it is defined. When it has one, as with a dataclass, the server raises TypeError at startup naming the parameter. The check covers the server's own tools, resources and prompts, not those of a mounted server or ones added after startup.

To stop ruff's B008 from flagging every FromDI default, add it to your ruff config:

[tool.ruff.lint.flake8-bugbear]
extend-immutable-calls = ["modern_di_fastmcp.FromDI"]

The current fastmcp.Context is resolvable within DI via the pre-built fastmcp_context_provider context provider.

Shutdown order

setup_di closes the root container from a provider lifespan it adds to the server. Providers added after setup_di tear down before the close and can still resolve from the container. These run after the close and get ContainerClosedError:

• the teardown of FastMCP(lifespan=...)
• the teardown of providers added before setup_di

For these, pass manage_lifespan=False and open and close the container in your own server lifespan:

import collections.abc
import contextlib


@contextlib.asynccontextmanager
async def lifespan(server: fastmcp.FastMCP) -> collections.abc.AsyncIterator[None]:
    async with container:
        yield
        ...  # shutdown code that still needs the container


mcp = fastmcp.FastMCP("greeter", lifespan=lifespan)
container = Container(groups=[Dependencies])
setup_di(mcp, container, manage_lifespan=False)

API

📦 PyPI

📝 License

Part of modern-python

Built on modern-di, a dependency-injection framework with an IoC container and scopes.

Browse the full list of templates and libraries in modern-python; the org profile has the categorized index.