Archive MCP Server

Un servidor MCP que expone los registros y la lógica de retención del Enterprise Data Archival & Records Management System a cualquier cliente MCP — Claude Code, Claude Desktop, Cursor, o tu propio cliente — a través de stdio.

En lugar de hacer clic en el panel de React para responder "¿qué podemos archivar en Finance?", le preguntas al modelo, y este llama a estas herramientas.

Herramientas

Related MCP server: EndpointRead-MCP

Recursos

Requisitos

Python 3.10+ y MCP SDK 2.x. El SDK v2 renombró FastMCP a MCPServer y lo movió a mcp.server.mcpserver; este código apunta a la v2. El acceso a datos es SQLAlchemy 2.x, con psycopg2 para PostgreSQL.

Configuración

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

Luego verifícalo en una sesión MCP real:

python verify_mcp.py

Elegir una base de datos

El servidor lee DATABASE_URL (del entorno, o de un archivo .env — consulta .env.example):

archive.db contiene registros sintéticos, de modo que el servidor — y --selftest — funcionan para cualquiera que clone este repositorio sin credenciales. No es un código distinto: seed_db.py construye el mismo esquema de cinco tablas que usa la base de datos de producción (active_records, archived_records, retention_policy, audit_logs, documents), de modo que todas las consultas de server.py se ejecutan sin cambios contra cualquiera de las dos.

Nunca hagas commit de un DATABASE_URL real. .env está en gitignore; .env.example es la plantilla versionada.

Conexión con Claude Code

Desde el directorio del proyecto:

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

--scope project escribe un .mcp.json listo para commit en la raíz del proyecto, de modo que cualquiera que clone el repositorio obtiene el servidor. Inicia claude, aprueba el servidor del proyecto cuando se te pida, y comprueba /mcp — archive-system debería mostrar Connected con 6 herramientas. Luego pregunta:

¿Qué registros del departamento de TI están vencidos para su archivado?

Si falla al iniciar, ejecuta claude --debug=mcp y lee el log en ~/.claude/debug/.

Conexión con Claude Desktop

Añade esto a 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"]
    }
  }
}

Apunta command al Python del venv, no al python a secas — el host no hereda el PATH de tu shell ni tu virtualenv activado. En Windows, ambas rutas necesitan barras invertidas dobles.

Reinícialo desde el icono de la bandeja del sistema — Quit, no el botón de cerrar la ventana — o la aplicación seguirá ejecutándose con la configuración anterior.

Nota para la compilación de Microsoft Store (MSIX) en Windows: su configuración no está en %APPDATA%, sino en el directorio propio del paquete, %LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\. Lanza los servidores stdio locales con normalidad. No intentes confirmarlo desde logs\mcp.log — ese archivo puede permanecer vacío e intacto mientras todo funciona. Comprueba en su lugar el proceso; el servidor se ejecuta como un proceso hijo de Claude Desktop:

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

Notas de diseño

• Transporte stdio, porque el cliente lanza el servidor como un subproceso en la misma máquina. Un transporte HTTP tendría sentido si el servidor se ejecutara de forma remota y atendiera a varios clientes.

• Una única costura para el almacenamiento. _connect() devuelve un Engine de SQLAlchemy y es el único lugar que sabe qué base de datos es. Las consultas usan parámetros de enlace con nombre (:department), que son neutrales al dialecto, de modo que SQLite y PostgreSQL comparten un único conjunto de consultas en lugar de dos.

• pool_pre_ping=True, porque un PostgreSQL serverless (Neon y compañía) suspende el cómputo inactivo y un servidor MCP permanece ocioso entre pregunta y pregunta. Sin esto, la primera pregunta tras un período de inactividad falla por una conexión obsoleta del pool.

• La elegibilidad se calcula en Python, no en SQL. La aritmética de INTERVAL de PostgreSQL no tiene equivalente en SQLite, y mantener la comparación en un solo lugar mantiene honestos a los dos backends. Con unos pocos miles de filas activas, el coste no merece la pena optimizarlo.

• La antigüedad se mide desde joining_date. created_at es la marca de tiempo de la carga masiva y es idéntica para todas las filas, de modo que la retención calculada a partir de ella no encontraría nada elegible, nunca. joining_date es una fecha a nivel de empleado que hace las veces de fecha del documento — el esquema no incluye ninguna fecha del documento, lo cual es una laguna real que merece la pena cerrar en el origen.

• El estado de archivado es una tabla, no una bandera. Un registro vive en active_records o en archived_records, y los ids son estables a lo largo del movimiento, de modo que get_record comprueba ambas. La columna status es el estado de empleo y no está relacionada.

• Las herramientas están anotadas como de solo lectura. Cada una lleva ToolAnnotations(read_only_hint=True, destructive_hint=False), de modo que un cliente puede distinguir una llamada segura de una que cambia el estado antes de ejecutarla.

• Las herramientas también son de solo lectura en la práctica. El archivado es destructivo y está sujeto a políticas; archival_candidates informa deliberadamente de lo que podría archivarse y deja la decisión al trabajo programado existente. Exponer una herramienta destructiva a un modelo es una decisión que requiere antes un flujo de confirmación.

• Los docstrings son la API. El modelo elige las herramientas a partir del docstring y de las type hints, así que los departamentos y tipos de documento válidos están enumerados allí. Un enum obsoleto es peor que ninguno: el modelo pasa un valor de apariencia plausible como Legal, obtiene un resultado vacío y reporta que no hay nada que archivar.

• Una única definición de "eligible", usada en ambas direcciones. _verdict calcula la antigüedad de un registro frente a su período de retención; _eligible_on la invierte para dar la fecha en que un registro cruza ese período, que es el criterio por el que agrupa retention_forecast. Deben coincidir exactamente, o un registro puede aparecer como próximo en la previsión y como vencido en archival_candidates el mismo día. Escribir la inversa de la manera obvia (joining + timedelta(days=years * 365.25)) lo rompe, porque date + timedelta conserva solo los días completos y descarta silenciosamente el .75.

• La salida es texto formateado, no volcados JSON en bruto, de modo que el modelo pueda citarlo de vuelta al usuario sin reformatearlo.