Устранение неполадок MCP [Работа в процессе]
⚠️ ВАЖНО : этот пакет в настоящее время находится в стадии разработки и еще не готов к использованию в производстве. Текущая версия находится в стадии разработки и может содержать неполные функции или критические изменения.
Самодиагностическая платформа для моделей ИИ, позволяющая им диагностировать и устранять проблемы, связанные с MCP.
Архитектура
Обзор
MCP Troubleshooter — это специализированный сервер MCP, который превращает устранение неполадок из задачи, доступной только разработчикам, в возможность, которую может использовать сам ИИ, позволяя моделям ИИ:
- Анализируйте журналы MCP — автоматически сканируйте на наличие распространенных ошибок и предоставляйте подробную диагностику.
- Проверка конфигураций — проверка конфигураций сервера на соответствие передовым практикам и выявление проблем.
- Тестовые соединения — проверка сетевого подключения и доступности сервера.
- Создание шаблонов — создание рабочих конфигураций сервера MCP для быстрой настройки.
- Устранение распространенных проблем — обновление конфигураций и непосредственное внедрение решений
Установка
# Install the package globally
npm install -g @devlimelabs/mcp-troubleshooter
# Start the server
mcp-troubleshooter
Использование
Конфигурация для Claude Desktop
Добавьте это в конфигурацию вашего Claude Desktop:
{
"mcpServers": {
"troubleshooter": {
"command": "mcp-troubleshooter"
}
}
}
Инструменты
Инструменты управления журналами
- read-mcp-logs : извлекает и отображает файлы журналов MCP
- analyze-mcp-logs : использует распознавание образов для определения распространенных сигнатур ошибок
Инструменты конфигурации
- read-mcp-config : извлекает и проверяет конфигурацию MCP Claude Desktop
- update-mcp-config : безопасное обновление конфигураций с использованием надлежащих механизмов резервного копирования
- validate-mcp-server-config : выполняет глубокую проверку конфигураций сервера
Инструменты для тестирования соединения
- test-port-availability : проверяет, доступны ли требуемые порты для серверов MCP
- check-mcp-server-process : проверяет правильность работы процессов сервера MCP
Инструменты для исправления реализации
- generate-mcp-server-template : создает настраиваемые шаблоны сервера для разных языков
- generate-claude-desktop-config : Создает оптимизированные файлы конфигурации для Claude Desktop
Ресурсы
- common-mcp-issues : подробное руководство по общим проблемам MCP и их решениям
- mcp-config-templates : Шаблоны конфигурации для различных настроек сервера MCP
Примеры использования
Диагностика неисправного сервера MCP
User: My MCP server isn't connecting properly to Claude Desktop. Can you help diagnose it?
Claude: I'll help diagnose your MCP server connection issue. First, let me run some diagnostics.
[Uses check-mcp-server-process tool with the command from the user]
I've identified several possible issues with your MCP server:
1. **Connection Timeout**: The server isn't responding within the expected timeframe.
2. **JSON-RPC Format Error**: There seems to be a format issue in the JSON-RPC responses.
3. **Transport Mismatch**: Claude Desktop is expecting stdio transport, but your server might be using SSE.
Let me run a more specific connection test to confirm:
[Uses test-port-availability tool]
The connection test confirms that your server is starting, but it's timing out during the handshake phase. This is likely due to incorrect JSON-RPC message formatting in your server implementation.
Recommended fixes:
1. Ensure your server returns properly formatted JSON-RPC 2.0 responses
2. Check your transport implementation, it should be using proper stdio pipes
3. Verify that your server is correctly handling the initialize method
Would you like me to analyze a specific log file or check your server's code for these issues?
Проверка конфигурации MCP
User: Can you validate my Claude Desktop MCP configuration?
Claude: I'd be happy to validate your Claude Desktop MCP configuration.
[Uses read-mcp-config tool]
I've analyzed your Claude Desktop configuration file. Here are my findings:
✅ **Valid Configuration Structure**: The overall structure of your configuration is valid.
⚠️ **Path Issues**: 2 servers have invalid paths:
- "code-llm": The file path "/usr/local/bin/code-llm" doesn't exist
- "database-tool": The command "db-tool" is not in the PATH
❌ **Environment Variables**: 1 server has missing required environment variables:
- "firebase-mcp": Missing required FIREBASE_API_KEY
✅ **Transport Configuration**: All servers properly specify transport options
Recommended fixes:
1. Update the path for "code-llm" to the correct location
2. Install "db-tool" or correct its path
3. Add the missing FIREBASE_API_KEY to the "firebase-mcp" server configuration
Would you like me to help you implement any of these fixes?
- Windows : доступ к журналам и конфигурациям в
%APPDATA%\Claude\ - macOS : доступ к журналам в
~/Library/Logs/Claude/ и конфигурациям в ~/Library/Application Support/Claude/ - Linux : доступ к журналам в
~/.local/share/Claude/logs/ и конфигурациям в ~/.config/Claude/
Разработка
# Clone the repository
git clone https://github.com/devlimelabs/master-mcps.git
cd master-mcps
# Install dependencies
pnpm install
# Build the package
pnpm -F @devlimelabs/mcp-troubleshooter build
# Run tests
pnpm -F @devlimelabs/mcp-troubleshooter test
Лицензия
Массачусетский технологический институт