feat(reconnection): add slow probe mode after max attempts

[Milofax]

Summary

• After max reconnection attempts are reached, the proxy now enters "slow probe mode" instead of giving up
• Periodically attempts to reconnect every 60 seconds (circuit breaker pattern best practice)
• Proper cleanup on shutdown and on successful reconnection
• Fixed: Transport cache is cleared before each reconnect attempt to ensure fresh transport creation

Motivation

When actively developing local MCP servers (e.g., custom integrations, Docker-based services), frequent restarts are common during development. Currently, when a backend MCP server restarts, mcp-funnel reaches max reconnection attempts and gives up completely - requiring users to restart their entire Claude Code / mcp-funnel session just to reconnect.

This is especially frustrating when:

• Developing and testing MCP servers locally
• Running MCP servers in Docker containers that restart on code changes
• Managing multiple MCP servers where one might temporarily be down

Problem

When a backend MCP server restarts (e.g., Docker container restart), the proxy eventually reaches max reconnection attempts and gives up completely. Users then need to restart the entire mcp-funnel process to reconnect.

Solution

Implements the "slow probe" phase of the circuit breaker pattern:

1. After exponential backoff exhausts max attempts, enter slow probe mode
2. Attempt reconnection every 60 seconds
3. Clear transport cache before each attempt (critical fix - closed transports were being reused)
4. On success, stop probing and resume normal operation
5. Emit events for monitoring (server.slow_probe_started, recovery logs)

This follows industry best practices (AWS, Microsoft) for resilient service connections - never give up entirely, just back off to a slower probe interval.

Changes

server-connection-manager.ts:

• Add slowProbeTimers Map and SLOW_PROBE_INTERVAL_MS constant (60s)
• Add startSlowProbeMode() and stopSlowProbeMode() private methods
• Modify onMaxAttemptsReached callback to call startSlowProbeMode instead of just deleting the manager
• Update shutdown() to clean up slow probe timers
• Update connectToSingleServer() to stop slow probe mode on successful connection
• Call clearTransportCache() before each reconnection attempt

transport-cache.ts:

• Add removeCachedTransport() helper function
• Add invalidateCachedTransport() helper function

transport/index.ts:

• Export new cache management functions

Test plan

• Unit tests for slow probe mode start/stop (9 tests passing)
• E2E test: Graphiti Docker container restart → automatic recovery via slow probe ✅

🤖 Generated with Claude Code

[Milofax]

Additional Fix: Singleton Enforcement (Commit 74049f3)

Added PID-file based singleton pattern to prevent zombie processes.

Problem

Claude Code starts new MCP-Funnel processes per session but doesn't always send clean shutdown signals. This leads to zombie processes accumulating (observed: 10+ processes, ~1.2GB RAM).

Solution

• Check ~/.mcp-funnel.pid on startup
• Kill stale process if still running
• Write current PID to file
• Clean up on shutdown

Background

This is a known MCP ecosystem issue: typescript-sdk#208

The VS Code/LSP approach passes host PID for periodic liveness checks. Since Claude Code doesn't support this, PID-file singleton is a practical workaround.

[chris-schra]

thanks! Sorry, was totally busy - still interested in merging this?

[Milofax]

Yes, absolutely still interested! Ready to merge whenever you are. Let me know if you need any changes.