Skip to main content
Glama
Archive MCP Server

Archive MCP Server

by Surajp1602

Archive MCP Server

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

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

工具

工具

功能

search_records

按员工、部门或文档类型查找记录

get_record

获取单条记录及其保留判定

archival_candidates

超过保留期限的现行记录,按超期最久者优先排序

department_summary

每个部门现行记录与已归档记录的数量对比

retention_forecast

逐月预测接下来哪些记录将达到可归档条件

audit_history

定时归档作业执行了哪些操作,以及执行时间

Related MCP server: context-archive

资源

URI

内容

policy://retention

每种文档类型的保留期限(以年为单位)

环境要求

需要 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):

DATABASE_URL

后端

未设置

sqlite:///archive.db,即由 seed_db.py 构建的本地演示数据库

已设置

真实的归档数据库,例如 postgresql://user:pw@host/db?sslmode=require

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 转储,这样模型可以直接把结果引用给 用户,无需重新格式化。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Provides a stdio MCP server for Codex to inspect and query configured datasources, with tools for health checks, read-only queries, metadata, and fixed physical sessions with audit trails.
      8 npm
      -
    • A
      license
      C
      quality
      C
      maintenance
      Enables agents to query a local macOS archive of Knowledge and browser history through read-only stdio MCP tools for status, timelines, search, original records/blobs, schemas, bounded SQL, and usage or domain summaries.
      14
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides read-only, deterministic tools for searching accounts and knowledge and retrieving tickets, ticket details, and product information over a stdio MCP connection.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients to deterministically audit claimed data-deletion requests, reconstruct what personal data remains reachable at a chosen cut-off, and retrieve evidence, case details, queues, what-if results, and verification outputs. It is read-only and lets agents build risk dashboards, review queues, case cards, and DPO briefs from the same capabilities as the CLI.
      10
      MIT