Archive MCP Server

一个 MCP 服务器，通过 stdio 将 Enterprise Data Archival & Records Management System 的记录和保留逻辑暴露给任何 MCP 客户端——Claude Code、Claude Desktop、Cursor，或你自己的客户端。

你不再需要在 React 仪表板中层层点击去回答*“财务部门可以归档什么？”*——直接问模型，模型就会调用这些工具。

工具

Related MCP server: EndpointRead-MCP

资源

环境要求

需要 Python 3.10+ 和 MCP SDK 2.x。v2 SDK 将 FastMCP 重命名为 MCPServer， 并移到了 mcp.server.mcpserver；本代码面向 v2。数据访问使用 SQLAlchemy 2.x，PostgreSQL 使用 psycopg2。

安装

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 已被加入 gitignore；.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 个工具。 然后提问：

哪些 IT 部门的记录已超过保留期限、需要归档？

如果启动失败，请运行 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 指向 venv 中的 Python，而不是直接写 python——宿主进程不会 继承你 shell 的 PATH，也不会继承你激活的虚拟环境。在 Windows 上，两个路径 都需要写成双反斜杠。

从托盘图标重启——选择 退出，而不是点窗口的关闭按钮——否则应用会继续 使用旧配置运行。

关于 Windows 上 Microsoft Store (MSIX) 版本的说明：其配置不在 %APPDATA% 下，而在软件包自己的目录下， %LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\。它可以正常 启动本地 stdio 服务器。不要试图通过 logs\mcp.log 来确认这一点——一切正常时， 该文件也可能始终是空的、从未被写入。请改为检查进程；服务器作为 Claude Desktop 的子进程运行：

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

设计说明

• stdio 传输，因为客户端将服务器作为同一台机器上的子进程启动。如果服务器 在远端运行并为多个客户端服务，HTTP 传输才更有意义。

• 存储层只有一个接缝。 _connect() 返回一个 SQLAlchemy Engine，并且是 唯一知道数据库是什么的地方。查询使用命名绑定参数（:department）， 这些参数与方言无关，因此 SQLite 和 PostgreSQL 共用一套查询，而不是两套。

• pool_pre_ping=True，因为无服务器 PostgreSQL（Neon 及同类产品） 会挂起空闲计算资源，而 MCP 服务器在两次提问之间正好空闲。如果没有它， 沉寂一段时间后的第一个提问会因过期的连接池连接而失败。

• 归档资格在 Python 中计算，而不是在 SQL 中。 PostgreSQL 的 INTERVAL 运算在 SQLite 中没有对应实现，而把比较逻辑放在一处也能让两个后端保持一致。 在只有几千条现行记录的情况下，这个开销不值得优化掉。

• 记录时长从 joining_date 起算。 created_at 是批量加载的时间戳， 每一行都相同，因此按它计算保留期将永远找不到任何符合条件的记录。 joining_date 是员工级别的日期，用来充当文档日期——该表结构没有任何 文档日期字段，这是一个值得在上游弥补的真实缺陷。

• 归档状态是一张表，而不是一个标志位。 一条记录要么在 active_records 中，要么在 archived_records 中，id 在迁移过程中保持稳定，因此 get_record 会同时查询两者。status 列是雇佣状态，与归档无关。

• 工具被标注为只读。 每个工具都带有 ToolAnnotations(read_only_hint=True, destructive_hint=False)，因此客户端 在调用前就能区分安全调用与改变状态的调用。

• 工具实际上也是只读的。 归档具有破坏性且受策略约束；archival_candidates 刻意只报告可以归档的内容，把决定权留给现有的定时作业。将破坏性工具暴露 给模型，是一个需要先有确认路径的选择。

• 文档字符串就是 API。 模型根据文档字符串和类型提示来选择工具，因此 有效的部门和文档类型都在其中逐一列出。过时的枚举比没有更糟：模型传入一个 看似合理的值，比如 Legal，得到空结果，然后报告说没有可归档的内容。

• “符合资格”只有一个定义，两个方向共用。 _verdict 按照保留期限对记录 做时效判定；_eligible_on 是其逆运算，给出记录跨过该期限的日期，也就是 retention_forecast 分桶的依据。两者必须完全一致，否则同一条记录可能 同一天在预测中显示为即将到期，又在 archival_candidates 中显示为 已超期。用显而易见的方式实现逆运算（joining + timedelta(days=years * 365.25)） 会破坏这一点，因为 date + timedelta 只保留整天，会悄悄丢掉 .75。

• 输出是格式化文本，而不是原始 JSON 转储，这样模型可以直接把结果引用给 用户，无需重新格式化。