atlas-introspect-mcp

MCP-сервер, который позволяет ATLAS смотреть на себя — и редактировать себя:

Почему это работает через HTTP API

История чатов, рабочие области и промпты хранятся в одном файле DuckDB (data/chat_history.db). DuckDB поддерживает только одного писателя, и процесс ATLAS удерживает блокировку записи всё время своей работы — второй процесс, открывающий файл, даже в режиме только для чтения, завершается ошибкой конфликта блокировок. Поэтому этот сервер обращается к ATLAS через loopback HTTP. Это также означает, что ограничение по пользователям обеспечивается ATLAS, а не переопределяется здесь.

Напрямую изменяются только mcp.json и prompts/*.md; у ATLAS нет API ни для того, ни для другого.

Отдельный процесс — это то, что делает обратный вызов к ATLAS безопасным: ATLAS ожидает ответ этого сервера через stdio, пока его собственный цикл событий остаётся свободным для обработки запроса. Инструмент внутри процесса, делающий то же самое, привёл бы к взаимоблокировке.

Related MCP server: Atlas MCP Server

Идентификация

Каждый запрос привязан к одному пользователю и отправляется с заголовком X-User-Email. При DEBUG_MODE=true ATLAS учитывает этот заголовок; при выключенном режиме заголовок — это то, что предоставил бы прокси аутентификации, так что один и тот же флаг работает в обоих случаях. По умолчанию используется test@test.com — тестовый пользователь, к которому ATLAS обращается в режиме отладки, и, следовательно, владелец разговоров, созданных через интерфейс на этом хосте.

Установка

git clone https://github.com/garland3/atlas-introspect-mcp
cd atlas-introspect-mcp
uv venv .venv
uv pip install -e ".[dev]" --python .venv/bin/python

Автономная проверка (при запущенном ATLAS):

.venv/bin/atlas-introspect-mcp --list-tools
.venv/bin/python -c "
import asyncio; from fastmcp import Client
from fastmcp.client.transports import StdioTransport
async def m():
    async with Client(StdioTransport(command='.venv/bin/atlas-introspect-mcp', args=['--stdio'])) as c:
        print(await c.call_tool('atlas_status', {}))
asyncio.run(m())"

Регистрация в ATLAS

Добавьте в ваш config/mcp.json ATLAS (абсолютные пути — команда ищется в PATH менеджера служб, а не вашей оболочки), затем перезапустите ATLAS:

"atlas_introspect": {
  "command": [
    "/abs/path/to/atlas-introspect-mcp/.venv/bin/atlas-introspect-mcp",
    "--stdio",
    "--atlas-url", "http://127.0.0.1:8090",
    "--user", "test@test.com"
  ],
  "cwd": "/abs/path/to/atlas-introspect-mcp",
  "transport": "stdio",
  "groups": ["users"],
  "description": "Introspect and configure this ATLAS instance: browse chat history, read/edit config/mcp.json, manage workspaces and custom prompts.",
  "short_description": "ATLAS self-introspection",
  "compliance_level": "Public"
}

Добавьте "--read-only" в команду для сборки только для просмотра; тогда каждый изменяющий инструмент будет отказываться вместо записи.

Порты: для stdio не нужны. --transport http по умолчанию использует 8101. Он категорически отказывается от порта 8080 — на хосте с k3s klipper-lb перенаправляет 8080 на Traefik включая 127.0.0.1, поэтому сервер, привязанный к этому адресу, ничего не получает, и каждый запрос возвращается как пустой 500 без записи в вашем журнале.

Конфигурация

У каждого флага есть эквивалент в виде переменной окружения.

Инструменты

Разговоры (только чтение) — list_conversations, search_conversations, get_conversation, list_conversation_tags

config/mcp.json — get_mcp_config, upsert_mcp_server, delete_mcp_server, replace_mcp_config

Рабочие области — list_workspaces, create_workspace, update_workspace, delete_workspace

Пользовательские промпты — list_custom_prompts, get_custom_prompt, create_custom_prompt, update_custom_prompt, delete_custom_prompt

Файлы промптов на диске — list_prompt_files, read_prompt_file, write_prompt_file

Здоровье — atlas_status

Что может укусить

• Изменения mcp.json не применяются сразу. ATLAS запускает stdio-серверы при старте. Каждый инструмент записи сообщает об этом в своём результате; применяйте с помощью systemctl --user restart atlas или ./redeploy.sh --no-pull.

• Редактирование собственной записи работает, но вступает в силу только после перезапуска — после чего сломанная запись означает, что этот сервер исчез, и вы не сможете исправить его изнутри ATLAS. Резервные копии сохраняются рядом с файлом как mcp.json.bak-<stamp>.

• upsert_mcp_server заменяет запись целиком, а не объединяет. Сначала прочитайте её, измените, отправьте всю обратно. То же самое для config рабочей области и content промпта.

• Инструменты разговоров предназначены только для чтения. В ATLAS есть конечные точки удаления; они намеренно не представлены здесь.

• write_prompt_file изменяет каждый чат в экземпляре. Он сначала создаёт резервную копию и, как и mcp.json, применяется при следующем перезапуске.

Тесты

.venv/bin/pytest

Они покрывают логику редактирования файлов и проверки (атомарная запись, резервное копирование, отказ от обхода каталогов, предупреждения линтера, режим только для чтения) во временном каталоге — запущенный ATLAS не требуется.