UK National Archives Discovery

tna-discovery-mcp

一个用于 英国国家档案馆（TNA）的 Discovery 目录的 MCP 服务：该目录包含在邱园保存的记录的 3,700 多万条描述，以及英国各地及其他地区 2,500 多家档案馆的目录，均可通过 TNA 的免密钥 Discovery API访问。

对于家谱研究者来说，目录是查找英国士兵、遗嘱、点名册或郡档案馆文件的起点。其中一个系列有专属工具：WO 97，切尔西皇家医院的士兵服役档案，记录了 1760 至 1854 年间所有因退伍而领取养老金的人员，每条都采用标准句式描述（“JOHN ATKINSON Born MANCHESTER, Lancashire Served in Royal Artillery Discharged aged 41”）。find_soldier 按姓名搜索，并筛选出团、出生地和退伍年份符合条件的人员，同时将每条记录解析为字段，并估算出生年份。

它的工作方式与细致的家谱研究者相同。目录描述是查找线索：它说明记录存在以及记录所在之处，而不是记录的内容。Discovery 上大多数系列的影像并非免费。WO 97 的影像可在 Findmypast 上查看，FamilySearch 馆藏 1952868 对其进行了索引。每条结果都附有保管档案馆、档案编号和记录的 Discovery 页面，因为引用时应使用档案馆的档案编号，而不是此服务。

它是 nara-catalog-mcp 的英国对应版本。本项目不会写入任何地方，也不会保存家谱。

这是一个独立项目，与 The National Archives 无关联，也未获得其认可或支持。

工具

此服务提供五种工具。全部为只读工具。

工具	用途
search_records	按词语、系列（WO 97）、部门（WO）、涵盖日期和保管方（TNA、其他档案馆或通过 Archon 代码指定的单家档案馆）搜索目录描述。每条命中结果都包含其 ID、档案编号、描述、涵盖日期、保管方、digitised 标记和页面；WO 97 条目还会进行解析。按保管方、档案馆和世纪报告数量。
get_record	根据 ID 或精确档案编号（WO 97/1211/256）获取完整描述：Discovery 提供的每个字段、该记录在层级结构中的位置（部门、系列、案卷）、记录的查阅地点，以及引用信息。WO 97 条目的描述会解析为姓名、出生地、郡、所属团、退伍年龄和年份、服役年份及估算出生年份，同时保留原文。
browse	按目录顺序列出系列、子系列或案卷下一级的记录，并提供用于继续浏览的游标：例如 WO 97 中某团士兵的案卷，以及 WO 12 中的团和各年份点名簿。
find_soldier	按姓氏（末尾加 * 可匹配变体）、名字、退伍年份、团和出生地搜索 WO 97，并解析每条匹配结果。说明读取了多少条描述，以及其余描述被排除的原因。
budget_status	查看今日请求量与每日预算、本次会话的请求量以及最近一次错误。不发送请求。

设置

你需要 Python 3.11 或更高版本，以及 uv。无需申请密钥。

无需克隆。 uvx 会从 PyPI 获取并一步运行：

uvx tna-discovery-mcp

从克隆版本运行，适合需要修改代码的情况：

git clone https://github.com/ianderso/tna-discovery-mcp
cd tna-discovery-mcp
uv sync
uv run tna-discovery-mcp   # stdio server, usually launched by the client

无论采用哪种方式，此服务都通过 stdio 使用 MCP 通信，因此通常应由 MCP 客户端启动，而不是手动运行。

Claude Desktop

{
  "mcpServers": {
    "tna-discovery": {
      "command": "uvx",
      "args": ["tna-discovery-mcp"]
    }
  }
}

桌面应用并不总会继承 shell 的 PATH。如果服务因找不到 uvx 而无法启动，请将 which uvx 输出的完整路径填入 command。

Claude Code

claude mcp add tna-discovery -- uvx tna-discovery-mcp

TNA 希望听取您的意见

TNA 的 API 页面要求开发者通过电子邮件联系他们，并附上请求所用的 IP 地址：“请通过电子邮件联系我们，并附上 IP 地址”。构建此服务时，即使不提供该信息，API 也会正常响应，因此这只是请求，而非访问条件。由于此服务的每位用户都会从自己的地址发送请求，这项请求也就交给了您：如果您经常使用此服务，请将您的 IP 地址以及一行关于您如何使用该 API 的说明发送至 [email protected]。TNA 也欢迎您对该 API 提供反馈。

配置

无需进行任何配置。服务启动目录中的 .env 文件可提供环境中缺少的内容；只会读取该目录。

变量	含义
TNA_DISCOVERY_TIMEOUT	单次请求的 HTTP 超时时间，单位为秒。默认值为 30。
TNA_DISCOVERY_MIN_INTERVAL	两次请求之间的最短间隔秒数。默认值为 1，且绝不会低于 1：这是 TNA 的指导要求。
TNA_DISCOVERY_DAILY_BUDGET	每日（UTC）请求数上限，达到后所有工具都会拒绝请求，并返回 budget_spent。默认值为 3,000，且绝不会超过该值：这是 TNA 的指导要求。设置更低的值可留出余量。
TNA_DISCOVERY_CONTACT	添加到 User-Agent 中的电子邮件地址或 URL，以便在您的使用造成问题时 TNA 能联系您。此项为可选，提供会更为周到。
TNA_DISCOVERY_STATE_DIR	保存当日调用次数的位置。默认值为 ~/.local/state/tna-discovery-mcp。文件中仅包含日期和数字，不包含 API 返回的任何内容。

无法使用的值会在首次工具调用时作为 not_configured 结果报告，并指出对应的变量。此处特意没有缓存目录：见下文。

TNA 的条款，以及服务如何遵守这些条款

TNA 的 Discovery API 条款（于 2026-10-10 和 2026-10-11 阅读）简要如下：

• 许可。 目录信息可依据 Open Government Licence v3.0 用于个人、教育或商业用途。
• 请求频率。 “作为指导，您每天发出的 API 调用不应超过 3,000 次”，且频率不得超过每秒一次；TNA“可能会选择更正式地限制 API 调用次数”。服务一次只发送一个请求，两次请求之间至少间隔一秒，并将发送的每个请求（包括重试和失败的请求）都计入每日 3,000 次的预算。所有使用同一状态目录的会话共用同一本账簿。当日预算用尽后，工具会返回 budget_spent，直到 UTC 午夜之前不会再发送请求。budget_status 会显示调用次数。
• 禁止缓存。 “请勿缓存或存储 API 返回的任何内容。”服务不保留缓存：API 返回的内容不会写入磁盘，也不会在调用之间留存。同一时刻发出的两个相同调用会共用一个请求，仅此而已。引用内容包含参考编号和记录所在页面，而非存储的副本。因此，每次重复请求都会计入请求次数，这也是预算如此重要的原因。
• IP 地址和反馈是以“请”的方式提出的请求；见 TNA 希望听取您的意见。
• 条款还禁止未经许可使用 TNA 的徽标，也禁止将 API 用于非法或诽谤目的；条款同时声明，TNA 不提供技术支持，也不保证服务可用。

discovery.nationalarchives.gov.uk 上的 robots.txt 禁止访问网站的浏览、结果、搜索界面和图像路径等；其中没有提及 /API/，而本服务使用的正是该路径。

Discovery 可能会被替代。 2025 年末，TNA 发布了新版目录的测试版，该目录今后可能会取代 Discovery。本服务仅读取 Discovery API；如果 Discovery 停用，服务就需要为其替代产品开发新的客户端。

如何解读返回的结果

• 描述是检索线索。 它会告诉你记录是否存在、参考编号和日期。档案材料本身包含更多信息（WO 97 的退伍记录会注明年龄、身高、职业和退伍原因），也是引用时应使用的材料。get_record 的 images 会告诉你在哪里查看这些材料。
• WO 97 的图像不在 Discovery 上。 它们在 Findmypast（付费）上，FamilySearch 的馆藏 1952868 为其建立了索引。标记为 digitised 的记录在 Discovery 页面上就能查看图像。此服务不会下载任何内容。
• 同名不代表同一人。 WO 97 收录了数十名姓名最常见的士兵。将记录与某个人关联前，请根据团、出生地和日期确认。
• 起止日期是档案材料的最早和最晚日期， 通常是入伍和退伍日期。WO 97 条目若只有一个日期，会注明该日期的含义（“Covering date gives year of discharge” 或“...of enlistment”），解析后的字段也会遵循这一说明。估算出生年份时，用退伍年份减去退伍时的年龄，误差约为一年。
• 日期筛选会选取日期范围有重叠的记录。 date_from 和 date_to 会保留起止日期与所选范围重叠的记录，因此，服役时间为 1811-1835 年的士兵也会出现在搜索 1831-1834 年的结果中。find_soldier 随后只保留退伍年份在该范围内的士兵。
• 拼写可能不同。 Discovery 会按原样匹配词语：“hargreaves”会找到“HARGRAVES alias HARGREAVES”，但找不到只写作“HARGRAVES”的记录。请尝试不同拼写，并在末尾加上 *。
• WO 97 只收录领取抚恤金的士兵。 服役期间死亡或离队时未领取抚恤金的士兵不在其中，军官也不在其中。1854 年之后的 WO 97 按箱号（团和姓氏范围）编目，而非按个人编目，因此 find_soldier 找不到此后退伍的人；请改用 browse 浏览档案。
• 参考编号必须准确。 WO 97/1211/256：部门代码、空格，然后是系列、档案卷和条目。服务会统一大小写和空格（wo97/1211 也有效）；其他任何内容都会作为搜索词搜索，不会猜测。
• 相关度相同的结果在不同页面间会重新排列。 要翻阅较长的结果列表，请按 reference 或 date 排序。
• 引用档案馆的参考编号。 citation.cite_as 包含馆藏机构和参考编号（“The National Archives, Kew, WO 97/1211/256”）；请补充系列名称、起止日期以及图像的查看位置。

刻意不提供的功能

• 下载图像。 Discovery 自带的图像需通过网站获取，大多数系列的图像则在其他地方。服务会指出查看位置。
• 任何缓存。 TNA 要求不使用缓存。
• 其他档案馆的网站。 在其他地方保存的记录会在 Discovery 中描述；要查看记录，需访问相应档案馆自己的目录或亲自前往。
• 绕过限制或机器人检查。 遇到验证挑战时会报告为 blocked；预算耗尽时会报告为 budget_spent。

安全

工具参数由模型生成，而模型会读取此服务无法控制的文本：目录描述、网页以及其他工具的输出。服务会假定这些文本可能引导模型，并限制被引导的模型能够执行的操作。

• 仅限一个主机。 每个请求都会发送到 https://discovery.nationalarchives.gov.uk/API/。 请求钩子会拒绝任何其他主机，包括重定向中指定的主机；重定向仅会在该主机上跟随。
• 仅允许公共地址，并在建立连接时检查。 如果某个名称指向私有、环回、链路本地、CGNAT、多播、保留或未指定地址（无论是 IPv4 还是 IPv6），请求都会被拒绝；连接会发往已检查的地址，因此 DNS 重绑定无从获利。不会使用环境中的代理设置。
• 传入请求前会收紧参数范围：按模式限制 ID，按模式限制系列和部门代码，将日期限定为完整的 ISO 日期，将参考编号进行百分号编码并作为单个路径段，搜索词则始终只作为查询参数传递。
• 限制响应大小。 超过 10 MB 的响应会在流式传输时被拒绝。
• 除一项外，不进行写入。 唯一写入的文件是当天的调用计数。
• 目录文本不可信。 描述会原样传给模型。服务的指令要求模型将这些文本视为需要权衡的材料，而不是指令；但最终仍由模型决定，因此请审查它提出的操作。

如需报告漏洞，请参阅 SECURITY.md。

开发

uv sync --extra dev
uv run pytest                      # mocked with respx; never touches the API
uv run ruff check .
uv run ruff format --check .
uv run python -m tests.live_check  # paced calls to the live API

实时检查会向 Discovery 查询已记录的固定测试数据无法确认的内容：其响应是否仍符合服务读取的格式。请参阅 CONTRIBUTING.md，了解测试套件的组织方式；参阅 docs/API-NOTES.md，了解对 API 的观察内容及时间；参阅 docs/DESIGN.md，了解服务采用这种设计的原因。

致谢

该目录归 The National Archives 及其收录描述的档案馆所有，并依据 Open Government Licence v3.0 使用：“Contains public sector information licensed under the Open Government Licence v3.0.”

许可证

MIT。