[HOLD] SEP-1686 tasks

[chrisguidry]

This PR represents the feature branch for bringing SEP-1686 to fastmcp. The work will proceed in phases, and will land against this branch. When the low-level SDK and fastmcp are both ready to go, this will be the final PR we merge to main.

Phases:

• Phase 1: FastAPI/Docket-style dependency injection for all components
• Phase 2: Making a Docket available to all components for background processing
• Phase 3: Implement the SEP-1686 protocol and backgrounding of components
• Phase 4: Add command-line support for running additional/dedicated fastmcp workers
• Phase 5: Promote the feature out of experimental status ahead of the release

[marvin-context-protocol]

Test Failure Analysis

Summary: Integration test test_call_tool_list_commits hit a rate limit (HTTP 429) from the GitHub Copilot API during teardown, causing an unhandled exception during asyncio shutdown and a pytest teardown error.

Root Cause: The failure is caused by two related issues:

1. Rate Limiting During Cleanup: When the test timed out on its first attempt (>15s), the client's disconnect logic attempted to properly clean up the HTTP session. During this cleanup, the StreamableHttpTransport made a final HTTP request to https://api.githubcopilot.com/mcp/ which was rate-limited (HTTP 429). This exception occurred during the asyncio shutdown phase, causing an unhandled exception.

2. Pytest Stash KeyError: The timeout interrupted pytest's normal teardown flow, causing a KeyError when accessing tmppath_result_key from pytest's stash during fixture cleanup. This is a secondary symptom of the abrupt timeout.

The test is marked with @pytest.mark.flaky(retries=2, delay=1) and did pass on the second attempt, indicating this is an intermittent external API issue rather than a code bug.

Suggested Solution:

The failure is primarily caused by external rate limiting from GitHub's API, not a bug in the PR changes. However, there are a few options to make the tests more robust:

1. Suppress rate limit errors during disconnect - Modify Client._disconnect() to catch and log HTTP 429 errors during cleanup instead of propagating them:

# In src/fastmcp/client/client.py, around line 564
try:
    await self._session_state.session_task
except httpx.HTTPStatusError as e:
    if e.response.status_code == 429:
        logger.warning(f"Rate limited during disconnect: {e}")
    else:
        raise

2. Extend the rate limit handler - The existing conftest.py handles BrokenResourceError during the call phase, but doesn't handle HTTPStatusError during teardown. Consider adding a teardown hook to catch and suppress 429 errors.

3. Increase test timeout - The 15s timeout may be too aggressive for external API calls. Consider increasing it for this specific test class.

4. No action needed - Since the test passed on retry and this is an external API rate limit issue (not caused by the PR changes), this may be acceptable as-is given the @pytest.mark.flaky decorator.

Detailed Analysis

Error Flow

1. Test test_call_tool_list_commits starts execution
2. External GitHub Copilot API is slow or rate-limiting requests
3. Test hits 15-second timeout and is killed by pytest-timeout
4. Test's async with streamable_http_client context exits, triggering Client.__aexit__()
5. Client._disconnect() waits for session_task to complete
6. _session_runner() exits the AsyncExitStack, unwinding _context_manager()
7. transport.connect_session() context exits, making a final HTTP request
8. This request gets HTTP 429 response from https://api.githubcopilot.com/mcp/
9. Exception bubbles up during asyncio shutdown as unhandled
10. Pytest teardown encounters KeyError because the timeout interrupted normal cleanup

Relevant Log Excerpt

httpx.HTTPStatusError: Client error '429 Too Many Requests' for url 'https://api.githubcopilot.com/mcp/'
For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429

ERROR   asyncio:base_events.py:1758 unhandled exception during asyncio.run() shutdown
task: <Task finished name='Task-7' coro=<TestGithubMCPRemote.test_call_tool_list_commits() done...

PR Changes Context

The PR implements SEP-1686 (tasks protocol) with significant changes to the client code (client.py +888/-127 lines). The new disconnect logic uses reference counting and proper session cleanup, which is working correctly. The rate limit error is not caused by these changes—it's an external API constraint.

Related Files

• tests/integration_tests/test_github_mcp_remote.py:100 - The failing test (not modified in this PR)
• src/fastmcp/client/client.py:529 - _disconnect() method with new cleanup logic
• src/fastmcp/client/client.py:567 - _session_runner() that manages session lifecycle
• src/fastmcp/client/client.py:376 - _context_manager() that wraps transport connection
• tests/integration_tests/conftest.py:8 - Existing rate limit handling for call phase (handles BrokenResourceError, not HTTPStatusError)

[marvin-context-protocol]

Test Failure Analysis

Summary: Windows-specific file locking error during teardown of tests when using SQLite files.

Root Cause: The fixture creates a with a SQLite database in a temporary directory. On Windows, the SQLite database file () is not being properly closed before pytest attempts to clean up the temporary directory. Windows file locking prevents deletion of open files, causing a during teardown.

The issue occurs in the fixture at :

@pytest.fixture(params=["memory", "disk"])
async def caching_server(
    self,
    tracking_calculator: TrackingCalculator,
    request: pytest.FixtureRequest,
):
    mcp = FastMCP("CachingTestServer")

    with tempfile.TemporaryDirectory() as temp_dir:
        disk_store = DiskStore(directory=temp_dir)
        response_caching_middleware = ResponseCachingMiddleware(
            cache_storage=disk_store if request.param == "disk" else MemoryStore(),
        )
        # ... setup code ...
        yield mcp
        await disk_store.close()  # Line 306

The problem: context manager exits BEFORE completes, so the temp directory cleanup tries to delete the still-open database file.

Suggested Solution:

Reorder the context management to ensure is called before the temporary directory cleanup:

@pytest.fixture(params=["memory", "disk"])
async def caching_server(
    self,
    tracking_calculator: TrackingCalculator,
    request: pytest.FixtureRequest,
):
    mcp = FastMCP("CachingTestServer")

    # Create temp dir but don't use context manager yet
    temp_dir = tempfile.mkdtemp() if request.param == "disk" else None
    
    try:
        disk_store = DiskStore(directory=temp_dir) if temp_dir else None
        response_caching_middleware = ResponseCachingMiddleware(
            cache_storage=disk_store if request.param == "disk" else MemoryStore(),
        )

        mcp.add_middleware(middleware=response_caching_middleware)
        tracking_calculator.add_tools(fastmcp=mcp)
        tracking_calculator.add_resources(fastmcp=mcp)
        tracking_calculator.add_prompts(fastmcp=mcp)

        yield mcp

    finally:
        # Close disk store BEFORE cleaning up temp directory
        if disk_store is not None:
            await disk_store.close()
        
        # Now safe to remove temp directory
        if temp_dir is not None:
            import shutil
            shutil.rmtree(temp_dir)

Detailed Analysis

Error Pattern

All 9 failing tests follow the same pattern:

• Test:
• Error:
• Location: During pytest teardown when temp directory cleanup runs

Affected Tests

Why This Happens on Windows

Windows enforces stricter file locking than Unix systems. When SQLite has an open file handle, Windows prevents any other process (including Python's ) from deleting the file. Unix systems allow deletion of open files (the file remains until all handles are closed).

File Location

Related Files

• • The problematic fixture
• External: - SQLite-based cache store from py-key-value-aio library

[marvin-context-protocol]

Test Failure Analysis

Summary: Windows-specific file locking error during teardown of TestResponseCachingMiddlewareIntegration tests when using SQLite cache.db files.

Root Cause: The caching_server fixture creates a DiskStore with a SQLite database in a temporary directory. On Windows, the SQLite database file is not being properly closed before pytest attempts to clean up the temporary directory. Windows file locking prevents deletion of open files, causing a PermissionError during teardown.

The issue occurs in the fixture at tests/server/middleware/test_caching.py:283-306. The problem is that tempfile.TemporaryDirectory() context manager exits BEFORE disk_store.close() completes, so the temp directory cleanup tries to delete the still-open database file.

Suggested Solution:

Reorder the context management to ensure disk_store.close() is called before the temporary directory cleanup. Replace the with tempfile.TemporaryDirectory() pattern with try/finally to control cleanup order:

• Create temp dir manually with tempfile.mkdtemp()
• In finally block, close disk_store first
• Then remove temp directory with shutil.rmtree()

This ensures SQLite closes its file handles before Windows attempts to delete the directory.

Affected Tests

All 9 tests in TestResponseCachingMiddlewareIntegration fail with the same pattern:

• test_list_tools[memory]
• test_call_tool[memory]
• test_call_tool_very_large_value[memory]
• test_call_tool_crazy_value[memory]
• test_list_resources[memory]
• test_read_resource[memory]
• test_list_prompts[memory]
• test_get_prompts[memory]
• test_statistics[memory]

Why This Happens on Windows

Windows enforces stricter file locking than Unix systems. When SQLite has an open file handle, Windows prevents any other process from deleting the file. Unix systems allow deletion of open files (the file remains until all handles are closed).

Related Files

• tests/server/middleware/test_caching.py:283 - The problematic fixture
• External: key_value.aio.stores.disk.DiskStore - SQLite-based cache store from py-key-value-aio library
• Note: py-key-value-aio dependency was upgraded from >=0.2.8,<0.3.0 to >=0.3.0 in this PR

[marvin-context-protocol]

Test Failure Analysis

Summary: Windows-specific file locking error persists in after switching from pytest-retry to pytest-rerunfailures.

Root Cause: The fixture at uses a context manager that exits before executes. On Windows, this causes because SQLite still has an open file handle when pytest tries to delete the temporary directory.

The recent commit (c3aac59) replaced pytest-retry with pytest-rerunfailures, but this doesn't address the underlying fixture cleanup order issue. The problem exists in the fixture design itself.

Suggested Solution:

Replace the with tempfile.TemporaryDirectory() pattern with manual cleanup using try/finally to ensure disk_store.close() runs before directory deletion:

@pytest.fixture(params=["memory", "disk"])
async def caching_server(
    self,
    tracking_calculator: TrackingCalculator,
    request: pytest.FixtureRequest,
):
    """Create a FastMCP server for caching tests."""
    mcp = FastMCP("CachingTestServer")
    
    # Create temp dir manually (only for disk param)
    temp_dir = tempfile.mkdtemp() if request.param == "disk" else None
    disk_store = None
    
    try:
        disk_store = DiskStore(directory=temp_dir) if temp_dir else None
        response_caching_middleware = ResponseCachingMiddleware(
            cache_storage=disk_store if request.param == "disk" else MemoryStore(),
        )

        mcp.add_middleware(middleware=response_caching_middleware)
        tracking_calculator.add_tools(fastmcp=mcp)
        tracking_calculator.add_resources(fastmcp=mcp)
        tracking_calculator.add_prompts(fastmcp=mcp)

        yield mcp

    finally:
        # CRITICAL: Close disk store BEFORE removing temp directory
        if disk_store is not None:
            await disk_store.close()
        
        # Now safe to remove temp directory (no open file handles)
        if temp_dir is not None:
            import shutil
            shutil.rmtree(temp_dir)

Why This Fixes It:

1. The try/finally block guarantees cleanup order: disk_store.close() always runs before shutil.rmtree()
2. This closes SQLite's file handle before attempting directory deletion
3. Windows file locking is satisfied because the database file is properly closed

Alternative Solution (if you prefer to keep the context manager pattern):

Use contextlib.AsyncExitStack to control cleanup order:

from contextlib import AsyncExitStack

@pytest.fixture(params=["memory", "disk"])
async def caching_server(
    self,
    tracking_calculator: TrackingCalculator,
    request: pytest.FixtureRequest,
):
    """Create a FastMCP server for caching tests."""
    mcp = FastMCP("CachingTestServer")
    
    async with AsyncExitStack() as stack:
        if request.param == "disk":
            temp_dir_ctx = tempfile.TemporaryDirectory()
            temp_dir = stack.enter_context(temp_dir_ctx)
            disk_store = DiskStore(directory=temp_dir)
            # Register close callback BEFORE temp dir cleanup
            stack.push_async_callback(disk_store.close)
        else:
            disk_store = None
            
        response_caching_middleware = ResponseCachingMiddleware(
            cache_storage=disk_store if request.param == "disk" else MemoryStore(),
        )

        mcp.add_middleware(middleware=response_caching_middleware)
        tracking_calculator.add_tools(fastmcp=mcp)
        tracking_calculator.add_resources(fastmcp=mcp)
        tracking_calculator.add_prompts(fastmcp=mcp)

        yield mcp

Affected Tests (9 failures, all same root cause)

All tests in TestResponseCachingMiddlewareIntegration fail during teardown with PermissionError: [WinError 32]:

• test_list_tools[memory]
• test_call_tool[memory]
• test_call_tool_very_large_value[memory]
• test_call_tool_crazy_value[memory]
• test_list_resources[memory]
• test_read_resource[memory]
• test_list_prompts[memory]
• test_get_prompts[memory]
• test_statistics[memory]

Note: The [memory] parameter failures happen because the fixture still creates a DiskStore regardless of param value (line 293), then conditionally uses it. This means the temp directory and SQLite file are created for ALL parameterizations.

Related Files

• tests/server/middleware/test_caching.py:283 - The problematic fixture
• pyproject.toml:73 - Recent change from pytest-retry to pytest-rerunfailures (didn't fix the issue)
• External dependency: key_value.aio.stores.disk.DiskStore from py-key-value-aio (SQLite-based cache)

---

Note: This PR also bumped py-key-value-aio from <0.3.0 to >=0.3.0 (pyproject.toml:18). If the newer version has different cleanup behavior, that could also be investigated, but the fixture cleanup order is the primary issue.

[marvin-context-protocol]

Test Failure Analysis

Summary: Windows-specific file locking error persists in TestResponseCachingMiddlewareIntegration after switching from pytest-retry to pytest-rerunfailures.

Root Cause: The caching_server fixture at tests/server/middleware/test_caching.py:283-306 uses a tempfile.TemporaryDirectory() context manager that exits BEFORE await disk_store.close() executes. On Windows, this causes PermissionError: [WinError 32] because SQLite still has an open file handle when pytest tries to delete the temporary directory.

The recent commit (c3aac59) replaced pytest-retry with pytest-rerunfailures, but this doesn't address the underlying fixture cleanup order issue. The problem exists in the fixture design itself.

Suggested Solution:

Replace the with tempfile.TemporaryDirectory() pattern with manual cleanup using try/finally to ensure disk_store.close() runs before directory deletion:

@pytest.fixture(params=["memory", "disk"])
async def caching_server(
    self,
    tracking_calculator: TrackingCalculator,
    request: pytest.FixtureRequest,
):
    """Create a FastMCP server for caching tests."""
    mcp = FastMCP("CachingTestServer")

    # Create temp dir manually (only for disk param)
    temp_dir = tempfile.mkdtemp() if request.param == "disk" else None
    disk_store = None

    try:
        disk_store = DiskStore(directory=temp_dir) if temp_dir else None
        response_caching_middleware = ResponseCachingMiddleware(
            cache_storage=disk_store if request.param == "disk" else MemoryStore(),
        )

        mcp.add_middleware(middleware=response_caching_middleware)
        tracking_calculator.add_tools(fastmcp=mcp)
        tracking_calculator.add_resources(fastmcp=mcp)
        tracking_calculator.add_prompts(fastmcp=mcp)

        yield mcp

    finally:
        # CRITICAL: Close disk store BEFORE removing temp directory
        if disk_store is not None:
            await disk_store.close()

        # Now safe to remove temp directory (no open file handles)
        if temp_dir is not None:
            import shutil
            shutil.rmtree(temp_dir)

Why This Fixes It:

1. The try/finally block guarantees cleanup order: disk_store.close() always runs before shutil.rmtree()
2. This closes SQLite's file handle before attempting directory deletion
3. Windows file locking is satisfied because the database file is properly closed

Affected Tests (9 failures, all same root cause)

All tests in TestResponseCachingMiddlewareIntegration fail during teardown with PermissionError: [WinError 32]:

• test_list_tools[memory]
• test_call_tool[memory]
• test_call_tool_very_large_value[memory]
• test_call_tool_crazy_value[memory]
• test_list_resources[memory]
• test_read_resource[memory]
• test_list_prompts[memory]
• test_get_prompts[memory]
• test_statistics[memory]

Note: The [memory] parameter failures happen because the fixture still creates a DiskStore regardless of param value (line 293), then conditionally uses it. This means the temp directory and SQLite file are created for ALL parameterizations.

Related Files

• tests/server/middleware/test_caching.py:283 - The problematic fixture
• pyproject.toml:73 - Recent change from pytest-retry to pytest-rerunfailures (didn't fix the issue)
• External dependency: key_value.aio.stores.disk.DiskStore from py-key-value-aio (SQLite-based cache)

---

Note: This PR also bumped py-key-value-aio from <0.3.0 to >=0.3.0 (pyproject.toml:18). If the newer version has different cleanup behavior, that could also be investigated, but the fixture cleanup order is the primary issue.

[marvin-context-protocol]

Test Failure Analysis

Summary: Test test_multi_client_lifespan times out after 5 seconds because child MCP server processes are not being terminated when exiting the Client context manager.

Root Cause: The Client.__aexit__() method at src/fastmcp/client/client.py:376 only calls _disconnect() but does NOT call transport.close(). This means that when using the async with client: pattern, the underlying transport's cleanup is never executed, leaving child processes running.

Code Flow:

1. Client.__aexit__() → calls _disconnect()
2. _disconnect() → manages reference counting and stops the session task
3. BUT transport.close() is never called from __aexit__
4. Child processes spawned by MCPConfigTransport remain running
5. Test loops indefinitely waiting for processes to terminate

Suggested Solution: Modify Client.__aexit__() to call transport.close() after _disconnect():

# src/fastmcp/client/client.py:376
async def __aexit__(self, exc_type, exc_val, exc_tb):
    await self._disconnect()
    await self.transport.close()  # Add this line

This ensures that context manager cleanup properly terminates child processes, matching the behavior of explicitly calling client.close().

Detailed Analysis

Test Details (tests/test_mcp_config.py:295):

• Test creates MCPConfigTransport with 2 child Python MCP servers
• Gets PIDs of both server processes
• Exits context manager
• Expects processes to be terminated via psutil.NoSuchProcess
• Times out at 5 seconds waiting for process termination

Current Behavior:

• __aexit__ only calls _disconnect() which manages session lifecycle
• transport.close() is only called when explicitly calling client.close()
• Child processes remain running after context manager exits

Expected Behavior:

• Context manager exit should clean up all resources
• Child processes should be terminated
• Test should pass within timeout

Evidence from PR Diff:
The close() method exists and properly calls both _disconnect(force=True) and transport.close():

async def close(self):
    await self._disconnect(force=True)
    await self.transport.close()

But __aexit__ only calls _disconnect(), missing the transport.close() call.

Related Files

• src/fastmcp/client/client.py:376 - Client.__aexit__() missing transport.close()
• src/fastmcp/client/client.py:490 - Client.close() properly calls both disconnect and transport.close()
• src/fastmcp/client/transports.py:980 - MCPConfigTransport.close() cleans up underlying transports
• tests/test_mcp_config.py:295 - Failing test test_multi_client_lifespan