Claude-Atlas-MCP

Самостоятельно размещаемый MCP-сервер, который дает Клоду постоянную память между разговорами — сущности, наблюдения, история, временные напоминания, а также лоток для поступающих вещей и полка для идей — в легковесном бэкенде на Node/SQLite, который вы запускаете сами.

Укажите Клоду на него как на MCP-коннектор, и он сможет запоминать, над чем вы работаете, от одного разговора к другому: текущие проекты, решения и их обоснование, факты о вас и вашей среде, а также вещи, которые нужно всплыть в будущем.

Зачем

Клод забывает всё, когда разговор заканчивается. Atlas — это маленький, скучный, надежный слой памяти, которым вы владеете от начала до конца — никаких сторонних сервисов, никакой привязки к вендору. Это один процесс Node, работающий на одном файле SQLite. Запускайте его на домашнем сервере, VPS или ноутбуке.

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

Related MCP server: Cortex

Быстрый старт

git clone https://github.com/dcazman/Claude-Atlas-MCP.git
cd Claude-Atlas-MCP
docker compose up -d --build
docker compose logs atlas-mcp

Никакого .env, никакого токена, никакой конфигурации. При первом запуске Atlas создает базу данных, генерирует по одному токену на область и выводит их:

    work     3f2a…   (caller "work-client")
    personal 9c41…   (caller "personal-client")
    shared   b7e0…   (caller "shared-client")

  Connect a client to:  http://localhost:7784/atlas-mcp?token=<one of the above>

Токены сохраняются рядом с базой данных и используются повторно при каждом перезапуске. Данные хранятся в ./data, одном файле SQLite. Это вся настройка.

Проверьте, что работает:

curl -s localhost:7784/health
# {"ok":true,"service":"atlas-mcp","version":2,"port":"7784"}

TOKEN=<one of the tokens printed above>
curl -s -X POST localhost:7784/atlas-mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H "x-atlas-token: $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":
       {"name":"add_observation","arguments":
        {"section":"work","entity":"Atlas","content":"Installed today."}}}'

Если это возвращает observation_id, весь стек работает: ваша первая память на диске, и Клод может ее прочитать.

CI публикует образ при каждом пуше в main, если вы предпочитаете не собирать:

docker run -d --name atlas -p 7784:7784 -v "$PWD/atlas-data:/app/data" \
  ghcr.io/dcazman/claude-atlas-mcp:latest
docker logs atlas

Чистый Node — 22.13+ для встроенного node:sqlite. Никаких нативных зависимостей, ничего компилировать:

npm install
npm start

Чтобы выбрать собственные токены, часовой пояс или час уборки вместо значений по умолчанию, выполните cp .env.example .env и раскомментируйте то, что нужно. Копирование без изменений ничего не меняет — каждая строка намеренно закомментирована.

Модель данных

Воронка

Три поверхности в порядке возрастания обязательств:

  shelf  ──graduate──▶  tray  ──promote──▶  memory
 (ideas)              (triage)          (observations)

• Полка хранит то, что вы придумали. Идея, лежащая там год, — это не провал бэклога, это полка работает. Идеи покидают полку, переходя в лоток или будучи намеренно убитыми, с сохранением причины.

• Лоток хранит то, что поступило. Это очередь, а не куча: захватить, затем продвинуть, объединить или отклонить.

• Память — это часть, которую Клод считывает в начале разговора.

Ничто не уничтожается на пути. Решенные элементы перестают отображаться, но сохраняют свою историю, включая то, во что они превратились.

Как вы на самом деле видите это. get_landscape — это единственный вызов, который Клод делает в начале разговора, поэтому все, что требует вашего внимания, должно возвращаться в нем:

Так что «захватить сейчас, решить позже» работает: все, что вы бросаете в лоток в середине разговора, возвращается в начале следующего, без необходимости помнить о его существовании.

Инструменты

31 MCP-инструмент.

Чтение

• get_landscape — все в разделе (с объединенным shared): все сущности с их наблюдениями, просроченные напоминания, неотсортированные элементы лотка и количество открытых идей на полке. Вызывайте в начале разговора, чтобы сориентироваться.

• search — поиск по ключевым словам по сущностям, наблюдениям и истории.

• get_entity — одна сущность и ее наблюдения по имени.

• get_observation — получить до 20 наблюдений напрямую по id. Id стабильны и никогда не используются повторно, что делает их дешевым способом передавать конкретные факты из одного разговора в другой.

• get_history — временная шкала зарегистрированных событий.

• get_time — текущее время плюс время с последнего вызова этого токена.

Запись

• upsert_entity — создать или обновить имя/описание сущности.

• add_observation — прикрепить факт к сущности.

• update_observation — редактировать факт на месте; id остается стабильным. Работает с защищенными строками.

• remove_observation — удалить факт, который устарел или завершен (отказывается, если защищен).

• protect_observation / unprotect_observation — пометить факт как неудаляемый или снять эту пометку.

• remove_entity — удалить сущность и ее наблюдения (отказывается, если какое-либо защищено).

• log_event — записать примечательное событие в историю.

Напоминания

• create_reminder — заметка с trigger_date, необязательным trigger_time и необязательной ссылкой на сущность.

• list_reminders — все запланированные, просроченные или нет.

• list_due_reminders — все, что должно быть выполнено прямо сейчас. Это то, что опрашивает уведомитель.

• mark_reminder_fired — пометить временное напоминание как доставленное, чтобы оно никогда не сработало дважды.

• dismiss_reminder — пометить напоминание как обработанное (оно перестает всплывать).

• remove_reminder — полностью удалить напоминание.

Лоток

• pending_add — захватить то, что поступило.

• pending_list — что еще требует сортировки, сначала самое старое.

• pending_promote — превратить захват в наблюдение на сущности.

• pending_merge — свернуть дубликат в тот, который вы сохраняете.

• pending_dismiss — решить, что оно не требует ничего, с сохранением причины.

• pending_reopen — отменить любое из вышеперечисленных.

Полка

• research_add — припарковать идею.

• research_list — открытые идеи, сначала самые старые.

• research_promote — перевести идею в лоток.

• research_kill — намеренно удалить идею, с указанием причины.

• research_reopen — вернуть обратно.

Каждый ответ инструмента содержит небольшой временной нижний колонтитул — текущее время сервера в вашем настроенном часовом поясе плюс прошедшее время с последнего вызова этого токена — чтобы модели никогда не приходилось гадать или выполнять вычисления дат на основе устаревших мысленных часов.

Получение уведомлений

Atlas никогда ничего не отправляет сам — он понятия не имеет, где вы хотите быть достигнуты. Вместо этого list_due_reminders — это контракт для всего, что это делает:

1. Опрашивайте list_due_reminders с любым интервалом, который вам подходит.

2. Доставляйте строки, содержащие trigger_time (пассивные просто ждут, чтобы их увидели в ландшафте).

3. Вызывайте mark_reminder_fired для каждой доставленной строки.

Шаг 3 обеспечивает доставку ровно один раз: метка защищена в SQL, поэтому два перекрывающихся опрашивателя не могут отправить дважды. Дюжины строк скрипта, управляемого cron, достаточно, чтобы подключить это к электронной почте, вебхуку чата или push-уведомлению на телефоне.

Работник уборки

src/groom.js запускается каждую ночь внутри процесса сервера (не нужен cron на хосте) или по требованию с помощью npm run groom. Он намеренно только для отчетов и механический — никаких вызовов LLM, никакого удаления ваших данных:

• помечает вероятные почти дублирующиеся наблюдения внутри сущности

• помечает бездействующие сущности (60+ дней без изменений) как кандидаты на архивацию/сжатие

• помечает давно отклоненные напоминания (90+ дней) как кандидаты на удаление

• ротирует собственный audit_log (90+ дней) — единственное, что он фактически удаляет

• пропускает сущности, не тронутые с последнего запуска, поэтому повторные запуски дешевы

Результаты попадают в сущность «Groom Report» для каждого раздела, чтобы вы (или Клод) могли на них отреагировать. Он запускается в ATLAS_GROOM_HOUR (по умолчанию 4 утра) в вашем часовом поясе и самовосстанавливается: окно, пропущенное из-за остановки контейнера, запускается при следующей проверке.

Подключение Клода

Atlas общается по MCP через потоковый HTTP по адресу POST /atlas-mcp. Добавьте его как коннектор, используя URL сервера с вашим токеном:

https://<your-host>/atlas-mcp?token=<your-secret>

Токен — это секретная половина тройки ATLAS_TOKEN (см. Конфигурацию). Вы также можете передать его как заголовок X-Atlas-Token или токен Bearer вместо строки запроса.

В URL нет section — каждый инструмент принимает аргумент section, и какой из них должен быть по умолчанию для данного разговора, лучше всего задать в пользовательских инструкциях вашего проекта Claude (например, «Ваш раздел Atlas — personal»). Конечная точка GET /health доступна для проверки работоспособности.

Для реального использования вам понадобится HTTPS — обратный прокси или туннель (Cloudflare Tunnel, Tailscale, nginx и т.д.) перед контейнером. Токен — единственная аутентификация, поэтому не открывайте порт публично без TLS.

После подключения хорошей привычкой будет попросить Клода вызывать get_landscape в начале каждого разговора и обновлять записи по мере изменений. Сервер поставляется с инструкциями, которые говорят именно об этом, так что большинство клиентов подхватывают это без вашего участия.

Обеспечение безопасности

Встроенная аутентификация Atlas — это общий токен — хорошо за частной сетью или туннелем, но слабо, если вы выставляете его в интернет. Для реального контроля доступа поставьте перед ним выделенный шлюз аутентификации, а не укрепляйте этот сервер самостоятельно.

mcp-auth-proxy — это готовый шлюз OAuth 2.1 / OIDC для MCP-серверов, не требующий изменений в коде Atlas:

• Аутентификация через собственного IdP (Google, GitHub, Okta, Auth0, Azure AD, Keycloak, любой OIDC-провайдер) с опциональным паролем.

• Авторизация пользователей по точному совпадению или glob (например, *@yourcompany.com).

• Завершает TLS и проксирует HTTP-транспорт как есть, проверено на Claude, Claude Code, ChatGPT, Copilot и Cursor.

В общих чертах, вы направляете его на HTTP-эндпоинт Atlas:

./mcp-auth-proxy \
  --external-url https://<your-domain> \
  --tls-accept-tos \
  -- http://localhost:7784/atlas-mcp

См. документацию по настройке и конфигурации IdP. (Не аффилирован — просто хорошо подходит для самостоятельно размещённых MCP-серверов, таких как этот.)

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

Всё опционально. Задаётся через .env (см. .env.example) или переменные окружения:

Как сделать своим

Дизайн намеренно компактен, чтобы вы могли расширять его без борьбы.

• Добавить инструмент. Всё находится в src/tools.js, регистрируется через единую обёртку guarded(), которая выполняет проверку scope и запись аудита. Новый инструмент — это блок guarded(name, {description, inputSchema}, handler) плюс функция в src/db.js. Описание важнее кода — именно его читает Claude, чтобы решить, когда его использовать.

• Добавить таблицу. Миграции — это лестница PRAGMA user_version в src/db.js: увеличьте номер, напишите аддитивный SQL, защищённый этим номером, готово. Каждая миграция идемпотентна и выполняется при запуске, так что обновление — это просто перезапуск.

• Перенести правила в базу данных. Стиль проекта таков: правило, которое нужно помнить, — это правило, которое нарушается. Поэтому resolved_at проставляется триггером, scope проверяется на сервере, а защищённые строки защищены в SQL. Следуйте этому шаблону, и ваши дополнения унаследуют его.

• Изменить разделы. work/personal/shared зафиксированы в CHECK-ограничениях схемы и в карте scope в src/server.js. Переименование — это миграция плюс правка карты из двух строк; стоит сделать, если словарь не подходит под вашу жизнь.

Тесты

npm test

Каждый запуск начинается с пустой базы данных, поэтому набор тестов также служит проверкой «с чистого листа»: схема строится с нуля, матрица scope токенов работает (в том числе то, что идентификаторы вне scope неотличимы от несуществующих), временные напоминания срабатывают ровно один раз, а воронка перемещает элементы так, как заявлено.

Безопасность

См. SECURITY.md — модель угроз, рекомендации по усилению развёртывания и как сообщить об уязвимости.

Изменения

См. CHANGELOG.md. Кратко: в v3 добавлены лоток, полка, временные напоминания, адресация по observation-id и запуск без конфигурации.

Лицензия

MIT — см. LICENSE.