{
  "markdown": "# MCP Debug\n\nA debugging and development tool for [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers.\n\n[![Go Version](https://img.shields.io/badge/Go-1.24+-blue.svg)](https://golang.org/)\n[![MCP Spec](https://img.shields.io/badge/MCP-2025--06--18-green.svg)](https://modelcontextprotocol.io/specification/2025-06-18)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![PyPI](https://img.shields.io/pypi/v/mcp-debug.svg)](https://pypi.org/project/mcp-debug/)\n[![npm](https://img.shields.io/npm/v/mcp-debug.svg)](https://www.npmjs.com/package/mcp-debug)\n\nMCP Debug enables rapid development and testing of MCP servers with hot-swapping, session recording, and automated playback testing.\n\n## Features\n\n### Hot-Swap Development\n- Replace server binaries without disconnecting MCP clients\n- Add/remove servers dynamically during development\n- Tool name preservation - same interface, new implementation\n- Graceful disconnect/reconnect workflow for binary replacement\n\n### Session Recording & Playback\n- Record JSON-RPC traffic for debugging and documentation\n- Playback client mode - replay requests to test servers\n- Playback server mode - replay responses to test clients\n- Regression testing with recorded sessions\n\n### Development Proxy\n- Multi-server aggregation with tool prefixing\n- Real-time connection monitoring\n- Management API for server lifecycle control\n- Comprehensive logging\n\n## Installation\n\n```bash\n# Using uvx (Python - recommended)\nuvx mcp-debug --help\n\n# Using npx (Node.js)\nnpx @standardbeagle/mcp-debug --help\n\n# Or install globally\npip install mcp-debug              # Python\nnpm install -g @standardbeagle/mcp-debug  # Node.js\n\n# Or build from source\ngo install github.com/standardbeagle/mcp-debug@latest\n```\n\n## Quick Start\n\n```bash\n# Start proxy with a config file\nuvx mcp-debug --proxy --config config.yaml\n\n# Or with mcp-tui for interactive testing\nmcp-tui uvx mcp-debug --proxy --config config.yaml\n```\n\n## Usage\n\n### Proxy Mode\n\n```bash\n# Basic proxy\nuvx mcp-debug --proxy --config config.yaml\n\n# With recording\nuvx mcp-debug --proxy --config config.yaml --record session.jsonl\n\n# With custom log file\nuvx mcp-debug --proxy --config config.yaml --log /tmp/debug.log\n```\n\n**Management Tools:**\n- `server_add` - Add a server: `{name: \"fs\", command: \"npx -y @mcp/filesystem /path\"}`\n- `server_remove` - Remove server completely\n- `server_disconnect` - Disconnect server (tools return errors)\n- `server_reconnect` - Reconnect with new command\n- `server_list` - Show all servers and status\n\n### Playback Modes\n\n```bash\n# Replay recorded requests to test a server\nuvx mcp-debug --playback-client session.jsonl | ./your-mcp-server\n\n# Replay recorded responses to test a client\nmcp-tui uvx mcp-debug --playback-server session.jsonl\n```\n\n## Configuration\n\n```yaml\n# config.yaml\nservers:\n  - name: \"filesystem\"\n    prefix: \"fs\"\n    transport: \"stdio\"\n    command: \"npx\"\n    args: [\"-y\", \"@modelcontextprotocol/filesystem\", \"/home/user\"]\n    timeout: \"30s\"\n\nproxy:\n  healthCheckInterval: \"30s\"\n  connectionTimeout: \"10s\"\n  maxRetries: 3\n```\n\n### Environment Variables\n\n```bash\nMCP_LOG_FILE=\"/tmp/mcp-debug.log\"  # Log location\nMCP_DEBUG=1                         # Enable debug logging\nMCP_RECORD_FILE=\"session.jsonl\"     # Auto-record sessions\nMCP_CONFIG_PATH=\"./config.yaml\"     # Default config\n```\n\n## Development Workflow\n\n```bash\n# 1. Start with empty config\nmcp-tui uvx mcp-debug --proxy --config empty-config.yaml\n\n# 2. Add your server dynamically\nserver_add: {name: myserver, command: ./my-server-v1}\n\n# 3. Test tools: myserver_read_file, myserver_process, etc.\n\n# 4. Make changes and rebuild\ngo build -o my-server-v2\n\n# 5. Hot-swap the server\nserver_disconnect: {name: myserver}\nserver_reconnect: {name: myserver, command: ./my-server-v2}\n\n# 6. Same tools work immediately with new implementation!\n```\n\n## CLI Commands\n\n```bash\nuvx mcp-debug --help              # Show help\nuvx mcp-debug --version           # Show version\nuvx mcp-debug config init         # Create default config\nuvx mcp-debug config show         # Show current config\nuvx mcp-debug config validate     # Validate config file\nuvx mcp-debug env list            # List environment variables\nuvx mcp-debug env check           # Check required env vars\nuvx mcp-debug tools list          # List tools with details\n```\n\n## Project Structure\n\n```\nmcp-debug/\n├── main.go              # CLI entry point\n├── config/              # Configuration loading\n├── client/              # MCP client implementation\n├── integration/         # Proxy server and wrapper\n├── discovery/           # Tool discovery\n├── proxy/               # Request forwarding\n├── playback/            # Recording and playback\n└── test-servers/        # Example MCP servers\n```\n\n## Building\n\n```bash\n# Development build\ngo build -o mcp-debug .\n\n# Production build with version info\ngo build -ldflags \"-X main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ) -X main.GitCommit=$(git rev-parse HEAD)\" -o mcp-debug .\n\n# Run tests\ngo test ./...\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n",
  "bytes": 5180,
  "sha": "2a7398483e26c1ea91b1764a6756807fcab052d8dbd177c2abbbd62f209ef1e7",
  "repo_slug": "standardbeagle/mcp-debug",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_standardbeagle_mcp_debug_2b85de54/readme"
}