modal-workspace-mcp

Eine Remote-MCP-Brücke, die es GitHub Copilot, Copilot CLI und anderen MCP-Clients ermöglicht, dein Modal-Konto für Linux-Ausführung, Abhängigkeitsinstallation, Git-Operationen, GPU-Jobs und Aufrufe bereitgestellter Modal Functions zu nutzen.

Dieses Projekt ist bewusst eine Brücke, keine IDE und kein gehosteter Entwickler-Workspace.

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-Werkzeuge

• sandbox_create — erstellt eine eigenständige Sandbox mit konfigurierbarer CPU/RAM/GPU, apt/pip-Paketen, Netzwerkrichtlinie, zugelassenen Secrets und Volumes.

• sandbox_exec — führt bash -lc-Befehle aus und gibt Exit-Code/stdout/stderr zurück.

• sandbox_status — prüft, ob eine Sandbox läuft.

• sandbox_list — listet die von diesem MCP verwalteten Sandboxes auf.

• sandbox_snapshot — erstellt einen Snapshot des Sandbox-Dateisystems als Modal Image.

• sandbox_terminate — beendet eine Sandbox.

• function_call — ruft eine bereits bereitgestellte Modal Function über den App-/Funktionsnamen auf.

• app_get — löst eine benannte Modal App und die Dashboard-URL auf.

• app_list — listet Modal Apps über die offizielle modal app list --json-CLI-Oberfläche auf.

Warum dies das DNS-Problem des GitHub-Containers löst

Der GitHub-Agent führt apt, curl, git clone und pip nicht lokal aus. Er sendet lediglich eine MCP-HTTP-Anfrage an deinen Modal-Endpunkt. Die eigentlichen Netzwerk- und Shell-Operationen finden in einer Modal Sandbox statt.

1. Gateway-Token konfigurieren

Erzeuge lokal ein zufälliges Token:

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

Erstelle ein Modal Secret namens modal-workspace-mcp-auth, das diesen Wert enthält:

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

Dasselbe Gateway-Secret kann auch nicht-geheime Konfigurationen wie Zulassungslisten enthalten, sodass die bereitgestellte Function diese als Umgebungsvariablen erhält.

Führe keinen Commit des Tokens durch.

2. Optional: Sandbox-Secrets und -Volumes zulassen

Das MCP verweigert standardmäßig das willkürliche Mounten von Secrets/Volumes. Konfiguriere Zulassungslisten auf der Gateway-Function, falls du sie benötigst.

Vom Server verstandene Umgebungsvariablen:

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

Erstelle beispielsweise Anmeldedaten als separate Modal Secrets:

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

Aktualisiere dann das Gateway-Secret, sodass diese Secret-Namen explizit zugelassen werden (ihre Werte bleiben weiterhin in den separaten Secrets):

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

3. Bereitstellen

Wenn Modal lokal authentifiziert ist:

uv sync
uv run modal deploy modal_app.py

Modal gibt die öffentliche Web-Function-URL aus. Der MCP-Endpunkt ist diese URL plus /mcp/.

Health-Check:

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

Für den MCP Inspector:

npx @modelcontextprotocol/inspector

Verwende Streamable HTTP, URL:

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

und Header:

Authorization: Bearer <generated-token>

4. GitHub Copilot Cloud-Agent

Konfiguriere diese Agents-Werte im Ziel-GitHub-Repository:

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

Verwende dann die Repository-MCP-Konfiguration aus .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 Cloud-Agent unterstützt entfernte HTTP-MCP-Server und die Substitution von Agents-Secrets/Variablen mit dem Präfix COPILOT_MCP_. OAuth-basiertes Remote-MCP wird hier bewusst nicht verwendet; das Gateway verwendet ein Bearer-Token.

4A. Als GitHub Copilot-Plugin installieren

Dieses Repository ist auch ein kleiner Copilot-Plugin-Marketplace. Nach der Veröffentlichung auf GitHub kann ein Ziel-Repository das Plugin mit .github/copilot/settings.json aktivieren, wobei die Vorlage in examples/github-copilot-settings.json verwendet wird:

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

Der Marketplace-Eintrag verweist auf plugins/modal-workspace/, dessen .mcp.json Copilot mit dem bereitgestellten Modal-HTTP-MCP-Endpunkt verbindet. Für die erste Fehlersuche kannst du dasselbe Remote-MCP auch direkt in den Copilot-MCP-Einstellungen des Repositorys konfigurieren, bevor du die Plugin-Installation testest.

5. Erster End-to-End-Test

Bitte Copilot, das Äquivalent zu Folgendem zu tun:

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.

Ein stärkerer Test:

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.

Sicherheitsmodell

• Der HTTP-MCP-Endpunkt erfordert ein Bearer-Token.

• Das Mounten von Sandbox-Secrets und -Volumes ist standardmäßig verweigert und basiert auf Zulassungslisten.

• Secret Werte werden niemals als MCP-Tool-Argumente akzeptiert.

• Die Ausgabe wird abgeschnitten, um unkontrollierte MCP-Antworten zu vermeiden.

• Sandboxes werden getaggt und unter einer dedizierten Modal App isoliert.

• Halte destruktive Operationen innerhalb der Sandbox.

• Bevorzuge ein dediziertes GitHub-Token mit minimalen Repository-Berechtigungen gegenüber einem breit angelegten persönlichen Token.

Lokale Validierung

Das Repository enthält abhängigkeitsfreie Helfer-Tests:

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

Vollständige MCP/Modal-Integrationstests erfordern Internetzugang und ein authentifiziertes Modal-Konto.