Skip to content

PERFORMANCE.md

Latest commit

 

History

History
21 lines (18 loc) · 2.58 KB

PERFORMANCE.md

File metadata and controls

21 lines (18 loc) · 2.58 KB

Performance Guide

Quick benchmarks

  • Capture a baseline with time bin/mcp-bash < sample.json (or the compatibility fixture in test/compatibility/) before making concurrency or timeout changes.
  • Run test/integration/test_capabilities.sh to exercise discovery, pagination, and registry notifications under load.
  • Use MCPBASH_DEBUG_PAYLOADS=true sparingly while debugging to avoid skewing timings with disk I/O.

Tuning levers

  • Static registry mode: Bundles use static registry mode by default for optimal cold start - no configuration needed. For non-bundle production deployments, set MCPBASH_STATIC_REGISTRY=1 to skip runtime discovery and load pre-generated .registry/*.json caches directly. This eliminates cold-start overhead from filesystem scans. To opt out of static mode in bundles, set MCPB_STATIC=false in mcpb.conf.
  • Concurrency: MCPBASH_MAX_CONCURRENT_REQUESTS (default 16) sets worker slots. Increase gradually and watch CPU steal/memory pressure; decrease on small hosts.
  • Timeouts: Set per-tool timeoutSecs in <tool>.meta.json; global default comes from MCPBASH_DEFAULT_TOOL_TIMEOUT (30s by default).
  • Registry scans: Adjust TTLs (MCP_TOOLS_TTL, MCP_RESOURCES_TTL, MCP_PROMPTS_TTL) and scope (MCPBASH_REGISTRY_REFRESH_PATH) to reduce filesystem churn on large trees.
  • Very large registries: If you have hundreds/thousands of tools/resources/prompts, prefer manual registration hooks over auto-discovery to avoid find/stat overhead across huge trees.
  • Resource polling: MCPBASH_RESOURCES_POLL_INTERVAL_SECS controls subscription polling (poller starts after the first resources/subscribe); use 0 to disable when live updates are unnecessary.
  • Progress streaming: MCPBASH_ENABLE_LIVE_PROGRESS=true streams progress/log updates mid-flight (starts a background flusher); tune MCPBASH_PROGRESS_FLUSH_INTERVAL (seconds) to balance responsiveness vs overhead.

Diagnostics

  • Enable MCPBASH_LOG_LEVEL=debug to log registry fast-path decisions, path resolution, and worker lifecycle events. Add MCPBASH_LOG_VERBOSE=true to include full paths in debug output (increases log volume; disable after troubleshooting).
  • Inspect .registry/*.json sizes and counts when pagination feels slow; large registries may warrant manual registration or narrower scan roots.
  • Use ps/top/htop to spot runaway tools; align timeoutSecs and watchdogs in lib/timeout.sh with observed runtimes.
  • On Windows/MSYS, prefer shorter TTLs and smaller payloads to offset filesystem overhead; watch for MSYS2_ARG_CONV_EXCL quirks in provider scripts.