modal-workspace-mcp

Удалённый MCP-мост, который позволяет GitHub Copilot, Copilot CLI и другим MCP-клиентам использовать ваш аккаунт Modal для выполнения Linux-команд, установки зависимостей, Git-операций, GPU-задач и вызовов развёрнутых Modal-функций.

Этот проект намеренно является мостом, а не IDE или размещённым рабочим пространством разработчика.

GitHub Copilot / MCP client
          |
          | Streamable HTTP MCP + Bearer token
          v
https://...modal.run/mcp/
          |
          v
modal-workspace-mcp gateway
          |
          +--> Modal Sandbox --> apt / git / curl / uv / pip / GPU / Internet
          |
          +--> deployed Modal Function

Инструменты V1

• sandbox_create — создаёт автономную Sandbox с настраиваемыми CPU/RAM/GPU, apt/pip-пакетами, сетевой политикой, Secrets и Volumes из белого списка.

• sandbox_exec — выполняет команды bash -lc и возвращает код выхода/stdout/stderr.

• sandbox_status — проверяет, запущена ли Sandbox.

• sandbox_list — перечисляет Sandbox, управляемые этим MCP.

• sandbox_snapshot — создаёт снимок файловой системы Sandbox в Modal Image.

• sandbox_terminate — завершает работу Sandbox.

• function_call — вызывает уже развёрнутую Modal Function по имени приложения/функции.

• app_get — определяет именованное Modal App и URL панели управления.

• app_list — перечисляет Modal Apps через официальный CLI modal app list --json.

Почему это решает проблему DNS в GitHub-контейнере

GitHub-агент не выполняет apt, curl, git clone или pip локально. Он лишь отправляет MCP HTTP-запрос к вашему Modal endpoint. Фактические сетевые операции и операции в оболочке выполняются внутри Modal Sandbox.

1. Настройте токен шлюза

Сгенерируйте случайный токен локально:

python -c "import secrets; print(secrets.token_urlsafe(48))"

Создайте Modal Secret с именем modal-workspace-mcp-auth, содержащий это значение:

modal secret create modal-workspace-mcp-auth MODAL_WORKSPACE_MCP_TOKEN='<generated-token>'

Тот же Secret шлюза может также содержать несекретную конфигурацию, например, белые списки, чтобы развёрнутая Function получала их как переменные окружения.

Не коммитьте токен.

2. Необязательно: разрешите использование Secrets и Volumes в Sandbox

MCP по умолчанию запрещает монтирование произвольных Secret/Volume. Если они вам нужны, настройте белые списки на gateway Function.

Переменные окружения, поддерживаемые сервером:

MODAL_WORKSPACE_ALLOWED_SECRETS=github-agent,huggingface-agent
MODAL_WORKSPACE_ALLOWED_VOLUMES=model-cache,workspace-cache
MODAL_WORKSPACE_SANDBOX_APP=modal-workspace-sandboxes
MODAL_WORKSPACE_MAX_OUTPUT_CHARS=120000

Например, создайте учётные данные как отдельные Modal Secrets:

modal secret create github-agent GH_TOKEN="$GH_TOKEN"
modal secret create huggingface-agent HF_TOKEN="$HF_TOKEN"

Затем обновите gateway Secret, чтобы эти имена Secret были явно включены в белый список (их значения по-прежнему хранятся в отдельных Secrets):

modal secret create modal-workspace-mcp-auth \
  MODAL_WORKSPACE_MCP_TOKEN='<generated-token>' \
  MODAL_WORKSPACE_ALLOWED_SECRETS='github-agent,huggingface-agent'

3. Развёртывание

При локальной аутентификации Modal:

uv sync
uv run modal deploy modal_app.py

Modal выведет публичный URL Web Function. MCP endpoint — это этот URL плюс /mcp/.

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

curl https://YOUR-ENDPOINT.modal.run/healthz

Для MCP Inspector:

npx @modelcontextprotocol/inspector

Используйте Streamable HTTP, URL:

https://YOUR-ENDPOINT.modal.run/mcp/

и заголовок:

Authorization: Bearer <generated-token>

4. Облачный агент GitHub Copilot

Настройте эти значения Agents в целевом GitHub-репозитории:

COPILOT_MCP_MODAL_URL=https://YOUR-ENDPOINT.modal.run
COPILOT_MCP_MODAL_GATEWAY_TOKEN=<generated-token>

Затем используйте конфигурацию MCP репозитория из .mcp.json:

{
  "mcpServers": {
    "modal-workspace": {
      "type": "http",
      "url": "${COPILOT_MCP_MODAL_URL}/mcp/",
      "headers": {
        "Authorization": "Bearer ${COPILOT_MCP_MODAL_GATEWAY_TOKEN}"
      },
      "tools": [
        "sandbox_create",
        "sandbox_exec",
        "sandbox_status",
        "sandbox_list",
        "sandbox_snapshot",
        "sandbox_terminate",
        "function_call",
        "app_get",
        "app_list"
      ]
    }
  }
}

Облачный агент GitHub Copilot поддерживает удалённые HTTP MCP-серверы и подстановку секретов/переменных Agents с префиксом COPILOT_MCP_. Удалённый MCP на основе OAuth здесь намеренно не используется; шлюз использует Bearer-токен.

4A. Установка в качестве плагина GitHub Copilot

Этот репозиторий также является небольшим маркетплейсом плагинов Copilot. После публикации его на GitHub целевой репозиторий может включить плагин с помощью .github/copilot/settings.json, используя шаблон из examples/github-copilot-settings.json:

{
  "enabledPlugins": {
    "modal-workspace@modal-workspace-mcp": true
  },
  "extraKnownMarketplaces": {
    "modal-workspace-mcp": {
      "source": {
        "source": "github",
        "repo": "xiaoqianran/modal-workspace-mcp"
      }
    }
  }
}

Запись маркетплейса указывает на plugins/modal-workspace/, чей .mcp.json подключает Copilot к развёрнутому Modal HTTP MCP endpoint. Для первой отладки вы также можете настроить тот же удалённый MCP напрямую в настройках Copilot MCP репозитория, прежде чем тестировать установку плагина.

5. Первый сквозной тест

Попросите Copilot выполнить эквивалент:

1. Call sandbox_create with timeout_seconds=1800.
2. Call sandbox_exec on the returned sandbox_id with:
   apt-get update && apt-get install -y ffmpeg && git --version && curl -I https://github.com
3. Return the exit code and the last part of stdout/stderr.
4. Call sandbox_terminate.

Более серьёзный тест:

Create a Modal Sandbox, clone a public GitHub repository into /root/repo,
install its dependencies, run its tests, report results, then terminate the Sandbox.
Do not use the local GitHub agent shell for network operations.

Модель безопасности

• HTTP MCP endpoint требует Bearer-токен.

• Монтирование Secret и Volume в Sandbox запрещено по умолчанию и основано на белых списках.

• Значения Secret никогда не принимаются в качестве аргументов инструментов MCP.

• Вывод усекается, чтобы избежать неконтролируемых MCP-ответов.

• Sandbox тегируются и изолируются в рамках выделенного Modal App.

• Выполняйте разрушительные операции внутри Sandbox.

• Предпочитайте выделенный GitHub-токен с минимальными правами доступа к репозиторию, а не широкий личный токен.

Локальная проверка

Репозиторий содержит вспомогательные тесты без зависимостей:

python -m unittest discover -s tests -v
python -m compileall modal_workspace_mcp modal_app.py

Полное интеграционное тестирование MCP/Modal требует доступа в Интернет и аутентифицированного аккаунта Modal.