0.4.11
Поиск по документации… ⌘K
06 · Техническая документация

06. MCP (Model Context Protocol)

MCP — открытый протокол для интеграции внешних инструментов в LLM-агентов. AstraCode выступает и клиентом (подключается к внешним MCP-серверам), и сервером (может сам выставляться наружу).

1. Крейты

Крейт Назначение
mcp Клиент: менеджер MCP-серверов, регистрация инструментов
mcp-server Сервер: AstraCode как MCP-сервер для других клиентов
rmcp-client Низкоуровневый клиент (transport, framing)
stdio-to-uds Мост stdio↔UDS — для удалённого MCP-сервера через сокет

2. Транспорты

AstraCode поддерживает два транспорта для подключения к MCP-серверам:

Stdio (локальный процесс)

toml
[mcp_servers.local_tools]
command = "python"
args = ["-m", "my_mcp_server"]
env_vars = ["API_KEY"]   # переменные пробрасываются из текущего env
cwd = "/path/to/dir"
enabled = true
required = false
startup_timeout_sec = 10

AstraCode запускает процесс, пишет JSON-RPC сообщения в stdin, читает ответы из stdout. stderr идёт в логи.

Streamable HTTP / SSE (удалённый)

toml
[mcp_servers.remote_tools]
url = "https://mcp-server.example.com"
bearer_token_env_var = "MCP_AUTH_TOKEN"
http_headers = { "X-Custom" = "value" }
enabled = true

Используется HTTP с поддержкой Server-Sent Events для стриминга. Поддерживается OAuth2 (см. ниже).

3. Параметры конфигурации

toml
[mcp_servers.my_server]
command = "..."
args = ["..."]
env_vars = ["VAR1", "VAR2"]
cwd = "/path"
url = "https://..."
bearer_token_env_var = "..."
http_headers = { ... }

enabled = true
required = false
# required = true → если сервер не отвечает, AstraCode остановит старт

default_tools_approval_mode = "prompt"   # auto | prompt | approve
supports_parallel_tool_calls = true
startup_timeout_sec = 10

# Per-tool overrides:
[mcp_servers.my_server.tools.dangerous_tool]
approval_mode = "prompt"
disabled = false
display_name = "Dangerous Tool"

default_tools_approval_mode: - auto — AstraCode сам решает по полю tool'а requires_approval. - prompt — каждый вызов требует подтверждения пользователя. - approve — без подтверждений (использовать осторожно).

4. OAuth2 для HTTP-MCP

Для серверов, требующих OAuth2:

toml
[mcp_servers.github]
url = "https://api.github.com/mcp"
# bearer_token_env_var не указан → AstraCode пройдёт OAuth-flow

mcp_oauth_credentials_store = "keyring"   # keyring | file | auto

OAuth-токены хранятся в keyring (или в зашифрованном файле как запасной вариант). При первом подключении открывается браузерный flow.

5. Встроенный MCP-сервер

astracode mcp-server запускает AstraCode как MCP-сервер, экспонируя его возможности (codebase navigation, file edit, run tests) другим клиентам — например, Claude Desktop или другому AstraCode.

bash
astracode mcp-server          # запуск как child process (только stdio)

Транспорт — только stdio. HTTP-режима у встроенного сервера нет: подкоманда mcp-server не принимает флагов --transport/--port.

В Claude Desktop конфиг:

json
{
  "mcpServers": {
    "astracode": {
      "command": "astracode",
      "args": ["mcp-server"]
    }
  }
}

6. Команды CLI для MCP

bash
astracode mcp list                          # список всех настроенных серверов
astracode mcp get my_server                 # показать конфигурацию одного сервера
astracode mcp add my_server -- cmd args...   # добавить stdio-сервер (или --url <URL> для streamable HTTP)
astracode mcp remove my_server              # удалить сервер из конфига
astracode mcp login my_server               # запустить OAuth-flow
astracode mcp logout my_server              # стереть сохранённый OAuth-токен

7. В TUI

text
/mcp           # краткий список серверов и количества tools
/mcp verbose   # подробно: имена tools, описания, статус auth

В status-баре можно показать число активных MCP — настроить через /statusline.

8. Жизненный цикл MCP-сервера

text
TUI startup
  ↓
app-server загружает [mcp_servers.*] из config.toml
  ↓
Для каждого enabled-сервера:
  - Stdio: spawn процесс, посылает `initialize` RPC
  - HTTP: handshake, OAuth если нужен
  ↓
Получает список tools, регистрирует в реестре
  ↓
Когда модель вызывает tool:
  - Проверяется approval_mode
  - Если prompt → диалог пользователю
  - Если approved → RPC `tools/call` к серверу
  - Результат возвращается в модель
  ↓
TUI shutdown:
  - Stdio: graceful close stdin → ждёт exit
  - HTTP: закрывает соединение

9. Логирование и отладка

Логи MCP пишутся в ~/.astracode/log/astracode-tui.log с префиксом mcp::. Для детальной отладки:

bash
RUST_LOG=astracode_mcp=debug astracode

В TUI:

text
/mcp verbose

покажет статусы (connected / disconnected / error) и последние ошибки.

10. Безопасность MCP

Каждый MCP-сервер — это отдельный процесс или удалённый сервис, не доверенный AstraCode'у автоматически:

  • Все вызовы инструментов проходят через approval_mode.
  • Можно отключить конкретные tools: tools.<name>.disabled = true.
  • HTTP-серверы должны иметь TLS; bearer-токены берутся из env (не из config.toml в plaintext).
  • Stdio-серверы запускаются с inherited env, но shell_environment_policy к ним не применяется — будьте внимательны при экспорте секретов.

11. Популярные MCP-серверы (примеры)

  • filesystem — расширенная работа с файлами.
  • git-mcp — git operations через MCP вместо встроенных tools.
  • playwright-mcp — браузер-автоматизация (альтернатива встроенному скиллу).
  • postgres-mcp — выполнение SQL-запросов.
  • github-mcp — issues, PRs, releases (требует OAuth).

См. официальный реестр MCP-серверов.

12. AstraCode как MCP-сервер для других клиентов

Встроенный MCP-сервер работает только по stdio и запускается клиентом как дочерний процесс (см. раздел 5). HTTP-режима serve у AstraCode нет, поэтому слушать порт и подключаться по http://localhost:... нельзя.

bash
# Клиент (например, Claude Desktop) сам спаунит процесс:
astracode mcp-server

Для интеграций IDE используется отдельная подкоманда astracode app-server (тоже stdio-транспорт), а не MCP.

ESC