🤖 Клод Код MCP Сервер

Хотите быстро начать? Ознакомьтесь с нашим руководством QUICKSTART.md !

Этот проект представляет собой ответвление steipete/claude-code-mcp с расширенными возможностями оркестровки, улучшениями надежности и дополнительной документацией.

Расширенный сервер Model Context Protocol (MCP), позволяющий запускать Claude Code в режиме одноразового запуска с автоматическим обходом разрешений. Этот сервер включает расширенные возможности оркестровки задач, надежную обработку ошибок и «шаблон бумеранга» для разбиения сложных задач на управляемые подзадачи.

Вы заметили, что стандартные помощники ИИ иногда испытывают трудности со сложными, многошаговыми правками или операциями? Этот сервер с его мощным унифицированным инструментом claude_code и улучшенными функциями надежности призван сделать Claude более прямым и способным агентом для ваших задач кодирования.

🔍 Обзор

Этот сервер MCP предоставляет мощные инструменты, которые могут использоваться LLM для взаимодействия с Claude Code. При интеграции с Claude Desktop или другими клиентами MCP он позволяет LLM:

• Запустить Claude Code с обходом всех разрешений (используя --dangerously-skip-permissions )

• Выполнять код Клода с любой подсказкой без прерываний на разрешение

• Прямой доступ к возможностям редактирования файлов

• Выполнение сложных многошаговых операций с надежной обработкой ошибок и повторными попытками

• Организуйте задачи с помощью специализированных ролей агентов, используя модель «бумеранга»

• Поддерживайте надежное выполнение с помощью механизмов пульсации для предотвращения тайм-аутов

Related MCP server: Scenario Word

✨ Преимущества

• Повышенная надежность: надежная обработка ошибок, автоматические повторные попытки, плавное завершение работы и отслеживание запросов.

• Оркестровка задач: сложные рабочие процессы можно разбить на специализированные подзадачи.

• Автоматизация задач: автоматическое преобразование понятных человеку списков задач Markdown в исполняемые команды MCP.

• Оптимизация производительности: улучшенное выполнение с кэшированием конфигурации и эффективностью использования ресурсов

• Лучший мониторинг: API проверки работоспособности, подробные отчеты об ошибках и комплексное ведение журнала

• Опыт разработчика: горячая перезагрузка конфигурации, гибкое управление средой и упрощенный API

Плюс все стандартные преимущества Claude Code:

• У Claude/Windsurf часто возникают проблемы с редактированием файлов. У Claude Code это получается лучше и быстрее.

• Несколько команд могут быть поставлены в очередь вместо прямого выполнения. Это экономит контекстное пространство, поэтому более важная информация сохраняется дольше.

• Файловые операции, git или другие операции не требуют дорогостоящих моделей. Claude Code экономически эффективен, если вы зарегистрируетесь в Anthropic Max.

• У Клода более широкий доступ к системе, поэтому, когда стандартные помощники застревают, просто попросите их «использовать код Клода», чтобы разблокировать прогресс.

📝 Предварительные условия

• Node.js v20 или более поздней версии (используйте fnm или nvm для установки)

• Claude CLI установлен локально (запустите его и вызовите /doctor) и -dangerously-skip-permissions принят.

💾 Установка и использование

Вы можете установить и использовать этот MCP-сервер тремя различными способами:

🚀 Метод 1: через URL-адрес GitHub (рекомендуется)

Самый гибкий метод — установка напрямую из GitHub с помощью npx . Это всегда извлекает последнюю версию из репозитория.

Добавьте в файл .mcp.json следующее:

{
  "mcpServers": {
    "claude-code-mcp-enhanced": {
      "command": "npx",
      "args": [
        "github:grahama1970/claude-code-mcp-enhanced"
      ],
      "env": {
        "MCP_CLAUDE_DEBUG": "false",
        "MCP_HEARTBEAT_INTERVAL_MS": "15000",
        "MCP_EXECUTION_TIMEOUT_MS": "1800000"
      }
    }
  }
}

📦 Метод 2: Через пакет npm

Если пакет опубликован в npm, вы можете установить его, используя имя пакета npm:

{
  "mcpServers": {
    "claude-code-mcp-enhanced": {
      "command": "npx",
      "args": [
        "-y",
        "@grahama1970/claude-code-mcp-enhanced@latest"
      ],
      "env": {
        "MCP_CLAUDE_DEBUG": "false",
        "MCP_HEARTBEAT_INTERVAL_MS": "15000",
        "MCP_EXECUTION_TIMEOUT_MS": "1800000"
      }
    }
  }
}

🔧 Метод 3: Локальная установка

В целях разработки или тестирования вы можете запустить сервер из локальной установки:

1. Клонируйте репозиторий:

   git clone https://github.com/grahama1970/claude-code-mcp-enhanced.git
   cd claude-code-mcp-enhanced

2. Установка зависимостей и сборка:

   npm install
   npm run build

3. Настройте файл .mcp.json для использования локального сервера:

{
  "mcpServers": {
    "claude-code-mcp-enhanced": {
      "command": "node",
      "args": [
        "/path/to/claude-code-mcp-enhanced/dist/server.js"
      ],
      "env": {
        "MCP_CLAUDE_DEBUG": "false",
        "MCP_HEARTBEAT_INTERVAL_MS": "15000",
        "MCP_EXECUTION_TIMEOUT_MS": "1800000"
      }
    }
  }
}

🔑 Важная первоначальная настройка: принятие разрешений

Прежде чем сервер MCP сможет успешно использовать инструмент claude_code , необходимо сначала вручную запустить CLI Claude один раз с флагом --dangerously-skip-permissions , войти в систему и принять условия.

Это единовременное требование Claude CLI.

npm install -g @anthropic-ai/claude-code

claude --dangerously-skip-permissions

Следуйте подсказкам, чтобы принять. После этого сервер MCP сможет использовать флаг неинтерактивно.

При первом запуске инструмента macOS может запросить различные разрешения для папок, и первый запуск может завершиться неудачей. Последующие запуски будут работать нормально.

🔗 Подключение к вашему MCP-клиенту

После настройки сервера вам необходимо настроить ваш клиент MCP (например, Cursor, Claude Desktop или другие, использующие mcp.json или mcp_config.json ).

Пример файла конфигурации MCP

Вот пример того, как добавить сервер Claude Code MCP в ваш файл .mcp.json :

{
  "mcpServers": {
    "Local MCP Server": {
      "type": "stdio",
      "command": "node",
      "args": [
        "dist/server.js"
      ],
      "env": {
        "MCP_USE_ROOMODES": "true",
        "MCP_WATCH_ROOMODES": "true",
        "MCP_CLAUDE_DEBUG": "false"
      }
    },
    "other-services": {
      // Your other MCP services here
    }
  }
}

Места конфигурации MCP

Конфигурация обычно выполняется в файле JSON. Имя и местоположение могут различаться в зависимости от вашего клиента.

Курсор

Курсор использует mcp.json .

• macOS: ~/.cursor/mcp.json

• Windows: %APPDATA%\\Cursor\\mcp.json

• Linux: ~/.config/cursor/mcp.json

Виндсерфинг

Пользователи Windsurf используют mcp_config.json

• macOS: ~/.codeium/windsurf/mcp_config.json

• Windows: %APPDATA%\\Codeium\\windsurf\\mcp_config.json

• Linux: ~/.config/.codeium/windsurf/mcp_config.json

(Примечание: в некоторых смешанных установках, если также установлен Cursor, эти клиенты могут вернуться к использованию пути Cursor ~/.cursor/mcp.json . Отдайте приоритет специфичным для Codeium путям, если используете расширение Codeium.)

Создайте этот файл, если его нет.

🛠️ Предоставляемые инструменты

Этот сервер предоставляет три основных инструмента:

claude_code 💬

Выполняет запрос напрямую с помощью Claude Code CLI с --dangerously-skip-permissions .

Аргументы:

• prompt (строка, обязательно): Подсказка для отправки Клоду Коду.

• workFolder (строка, необязательно): рабочий каталог для выполнения Claude CLI, необходимый при использовании файловых операций или при обращении к любому файлу.

• parentTaskId (строка, необязательно): идентификатор родительской задачи, создавшей данную задачу (для оркестровки задач/бумеранга).

• returnMode (string, необязательно): Как должны возвращаться результаты: «summary» (краткий) или «full» (подробный). По умолчанию «full».

• taskDescription (строка, необязательно): Краткое описание задачи для лучшей организации и отслеживания в организованных рабочих процессах.

• mode (строка, необязательно): если MCP_USE_ROOMODES=true, указывает режим Roo для использования (например, «boomerang-mode», «coder», «designer» и т. д.).

health 🩺

Возвращает состояние работоспособности, информацию о версии и текущую конфигурацию сервера Claude Code MCP.

Пример запроса на проверку работоспособности:

{
  "toolName": "claude_code:health",
  "arguments": {}
}

Пример ответа:

{
  "status": "ok",
  "version": "1.12.0",
  "claudeCli": {
    "path": "claude",
    "status": "available"
  },
  "config": {
    "debugMode": true,
    "heartbeatIntervalMs": 15000,
    "executionTimeoutMs": 1800000,
    "useRooModes": true,
    "maxRetries": 3,
    "retryDelayMs": 1000
  },
  "system": {
    "platform": "linux",
    "release": "6.8.0-57-generic",
    "arch": "x64",
    "cpus": 16,
    "memory": {
      "total": "32097MB",
      "free": "12501MB"
    },
    "uptime": "240 minutes"
  },
  "timestamp": "2025-05-15T18:30:00.000Z"
}

convert_task_markdown 📋

Конвертирует файлы задач markdown в формат JSON, совместимый с Claude Code MCP.

Аргументы:

• markdownPath (строка, обязательно): путь к файлу задачи разметки для преобразования.

• outputPath (строка, необязательно): Путь, куда сохранить вывод JSON. Если не указано, возвращает JSON напрямую.

Пример запроса:

{
  "toolName": "claude_code:convert_task_markdown",
  "arguments": {
    "markdownPath": "/home/user/tasks/validation.md",
    "outputPath": "/home/user/tasks/validation.json"
  }
}

Примеры сценариев использования

1. Базовая операция кода

Пример запроса MCP:

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nRefactor the function foo in main.py to be async.",
    "workFolder": "/path/to/project"
  }
}

2. Оркестровка задач (шаблон «Бумеранг»)

Запрос родительской задачи:

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nOrchestrate the implementation of a new API endpoint with the following subtasks:\n1. Create database models\n2. Implement API route handlers\n3. Write unit tests\n4. Document the API",
    "workFolder": "/path/to/project"
  }
}

Запрос подзадачи (создан родителем):

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nCreate database models for the new API endpoint as specified in the requirements.",
    "workFolder": "/path/to/project",
    "parentTaskId": "task-123",
    "returnMode": "summary",
    "taskDescription": "Database model creation for API endpoint"
  }
}

3. Запрос специализированного режима

Пример использования режима Roo:

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nCreate unit tests for the user authentication module.",
    "workFolder": "/path/to/project",
    "mode": "coder"
  }
}

🔄 Конвертер задач

Сервер MCP включает мощный инструмент-конвертер задач, который автоматически преобразует понятные человеку списки задач Markdown в полностью исполняемые команды MCP. Этот интеллектуальный конвертер устраняет разрыв между тем, как люди думают о задачах, и тем, как машины их выполняют.

Полный рабочий процесс

graph TD
    A["👤 User"] -->|"Create tasks.md"| B["📝 Multi-Task Markdown"]
    A -->|"Prompt Claude"| C["🤖 Claude Desktop"]
    C -->|"Use convert_task_markdown"| D["🔄 Task Converter MCP"]
    D -->|"Validate Format"| E{"Format Valid?"}
    E -->|"No"| F["📑 Error + Fix Instructions"]
    F -->|"Return to User"| A
    E -->|"Yes"| G["📋 MCP Task List"]
    G -->|"Execute Task"| H1["⚡ Claude Task #1"]
    H1 -->|"Complete"| I1["Next Task"]
    I1 -->|"Execute Task"| H2["⚡ Claude Task #2"]
    H2 -->|"Complete"| I2["Next Task"]
    I2 -->|"Execute Task"| H3["⚡ Claude Task #3"]
    H3 -->|"Complete"| I3["More Tasks"]
    I3 -->|"Execute Task"| HN["⚡ Claude Task #N"]
    HN -->|"Complete"| IN["🎉 All Tasks Completed!"]
    
    style A fill:#4A90E2,stroke:#fff,stroke-width:2px,color:#fff
    style C fill:#7C4DFF,stroke:#fff,stroke-width:2px,color:#fff
    style D fill:#00BCD4,stroke:#fff,stroke-width:2px,color:#fff
    style F fill:#FF5252,stroke:#fff,stroke-width:2px,color:#fff
    style G fill:#4CAF50,stroke:#fff,stroke-width:2px,color:#fff
    style H1 fill:#FFC107,stroke:#fff,stroke-width:2px,color:#fff
    style H2 fill:#FFC107,stroke:#fff,stroke-width:2px,color:#fff
    style H3 fill:#FFC107,stroke:#fff,stroke-width:2px,color:#fff
    style HN fill:#FFC107,stroke:#fff,stroke-width:2px,color:#fff
    style IN fill:#4CAF50,stroke:#fff,stroke-width:2px,color:#fff

Этапы рабочего процесса

1. Пользователь добавляет MCP в свой файл конфигурации

2. Пользователь подсказывает Клоду : «Используйте convert_task_markdown для выполнения моего файла tasks.md»

3. MCP автоматически :

   • Загружает файл разметки

   • Проверяет формат (возвращает ошибки, если разделы отсутствуют)

   • Преобразует понятные человеку задачи в точные исполняемые команды

   • Возвращает JSON, который Клод Код может выполнить последовательно

4. Клод получает JSON и может выполнить каждую задачу с помощью инструмента claude_code

Основные характеристики

• Автоматическое разрешение путей: преобразует общие инструкции, такие как «изменить каталог для проекта», в точные исполняемые команды с полными путями.

• Интеллектуальный перевод команд: преобразует инструкции на английском языке в точные команды терминала (например, «активировать виртуальную среду» → source .venv/bin/activate )

• Соответствие протоколу MCP: гарантирует, что все выходные данные на 100% совместимы с протоколом контекста модели.

• Никакой двусмысленности: все сгенерированные команды используют точные пути и исполняемый синтаксис — никаких заполнителей или общих ссылок.

• Проверка формата: обеспечивает правильную структуру разметки и выдает полезные сообщения об ошибках в случае неправильного форматирования.

• Обновления хода выполнения в режиме реального времени: предоставляет обновления хода выполнения в режиме реального времени во время преобразования, показывая, какие задачи обрабатываются.

Преобразование задач Markdown в команды MCP

Инструмент convert_task_markdown обрабатывает структурированные файлы разметки и генерирует совместимый с MCP JSON:

Формат запроса:

{
  "tool": "convert_task_markdown",
  "arguments": {
    "markdownPath": "/path/to/tasks.md",
    "outputPath": "/path/to/output.json" // optional
  }
}

Формат ответа:

{
  "tasksCount": 5,
  "outputPath": "/path/to/output.json",
  "tasks": [
    {
      "tool": "claude_code",
      "arguments": {
        "command": "cd /project && source .venv/bin/activate\n\nTASK TYPE: Validation...",
        "dangerously_skip_permissions": true,
        "timeout_ms": 300000
      }
    }
    // ... more tasks
  ]
}

Формат файла задачи Markdown

Файлы разметки задач должны иметь следующую структуру:

# Task 001: Task Title

## Objective
Clear description of what needs to be accomplished.

## Requirements
1. [ ] First requirement
2. [ ] Second requirement

## Tasks

### Module or Component Name
- [ ] Validate `path/to/file.py`
   - [ ] Step 1
   - [ ] Step 2
   - [ ] Step 3

Преобразователь будет:

1. Разбор структуры разметки

2. Извлечение метаданных и требований задачи

3. Создавайте подробные подсказки для каждой задачи проверки

4. Включите правильную настройку рабочего каталога

5. Добавить сводки проверки и завершения

Пример использования

1. Создайте файл задачи ( tasks/api_validation.md ):

# Task 001: API Endpoint Validation

## Objective
Validate all API endpoints work with real database connections.

## Requirements
1. [ ] All endpoints must use real database
2. [ ] No mock data in validation

## Core API Tasks
- [ ] Validate `api/users.py`
   - [ ] Change directory to project and activate .venv
   - [ ] Test user creation endpoint
   - [ ] Test user retrieval endpoint
   - [ ] Verify JSON responses

2. Преобразовать в задачи MCP :

{
  "tool": "convert_task_markdown",
  "arguments": {
    "markdownPath": "/project/tasks/api_validation.md"
  }
}

3. Конвертер показывает прогресс в реальном времени :

   [Progress] Loading task file...
   [Progress] Validating markdown structure...
   [Progress] Converting 27 validation tasks...
   [Progress] Task 1/27: Converting core/constants.py
   [Progress] Task 2/27: Converting core/arango_setup.py
   ...
   [Progress] Conversion complete!

4. Преобразователь преобразует общие инструкции в точные команды :

   • «Изменить каталог для проекта и активировать .venv» становится:

     cd /home/user/project && source .venv/bin/activate

   • Все пути преобразуются в абсолютные пути.

   • Все команды полностью выполнимы и не допускают двусмысленности.

5. Выполнение преобразованных задач : возвращенные задачи содержат точные исполняемые команды и могут быть выполнены последовательно с помощью инструмента claude_code .

Полный пример: от уценки до исполнения

Шаг 1: Пользователь создает файл задачи разметки ( project_tasks.md ):

# Task 001: Setup Development Environment

## Objective
Initialize the development environment with all dependencies.

## Requirements
1. [ ] Python 3.11+ installed
2. [ ] Virtual environment created

## Tasks
- [ ] Validate `setup.py`
   - [ ] Change to project directory
   - [ ] Create virtual environment
   - [ ] Install dependencies

Шаг 2: Пользователь подсказывает Клоду :

Use convert_task_markdown to process /home/user/project_tasks.md

Шаг 3: MCP преобразует и проверяет :

• Если формат правильный: возвращает исполняемый JSON

• Если формат неверный: возвращает ошибку с инструкциями

Шаг 4: Результат (в случае успеха) :

[
  {
    "tool": "claude_code",
    "arguments": {
      "prompt": "cd /home/user/project && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt",
      "workFolder": "/home/user/project"
    }
  }
]

Шаг 5: Клод может выполнять каждую задачу последовательно.

Проверка формата и обработка ошибок

Конвертер задач применяет определенную структуру разметки, чтобы обеспечить согласованное и надежное преобразование задач. Если ваш файл разметки неправильно отформатирован, конвертер выдает полезные сообщения об ошибках:

Пример ответа об ошибке:

{
  "status": "error",
  "error": "Markdown format validation failed",
  "details": "Markdown format validation failed:\n  - Missing required title. Format: '# Task NNN: Title'\n  - Missing or empty 'Requirements' section. Format: '## Requirements\\n1. [ ] Requirement'\n  - No validation tasks found. Format: '- [ ] Validate `module.py`' with indented steps\n\nRequired markdown format:\n# Task NNN: Title\n## Objective\nClear description\n## Requirements\n1. [ ] First requirement\n## Task Section\n- [ ] Validate `file.py`\n   - [ ] Step 1\n   - [ ] Step 2",
  "helpUrl": "https://github.com/grahama1970/claude-code-mcp-enhanced/blob/main/README.md#markdown-task-file-format"
}

Валидация гарантирует:

1. Присутствуют обязательные разделы (Название, Цель, Требования)

2. Задачи используют правильный формат флажков

3. Каждая задача имеет отступы шагов

4. Требования используют формат флажков для обеспечения согласованности

🦚 Шаблоны оркестровки задач

Этот сервер MCP поддерживает мощные возможности оркестровки задач для эффективной обработки сложных рабочих процессов.

Узор бумеранга (Claude Desktop ⟷ Claude Code)

Шаблон Boomerang позволяет Claude Desktop организовывать задачи и делегировать их Claude Code. Это позволяет вам:

1. Разбейте сложные рабочие процессы на более мелкие, управляемые подзадачи

2. Передача контекста из родительских задач в подзадачи

3. Получите результаты обратно из подзадач в родительскую задачу

4. Выбирайте между подробными или обобщенными результатами

5. Отслеживайте и управляйте прогрессом с помощью структурированных списков задач

Визуализация модели бумеранга

Вот простая схема, показывающая, как Клод разбивает задачу рецепта на шаги и делегирует их Клоду Коду:

graph TB
    User("👨‍🍳 User")
    Claude("🤖 Claude (Parent)")
    Code1("🧁 Claude Code")
    Code2("🧁 Claude Code")
    
    User-->|"Make chocolate cake"| Claude
    Claude-->|"Task 1: Find recipe"| Code1
    Code1-->|"Result: Recipe found"| Claude
    Claude-->|"Task 2: Convert measurements"| Code2
    Code2-->|"Result: Measurements converted"| Claude
    Claude-->|"Complete recipe + instructions"| User

В этом примере:

1. Пользователь просит Клода приготовить рецепт шоколадного торта.

2. Клод (родитель) разбивает это на отдельные задачи

3. Клод делегирует задачу «Найти рецепт» Клоду Коду с идентификатором родительской задачи

4. Клод Код возвращает Клоду информацию о рецепте

5. Клод делегирует задачу «Преобразовать измерения» Клоду Коду

6. Клод Код возвращает преобразованные измерения

7. Клод объединяет все результаты и представляет пользователю полное решение.

Примеры простых задач:

Задание 1 — Найти рецепт:

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Search for a classic chocolate cake recipe. Find one with good reviews.",
    "parentTaskId": "cake-recipe-123",
    "returnMode": "summary",
    "taskDescription": "Find Chocolate Cake Recipe"
  }
}

Задача 2 — Преобразование измерений:

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Convert the measurements in this recipe from cups to grams:\n\n- 2 cups flour\n- 1.5 cups sugar\n- 3/4 cup cocoa powder",
    "parentTaskId": "cake-recipe-123",
    "returnMode": "summary",
    "taskDescription": "Convert Recipe Measurements"
  }
}

Как это работает

1. Создание подзадачи:

   • Создайте уникальный идентификатор задачи в родительской задаче.

   • Отправьте запрос инструменту claude_code с:

     • Ваш конкретный запрос

     • Идентификатор родительской задачи

     • Описание задачи

     • Желаемый режим возврата («краткий» или «полный»)

2. Получение результатов:

   • Результат подзадачи будет включать специальный маркер: <!-- BOOMERANG_RESULT {...} -->

   • Этот маркер содержит JSON с метаданными задачи.

   • Родительская задача может проанализировать это, чтобы определить завершенные подзадачи.

3. Пример рабочего процесса с Claude Desktop:

You: I need to refactor this codebase. It's quite complex.

Claude Desktop: I'll help you with that. Let me break this down into smaller tasks for Claude Code to handle:

1. First, I'll have Claude Code analyze the codebase structure
2. Then, I'll have it identify problematic patterns
3. Finally, I'll ask it to generate a refactoring plan

[Claude Desktop sends a request to the claude_code tool with parentTaskId="task1" and returnMode="summary"]

[Claude Code analyzes the codebase and returns a summary with the BOOMERANG_RESULT marker]

Claude Desktop: Based on Claude Code's analysis, here are the key issues found:
- Duplicate code in modules X and Y
- Poor separation of concerns in module Z
- Inconsistent naming conventions

Now I'll ask Claude Code to suggest specific refactorings...

Такой подход особенно полезен для сложных задач, требующих глубокого анализа или многоэтапного выполнения.

Пример комплексного управления списком задач

Вот подробный пример использования Claude с Claude Code MCP для управления и выполнения структурированного списка задач:

1. Настройка структуры списка задач

Сначала создайте файл списка задач (например, tasks.md ) со следующей структурой:

# Project Task List

## Parent Task: API Optimization Project
- [ ] Optimize API performance for high-traffic endpoints
  - [ ] Analyze current API performance and identify bottlenecks
  - [ ] Implement database query optimization for user endpoints
  - [ ] Add Redis caching for frequently accessed data
  - [ ] Set up performance monitoring

## Assumptions and Decisions
- [2025-05-15] Assumption: Redis is available in the infrastructure
- [2025-05-15] Decision: Focus on user endpoints first (Rationale: Highest traffic area)

## Relevant Files
- `src/controllers/userController.js`: User API endpoints
- `src/services/userService.js`: Business logic for user operations

## Improvement Notes
- Pattern identified: N+1 query issue in user listing endpoint
- Automation opportunity: Add caching automatically for all get-by-id endpoints

2. Выполнение списка задач

Теперь Клод может систематически выполнять задания, используя Claude Code:

You: Please help me execute the task list in tasks.md, starting with the first subtask.

Claude: I'll help you work through your task list systematically. Let me first check the current task list to identify the next task to work on.

[Claude uses claude_code to read the task list]

I see the first subtask is "Analyze current API performance and identify bottlenecks". I'll execute this task now using Claude Code.

[Claude sends the following request to claude_code]:

{
  "toolName": "claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nTASK TYPE: Analysis\nTASK ID: api-perf-analysis\nCURRENT SUBTASK: Analyze current API performance and identify bottlenecks\n\nCONTEXT:\n- Parent task goal: Optimize API performance for high-traffic endpoints\n- This is the first step in our optimization process\n- Focus on user endpoints as noted in assumptions\n\nINSTRUCTIONS:\n1. Analyze the current API implementation in src/controllers/userController.js and src/services/userService.js\n2. Run performance tests on the user endpoints\n3. Identify specific bottlenecks and performance issues\n4. Document findings in a clear, structured format\n5. Update task list file after completion\n\nAfter completion, provide summary in this format:\n\nCOMPLETION SUMMARY:\n- What was done:\n- Results:\n- Files analyzed:\n- Issues identified:\n- Recommendations:\n- Next subtask in list:",
    "workFolder": "/path/to/project"
  }
}

[Claude Code executes the analysis task and returns results]

Great! Claude Code has completed the analysis. Here's what was found:

1. Main performance bottlenecks identified:
   - N+1 query problem in the user listing endpoint
   - Missing indexes on frequently queried fields
   - No caching for repetitive data lookups

2. Recommendations:
   - Add eager loading for user relationships
   - Create database indexes for user_id and email fields
   - Implement Redis caching with a 5-minute TTL

Let me update the task list to mark this task as complete and proceed to the next one.

[Claude uses claude_code to update the task list]:

{
  "toolName": "claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nTASK TYPE: Task List Update\n\n1. Read the current task list in tasks.md\n2. Mark the 'Analyze current API performance and identify bottlenecks' subtask as [x]\n3. Add new findings to the Improvement Notes section\n4. Add any new relevant files identified during analysis\n5. Write updated task list\n6. Return the updated task list",
    "workFolder": "/path/to/project"
  }
}

[Claude Code updates the task list and marks the first subtask complete]

I've updated the task list. The first subtask is now complete, and I've added the detailed findings to the Improvement Notes section. The next subtask is "Implement database query optimization for user endpoints".

Would you like me to proceed with this next subtask now?

3. Продолжение последующих задач

Получив подтверждение, Клод перешел к следующей подзадаче:

You: Yes, please proceed with the next subtask.

Claude: I'll now execute the next subtask: "Implement database query optimization for user endpoints". This will involve fixing the N+1 query problem identified in the analysis and adding appropriate database indexes.

[Claude sends the following request to claude_code]:

{
  "toolName": "claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nTASK TYPE: Code Implementation\nTASK ID: db-query-optimization\nCURRENT SUBTASK: Implement database query optimization for user endpoints\n\nCONTEXT:\n- Parent task goal: Optimize API performance for high-traffic endpoints\n- Previous subtask identified N+1 query issues and missing indexes\n- Need to implement eager loading and proper indexes\n\nINSTRUCTIONS:\n1. Modify src/controllers/userController.js to implement eager loading for related data\n2. Add appropriate database indexes to user-related tables\n3. Refactor any inefficient database queries in userService.js\n4. Ensure changes maintain existing functionality\n5. Run tests to verify performance improvements\n6. Update task list file after completion\n\nAfter completion, provide summary in this format:\n\nCOMPLETION SUMMARY:\n- What was done:\n- Results:\n- Files modified:\n- Performance improvements:\n- Next subtask in list:",
    "workFolder": "/path/to/project"
  }
}

[Claude Code implements the optimizations and returns results]

Excellent! The database query optimizations have been successfully implemented. Here's a summary:

1. Changes made:
   - Added eager loading in userController.js for user relationships
   - Created new database indexes for user_id and email fields
   - Refactored list query to use a single efficient JOIN statement
   - Added pagination to prevent large result sets

2. Performance results:
   - User listing endpoint response time reduced by 68%
   - Database query count reduced from 25+ to 3 for typical requests

Let me update the task list again to reflect this progress.

[Claude uses claude_code to update the task list again]:

{
  "toolName": "claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nTASK TYPE: Task List Update\n\n1. Read the current task list in tasks.md\n2. Mark the 'Implement database query optimization for user endpoints' subtask as [x]\n3. Add new files modified to the Relevant Files section\n4. Update Improvement Notes with performance metrics\n5. Write updated task list\n6. Return the updated task list",
    "workFolder": "/path/to/project"
  }
}

[Claude Code updates the task list and marks the second subtask complete]

I've updated the task list again. Two subtasks are now complete, and the next one is "Add Redis caching for frequently accessed data". Would you like me to continue with this subtask?

Такой структурированный подход позволяет Клоду систематически работать со сложными списками задач, сохраняя при этом четкое документирование прогресса, предположений и соответствующих файлов на протяжении всего процесса.

🎭 Паттерн самоорганизации (Клод Код в роли оркестратора)

Хотя Claude Desktop часто используется как родительский агент, вы можете использовать сам Claude Code как оркестратор и исполнитель. Такой подход создает автономную систему, в которой Claude Code управляет собственной оркестровкой задач, не требуя Claude Desktop.

graph TB
    User("👨‍💻 User")
    ClaudeCode("🤖 Claude Code\nOrchestrator")
    ClaudeCodeSubtask1("⚙️ Claude Code\nSubtask 1")
    ClaudeCodeSubtask2("⚙️ Claude Code\nSubtask 2")
    
    User-->|"Complex project request"| ClaudeCode
    ClaudeCode-->|"1. Plans tasks"| ClaudeCode
    ClaudeCode-->|"2. Executes subtask 1"| ClaudeCodeSubtask1
    ClaudeCodeSubtask1-->|"3. Returns result"| ClaudeCode
    ClaudeCode-->|"4. Executes subtask 2"| ClaudeCodeSubtask2
    ClaudeCodeSubtask2-->|"5. Returns result"| ClaudeCode
    ClaudeCode-->|"6. Final solution"| User

Этапы внедрения

1. Создайте входной скрипт , который инициализирует структуру вашей задачи и запускает Claude Code в качестве оркестратора.

2. Разработайте структуру данных задачи (обычно в формате JSON), которая отслеживает статус задачи и зависимости.

3. Создание сценариев исполнителя задач для обработки отдельных задач и обновления состояния задач.

Основные преимущества самоорганизации

1. Автономность : не требуется внешний оркестратор (вроде Claude Desktop)

2. Постоянное состояние : вся информация о задачах хранится в файлах JSON.

3. Восстановление после ошибки : можно возобновить выполнение последней успешной задачи в случае прерывания.

4. Упрощенное управление зависимостями : единая система управляет всеми взаимодействиями Claude Code

5. Автоматизация сценариев оболочки : легко интегрируется в конвейеры CI/CD или автоматизированные рабочие процессы.

Подробное руководство по внедрению с примерами сценариев и структурами задач см. в разделе Самоорганизация с Клодом Кодом .

👓 Интеграция режимов Roo

Этот сервер MCP поддерживает интеграцию со специализированными режимами через файл конфигурации .roomodes . При включении вы можете указать, какой режим использовать для каждой задачи, что позволяет реализовать специализированное поведение.

Как использовать режимы Roo

1. Включить поддержку режима Roo:

   • Установите переменную среды MCP_USE_ROOMODES=true в конфигурации MCP

   • Создайте файл .roomodes в корневом каталоге вашего сервера MCP.

   • При желании можно включить горячую перезагрузку с помощью MCP_WATCH_ROOMODES=true для автоматической перезагрузки конфигурации при изменении файла.

2. Настройте свои режимы:

   • Файл .roomodes должен содержать объект JSON с массивом customModes

   • Каждый режим должен иметь slug , name , roleDefinition и, опционально, apiConfiguration с modelId

3. Использование режима:

   • При создании запросов к инструменту claude_code включите параметр mode с обозначением желаемого режима.

   • Сервер MCP автоматически применит определение роли и конфигурацию модели.

4. Пример файла .roomodes:

   {
     "customModes": [
       {
         "slug": "coder",
         "name": "💻 Coder",
         "roleDefinition": "You are a coding specialist who writes clean, efficient code.",
         "apiConfiguration": {
           "modelId": "claude-3-sonnet-20240229"
         }
       },
       {
         "slug": "designer", 
         "name": "🎨 Designer",
         "roleDefinition": "You are a design specialist focused on UI/UX solutions."
       }
     ]
   }

5. Пример конфигурации среды:

   {
     "mcpServers": {
       "claude-code-mcp-enhanced": {
         "command": "npx",
         "args": ["github:grahama1970/claude-code-mcp-enhanced"],
         "env": {
           "MCP_USE_ROOMODES": "true",
           "MCP_WATCH_ROOMODES": "true",
           "MCP_CLAUDE_DEBUG": "false"
         }
       }
     }
   }

6. Выполнение запросов с режимами:

   {
     "toolName": "claude_code:claude_code",
     "arguments": {
       "prompt": "Your work folder is /path/to/project\n\nCreate unit tests for the user authentication module.",
       "workFolder": "/path/to/project",
       "mode": "coder"
     }
   }

Основные характеристики Roo Modes:

• Специализированное поведение : разные режимы могут иметь разные системные подсказки и конфигурации моделей.

• Горячая перезагрузка : если MCP_WATCH_ROOMODES=true , сервер автоматически перезагружает конфигурацию при изменении файла .roomodes

• Производительность : сервер кэширует конфигурацию roomodes для повышения производительности.

• Резервный вариант : если режим не найден или румоды отключены, сервер продолжает работу с поведением по умолчанию.

🛠️ Улучшенные характеристики надежности

Этот сервер включает в себя несколько улучшений для повышения надежности и производительности:

1. Предотвращение сердцебиения и тайм-аута

Чтобы предотвратить тайм-ауты на стороне клиента во время длительных операций:

• Добавлен настраиваемый механизм пульсации, который отправляет обновления хода выполнения каждые 15 секунд.

• Реализовано отслеживание времени выполнения и отчетность

• Добавлены настраиваемые параметры тайм-аута через переменные среды.

2. Надежная обработка ошибок с повторными попытками

Добавлена интеллектуальная логика повтора для временных ошибок:

• Реализован автоматический повтор с настраиваемыми параметрами

• Добавлена классификация ошибок для определения повторяющихся проблем.

• Созданы подробные отчеты об ошибках и отслеживание

3. Система отслеживания запросов

Реализовано комплексное управление жизненным циклом запросов:

• Добавлены уникальные идентификаторы для каждого запроса

• Создано отслеживание для текущих запросов

• Обеспечивает надлежащую очистку после завершения или сбоя

4. Плавное выключение

Добавлена правильная обработка завершения процесса:

• Реализованы обработчики сигналов для SIGINT и SIGTERM.

• Добавлено отслеживание текущих запросов.

• Создана логика ожидания для чистого завершения работы

• Обеспечивает надлежащую уборку на выходе

5. Кэширование конфигурации и горячая перезагрузка

Добавлена оптимизация производительности для конфигурации:

• Реализовано кэширование для файла roomodes

• Добавлена автоматическая аннуляция на основе изменений файла.

• Создан настраиваемый механизм наблюдения за файлами

⚙️ Параметры конфигурации

Поведение сервера можно настроить с помощью следующих переменных среды:

Их можно задать в вашей оболочке или в блоке env конфигурации вашего сервера mcp.json .

📸 Наглядные примеры

Вот несколько наглядных примеров работы сервера:

Исправление настройки ESLint

Вот пример использования инструмента Claude Code MCP для интерактивного исправления настройки ESLint путем удаления старых файлов конфигурации и создания новых:

Пример листинга файлов

Вот пример инструмента Claude Code, выводящего список файлов в каталоге:

Сложные многоэтапные операции

В этом примере показано, как claude_code обрабатывает более сложную многошаговую задачу, например, подготовку релиза путем создания ветки, обновления нескольких файлов ( package.json , CHANGELOG.md ), внесения изменений и инициирования запроса на извлечение — все это в рамках одной последовательной операции.

Исправление рабочего процесса действий GitHub

🎯 Основные варианты использования

Этот сервер, через свой унифицированный инструмент claude_code , открывает широкий спектр мощных возможностей, предоставляя вашему ИИ прямой доступ к Claude Code CLI. Вот несколько примеров того, чего вы можете достичь:

1. Генерация кода, анализ и рефакторинг:

   • "Generate a Python script to parse CSV data and output JSON."

   • "Analyze my_script.py for potential bugs and suggest improvements."

2. Операции с файловой системой (создание, чтение, редактирование, управление):

   • Создание файлов: "Your work folder is /Users/steipete/my_project\n\nCreate a new file named 'config.yml' in the 'app/settings' directory with the following content:\nport: 8080\ndatabase: main_db"

   • Редактирование файлов: "Your work folder is /Users/steipete/my_project\n\nEdit file 'public/css/style.css': Add a new CSS rule at the end to make all 'h2' elements have a 'color: navy'."

   • Перемещение/Копирование/Удаление: "Your work folder is /Users/steipete/my_project\n\nMove the file 'report.docx' from the 'drafts' folder to the 'final_reports' folder and rename it to 'Q1_Report_Final.docx'."

3. Контроль версий (Git):

   • "Your work folder is /Users/steipete/my_project\n\n1. Stage the file 'src/main.java'.\n2. Commit the changes with the message 'feat: Implement user authentication'.\n3. Push the commit to the 'develop' branch on origin."

4. Выполнение команд терминала:

   • "Your work folder is /Users/steipete/my_project/frontend\n\nRun the command 'npm run build'."

   • "Open the URL https://developer.mozilla.org in my default web browser."

5. Поиск в Интернете и обобщение:

   • "Search the web for 'benefits of server-side rendering' and provide a concise summary."

6. Сложные многоэтапные рабочие процессы:

   • Автоматизируйте повышение версии, обновление журналов изменений и выпуски тегов: "Your work folder is /Users/steipete/my_project\n\nFollow these steps: 1. Update the version in package.json to 2.5.0. 2. Add a new section to CHANGELOG.md for version 2.5.0 with the heading '### Added' and list 'New feature X'. 3. Stage package.json and CHANGELOG.md. 4. Commit with message 'release: version 2.5.0'. 5. Push the commit. 6. Create and push a git tag v2.5.0."

7. Исправление файлов с синтаксическими ошибками:

   • "Your work folder is /path/to/project\n\nThe file 'src/utils/parser.js' has syntax errors after a recent complex edit that broke its structure. Please analyze it, identify the syntax errors, and correct the file to make it valid JavaScript again, ensuring the original logic is preserved as much as possible."

8. Взаимодействие с GitHub (например, создание запроса на извлечение):

   • "Your work folder is /Users/steipete/my_project\n\nCreate a GitHub Pull Request in the repository 'owner/repo' from the 'feature-branch' to the 'main' branch. Title: 'feat: Implement new login flow'. Body: 'This PR adds a new and improved login experience for users.'"

9. Взаимодействие с GitHub (например, проверка статуса PR CI):

   • "Your work folder is /Users/steipete/my_project\n\nCheck the status of CI checks for Pull Request #42 in the GitHub repository 'owner/repo'. Report if they have passed, failed, or are still running."

ВАЖНО: Не забудьте указать контекст текущего рабочего каталога (CWD) в приглашениях для операций файловой системы или git (например, "Your work folder is /path/to/project\n\n...your command..." ).

🔧 Устранение неполадок

• "Команда не найдена" (claude-code-mcp): Если установлено глобально, убедитесь, что глобальный каталог bin npm находится в системной переменной PATH. Если используется npx , убедитесь, что сам npx работает.

• "Команда не найдена" (claude или ~/.claude/local/claude): Убедитесь, что Claude CLI установлен правильно. Запустите claude/doctor или проверьте его документацию.

• Проблемы с разрешениями: убедитесь, что вы выполнили шаг «Важный шаг первоначальной настройки».

• Ошибки JSON с сервера: если MCP_CLAUDE_DEBUG имеет true , сообщения об ошибках или журналы могут помешать анализу JSON MCP. Установите значение false для нормальной работы.

• Ошибки ESM/импорта: убедитесь, что вы используете Node.js v20 или более позднюю версию.

• Клиентские тайм-ауты: для длительных операций сервер отправляет сообщения heartbeat каждые 15 секунд, чтобы предотвратить клиентские тайм-ауты. Если тайм-ауты все еще возникают, вы можете настроить интервал heartbeat с помощью переменной среды MCP_HEARTBEAT_INTERVAL_MS .

• Ошибки сети/сервера: сервер теперь включает автоматическую логику повтора для временных ошибок. Если у вас все еще возникают проблемы, попробуйте увеличить значения MCP_MAX_RETRIES и MCP_RETRY_DELAY_MS .

• Предупреждение о возврате Claude CLI: Если вы видите предупреждение о том, что Claude CLI не найден в ~/.claude/local/claude, это нормально. Сервер возвращается к использованию команды claude из вашего PATH. Вы можете задать переменную среды CLAUDE_CLI_PATH , чтобы указать точный путь к исполняемому файлу Claude CLI, если это необходимо.

👨‍💻 Для разработчиков: локальная настройка и участие

Если вы хотите разработать этот сервер или внести в него свой вклад, или запустить его из клонированного репозитория для тестирования, ознакомьтесь с нашим Руководством по локальной установке и настройке разработки .

💪 Вклад

Вклады приветствуются! Пожалуйста, обратитесь к Руководству по локальной установке и настройке разработки для получения подробной информации о настройке вашей среды.

Отправляйте проблемы и запросы на извлечение в репозиторий GitHub .

⚖️ Лицензия

Массачусетский технологический институт

💬 Отзывы и поддержка

Если у вас возникли проблемы или есть вопросы по использованию сервера Claude Code MCP, пожалуйста:

1. Проверьте раздел «Устранение неполадок» выше.

2. Отправьте сообщение о проблеме в репозиторий GitHub

3. Присоединяйтесь к обсуждению в разделе обсуждений репозитория

Мы ценим ваши отзывы и вклад в улучшение этого инструмента!