Polish Archives Indexes

polish-archives-mcp

一个用于波兰志愿者生命记录索引及其指向的档案扫描件的 MCP 服务：

• Geneteka，由 Polskie Towarzystwo Genealogiczne 编制的教区和民事登记索引：涵盖波兰各地数千个教区及其他地区的数千万条洗礼、婚姻和安葬记录。其覆盖范围列表按教区列出已编入索引的登记册和年份。
• The Poznań Project：涵盖 1800-1899 年 Wielkopolska 和 Kujawy、前普鲁士波森省及其邻近地区的婚姻记录，并包含年龄和父母信息。
• BaSIA，由 Wielkopolskie Towarzystwo Genealogiczne "Gniazdo" 编制的档案索引，其条目注明档案馆、档案号和扫描件。
• Szukaj w Archiwach，波兰国家档案馆门户：给出扫描件名称后，此服务会从其开放照片托管站点下载完整尺寸的扫描件。

它的工作方式就像一位谨慎的系谱学家。索引条目是查找线索，由志愿者根据登记册录入：它指出要查看哪本登记册和哪条记录，而扫描件才是证据。没有结果仅代表已编入索引的内容中没有记录，因此应先查看 Geneteka 的覆盖范围列表。引用扫描件时，使用档案馆自己的档案号，即 Szukaj w Archiwach 单元页面上的 Sygnatura，而不是索引对它的显示方式。

此处不会写入任何内容，也不会保存家谱。该项目源自一个用于家族历史项目的脚本，并且可与 familysearch-mcp 配合使用；其目录收录了许多相同登记册的缩微胶片副本。

这是一个独立项目。它与 Polskie Towarzystwo Genealogiczne、Poznań Project、Wielkopolskie Towarzystwo Genealogiczne "Gniazdo"、Naczelna Dyrekcja Archiwów Państwowych 或任何档案馆均无关联，也未获得其认可或支持。

工具

该服务提供七种工具。除 swa_scan 外，其他工具均为只读； swa_scan 会写入一个新文件，且绝不会覆盖已有文件。

搜索前

工具	用途
regions	Geneteka 的地区代码和名称（15wp 是 Wielkopolska）。不会发送请求。
geneteka_coverage	Geneteka 为某个教区编入索引的登记簿：出生、婚姻或死亡记录，以及 Geneteka 列出的确切年份（包括缺失年份）和每个登记簿的 rid。指定 year 时，可查看每个登记簿是否涵盖该年份。列表缓存一周。

搜索索引

工具	用途
geneteka_search	搜索某个地区的出生、婚姻或死亡记录，或按 rid 搜索某个登记簿。每行包含保管该簿册的机构、编目者的备注（通常是日期或村庄）以及扫描件链接。每页五十行。
poznan_search	按新郎和新娘的姓氏，或按任一方配偶的姓氏，搜索 1800-1899 年的婚姻记录。名字按项目的姓名分组进行匹配；如果名字不属于任何分组，则返回这些分组。每行都会注明原始登记簿的保管方。
basia_search	按姓氏搜索 BaSIA 条目，条目中可能有更多人物，以及地点和半径、年份、登记处和记录类型。每行都包含 BaSIA 的索书号和扫描件、该单位在 szukajwarchiwach.gov.pl 上的地址，以及关于 BaSIA 系列编号的警告。

查看扫描件

工具	用途
swa_scan	根据 Szukaj w Archiwach 图片主机上 64 个字符的名称，下载一张全尺寸扫描件（约 3500 px）。保存为新的 .jpg 文件，不会保存为隐藏文件，也不会保存在 ~/Library 下。
cache_status	查看本会话按站点划分的请求、缓存和请求间隔。不会发送请求。

它们支持的工作流

1. 使用 geneteka_coverage 查询教区：索引中有哪些登记簿和年份。未列出的年份从未搜索过。
2. 使用 geneteka_search、poznan_search 和 basia_search。记录使用拉丁语、波兰语或德语：搜索 Wojciech 时，也搜索 Adalbertus 和 Adalbert；搜索 Jan 时，也搜索 Joannes 和 Johann；搜索 Marianna 时，也搜索 Maria；-ski 和 -ska 以及属格形式（“z Kowalskich”）属于同一个姓氏。
3. 在浏览器中打开单位页面（BaSIA 行中的 unit_url，或 Geneteka 行中的扫描件链接）。Szukaj w Archiwach 的页面需要通过机器人检查，本服务不会获取这些页面。在该页面读取 Sygnatura，并从每张扫描件的图片地址中读取其名称（photos.szukajwarchiwach.gov.pl/<name>）。
4. 使用该名称调用 swa_scan。在对扫描件作出任何说明前，先阅读扫描件。
5. 引用档案馆、Sygnatura 和扫描件编号，并附上单位页面的地址。保留用于查找的索引名称（Geneteka、Poznań Project 或 BaSIA）。

设置

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

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

uvx polish-archives-mcp

从克隆的仓库运行，如果你打算修改它，建议使用这种方式：

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

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

Claude Desktop

{
  "mcpServers": {
    "polish-archives": {
      "command": "uvx",
      "args": ["polish-archives-mcp"]
    }
  }
}

桌面应用不一定会继承 shell 的 PATH。如果 uvx 无法找到，导致服务启动失败，请将 which uvx 输出的完整路径设为 command。

Claude Code

claude mcp add polish-archives -- uvx polish-archives-mcp

配置

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

变量	含义
POLISH_ARCHIVES_CACHE_DIR	响应缓存目录。默认值为 ~/.cache/polish-archives-mcp。
POLISH_ARCHIVES_TIMEOUT	单次请求的 HTTP 超时时间，单位为秒。默认值为 60。扫描下载的读取超时时间为 180 秒。
POLISH_ARCHIVES_MIN_INTERVAL	向同一网站发送两次请求之间的最短间隔秒数。默认值为 4，且不会低于 4。BaSIA 的间隔始终至少为 10 秒。
POLISH_ARCHIVES_CONTACT	添加到 User-Agent 中的电子邮箱地址或 URL，以便网站在你的使用造成问题时联系你。可选，但建议填写。
POLISH_ARCHIVES_DOWNLOAD_DIR	一个已存在的文件夹。设置后，swa_scan 只会将文件保存到该文件夹。设置为 iCloud Drive 文件夹即可保存到其中，该文件夹位于 ~/Library 下。

无法使用的值会在首次调用工具时报告为 not_configured 结果，并指出变量名称。

做个好访客

每个网站都由志愿者协会或档案馆托管。客户端每次只向同一网站发送一个请求，两次请求间隔至少 4 秒；向 BaSIA 和 Geneteka 发出的请求间隔至少 10 秒。不同网站的请求互不等待。每次 Geneteka 搜索调用只获取一页 50 行结果，不会突发获取全部结果。两个同时进行的相同调用会共用一次请求。覆盖范围列表缓存一周，搜索结果缓存一天，Poznań Project 的名称分组缓存一个月；失败不会缓存。收到 429、5xx 或连接断开时会重试一次，并遵循 Retry-After。User-Agent 会标明软件包名称、版本和此代码库。

各数据源关于自动化使用的说明（截至 2026-10-11 核实）：

• Geneteka。 geneteka.genealodzy.pl 未链接任何使用条款。其 robots.txt 未禁止任何内容，并设置了 Crawl-delay: 120。此服务器每次工具调用只向该网站发送一个请求，间隔至少 10 秒。
• The Poznań Project。 其关于页面称，该数据库“dostępna dla wszystkich użytkowników sieci poprzez bezpłatną wyszukiwarkę”（所有互联网用户均可通过免费搜索引擎访问）。该网站未提供 robots.txt。
• BaSIA。 在 www.basia.famula.pl 上未找到使用条款。其 robots.txt 设置了 Crawl-delay: 10，禁止访问 /search.php 和其他脚本，并在注释中说明，机器人可以索引信息页面，“ale nie wyszukiwarkę ani skrypty pobierające dane”（但不能访问搜索引擎或获取数据的脚本），因为每次搜索都会产生耗费资源的数据库查询。此服务器会通过 /en/ 提交网站自己的搜索表单，每次工具调用搜索一次，间隔至少 10 秒，并将每个答案缓存一天。
• Szukaj w Archiwach。 门户网站的馆藏单位和全宗页面受 Imperva 机器人检查保护，因此此服务器不会请求这些页面；用户可以在浏览器中打开。照片主机未提供 robots.txt（返回 400）。不使用浏览器无法查看门户网站自己的条款；扫描件的再利用条款由档案馆制定，因此发布扫描件前请先查看相关条款。

如果网站要求你停止，就立即停止：告知服务器运营者，并提交一个 issue，以便项目进行调整。

如何解读返回结果

• 索引行是查找线索。 每个搜索结果都会说明这一点。该行告诉你应查阅哪个登记册、哪一年和哪条记录；扫描件才是原始记录。
• 确认覆盖范围，再相信零结果。 geneteka_search 使用 rid 和一段年份进行搜索时，会列出 Geneteka 尚未编入索引的年份（years_not_indexed）。Poznań Project 和 BaSIA 没有发布类似列表，因此它们的零结果说明的情况较少。
• “太多”不等于零结果。 Poznań Project 在搜索匹配项过多时不会显示任何记录；poznan_search 会返回 too_many_results 和匹配数量，请缩小搜索范围。BaSIA 只列出搜索结果的前 250 条，并会说明这一点（truncated）。
• 引用档案的索书号，而不是 BaSIA 的。 BaSIA 使用自己的方式书写索书号，其中间的（系列）编号可能与档案馆的编号不同。每条 BaSIA 结果都会附上此警告。请从案卷页面获取 Sygnatura。部分 BaSIA 结果仍链接到已停用的 szukajwarchiwach.pl 域名，该域名现已无法打开；这些结果没有 unit_url，只有旧链接中写明的参考信息，以及查找案卷的说明。
• 谁保管登记册。 Geneteka 结果会注明 Geneteka 所列的保管机构（教区总档案馆、国家档案馆或堂区）。Poznań Project 结果会根据项目自己的档案页面注明原始登记册的保管机构。
• 姓名有三种语言形式。 波兰家庭在三份记录中可能分别写作 Wojciech、Adalbertus 和 Adalbert。Poznań Project 的姓名组可以对应这些名字的不同形式；其他名字则需要逐一搜索各个形式。
• 评论是其他研究者的原话。 返回的 Poznań Project 评论不会包含作者姓名或地址。

此处刻意不包含的内容

• Szukaj w Archiwach 自己的页面。 访问这些页面需要通过浏览器会话完成机器人验证；通过驱动浏览器来绕过验证的服务会冒充真人。案卷页面仍可由用户自行访问；扫描件托管站点是公开的，swa_scan 使用的就是该站点。
• 其他索引（metryki.genealodzy.pl 的扫描件、Kartenmeister、波美拉尼亚 Greif 索引）。欢迎通过 issue 提交建议。
• 向任何网站写入内容，包括更正和评论。
• 绕过机器人验证。 对验证挑战作出响应的网站会被报告为 blocked，并且不再继续访问。

安全性

工具参数由模型编写，而模型会读取此服务无法控制的文本：索引备注、评论和网页。服务假设这些文本可能会影响模型，并限制受影响的模型能够执行的操作。

• 允许访问哪些主机。 代码中固定了四个主机：geneteka.genealodzy.pl、poznan-project.psnc.pl、www.basia.famula.pl 和 photos.szukajwarchiwach.gov.pl。没有任何参数可以指定主机：参数只能填入搜索内容，扫描件名称必须是由 64 个十六进制字符组成的字符串。请求钩子会拒绝其他所有情况，包括从响应中获取的地址。重定向只会在同一主机内跟随。
• 允许的数据量。 超过 10 MB 的网页或超过 60 MB 的扫描件会在流式传输时被拒绝。
• 允许的文件。 swa_scan 只会创建一个新文件，绝不覆盖现有文件。文件字节必须是 JPEG 格式（根据开头的字节判断），且不能是照片主机的“文件不可用”图片。文件名必须以 .jpg 或 .jpeg 结尾；不能是隐藏文件或文件夹，也不能位于 ~/Library 下；如果设置了 POLISH_ARCHIVES_DOWNLOAD_DIR，则文件必须位于该目录内。这些判断都会在解析链接后进行。下载遭拒时，磁盘上不会留下任何文件。
• 网站文本不可信。 姓名、备注和评论会原样传给模型。服务的指令会告诉模型将这些文本视为需要权衡的材料，而不是指令；但最终仍由模型决定，因此请检查它提议执行的操作。

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

开发

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

实时检查会向网站询问已记录的测试数据无法回答的问题：网站的响应是否仍符合服务器读取的格式。检查会花费几分钟，因为它会遵循相同的访问节奏。有关测试套件的组织方式，请参阅 CONTRIBUTING.md；有关各网站的观察结果及观察时间，请参阅 docs/API-NOTES.md；有关服务器为何采用这种设计，请参阅 docs/DESIGN.md。

致谢

这些索引由数千名志愿者共同编制，他们来自 Polskie Towarzystwo Genealogiczne、Poznań Project 和 Wielkopolskie Towarzystwo Genealogiczne "Gniazdo"。登记簿及其扫描件归保管它们的档案馆所有。

许可证

MIT。