feat: add configurable MCP timeout via environment variables

[PROJECT-OCULUS]

Summary

Adds configurable MCP server timeout support via environment variables, extending Cipher's existing timeout configuration pattern to server connection timeouts.

Background: Existing Environment Variable Pattern

Cipher already uses MCP timeout environment variables (defined in src/core/mcp/constants.ts):

• MCP_GLOBAL_TIMEOUT - Global timeout for all MCP operations
• MCP_TOOL_TIMEOUT - Tool execution timeout

This PR extends the existing pattern to server connection timeouts by:

• Using the established MCP_TIMEOUT variable (follows existing naming convention)
• Adding CIPHER_MCP_TIMEOUT for Cipher-specific granular control

Problem

The hardcoded 30-second server connection timeout in config.ts causes failures in one scenario:

1. Local Models (Ollama)

• Occasionally LLM operations fail when using local models via Ollama
• Mode of failure: timeout in config.ts (hardcoded 30s limit)
• Local models are generally reliable for MCP tools 95% of the time
• However, the remaining 5% of operations exceed the 30s timeout

Solution

Configurable server connection timeout via environment variables, following Cipher's existing pattern:

Priority Order:

1. CIPHER_MCP_TIMEOUT (Cipher-specific, highest priority)
2. MCP_TIMEOUT (generic MCP standard, aligns with existing env vars)
3. 30000ms (default, maintains backward compatibility)

Implementation:

• Adds getDefaultMcpTimeout() helper function to read env vars
• Applies to all MCP server connection schemas:
  • StdioServerConfigSchema
  • SseServerConfigSchema
  • StreamableHttpServerConfigSchema
• Validates parsed timeout values (must be positive integers)
• Updates schema descriptions to document configuration

Usage Examples

For local Ollama models with slower performance:

export CIPHER_MCP_TIMEOUT=90000  # 90 seconds

For complex operations or slower networks:

export MCP_TIMEOUT=180000  # 3 minutes

In .env file:

CIPHER_MCP_TIMEOUT=120000
MCP_TIMEOUT=90000

Testing

Comprehensive Vitest test suite (10 tests, all passing):

Environment Variable Tests:

• ✅ Default 30s timeout when no env vars set
• ✅ CIPHER_MCP_TIMEOUT environment variable respected
• ✅ MCP_TIMEOUT fallback works correctly
• ✅ Priority order: CIPHER_MCP_TIMEOUT > MCP_TIMEOUT > default
• ✅ Invalid values (negative, zero, non-numeric) fall back to default

Tool Execution Tests:

• ✅ Tools complete within configured timeout
• ✅ Timeout error thrown when limit exceeded
• ✅ Complex operations with longer timeouts succeed
• ✅ Clear timeout error messages
• ✅ Tools completing just before limit work correctly

Manual Testing:

• Tested with complex workloads requiring 40-60 second execution times
• Verified with local Ollama models
• Confirmed backward compatibility with default 30s timeout

Breaking Changes

None - Full backward compatibility maintained:

• Default timeout remains 30 seconds
• Existing configurations continue to work unchanged
• Optional environment variable configuration only for users who need it
• Follows established Cipher environment variable naming patterns

Files Changed

Modified (1 file):

• src/core/mcp/config.ts - Timeout configuration implementation (~30 lines)

Added (1 file):

• src/core/brain/tools/__test__/timeout-behavior.test.ts - Comprehensive test suite (10 tests, ~335 lines)

Total: 2 files changed, 362 insertions, 6 deletions

Alignment with Existing Codebase

This change:

• ✅ Follows existing MCP_*_TIMEOUT naming convention
• ✅ Extends established timeout configuration pattern
• ✅ Maintains consistency with MCP_GLOBAL_TIMEOUT and MCP_TOOL_TIMEOUT
• ✅ Uses Zod schema patterns already in config.ts
• ✅ Follows existing test structure and patterns