Vibe Coder MCP

Сервер Vibe Coder MCP

Vibe Coder — это сервер MCP (Model Context Protocol), разработанный для того, чтобы нагрузить вашего помощника AI (например, Cursor, Cline AI или Claude Desktop) мощными инструментами для разработки программного обеспечения. Он помогает в исследованиях, планировании, создании требований, создании стартовых проектов и многом другом!

Обзор и характеристики

Vibe Coder MCP интегрируется с MCP-совместимыми клиентами, предоставляя следующие возможности:

• Семантическая маршрутизация запросов : интеллектуальная маршрутизация запросов с использованием семантического сопоставления на основе встраивания с резервными вариантами последовательного мышления.
• Архитектура реестра инструментов : централизованное управление инструментами с саморегистрацией.
• Прямые вызовы LLM : инструменты генератора теперь используют прямые вызовы LLM для повышения надежности и структурированного управления выходными данными.
• Выполнение рабочего процесса : запускает предопределенные последовательности вызовов инструментов, определенные в workflows.json .
• Исследования и планирование : выполняет глубокие исследования ( research-manager ) и создает документы по планированию, такие как PRD ( generate-prd ), пользовательские истории ( generate-user-stories ), списки задач ( generate-task-list ) и правила разработки ( generate-rules ).
• Проектирование лесов : создает полнофункциональные стартовые комплекты ( generate-fullstack-starter-kit ).
• Генератор кодовой карты : рекурсивно сканирует кодовую базу, извлекает семантическую информацию и генерирует либо эффективный по токенам, контекстно-плотный индекс Markdown с диаграммами Mermaid, либо структурированное представление JSON с абсолютными путями к файлам для импорта и расширенной информацией о свойствах класса ( map-codebase ).
• Асинхронное выполнение : многие долго работающие инструменты (генераторы, исследования, рабочие процессы) теперь работают асинхронно. Они немедленно возвращают идентификатор задания, а окончательный результат извлекается с помощью инструмента get-job-result .
• Управление состоянием сеанса : поддерживает базовое состояние между запросами в течение сеанса (в памяти).
• Стандартизированная обработка ошибок : единообразные шаблоны ошибок во всех инструментах.

(Более подробную информацию см. в разделах «Подробная документация по инструменту» и «Подробности о функциях» ниже)

Руководство по настройке

Выполните следующие микрошаги, чтобы запустить сервер Vibe Coder MCP и подключить его к вашему помощнику на базе искусственного интеллекта.

Шаг 1: Предварительные условия

1. Проверьте версию Node.js:
   • Откройте терминал или командную строку.
   • Запустить node -v
   • Убедитесь, что на выходе отображается версия 18.0.0 или выше (обязательно).
   • Если не установлен или устарел: Загрузите с nodejs.org .
2. Проверьте установку Git:
   • Откройте терминал или командную строку.
   • Запустите git --version
   • Если не установлено: Загрузите с git-scm.com .
3. Получить ключ API OpenRouter:
   • Посетите openrouter.ai
   • Создайте учетную запись, если у вас ее нет.
   • Перейдите в раздел «Ключи API».
   • Создайте новый ключ API и скопируйте его.
   • Сохраните этот ключ под рукой для шага 4.

Шаг 2: Получите код

1. Создайте каталог проекта (необязательно):
   • Откройте терминал или командную строку.
   • Перейдите туда, где вы хотите сохранить проект:
     cd ~/Documents # Example: Change to your preferred location
2. Клонировать репозиторий:
   • Бегать:
     git clone https://github.com/freshtechbro/vibe-coder-mcp.git
     (Или используйте URL вашего форка, если применимо)
3. Перейдите в каталог проектов:
   • Бегать:
     cd vibe-coder-mcp

Шаг 3: Запустите сценарий установки

Выберите подходящий скрипт для вашей операционной системы:

Для Windows:

1. В терминале (все еще в каталоге vibe-coder-mcp) выполните:
   setup.bat
2. Дождитесь завершения работы скрипта (он установит зависимости, соберет проект и создаст необходимые каталоги).
3. Если вы видите какие-либо сообщения об ошибках, обратитесь к разделу «Устранение неполадок» ниже.

Для macOS или Linux:

1. Сделайте скрипт исполняемым:
   chmod +x setup.sh
2. Запустите скрипт:
   ./setup.sh
3. Дождитесь завершения скрипта.
4. Если вы видите какие-либо сообщения об ошибках, обратитесь к разделу «Устранение неполадок» ниже.

Скрипт выполняет следующие действия:

• Проверяет версию Node.js (v18+)
• Устанавливает все зависимости через npm
• Создает необходимые подкаталоги VibeCoderOutput/ (как определено в скрипте).
• Создает проект TypeScript.
• Копирует .env.example в .env , если .env еще не существует. Вам нужно будет отредактировать этот файл.
• Устанавливает права доступа к исполняемому файлу (в системах Unix).

Шаг 4: Настройка переменных среды ( .env )

Скрипт настройки (из шага 3) автоматически создает файл .env в корневом каталоге проекта, копируя шаблон .env.example , только если .env еще не существует .

1. Найдите и откройте .env : найдите файл .env в основном каталоге vibe-coder-mcp и откройте его с помощью текстового редактора.
2. Добавьте свой ключ API OpenRouter (обязательно):
   • Файл содержит шаблон на основе .env.example :
     # OpenRouter Configuration ## Specifies your unique API key for accessing OpenRouter services. ## Replace "Your OPENROUTER_API_KEY here" with your actual key obtained from OpenRouter.ai. OPENROUTER_API_KEY="Your OPENROUTER_API_KEY here" ## Defines the base URL for the OpenRouter API endpoints. ## The default value is usually correct and should not need changing unless instructed otherwise. OPENROUTER_BASE_URL=https://openrouter.ai/api/v1 ## Sets the specific Gemini model to be used via OpenRouter for certain AI tasks. ## ':free' indicates potential usage of a free tier model if available and supported by your key. GEMINI_MODEL=google/gemini-2.0-flash-thinking-exp:free
   • Важно, замените "Your OPENROUTER_API_KEY here" на ваш фактический ключ API OpenRouter. Уберите кавычки, если ваш ключ их не требует.
3. Настройте выходной каталог (необязательно):
   • Чтобы изменить место сохранения сгенерированных файлов (по умолчанию это VibeCoderOutput/ внутри проекта), добавьте эту строку в файл .env :
     VIBE_CODER_OUTPUT_DIR=/path/to/your/desired/output/directory
   • Замените путь на предпочитаемый вами абсолютный путь . Используйте косые черты ( / ) для путей. Если эта переменная не задана, будет использоваться каталог по умолчанию ( VibeCoderOutput/ ).
4. Настройте каталог генератора кодовой карты (необязательно):
   • Чтобы указать, какой каталог разрешено сканировать инструменту code-map-generator, добавьте эту строку в файл .env :
     CODE_MAP_ALLOWED_DIR=/path/to/your/source/code/directory
   • Замените путь на абсолютный путь к каталогу, содержащему исходный код, который вы хотите проанализировать. Это граница безопасности — инструмент не будет получать доступ к файлам за пределами этого каталога.
   • Обратите внимание, что CODE_MAP_ALLOWED_DIR (для чтения исходного кода) и VIBE_CODER_OUTPUT_DIR (для записи выходных файлов) разделены по соображениям безопасности. Инструмент code-map-generator использует отдельную проверку для операций чтения и записи.
5. Просмотрите другие настройки (необязательно):
   • Вы можете добавить другие переменные среды, поддерживаемые сервером, такие как LOG_LEVEL (например, LOG_LEVEL=debug ) или NODE_ENV (например, NODE_ENV=development ).
6. Сохраните файл .env .

Шаг 5: Интеграция с вашим помощником на основе искусственного интеллекта (настройки MCP)

Этот важный шаг подключает Vibe Coder к вашему ИИ-помощнику путем добавления его конфигурации в файл настроек MCP клиента.

5.1: Найдите файл настроек MCP вашего клиента

Местоположение зависит от вашего ИИ-помощника:

• Курсор AI / Windsurf / RooCode (на основе VS Code):
  1. Откройте приложение.
  2. Откройте палитру команд ( Ctrl+Shift+P или Cmd+Shift+P ).
  3. Введите и выберите Preferences: Open User Settings (JSON) .
  4. Откроется файл settings.json , в котором должен находиться объект mcpServers .
• Cline AI (расширение VS Code):
  • Windows : %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  • macOS : ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Linux : ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • (Примечание: если вместо Cursor используется стандартный VS Code, замените Cursor на Code в пути)
• Клод Десктоп:
  • Windows : %APPDATA%\Claude\claude_desktop_config.json
  • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux : ~/.config/Claude/claude_desktop_config.json

5.2: Добавьте конфигурацию Vibe Coder

1. Откройте указанный выше файл настроек в текстовом редакторе.
2. Найдите объект JSON "mcpServers": { ... } . Если он не существует, вам может потребоваться создать его (убедитесь, что весь файл остается допустимым JSON). Например, пустой файл может стать {"mcpServers": {}} .
3. Добавьте следующий блок конфигурации в фигурные скобки {} объекта mcpServers . Если другие серверы уже перечислены, добавьте запятую , после закрывающей скобки предыдущего сервера } перед вставкой этого блока.
   // This is the unique identifier for this MCP server instance within your client's settings "vibe-coder-mcp": { // Specifies the command used to execute the server. Should be 'node' if Node.js is in your system's PATH "command": "node", // Provides the arguments to the 'command'. The primary argument is the absolute path to the compiled server entry point // !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !! "args": ["/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/build/index.js"], // Sets the current working directory for the server process when it runs // !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !! "cwd": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP", // Defines the communication transport protocol between the client and server "transport": "stdio", // Environment variables to be passed specifically to the Vibe Coder server process when it starts // API Keys should be in the .env file, NOT here "env": { // Absolute path to the LLM configuration file used by Vibe Coder // !! IMPORTANT: Replace with the actual absolute path on YOUR system !! "LLM_CONFIG_PATH": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/llm_config.json", // Sets the logging level for the server "LOG_LEVEL": "debug", // Specifies the runtime environment "NODE_ENV": "production", // Directory where Vibe Coder tools will save their output files // !! IMPORTANT: Replace with the actual absolute path on YOUR system !! "VIBE_CODER_OUTPUT_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/VibeCoderOutput", // Directory that the code-map-generator tool is allowed to scan // This is a security boundary - the tool will not access files outside this directory "CODE_MAP_ALLOWED_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/src" }, // A boolean flag to enable (false) or disable (true) this server configuration "disabled": false, // A list of tool names that the MCP client is allowed to execute automatically "autoApprove": [ "research", "generate-rules", "generate-user-stories", "generate-task-list", "generate-prd", "generate-fullstack-starter-kit", "refactor-code", "git-summary", "run-workflow", "map-codebase" ] }
4. ВАЖНО: Замените все пути-заполнители (например /path/to/your/vibe-coder-mcp/... ) на правильные абсолютные пути в вашей системе, где вы клонировали репозиторий. Используйте прямые слеши / для путей, даже в Windows (например, C:/Users/YourName/Projects/vibe-coder-mcp/build/index.js ). Неправильные пути являются наиболее распространенной причиной того, что сервер не подключается.
5. Сохраните файл настроек.
6. Полностью закройте и перезапустите приложение AI-помощника (Cursor, VS Code, Claude Desktop и т. д.), чтобы изменения вступили в силу.

Шаг 6: Проверьте свою конфигурацию

1. Запустите своего помощника на основе искусственного интеллекта:
   • Полностью перезапустите приложение AI-помощника.
2. Проверьте простую команду:
   • Введите тестовую команду, например: Research modern JavaScript frameworks
3. Проверьте правильность ответа:
   • Если все сделано правильно, вы должны получить ответ по исследованию.
   • Если нет, проверьте раздел «Устранение неполадок» ниже.

Архитектура проекта

Сервер Vibe Coder MCP имеет модульную архитектуру, основанную на шаблоне реестра инструментов:

Структура каталога

Шаблон реестра инструментов

Реестр инструментов является центральным компонентом для управления определениями и выполнением инструментов:

Последовательный процесс мышления

Механизм последовательного мышления обеспечивает резервную маршрутизацию на основе LLM:

Управление состоянием сеанса

Механизм выполнения рабочего процесса

Система Workflow позволяет реализовать многошаговые последовательности:

Конфигурация рабочего процесса

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

Расположение и структура файла

• Файл workflows.json должен быть помещен в корневой каталог проекта (на том же уровне, что и package.json)
• Файл имеет следующую структуру:
  { "workflows": { "workflowName1": { "description": "Description of what this workflow does", "inputSchema": { "param1": "string", "param2": "string" }, "steps": [ { "id": "step1_id", "toolName": "tool-name", "params": { "param1": "{workflow.input.param1}" } }, { "id": "step2_id", "toolName": "another-tool", "params": { "paramA": "{workflow.input.param2}", "paramB": "{steps.step1_id.output.content[0].text}" } } ], "output": { "summary": "Workflow completed message", "details": ["Output line 1", "Output line 2"] } } } }

Шаблоны параметров

Параметры шагов рабочего процесса поддерживают строки шаблонов, которые могут ссылаться на:

• Входные данные рабочего процесса: {workflow.input.paramName}
• Выводы предыдущего шага: {steps.stepId.output.content[0].text}

Запуск рабочих процессов

Используйте инструмент run-workflow с:

Подробная документация по инструменту

Каждый инструмент в каталоге src/tools/ включает в себя полную документацию в своем собственном файле README.md. Эти файлы охватывают:

• Обзор и назначение инструмента
• Характеристики ввода/вывода
• Диаграммы рабочего процесса (Русалка)
• Примеры использования
• Системные подсказки используются
• Подробности обработки ошибок

Подробную информацию можно найти в следующих отдельных файлах README:

• src/tools/fullstack-starter-kit-generator/README.md
• src/tools/prd-generator/README.md
• src/tools/research-manager/README.md
• src/tools/rules-generator/README.md
• src/tools/task-list-generator/README.md
• src/tools/user-stories-generator/README.md
• src/tools/workflow-runner/README.md
• src/tools/code-map-generator/README.md

Категории инструментов

Инструменты анализа и информации

• Генератор кодовой карты ( map-codebase ) : сканирует кодовую базу для извлечения семантической информации (классы, функции, комментарии) и генерирует либо удобочитаемую карту Markdown с диаграммами Mermaid, либо структурированное представление JSON с абсолютными путями к файлам для импорта и расширенной информацией о свойствах класса.
• Менеджер по исследованиям ( research-manager ) : проводит глубокие исследования по техническим темам с использованием Perplexity Sonar, предоставляя резюме и источники.

Инструменты планирования и документирования

• Генератор правил ( generate-rules ): создает правила и рекомендации по разработке для конкретного проекта.
• Генератор PRD ( generate-prd ): создает комплексные документы с требованиями к продукту.
• Генератор пользовательских историй ( generate-user-stories ): создает подробные пользовательские истории с критериями приемки.
• Генератор списка задач ( generate-task-list ): создает структурированные списки задач разработки с зависимостями.

Инструмент для строительства лесов проекта

• Генератор стартовых наборов Fullstack ( generate-fullstack-starter-kit ): создает индивидуальные стартовые наборы проектов с указанными технологиями frontend/backend, включая базовые сценарии настройки и конфигурацию.

Рабочий процесс и оркестровка

• Workflow Runner ( run-workflow ): выполняет предопределенные последовательности вызовов инструментов для общих задач разработки.

Сгенерированное хранилище файлов

По умолчанию выходные данные инструментов генератора сохраняются для исторической справки в каталоге VibeCoderOutput/ в проекте. Это местоположение можно переопределить, установив переменную окружения VIBE_CODER_OUTPUT_DIR в файле .env или конфигурации помощника AI.

Границы безопасности для операций чтения и записи

В целях безопасности инструменты Vibe Coder MCP поддерживают отдельные границы безопасности для операций чтения и записи:

• Операции чтения : Такие инструменты, как code-map-generator, читают только из каталогов, явно разрешенных через переменную среды CODE_MAP_ALLOWED_DIR . Это создает четкую границу безопасности и предотвращает несанкционированный доступ к файлам за пределами разрешенного каталога.
• Операции записи : все выходные файлы записываются в каталог VIBE_CODER_OUTPUT_DIR (или его подкаталоги). Такое разделение гарантирует, что инструменты могут записывать только в указанные выходные расположения, защищая исходный код от случайных изменений.

Пример структуры (расположение по умолчанию):

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

Взаимодействуйте с инструментами с помощью подключенного помощника на основе искусственного интеллекта:

• Исследование: Research modern JavaScript frameworks
• Сгенерировать правила: Create development rules for a mobile banking application
• Генерация PRD: Generate a PRD for a task management application
• Генерация пользовательских историй: Generate user stories for an e-commerce website
• Создание списка задач: Create a task list for a weather app based on [user stories]
• Последовательное мышление: Think through the architecture for a microservices-based e-commerce platform
• Стартовый комплект Fullstack: Create a starter kit for a React/Node.js blog application with user authentication
• Запустить рабочий процесс: Run workflow newProjectSetup with input { "projectName": "my-new-app", "description": "A simple task manager" }
• Карта кодовой базы: Generate a code map for the current project , map-codebase path="./src" или Generate a JSON representation of the codebase structure with output_format="json"

Запуск локально (необязательно)

Хотя основное применение — интеграция с помощником на основе искусственного интеллекта (с использованием stdio), вы можете запустить сервер напрямую для тестирования:

Режимы работы

• Режим производства (Stdio):
  npm start
  • Логи отправляются в stderr (имитирует запуск помощника ИИ)
  • Использовать NODE_ENV=production
• Режим разработки (Stdio, Pretty Logs):
  npm run dev
  • Логи отправляются на стандартный вывод с красивым форматированием
  • Требуются nodemon и pino-pretty
  • Используйте NODE_ENV=development
• Режим SSE (интерфейс HTTP):
  # Production mode over HTTP npm run start:sse # Development mode over HTTP npm run dev:sse
  • Использует HTTP вместо stdio
  • Настраивается через PORT в .env (по умолчанию: 3000)
  • Доступ по адресу http://localhost:3000

Подробное устранение неполадок

Проблемы с подключением

Сервер MCP не обнаружен в AI Assistant

1. Проверьте путь конфигурации:
   • Проверьте правильность абсолютного пути в массиве args
   • Убедитесь, что все слеши являются прямыми слешами / даже в Windows)
   • Запустите node <path-to-build/index.js> напрямую, чтобы проверить, может ли Node его найти
2. Проверьте формат конфигурации:
   • Убедитесь, что JSON корректен и не имеет синтаксических ошибок.
   • Проверьте правильность запятых между свойствами.
   • Убедитесь, что объект mcpServers содержит ваш сервер.
3. Перезапустите Помощник:
   • Полностью закрыть (а не просто свернуть) приложение
   • Откройте снова и попробуйте еще раз

Сервер запускается, но инструменты не работают

1. Проверьте флаг «Отключено»:
   • Убедитесь, что "disabled": false
   • Удалите все комментарии // так как JSON их не поддерживает.
2. Проверьте массив autoApprove:
   • Проверьте, что названия инструментов в массиве autoApprove точно совпадают.
   • Попробуйте добавить "process-request" в массив, если используете гибридную маршрутизацию.

Проблемы с ключами API

1. Основные проблемы OpenRouter:
   • Еще раз проверьте, что ключ скопирован правильно.
   • Убедитесь, что ключ активен на панели управления OpenRouter.
   • Проверьте, достаточно ли у вас кредитов
2. Проблемы с переменными среды:
   • Проверьте правильность ключа в обоих случаях:
     • Файл .env (для локальных запусков)
     • Конфигурационный блок env вашего помощника ИИ

Проблемы с путями и разрешениями

1. Каталог сборки не найден:
   • Запустите npm run build чтобы убедиться, что каталог сборки существует.
   • Проверьте, направляется ли вывод сборки в другой каталог (проверьте tsconfig.json)
2. Ошибки прав доступа к файлу:
   • Убедитесь, что у вашего пользователя есть права на запись в каталог workflow-agent-files.
   • В системах Unix проверьте, имеет ли build/index.js разрешение на выполнение

Отладка журнала

1. Для местных заездов:
   • Проверьте вывод консоли на наличие сообщений об ошибках.
   • Попробуйте запустить с LOG_LEVEL=debug в вашем .env файле
2. Для запуска AI Assistant:
   • Установите "NODE_ENV": "production" в конфигурации env
   • Проверьте, есть ли у помощника консоль ведения журнала или окно вывода.

Проблемы, связанные с инструментами

1. Семантическая маршрутизация не работает:
   • При первом запуске может загрузиться модель внедрения — проверьте сообщения о загрузке
   • Попробуйте более явный запрос, в котором упоминается название инструмента.