Использование MCP в SourceCraft Code Assistant

Сервер MCP (Model Context Protocol) действует как мост, предоставляя Code Assistant доступ к более широкому спектру инструментов и внешних сервисов, таких как базы данных, API или пользовательские скрипты. Он использует стандартный метод связи, позволяя Code Assistant использовать эти внешние возможности.

Подробнее см. на странице Что такое MCP.

Настройка MCP-серверов

Конфигурации MCP-серверов можно управлять на следующих уровнях:

• Глобальная конфигурация — хранится в файле mcp_settings.json, доступном через настройки VS Code. Эти настройки применяются ко всем вашим рабочим пространствам, если не переопределены конфигурацией на уровне проекта.
• Конфигурация на уровне проекта — определяется в файле .codeassistant/mcp.json в корневом каталоге вашего проекта. Это позволяет настроить серверы, специфичные для проекта, и делиться конфигурациями с вашей командой, добавляя файл в систему контроля версий. Code Assistant автоматически обнаруживает и загружает этот файл, если он существует.

Если имя сервера существует как в глобальной, так и в проектной конфигурации, конфигурация на уровне проекта имеет приоритет.

Редактирование файлов с настройками MCP

Вы можете редактировать как глобальные, так и проектные файлы конфигурации MCP прямо из меню настроек MCP в Code Assistant:

1. Нажмите в верхней панели чата и выберите MCP-серверы.

2. Выберите соответствующую опцию:

   • Edit Global MCP — открывает глобальный файл mcp_settings.json.
   • Edit Project MCP — открывает проектный файл .codeassistant/mcp.json. Если этот файл отсутствует, Code Assistant создаст его автоматически.

   Оба файла используют формат JSON с объектом mcpServers, содержащим именованные конфигурации серверов:

   {
     "mcpServers": {
       "server1": {
         "command": "python",
         "args": ["/path/to/server.py"],
         "env": {
           "API_KEY": "your_api_key"
         },
         "alwaysAllow": ["tool1", "tool2"],
         "disabled": false
       }
     }
   }
   

Типы транспорта

MCP поддерживает следующие типы транспорта для связи с серверами: STDIO для локальных серверов, Streamable HTTP (рекомендуется для новых удаленных серверов) и SSE (для устаревших удаленных серверов).

Транспорт STDIO

Используется для локальных серверов, работающих на вашем компьютере:

• Обмен данными через стандартные потоки ввода/вывода.
• Низкая задержка (отсутствие сетевых накладных расходов).
• Повышенная безопасность (отсутствие сетевой доступности).
• Упрощенная настройка (не требуется HTTP-сервер).
• Запускается как дочерний процесс на вашем компьютере.

Подробнее см. на странице Транспорт STDIO.

Пример конфигурации STDIO:

{
  "mcpServers": {
    "local-server": {
      "command": "node",
      "args": ["server.js"],
      "cwd": "/path/to/project/root", // Необязательно: указание рабочей директории
      "env": {
        "API_KEY": "your_api_key"
      },
      "alwaysAllow": ["tool1", "tool2"],
      "disabled": false
    }
  }
}

Где:

• command (обязательный) — исполняемый файл для запуска (например node, python, npx или абсолютный путь).
• args (опциональный) — массив строковых аргументов, передаваемых в команду. Вы можете использовать системные переменные окружения через синтаксис ${env:VARIABLE_NAME}.
• cwd (опциональный) — рабочая директория, из которой будет запущен серверный процесс. Если не указано, используется путь первой папки рабочего пространства или рабочая директория основного процесса. Полезно, если скрипт сервера зависит от относительных путей.
• env (опциональный) — объект, содержащий переменные окружения для установки в процессе сервера.
• alwaysAllow (опциональный) — массив названий инструментов с этого сервера, которые будут автоматически одобрены.
• disabled (опциональный) — установите true, чтобы отключить эту конфигурацию сервера.

Использование системных переменных окружения в аргументах

Вы можете ссылаться на системные переменные окружения в массиве args, используя синтаксис ${env:VARIABLE_NAME}. Это позволяет передавать конфиденциальную информацию, такую как API-ключи или токены, из системного окружения без их прямого упоминания в конфигурации:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN=${env:GITHUB_PERSONAL_ACCESS_TOKEN}",
        "ghcr.io/github/github-mcp-server"
      ],
      "alwaysAllow": [
        "get_pull_request"
      ]
    }
  }
}

В этом примере ${env:GITHUB_PERSONAL_ACCESS_TOKEN} будет заменен значением переменной окружения GITHUB_PERSONAL_ACCESS_TOKEN из вашей системы. Это особенно полезно, когда:

• Вы работаете с Docker-контейнерами, которым нужно передавать переменные окружения.
• Вы хотите исключить конфиденциальные данные из конфигурационных файлов.
• Вы используете одну и ту же конфигурацию в разных окружениях с разными учетными данными.

Транспорт Streamable HTTP

Это современный стандарт для удаленных серверов, доступных через HTTP/HTTPS, обеспечивающий большую гибкость и заменяющий устаревший транспорт SSE для новых реализаций:

• Обмен данными через HTTP POST/GET с единым MCP-эндпоинтом.
• Опционально использует Server-Sent Events (SSE) для потоковой передачи.
• Может быть размещен на удаленном сервере.
• Поддерживает несколько клиентских подключений.
• Требует сетевого доступа.
• Поддерживает централизованное развертывание и управление.

Подробнее см. на странице Транспорт Streamable HTTP.

Пример конфигурации Streamable HTTP:

{
  "mcpServers": {
    "modern-remote-server": {
      "type": "streamable-http",
      "url": "https://your-modern-server.com/api/mcp-endpoint",
      "headers": {
        "X-API-Key": "your-secure-api-key"
      },
      "alwaysAllow": ["newToolA", "newToolB"],
      "disabled": false
    }
  }
}

Где:

• type (обязательный) — должен быть установлен в "streamable-http".
• url (обязательный) — полный URL единого эндпоинта удаленного MCP-сервера, например https://your-server.com/mcp.
• headers (опциональный) — объект, содержащий пользовательские HTTP-заголовки для отправки с запросами, например для токенов аутентификации.
• alwaysAllow (опциональный) — массив названий инструментов с этого сервера, которые будут автоматически одобрены.
• disabled (опциональный) — установите в true, чтобы отключить эту конфигурацию сервера.

Транспорт SSE (устаревший)

Используется для старых удаленных серверов, доступных через HTTP/HTTPS:

• Обмен данными через протокол Server-Sent Events (обычно требует отдельных эндпоинтов для связи клиент-сервер и сервер-клиент).
• Может быть размещен на удаленном сервере.
• Поддерживает несколько клиентских подключений.
• Требует сетевого доступа.
• Поддерживает централизованное развертывание и управление.

Для новых реализаций удаленных серверов рекомендуется использовать Streamable HTTP.

Подробнее см. на странице Транспорт SSE (устаревший).

Пример конфигурации SSE (устаревший):

{
  "mcpServers": {
    "legacy-remote-server": {
      "type": "sse", // Явно указать как SSE
      "url": "https://your-legacy-server-url.com/mcp-base", // Базовый URL
      "headers": {
        "Authorization": "Bearer your-legacy-token"
      },
      "alwaysAllow": ["oldToolX"],
      "disabled": false
    }
  }
}

Где:

• type (опциональный, но рекомендуется для ясности) — должен быть установлен в "sse", если указан url для SSE-сервера, чтобы отличить от Streamable HTTP. Если url указан, но type отсутствует, Code Assistant может попытаться определить тип автоматически, но явное указание предпочтительнее.
• url (обязательный) — базовый URL удаленного MCP-сервера. Для устаревшего SSE это обычно подразумевает отдельные пути, такие как /events (для потока SSE) и /message (для POST-запросов), которые будут определены или ожидаемы сервером.
• headers (опциональный) — объект, содержащий пользовательские HTTP-заголовки для отправки с запросами, например для токенов аутентификации.
• alwaysAllow (опциональный) — массив названий инструментов с этого сервера, которые будут автоматически одобрены.
• disabled (опциональный) — установите в true, чтобы отключить эту конфигурацию сервера.

Включение или отключение MCP-серверов

Отключение MCP-серверов удаляет всю связанную с MCP логику и определения из системного запроса, что снижает использование токенов. Это предотвратит подключение Code Assistant к любым MCP-серверам, а инструменты use_mcp_tool и access_mcp_resource станут недоступны. Установите этот параметр, если вы не планируете использовать MCP-серверы. По умолчанию включено.

1. Нажмите в верхней панели чата и выберите MCP-серверы.
2. Включите или выключите опцию Enable MCP Servers.

Включение или отключение создания MCP-серверов

Отключение создания MCP-серверов удаляет инструкции из системного запроса, которые Code Assistant использует для написания MCP-серверов, но не удаляет контекст, связанный с их работой. Это снижает использование токенов. По умолчанию включено.

1. Нажмите в верхней панели чата и выберите MCP-серверы.
2. Включите или выключите опцию Enable MCP Server Creation.

Как использовать Code Assistant для создания MCP-сервера

Если вам нужен определенный инструмент или возможность, которые недоступны через существующие MCP-серверы, вы можете попросить Code Assistant создать новый.

1. Сформулируйте запрос: явно попросите Code Assistant о новом инструменте или возможности. Например:
   • Создай MCP-инструмент, который получает текущую цену биткоина.
   • Мне нужен инструмент, который подключается к внутренней базе данных пользователей моей компании через ее API.
   • Создай MCP-сервер для взаимодействия с API GitHub Gist.
2. После вашего запроса Code Assistant выполнит следующие шаги:
   • Получит внутренние инструкции для создания сервера.
   • Создаст базовый проект сервера (обычно на TypeScript) в стандартной директории MCP, если вы не укажете иное.
   • Напишет код для реализации запрошенного инструмента, включая обработку необходимых API-вызовов.
   • Если инструмент требует ключи API или другие учетные данные, Code Assistant запросит их у вас с помощью инструмента ask_followup_question, чтобы настроить их безопасно как переменные окружения для сервера.
   • Автоматически добавит конфигурацию нового сервера в ваш глобальный файл mcp_settings.json или проектный файл .codeassistant/mcp.json.
   • Попытается подключиться к вновь настроенному серверу, чтобы его инструменты стали доступны.
3. Если предыдущие шаги выполнены успешно, Code Assistant подтвердит создание, и новый сервер и его инструменты появятся в вашем списке MCP-серверов, готовые к использованию.

Эта функция позволяет вам адаптировать возможности Code Assistant, создавая интеграции, которые вам нужны, прямо из ваших запросов.

Управление отдельными MCP-серверами

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

1. Нажмите в верхней панели чата и выберите MCP-серверы.
2. В списке MCP-серверов найдите нужный и выполните одно из следующих действий:

Удаление сервера

1. Нажмите рядом с MCP-сервером, который вы хотите удалить.
2. В окне подтверждения нажмите Delete.

Перезапуск сервера

Нажмите рядом с MCP-сервером, который вы хотите перезапустить.

Включение или отключение сервера

Нажмите переключатель рядом с MCP-сервером, который вы хотите включить или выключить.

Тайм-аут сети

Чтобы установить максимальное время ожидания ответа после вызова инструмента на MCP-сервере:

1. Раскройте выпадающий список рядом с MCP-сервером.
2. Выставьте время в поле Network Timeout. По умолчанию установлена 1 минута, но можно задать значение от 30 секунд до 5 минут.

Автоматическое одобрение инструментов

Автоматическое одобрение инструментов MCP работает для каждого инструмента отдельно и по умолчанию отключено. Чтобы настроить автоматическое одобрение:

1. На панели Auto-approve включите MCP.
2. Раскройте необходимый MCP-сервер и выберите параметр Auto-Run для конкретных инструментов.

После включения Code Assistant будет автоматически одобрять использование этого инструмента без запроса.

Поиск и установка MCP-серверов

Вы можете найти и установить MCP-серверы в Code Assistant самостоятельно, для этого:

• Проверьте списки MCP-серверов, поддерживаемых сообществом на GitHub.
• Попросите Code Assistant помочь вам найти или даже создать MCP-серверы, если включена опция Enable MCP Server Creation.
• Создайте пользовательские MCP-серверы с помощью SDK, чтобы расширить возможности Code Assistant своими инструментами.

Полную документацию SDK см. в репозитории MCP на GitHub.

Использование инструментов MCP в вашем рабочем процессе

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

Основные шаги рабочего процесса

Ваше взаимодействие с инструментами MCP обычно происходит в следующей последовательности:

1. Запуск задачи

Начните с ввода вашего запроса в интерфейсе чата Code Assistant.

2. Идентификация инструмента Code Assistant

Code Assistant анализирует ваш запрос, чтобы определить, может ли доступный инструмент MCP помочь. Этот этап сильно зависит от качества описаний ваших инструментов MCP.

Критическая роль описаний

Описания инструментов существенно влияют на способность Code Assistant:

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

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

Например, запрос Проанализируй производительность моего API может привести к тому, что Code Assistant выберет инструмент MCP, предназначенный для тестирования эндпоинтов API. Успешная идентификация и использование этого инструмента Code Assistant напрямую зависят от качества его описания.

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

Чтобы Code Assistant мог эффективно использовать ваши инструменты MCP, учитывайте следующее при их определении на сервере:

• Название инструмента — выберите описательное и однозначное название, которое четко указывает на основную функцию инструмента.
• Описание инструмента — предоставьте подробное резюме того, что делает инструмент, его назначение и любые важные контексты или предварительные условия для его использования. Объясните результат или итог использования инструмента.
• Описание параметров — это критически важно. Для каждого параметра:
  • Четко укажите его назначение и тип ожидаемых данных, например ID пользователя для поиска, Путь к файлу для обработки, Строка поискового запроса.
  • Укажите любые требования к формату, ограничения или пример допустимого значения, если применимо.
  • Укажите, является ли параметр необязательным или обязательным. Хотя схема MCP обычно обрабатывает это, заметка может быть полезной.
• Ясность для ИИ — пишите описания так, как если бы вы объясняли инструмент другому разработчику или ИИ. Чем больше контекста у Code Assistant, тем лучше он сможет интегрировать инструмент в свои рабочие процессы. Если инструмент предназначен для использования в определенной последовательности или в сочетании с другими инструментами, упоминание об этом также может быть полезным.
• Дополнение пользовательскими инструкциями — помимо описаний, встроенных в MCP-сервер, вы можете дополнительно направлять Code Assistant на использование конкретных инструментов MCP, предоставляя пользовательские инструкции. Это позволяет определить предпочтительные подходы, описать сложные рабочие процессы, включающие несколько инструментов, или указать, когда определенный инструмент MCP должен быть приоритетным или избегаться.

3. Вызов инструмента

Если Code Assistant, руководствуясь описаниями инструментов, определяет подходящий инструмент, он предложит его использование. Затем вы должны одобрить это, если автоодобрение не настроено для доверенных инструментов.

Максимизация взаимодействия с MCP-серверами

Вкладывая усилия в создание детализированных описаний и, возможно, дополняя их пользовательскими инструкциями, вы значительно улучшаете взаимодействие между Code Assistant и вашими MCP-серверами. Это раскрывает их полный потенциал для более надежного и эффективного выполнения задач.

Устранение неполадок MCP-серверов

Распространенные проблемы и их решения:

• Сервер не отвечает — проверьте, запущен ли процесс сервера, и убедитесь в наличии сетевого подключения.
• Ошибки прав доступа — убедитесь, что в mcp_settings.json для глобальных настроек или .codeassistant/mcp.json для настроек проекта правильно настроены API-ключи и учетные данные.
• Инструмент недоступен — убедитесь, что сервер правильно реализует инструмент и он не отключен в настройках.
• Медленная работа — попробуйте изменить значение тайм-аута сети для конкретного MCP-сервера.

Примеры конфигурации MCP для разных платформ

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

{
  "mcpServers": {
    "puppeteer": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

Конфигурация с использованием менеджеров версий сред выполнения

При работе с несколькими версиями языков программирования или сред выполнения вы можете использовать менеджеры версий, такие как asdf или mise (ранее rtx). Эти инструменты помогают управлять несколькими версиями сред выполнения на одной системе. Вот как настроить MCP-серверы для работы с этими менеджерами версий:

{
  "mcpServers": {
    "mcp-batchit": {
      "command": "mise",
      "args": [
        "x",
        "--",
        "node",
        "/Users/myself/workspace/mcp-batchit/build/index.js"
      ],
      "disabled": false,
      "alwaysAllow": [
        "search",
        "batch_execute"
      ]
    }
  }
}

{
  "mcpServers": {
    "appsignal": {
      "command": "/Users/myself/.asdf/installs/nodejs/22.2.0/bin/node",
      "args": [
        "/Users/myself/Code/Personal/my-mcp/build/index.js"
      ],
      "env": {
        "ASDF_NODE_VERSION": "22.2.0"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}