Modular system to define MCP Primitives

Description

Current fastmcp server implementations, both high-level and low-level, present fundamental challenges for writing scalable and modular, multi-file applications.

The high-level fastmcp server relies on decorators like @mcp.tool(), @mcp.resource() etc. A prerequisite for these decorators is access to the main server instance (mcp). This design often forces developers to define all their primitives within a single monolithic file (e.g., server.py), which hinders modularity and makes it difficult to organize larger projects.

While the low-level server implementation allows for defining primitives in separate files, this approach introduces its own complexities. It requires manually importing the primitives for the list_<primitive> handlers and routing callbacks through a large if/else ladder or a match/case block (e.g call_tool handler). This is cumbersome and less elegant compared to the clean, decorator-based interface the high-level server provides.

There is no out of the box method or exposed interface to build large scale modularized mcp servers, and to add primitives from other files or sources where the mcp instance is not present involves patching the internals or utilizing some internal methods/managers manually.

This is why it's unergonomic

Usually mcp servers are often wrappers around existing systems to provide the system resources to a llm, hence for systems with extensive apis, could benefit from organization, ex: (users/ -> tools.py, resources.py etc, items/)

Maintainability, if there are a large number of developers working on a particular mcp server, smaller atomic and role specific files are easier to read, debug and maintain.

Consistency & Reusability, some primitives can have shared configs for a particular set of tools/resources like metadata, tags etc. These primitive groups can also be modularly reused based on versioning or application set features.

Here is how I envision how this might look like:

user_tools_manager = MCPPluginManager(name="user-tools")

def has_bot_user(ctx: MiddlewareContext[CallToolRequest]) -> bool:
    return ctx.context.bot.user is not None

@user_tools_manager.register_tool
@user_tools_manager.check(has_bot_user)  # predicate checks, can be control logic or access control
async def get_current_user(ctx: DiscordMCPContext) -> DiscordUser:
    """Get the current bot user."""
    return DiscordUser.from_discord_user(ctx.bot.user)

@user_tools_manager.register_resource("resource://discord/user/{user_id}")
async def get_user_resource(ctx: DiscordMCPContext, user_id: str) -> DiscordUser:
    """Get a user resource by their ID."""
    user = ctx.bot.get_user(int(user_id)) or await ctx.bot.fetch_user(int(user_id))
    return DiscordUser.from_discord_user(user)

# Current completion/complete request handler requires a global handler, this could help with argument and callback specific handlers
@get_user_resource.autocomplete("user_id")
async def autocomplete_user_id(
    ctx: DiscordMCPContext, ref: DiscordMCPResourceTemplate, query: str, context_args: dict[str, t.Any] | None = None
) -> list[str]:
    """Autocomplete user IDs."""
    if not query:
        return []
    users = ctx.bot.users
    return [str(user.id) for user in users if query.lower() in user.name.lower() or query in str(user.id)][:10]


@user_tools_manager.register_tool
@user_tools_manager.limit(RateLimitType.FIXED_WINDOW, rate=1, per=180) # possible ratelimit, or cooldown logic
async def get_latency(ctx: DiscordMCPContext) -> float:
    """Get the latency of the bot."""
    latency = ctx.bot.latency * 1000
    return latency

These plugin managers or groups can be loaded and added to the respective primitive managers in the server when setting up the handlers.

This is working system we built when working on our own mcp server for discord, and the source code for the above can be found here, but the ability to do something similar natively out of the package would be a pretty nice option to have.

Plugin Manager- https://github.com/FallenDeity/discord-mcp/blob/master/src/discord_mcp/core/plugins/manager.py
Usage - https://github.com/FallenDeity/discord-mcp/blob/master/src/discord_mcp/core/discord_ext/user/tools.py
Server - https://github.com/FallenDeity/discord-mcp/blob/07dcc418aaa57cf22089c5db411e1c9c20063b77/src/discord_mcp/core/server/base.py#L819-L869

References

This already a common concept in quite a few popular frameworks like fastapi, django etc. which have the concept of routers which is largely used to create applications at scale

• https://fastapi.tiangolo.com/tutorial/bigger-applications
• https://www.django-rest-framework.org/api-guide/routers/
• https://flask.palletsprojects.com/en/stable/blueprints/

先檢查 issue 中描述的高階 decorator 流程，以及低階的 list 和 call_tool handler，接著比較所參照的 plugin manager 與 server 進入點。完成的定義是：有一種具備文件說明的原生方式，可以從分開的檔案註冊 primitives 或 groups，並在不需手動 routing 或內部 patching 的情況下，將它們附加至 server 的 primitive managers。