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, OAuth)
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 (см. ниже про формат)
env = { "EXTRA_FLAG" = "1" }   # plaintext-переменные прямо в config.toml (не для секретов)
cwd = "/path/to/dir"
enabled = true
required = false
startup_timeout_sec = 10

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

env_vars — массив: каждый элемент либо имя переменной окружения (значение берётся из env процесса), либо объект { name = "...", source = "..." } (name обязательно, source опционален — имя env-переменной-источника). source принимает значения local (по умолчанию) или remote — для проброса переменных из окружения remote-сессии.

env — plaintext-переменные { KEY = "value" }, заданные прямо в config.toml. Удобно для нечувствительных флагов; не используйте env для секретов — они хранятся в открытом виде. Для секретов применяйте env_vars (значение берётся из окружения процесса, не из config).

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

toml
[mcp_servers.remote_tools]
url = "https://mcp-server.example.com"
bearer_token_env_var = "MCP_AUTH_TOKEN"
bearer_token = "..."          # plaintext-токен (не рекомендуется — см. §10)
http_headers = { "X-Custom" = "value" }
enabled = true

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

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

toml
[mcp_servers.my_server]
command = "..."
args = ["..."]
env = { "EXTRA_FLAG" = "1" }                    # plaintext-переменные (не для секретов)
env_vars = ["VAR1", "VAR2"]
cwd = "/path"
url = "https://..."
bearer_token_env_var = "..."
bearer_token = "..."                            # plaintext-токен (не рекомендуется — см. §10)
http_headers = { "X-Custom" = "value" }
env_http_headers = { "X-Token" = "TOKEN_ENV_VAR" }  # значение берётся из env-переменной

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

default_tools_approval_mode = "prompt"   # auto | prompt | approve
supports_parallel_tool_calls = true
startup_timeout_sec = 10
startup_timeout_ms = 10000  # альтернатива для большей точности; при наличии обоих полей sec приоритетнее
tool_timeout_sec = 60       # только секунды (дробное, напр. 0.5); аналога в ms нет

# Списки имён tools на уровне сервера:
disabled_tools = ["dangerous_tool"]
enabled_tools = ["safe_tool_a", "safe_tool_b"]

# OAuth (для HTTP-серверов с OAuth2):
scopes = ["repo", "read:user"]
oauth_resource = "https://api.example.com"

# Per-tool override (только approval_mode):
[mcp_servers.my_server.tools.dangerous_tool]
approval_mode = "prompt"

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

Per-tool override [mcp_servers.<name>.tools.<tool>] поддерживает только approval_mode; чтобы полностью отключить tool, используйте disabled_tools = [...] на уровне сервера.

4. Источники MCP-серверов

[mcp_servers.*] собирается не из одного файла, а из многослойного стека конфигурации (слои объединяются, верхние приоритетнее):

Слой Где Назначение
MDM managed preferences (macOS) Корпоративные политики
System managed_config.toml Системный файл
User ~/.astracode/config.toml Пользовательский config (сюда пишет astracode mcp add)
Project .astracode/config.toml Привязка серверов к конкретному репо (несколько между cwd и корнем)
SessionFlags переопределения -c/--config Одноразовые переопределения запуска

Таким образом, сервер можно задать глобально (user) или привязать к проекту (.astracode/config.toml внутри репо). CLI astracode mcp add всегда пишет в user-слой ($ASTRACODE_HOME).

Дополнительно MCP-серверы могут поставляться плагинами — плагин декларирует свои серверы, и они добавляются в общий пул. Если имя сервера из плагина совпадает с уже заданным в config.toml, пользовательский config выигрывает (плагин не перезаписывает существующее имя).

5. OAuth2 для HTTP-MCP

Для серверов, требующих OAuth2, укажите url без bearer_token_env_var — AstraCode пройдёт OAuth-flow при первом подключении (откроется браузерный flow на 127.0.0.1).

Хранилище OAuth-credentials настраивается на верхнем уровне config (не внутри [mcp_servers.*]):

toml
mcp_oauth_credentials_store = "auto"   # keyring | file | auto (по умолчанию auto — можно не указывать)
# auto: keyring если доступен, иначе файл в ~/.astracode/
mcp_oauth_callback_port = 8765         # опц. фиксированный порт callback-сервера
mcp_oauth_callback_url = "http://127.0.0.1:8765/callback"  # опц. redirect URI

Login/logout для конкретного сервера — через CLI astracode mcp login <name> / astracode mcp logout <name> (см. §7).

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

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

bash
astracode mcp-server

В Claude Desktop конфиг:

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

Транспорт — stdio; HTTP-транспорта для встроенного MCP-сервера нет.

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

bash
astracode mcp list                  # список всех настроенных серверов (--json для JSON)
astracode mcp get my_server         # показать конфиг сервера (--json)
astracode mcp add my_server -- python -m my_mcp_server          # stdio-сервер
astracode mcp add my_server --url https://srv.example.com       # streamable HTTP
astracode mcp add my_server --url https://srv.example.com --bearer-token-env-var TOKEN  # HTTP + bearer
astracode mcp remove my_server     # удалить сервер из конфига
astracode mcp login my_server      # запустить OAuth-flow (--scopes для скоупов)
astracode mcp logout my_server     # стереть сохранённый OAuth-токен

astracode mcp add всегда пишет в user-слой ($ASTRACODE_HOME/config.toml). Для project-level серверов редактируйте .astracode/config.toml вручную. Флаг --bearer-token-env-var требует --url (только для HTTP).

8. В TUI

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

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

/mcp — только просмотр; добавлять/удалять серверы через TUI нельзя (используйте CLI или TOML).

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

text
TUI startup
  ↓
app-server загружает [mcp_servers.*] из config-стека (user + project + ...)
  ↓
Для каждого 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: закрывает соединение

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

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

bash
RUST_LOG=astracode_mcp=debug astracode

В TUI:

text
/mcp verbose

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

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

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

  • Все вызовы инструментов проходят через approval_mode.
  • Можно отключить конкретные tools списком disabled_tools = ["..."] на уровне сервера.
  • HTTP-серверы должны иметь TLS; bearer-токены берутся из env (bearer_token_env_var), а не из config.toml в plaintext. Поле bearer_token (plaintext) технически поддерживается, но не рекомендуется — используйте bearer_token_env_var.
  • Stdio-серверы: env_vars берёт значения из окружения процесса; env хранит значения в config.toml в открытом виде — не кладите туда секреты.
  • Stdio-серверы запускаются с inherited env, но shell_environment_policy к ним не применяется — будьте внимательны при экспорте секретов.

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

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

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

13. Подключение к удалённому app-server через MCP

AstraCode как MCP-сервер работает только по stdio. Для удалённого доступа к app-server используйте нативный remote-режим app-server (UDS/TCP через app-server-client), а не HTTP-транспорт MCP.

ESC