Archive MCP Server

MCP-сервер, который предоставляет записи и логику хранения Enterprise Data Archival & Records Management System любому MCP-клиенту — Claude Code, Claude Desktop, Cursor или вашему собственному клиенту — через stdio.

Вместо того чтобы кликать по дашборду React в поисках ответа на «что мы можем архивировать в Finance?», вы спрашиваете модель, и она вызывает эти инструменты.

Инструменты

Related MCP server: EndpointRead-MCP

Ресурсы

Требования

Требуются Python 3.10+ и MCP SDK 2.x. В SDK v2 FastMCP переименован в MCPServer и перенесён в mcp.server.mcpserver; этот код рассчитан на v2. Доступ к данным — SQLAlchemy 2.x, с psycopg2 для PostgreSQL.

Установка

python -m venv .venv
source .venv/bin/activate          # macOS/Linux
.venv\Scripts\activate             # Windows

python -m pip install -r requirements.txt
python seed_db.py                  # builds the local demo database
python server.py --selftest        # sanity check, no MCP client needed

Затем проверьте его в реальной MCP-сессии:

python verify_mcp.py

Выбор базы данных

Сервер читает DATABASE_URL (из окружения или из файла .env — см. .env.example):

archive.db содержит синтетические записи, поэтому сервер — и --selftest — работает у любого, кто склонирует этот репозиторий без учётных данных. Это не другая кодовая база: seed_db.py создаёт ту же схему из пяти таблиц, которую использует производственная база данных (active_records, archived_records, retention_policy, audit_logs, documents), так что каждый запрос в server.py выполняется без изменений на любой из них.

Никогда не коммитьте настоящий DATABASE_URL. .env игнорируется гитом; .env.example — это коммитируемый шаблон.

Подключение к Claude Code

Из каталога проекта:

claude mcp add --scope project archive-system -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py
claude mcp list

--scope project записывает коммитируемый .mcp.json в корень проекта, так что любой, кто склонирует репозиторий, получит сервер. Запустите claude, подтвердите проектный сервер по запросу и проверьте /mcp — archive-system должен показывать Подключено с 6 инструментами. Затем спросите:

Какие записи ИТ-отдела просрочены для архивирования?

Если запуск не удался, выполните claude --debug=mcp и прочтите лог в ~/.claude/debug/.

Подключение к Claude Desktop

Добавьте это в claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "archive-system": {
      "command": "D:\\Python\\project\\archive-mcp\\.venv\\Scripts\\python.exe",
      "args": ["D:\\Python\\project\\archive-mcp\\server.py"]
    }
  }
}

Укажите в command Python из виртуального окружения, а не голый python — хост не наследует ни PATH вашего шелла, ни активированного виртуального окружения. В Windows оба путя должны содержать удвоенные обртные слэши.

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

Примечание для сборки Microsoft Store (MSIX) в Windows: её конфиг находится не в %APPDATA%, а в собственном каталоге пакета, %LOCALAPPDATA%\Packages\Claude_<id>\LocaCache\Roamng\Claude\. Она нормально запускает локальные stdio-серверы. Не пытайтесь проверить это по logs\mcp.log — этот файл может оставаться пустым и нетронутым, пока всё работает. Проверьте вместо этого процесс; сервер работает как дочерний процесс Claude Desktop:

Get-CimInstance Win32_Process -Filter "Name like '%python%'" |
  Where-Object { $_.CommandLine -like "*archive-mcp*" }

Заметки о дизайне

• Транспорт stdio, потому что клиент запускает сервер как дочерний процесс на той же машине. HTTP-транспорт имел бы смысл, есл бы сервер работал удалённо и обслуживал несколько клиентов.

• Единая точка подключения к хранилищу. _connect() возвращает Engine SQLAlchemy и является единственным местоом, которое знает, что за база данных. Запросы используют именованные бинд-параметры (:department), которые не зависят от диалекта, поэтому SQLite и PostgreSQL используют один набор запросов, а не два.

• pool_pre_ping=True, потому что бессерверный PostgreSQL (Neon и подобные) приостанавливает простой вычислений, а MCP-сервер простаивает между вопросами. Без этого первый вопрос после затишья падает на устраевшем соединении из пула.

• Право на архивирование вычисляется в Python, а не в SQL. Арифметика INTERVAL в PostgreSQL не имеет эквивалента в SQLite, а хранение сравнения в одном месте не даёт двум бэкендам расходиться. При нескольких тысячах активных строк эти затраты не стоят оптимизации.

• Возраст отсчитывается от joining_date. created_at — это временная метка массовой загрузки, одинаковая для всех строк, поэтому расчёт срока хранения от неё никогда не нашёл бы ничего подлежащего архивированию. joining_date — это дата уровня сотрудника, заменяющая дату докуента; в схеме нет даты докуента, и это реальный пробел, который стоит закрть выше по потоку.

• Состояние архивирования — это таблица, а не флаг. Запись живёт в active_records или в archived_records, и идемтификаторы стабильны при переезде, поэтому get_record проверяет обе таблицы. Стоlбец status — это статус трудоустройства и не связан с этим.

• Инструменты аннотированы как «только для чтения». Каждый несёт ToolAnnotations(read_only_hint=True, destructive_hint=False), так что клиент может отличить безопасный вызов от изменяющего состояние до его выполнения.

• По факту инструменты тоже только для чтения. Архивирование разрушительно и подчиняется политыке; archival_candidates намеренно сообщает, что можно было бы архивировать, и оставляяет рещение существущей плановой задаче. Предоставление разрушительного инструмента модели — это решение, которое требует сначала пути подтверждения.

• Докстринги — это API. Модель выбирает инструменты по докстрингам и аннотациям типов, поэтому там перечислены допустимые отделы и типы докуентов. Устаревший enum хуже, чем его отсутствие: модель передаёт правдоподобное значение, например Legal, получает пустой результат и сообщает, что архивировать нечего.

• Одно определение «подходящего для архивирования», используемое в обоих направлениях. _verdict определяет возраст записи относительно её срока хранения; _eligible_on инвертирует его, чтобы получить дату, когда запись пересекает этот срок, — именно по ней retention_forecast группирует. Они должны точьно совпадать, иначе в один и тот же день запись может появиться как предстощая в прогнозе и просроченная в archival_candidates. Если написать обратную функцию очевидным способом (joining + timedelta(days=years * 365.25)), это сломается, потомучто date + timedelta сохраняет только целые дни и молча теряет .75.

• Вывод — это форматированый текст, а не сырые JSON-дампы, так что модель может цитировать его пользователю без переформатирования.