Support ToolsRepository for Dynamic Tool Management & Cursor-based Pagination Status

[ultramancode]

Support ToolsRepository for Dynamic Tool Management & Cursor-based Pagination

Related Issue

#740
#578

Motivation

The current MCP server implementation exposes every registered tool to all connected clients without exception. In a production environment, this "all-or-nothing" approach presents several challenges:

• Multi-tenant isolation: The ability to serve different toolsets to different clients or environments.
• Granular Access Control: Protecting administrative or sensitive tools by hiding them from unauthorized users.
• Dynamic Flexibility: Loading tool definitions on-the-fly from external sources (Databases, Config Servers, etc.) rather than being limited to static registration.
• Enterprise Scalability: Efficiently managing large-scale toolsets without overwhelming the client or the network, ensuring resource efficiency through Cursor-based Pagination.

Problem

The current architecture of McpAsyncServer is rigid:

• Tools are stored in a static ConcurrentHashMap<String, AsyncToolSpecification>.
• The tools/list request returns the entire map, regardless of the client's identity or needs.
• There is no way to access the client's context (e.g., client ID or role) during the tool discovery process.

Proposed Solution

We introduce the ToolsRepository interface to decouple tool storage from the server engine, providing a pluggable architecture for tool management:

public interface ToolsRepository {
    // Context-aware filtering and pagination support
    Mono<ToolsListResult> listTools(McpAsyncServerExchange exchange, String cursor);
    
    // Security validation during execution
    Mono<AsyncToolSpecification> resolveToolForCall(String name, McpAsyncServerExchange exchange);
    
    void addTool(AsyncToolSpecification tool);
    void removeTool(String name);
}

Key Advantages:

• Exchange Integration: Access client metadata and attributes via McpAsyncServerExchange.
• Pre-filtering: Prevent tool exposure at the listing stage, reducing the client-side attack surface.
• Spec-aligned Pagination: Support for opaque cursors, following the MCP specification.

Practical Applications

1. Role-Based Visibility (RBAC): Automatically hide admin tools from standard users by checking roles in the exchange.
2. Tenant-Specific Ecosystems: Dynamically provide a unique set of tools based on the tenant ID associated with the connection.
3. External Source Integration: Implement a repository that fetches tool definitions from a remote database or a plugin system at runtime, enabling updates without server restarts.

[ultramancode]

I've submitted a PR for this: #747. Please let me know if you have any feedback.