Claude finished @strawgate's task —— View job

Investigation Complete ✓

Recommendation

Convert BulkToolCaller from an MCPMixin-based class to a ToolInjectionMiddleware implementation. This aligns with the established pattern introduced in PR #2142 for exposing server capabilities as tools (e.g., PromptToolMiddleware, ResourceToolMiddleware).

The conversion simplifies usage from:

bulk_tool_caller = BulkToolCaller()
bulk_tool_caller.register_tools(mcp)

To:

mcp = FastMCP(middleware=[BulkToolCallerMiddleware()])

This eliminates the MCPMixin dependency, removes the need for FastMCPTransport connections, and provides a cleaner API consistent with other middleware.

Findings

Current Implementation

Location: src/fastmcp/contrib/bulk_tool_caller/bulk_tool_caller.py

The BulkToolCaller class currently:

Extends MCPMixin for tool registration
Creates a FastMCPTransport connection to call tools on the same server
Provides two tools: call_tools_bulk and call_tool_bulk
Uses @mcp_tool() decorator for tool registration
Requires explicit register_tools() call

Tool Injection Middleware Pattern

Location: src/fastmcp/server/middleware/tool_injection.py

The ToolInjectionMiddleware pattern (introduced in PR #2142):

Accepts a list of Tool objects in __init__
Injects tools via on_list_tools() middleware hook
Intercepts calls to injected tools via on_call_tool() middleware hook
Bypasses tag filtering (injected tools always appear)
Follows "later wins" deduplication for naming conflicts

Existing implementations:

PromptToolMiddleware - exposes list_prompts and get_prompt as tools
ResourceToolMiddleware - exposes list_resources and read_resource as tools

Key Differences

Aspect	Current MCPMixin Approach	Middleware Approach
Registration	`bulk_tool_caller.register_tools(mcp)`	`FastMCP(middleware=[...])`
Tool Access	Creates internal client with `FastMCPTransport`	Direct access via `Context`
Dependencies	Requires `MCPMixin`, `FastMCPTransport`, `Client`	Only requires `Tool`, `Context`
API Consistency	Unique pattern (only used by BulkToolCaller)	Matches `PromptToolMiddleware`, `ResourceToolMiddleware`
Tag Filtering	Tools respect filtering rules	Tools bypass filtering (always visible)

Detailed Action Plan

Implementation Steps

1. Create BulkToolCallerMiddleware class (src/fastmcp/server/middleware/bulk_tool_caller.py)

Extend ToolInjectionMiddleware
Define call_tools_bulk and call_tool_bulk as standalone async functions accepting Context
Use context.fastmcp to access the server's tool manager
Call tools directly via context.fastmcp._tool_manager.call_tool()
Convert to Tool objects via Tool.from_function()
Pass tools to parent ToolInjectionMiddleware.__init__()

2. Update existing BulkToolCaller class

Mark as deprecated with warnings.warn()
Add deprecation notice to docstring
Update to internally use BulkToolCallerMiddleware for compatibility
Keep in src/fastmcp/contrib/bulk_tool_caller/ for backward compatibility

3. Add comprehensive tests (tests/server/middleware/test_bulk_tool_caller.py)

Test both middleware methods work correctly
Test error handling with continue_on_error parameter
Test that bulk caller can call other server tools
Test structured vs. text content handling
Follow pattern from test_tool_injection.py

4. Update documentation

Add BulkToolCallerMiddleware to docs/servers/middleware.mdx
Update src/fastmcp/contrib/bulk_tool_caller/README.md with deprecation notice
Add migration guide showing old vs. new usage
Update src/fastmcp/contrib/bulk_tool_caller/example.py with both approaches

5. Update exports

Export BulkToolCallerMiddleware from src/fastmcp/server/middleware/__init__.py
Keep BulkToolCaller export in src/fastmcp/contrib/bulk_tool_caller/__init__.py

Implementation Details

Key Challenge: The bulk tool caller needs to call tools on its own server. The middleware approach requires accessing the tool manager:

async def call_tools_bulk(
    context: Context,
    tool_calls: list[CallToolRequest],
    continue_on_error: bool = True,
) -> list[CallToolRequestResult]:
    """Call multiple tools in a single request."""
    results = []
    for tool_call in tool_calls:
        try:
            # Access tool manager through context
            result = await context.fastmcp._tool_manager.call_tool(
                key=tool_call.tool,
                arguments=tool_call.arguments
            )
            results.append(CallToolRequestResult.from_call_tool_result(
                result, tool_call.tool, tool_call.arguments
            ))
        except Exception as e:
            # Handle errors
            if not continue_on_error:
                break
    return results

Backward Compatibility:

Keep BulkToolCaller class with deprecation warning
Internally delegate to middleware for actual functionality
Maintain existing API surface

Related Pull Requests

Repository	PR	Relevance
jlowin/fastmcp	#2142 - Add ToolInjectionMiddleware	High - Introduced the tool injection pattern that bulk tool caller should follow
jlowin/fastmcp	#2249 - Add list_resources, list_prompts to Context	High - Shows how ToolInjectionMiddleware uses Context to access server internals

Related Issues

Repository	Issue	Relevance
jlowin/fastmcp	#2140 - Resource/Prompt Tools for Client Compat	High - Original issue that led to ToolInjectionMiddleware creation
jlowin/fastmcp	#265 - Add't Example/Reference Server	Medium - References BulkToolCaller as an example feature

Related Files

Repository	File	Relevance	Key Sections
jlowin/fastmcp	tool_injection.py	Critical - Base class and pattern to follow	Lines 21-52 (ToolInjectionMiddleware), 80-116 (PromptToolMiddleware, ResourceToolMiddleware examples)
jlowin/fastmcp	bulk_tool_caller.py	Critical - Current implementation to convert	Lines 69-133 (tool methods to migrate)
jlowin/fastmcp	test_tool_injection.py	High - Test patterns to follow	Lines 38-274 (comprehensive middleware tests)
jlowin/fastmcp	test_bulk_tool_caller.py	High - Existing tests to adapt	Lines 93-288 (test cases to migrate)
jlowin/fastmcp	context.py	Medium - Shows Context API for accessing server	Context.fastmcp property

Convert Bulk Tool Caller to Middleware #2262

Description

Enhancement

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions