Archive MCP Server
Archive MCP Server
一个 MCP 服务器,通过 stdio 将 Enterprise Data Archival & Records Management System 的记录和保留逻辑暴露给任何 MCP 客户端——Claude Code、Claude Desktop、Cursor,或你自己的客户端。
你不再需要在 React 仪表板中层层点击去回答*“财务部门可以归档什么?”*——直接问模型,模型就会调用这些工具。
工具
工具 | 功能 |
| 按员工、部门或文档类型查找记录 |
| 获取单条记录及其保留判定 |
| 超过保留期限的现行记录,按超期最久者优先排序 |
| 每个部门现行记录与已归档记录的数量对比 |
| 逐月预测接下来哪些记录将达到可归档条件 |
| 定时归档作业执行了哪些操作,以及执行时间 |
Related MCP server: context-archive
资源
URI | 内容 |
| 每种文档类型的保留期限(以年为单位) |
环境要求
需要 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.jsonWindows:
%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()返回一个 SQLAlchemyEngine,并且是 唯一知道数据库是什么的地方。查询使用命名绑定参数(: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
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Read-only MCP access to authorized Vocci sessions, notes, files, and memory search.
A paid remote MCP for AI SDK data query MCP, built to return verdicts, receipts, usage logs, and aud
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceProvides 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-
- AlicenseCqualityCmaintenanceEnables 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.143MIT
- AlicenseNot gradedqualityBmaintenanceProvides read-only, deterministic tools for searching accounts and knowledge and retrieving tickets, ticket details, and product information over a stdio MCP connection.MIT
- AlicenseAqualityBmaintenanceEnables 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.10MIT