FragDenStaat

fds-mcp — 面向 AI 助手的 FragDenStaat.de

一个用于 FragDenStaat.de 的 MCP 服务。FragDenStaat.de 是基于 froide 构建的德国信息自由平台。

德语版

只需用日常语言提出需求，即可准备一份德国信息自由申请。 你的助手会找到必须答复的主管机关，并说明为何由它负责；指出适用的法律及其规定的期限；跟踪你已提交的申请；收集回复及其附件；并将新申请写入本地文件，供你在任何内容离开设备之前审阅。

MCP 是什么？它在这里有什么作用？

MCP，即模型上下文协议，是一种让 AI 助手使用外部工具的标准——大致相当于浏览器扩展的作用。 fds-mcp 就是这样一种工具。安装一次后，Claude 或任何其他 MCP 客户端便可使用 15 个与 FragDenStaat.de 通信的工具。FragDenStaat.de 是基于 froide 构建的德国信息自由平台。

其中 4 个工具无需账户或令牌：搜索主管机关、阅读法律，以及确定某个地点由谁负责，都可以立即使用。

其他 froide 实例

froide 是 FragDenStaat.de 底层使用的 Django 软件，其 README 还列出了第二个生产门户：fragdenstaat.at。将此服务指向其中一个实例：

export FDS_MCP_BASE_URL=https://fragdenstaat.at

只接受不含路径或凭据的 https 源站；用于防止持有者令牌跟随链接发送给陌生人的主机允许列表也会根据此值生成——因此，配置 .at 后，fragdenstaat.de 就是外部主机，会被拒绝。

以下是截至 2026-09-05 与 fragdenstaat.at 对比所得的结果，并已作为持续运行的测试保留：

search_authorities、get_authority、get_law	可用，无需账户
check_jurisdiction	无法在该实例上使用——.at 的 /api/v1/georegion/ 中有 0 条记录，而 .de 中有 24,216 条。这不是此客户端能够解决的问题
绑定令牌的工具	需要在该实例上注册 OAuth 应用
发送前规则集	编码的是德国信息自由法，无法移植。请将通过其他实例提交的申请视为未经验证

使用示例

你： 关于波恩市的信息自由申请应由谁答复？适用哪部法律？

助手会调用 check_jurisdiction("Bonn")，获取区域层级和 Kommunalverwaltung Bonn（主管机关 3495），然后调用 get_authority(3495) 获取适用的法律及其期限；并报告所用的 API URL，方便你核实答案，而不是盲目相信。

也可以提交申请，但这是此服务刻意设置得最严格的操作。

---

⚠️ POST /api/v1/request/ 会立即且不可撤销地发送申请

FragDenStaat 的 REST API 没有草稿模式、没有预览，也没有撤销功能。POST /api/v1/request/ 一旦成功，电子邮件就会发往主管机关，申请默认会根据 CC0 公开发布，而且无法撤回。

更糟的是，MakeRequestSerializer 没有 law_type 字段。因此，API 总是按照 publicbody.default_law 提交申请；而由于 froide 按 ("-meta", "-priority") 排序，选中的几乎总是综合元法，而不是你想要的具体法律。例如，通过 API 向莱茵兰-普法尔茨的市镇申请 LTranspG（法律 16）信息时，系统会悄无声息地按「LTranspG, VIG」（法律 18）提交。

因此，我们建议使用此服务的 build_submit_url 作为退出方式：它会提供一个已预填正确 law_type 的网页表单，让你自行点击发送。 submit_request 也可使用，默认设置为 dry_run=True；除非 5 道相互独立的关卡全部通过，否则会拒绝提交——详见安全模型。

---

文档

• API 能做什么、不能做什么 — 我们遇到的每个限制、测量方法、尝试过的行不通的方案，以及一路犯下的错误
• OAuth 设置（含截图） — 注册应用、权限范围、重定向 URI 规则，以及本地 HTTPS 监听器被阻止时的处理方法
• README.de.md 和 docs/oauth-setup.de.md — 同样的文档，提供德语版本。美式英语是原文；德语版本以此为准。

安装

pip install fds-mcp

或者直接通过 PyPI 运行，无需安装任何内容：

uvx fds-mcp serve

从代码检出目录运行，用于开发：

git clone https://github.com/notDIRK/fds-mcp.git
cd fds-mcp
pip install -e ".[dev]"

需要 Python 3.10 或更高版本。

在 MCP 客户端中注册

该服务通过 stdio 通信。对于 Claude Code：

claude mcp add fds -- fds-mcp serve

对于读取 JSON 配置的客户端：

{
  "mcpServers": {
    "fds": {
      "command": "fds-mcp",
      "args": ["serve"]
    }
  }
}

或者完全无需安装：

{
  "mcpServers": {
    "fds": {
      "command": "uvx",
      "args": ["fds-mcp", "serve"]
    }
  }
}

四个绿色工具无需账户和令牌即可立即使用。

---

OAuth 设置

黄色和红色工具需要 OAuth 2.0 bearer token。FragDenStaat 的 API 仅支持两种身份验证方案——OAuth2 和会话 Cookie。没有个人 API 密钥，也不支持 Basic Auth（froide 自带的 docs/api.rst 声称情况并非如此；该文档已过时）。

1. 注册应用

登录并打开 https://fragdenstaat.de/account/applications/register/。所有账户页面都受 recent_auth_required 保护，因此系统可能会要求你再次输入密码。

字段	值
名称	任意名称，例如 fds-mcp
客户端类型	public（因此必须使用 PKCE）
授权许可类型	authorization-code
重定向 URI	https://localhost:8765/callback

仅接受 https 和 fragdenstaat 这两种方案。 注册时会拒绝 http://localhost/...——这是服务器上的 OAUTH2_PROVIDER.ALLOWED_REDIRECT_URI_SCHEMES 设置。因此默认重定向地址是 HTTPS 环回监听器，它使用 fds-mcp 为你生成的自签名证书（通过 openssl）；备用方式则是 fragdenstaat://callback，需要手动粘贴。

2. 配置并登录

fds-mcp configure --client-id <your-client-id>
fds-mcp login

login 会执行 Authorization Code + PKCE（S256），打开浏览器，并在 https://localhost:8765/callback 捕获重定向。浏览器会警告证书是自签名的——这是本地监听器，请接受该证书。

没有浏览器或没有 openssl 时：

fds-mcp login --manual     # uses fragdenstaat://callback, you paste the URL back

令牌会存放在 ~/.config/fds-mcp/tokens.json 中，文件权限为 0600。令牌会自动刷新；刷新令牌的有效期为 180 天。

fds-mcp status     # config, token and throttle state
fds-mcp whoami     # the authenticated account
fds-mcp logout --revoke

权限范围

fds-mcp 默认请求 read:user read:request make:request。如果你不打算提交申请，可以通过 fds-mcp configure --scopes "read:user read:request" 覆盖默认设置。

权限范围	用途
read:user	识别你自己的账户（/api/v1/user/）
read:request	读取你自己的申请，包括非公开申请
make:request	POST /api/v1/request/ — 提交申请
write:message、write:attachment	记录邮寄信件（尚未实现）

这里没有任何权限允许删除。如果移除 make:request，submit_request 将永远无法使用，其他功能仍可正常使用。

---

工具

工具	等级	身份验证	副作用
search_authorities(query, jurisdiction=None, limit=20)	🟢 green	无	无
get_authority(id)	🟢 green	无	无
get_law(id)	🟢 green	无	无
check_jurisdiction(place_name)	🟢 green	无	无
list_my_requests(status=None, limit=50)	🟡 yellow	令牌，只读	无
get_request(id)	🟡 yellow	令牌，只读	无
get_messages(request_id)	🟡 yellow	令牌，只读	无
list_attachments(message_id)	🟡 yellow	令牌，只读	无
download_attachment(attachment_id, target_dir)	🟡 yellow	令牌，只读	写入本地文件
check_deadlines()	🟡 yellow	令牌，只读	无
build_reply_draft(request_id, text, subject=None, path=None)	🟡 yellow	令牌，只读	如果给定 path，则写入本地 YAML 文件
create_request_draft(...)	🔴 red	无	写入本地 YAML 文件，完全不访问网络
validate_draft(path)	🔴 red	无	为 L01–L05 读取 API
build_submit_url(path)	🔴 red	无	写入本地 .body.txt 附属文件
submit_request(path, confirmation_token)	🔴 red	令牌 + make:request	发送申请，无法撤回
send_reply_via_browser(draft_path, confirmation_token)	🔴 red，需主动启用	已登录的浏览器配置文件	发送回复，无法撤回

全部 4 个红色工具都接受 dry_run: bool = True。

send_reply_via_browser 是第 16 个工具，只有设置 FDS_MCP_BROWSER_SEND=1 后才会注册。如果未设置该变量，它完全不会出现在工具列表中。启用前请阅读发送回复。

check_jurisdiction 会返回其证据

该工具沿着 /georegion/?name=<place> 的 part_of 链逐级查询，并在每一级调用 /publicbody/?regions=<id>，然后返回区域链、匹配的主管部门以及所用 API URL 列表。这在莱茵兰-普法尔茨州很重要：当地的 Ortsgemeinde 通常根本不会列在 FragDenStaat 上，而负责管理它的 Verbandsgemeindeverwaltung 则会。

build_submit_url 对较长申请采用两步方式

在 2026-09-05 的测试中，fragdenstaat.de 对超过约 4096 字节的 GET URL 返回 HTTP 400（4086 字节 → 200，4106 字节 → 400）。典型的 4000 个字符的申请经过 URL 编码后会超出此限制。超过限制时，该工具会返回一个较短的 URL，用于预填主题和 law_type，并将正文写入草稿旁的 .body.txt 文件，供你粘贴到表单中。

FragDenStaat 的 API 无法实现的功能

以下功能仅能通过前端使用，没有对应的 REST 接口。服务端不会假装能够实现这些功能：

• 回复主管部门——POST /api/v1/message/ 只能创建邮寄消息（OnlyPostalMessagesWritable），且 subject/content 是只读序列化字段。电子邮件回复需通过 /anfrage/<slug>/send/message/ 发送；这是一个受 CSRF 保护的 Django 视图，会忽略 bearer token。请参阅发送回复；
• 选择法律依据——序列化器中没有 law_type；
• 草稿——RequestDraft 未在 API 路由器中注册；
• 事后设置状态、解决结果、标签或法律；发布申请；提出异议或向州信息专员升级处理。

---

发送回复

无法通过 FragDenStaat API 向主管部门发送电子邮件回复。 换个载荷不行，增加权限范围不行，使用更好的令牌也不行。2026-09-05 进行的三次测量由 tests/test_api_contract.py 如实记录：

1. 使用 kind: "email" 调用 POST /api/v1/message/，会返回 HTTP 400，并在 kind 键下报告："Nachrichten dieser Art können nicht über die API erstellt werden." 这是 froide 的 OnlyPostalMessagesWritable。
2. 使用 kind: "post" 进行完全相同的调用，同样返回 400——该测试特意使用无法解析的请求 URI，所以无论如何都无法创建消息——但没有 kind 错误。这就是校准结果。没有这项校准，第一次测量就无法证明任何事：400 也可能是无效 URI 导致的、端点拒绝所有 POST 导致的，或是缺少权限范围导致的。
3. 使用和不使用 bearer 令牌调用 POST https://fragdenstaat.de/anfrage/<slug>/send/message/，结果完全相同：HTTP 302，重定向至 /account/login/，状态码和 Location 均相同。网页视图只接受会话和 CSRF。OAuth 无法绕过第 1 点。

所以，实话是：回复需要由人工发送。build_reply_draft 能让这件事变得简短。

build_reply_draft

它会查找请求、验证你的文本，并返回完整消息、符合 froide 自有格式的主题（AW: <title> [#<id>]）以及表单 URL。它不会写入网络——没有任何参数能让它发送消息。

后续回复的验证方式与请求不同，很容易搞错。froide 会在新请求前后加上该法案的 letter_start/letter_end；但后续回复不会加上这些内容。文本框会预先填入

Guten Tag,

…

Mit freundlichen Grüßen
<your name>

主管部门收到的内容，正是文本框里的内容。因此：

• R19 要求恰好包含一次称呼和一次结束语——这与 R10 相反；在框架生效时，R10 会禁止这两者；
• R04 会拒绝此表单当前显示的占位符 …（U+2026）。这是此流程中最容易犯的错误；
• R06 会阻止在公开且采用 CC0 许可的对话串中包含电子邮件地址和 IBAN；
• 主题最长为 230 个字符。

每项结果都会无条件附带另一条警告：表单已预先填入你的邮寄地址，其复选框标注为 "Adresse mitsenden"。在公开请求中，勾选该项会以 CC0 许可永久公开你的居住地址。除非主管部门明确要求提供邮寄地址，否则请勿勾选。

send_reply_via_browser — 可选，默认关闭

还有一种自动执行最后一步的方式：在带有你已登录会话的浏览器中操作表单。此服务可以执行此操作，但默认未启用。只有设置 FDS_MCP_BROWSER_SEND=1 后才会注册，并且还需要额外的：

pip install 'fds-mcp[browser]'
python -m playwright install chromium
export FDS_MCP_BROWSER_SEND=1

它绝不会撰写文本。它只会发送 build_reply_draft 写入、随后经人工批准的回复草稿文件中的 subject 和 body，不接受其他任何输入。 五道关卡：

1. 文件是回复草稿，且 status: approved，同时 send_address 为 false；
2. 根据后续处理规则，没有未解决的 ERROR 项；
3. confirmation_token 与人工写入文件中的令牌逐字节匹配；
4. 本地台账显示，另一条消息仍在 2/5min、6/6h、8/24h 的限制范围内。froide 在此路径上不会以我们能够依赖的方式执行 message_throttle，因此这道限制是自愿执行的；
5. 在表单中：“Adresse mitsenden” 已关闭，收件人可读且会被报告；主题和消息输入后会逐字节读回；不得包含 U+2026；且必须恰好有一个称呼和一个结束语。任何找不到的内容都会被视为失败——表单形状发生变化时，就不应在其中按下按钮。

之后，它会询问 API，确认该请求下是否确实出现了新消息。如果没有，则将结果报告为 unconfirmed，且不会将草稿标记为已发送。无法确认不代表失败，也不代表成功。

警告

启用此功能意味着你接受以下事项

1. 浏览器自动化违背了最后一步由人工执行的原则。 此服务中的其他所有发送流程，最后一步都是由人点击发送。只有这一种情况例外。

2. **如果同时存在通用文件写入工具，那么关卡 1 和 3 就形同虚设。**它们只是你磁盘上 YAML 文件中的两个值。此服务中的任何工具都无法设置这两个值——build_reply_draft 始终会写入 status: draft 和占位令牌。但大多数 MCP 宿主也会向模型提供 write_file 工具，而能够写入文件的模型可以写入 status: approved 和自行选择的令牌。如果再遇到来自主管部门回复的提示注入——此服务会读取这类文本并将其标记为不可信，但仍会将其呈现给模型——那么发往公共主管部门的消息就会在没有人工参与的情况下发出，而且无法撤回。

3. **浏览器中保存着你的已登录会话。**发生故障时，操作将拥有你在 fragdenstaat.de 上的全部权限：你的请求、账户页面和地址。

4. 防范措施，按有效性排序：

   • 关闭此功能。取消设置 FDS_MCP_BROWSER_SEND，该工具就不会存在。
   • 通过 FDS_MCP_BROWSER_PROFILE 使用单独的浏览器配置文件，其中不要登录其他账户。该配置文件中的会话就是风险影响范围。
   • 通过 FDS_MCP_DRAFT_DIR 将草稿目录放在其他工具无法访问的位置。只有在没有其他工具能写入该文件时，关卡 1 和 3 才有意义。
   • 日常使用时保持 dry_run=True。它会填写表单，然后在点击前停止。

安全模型

七条规则由代码强制执行，而不只是写在文档中。每条规则都在 tests/test_security_gates.py 中有测试，证明它确实会触发。

1. 除非草稿的 status 为 approved，否则 submit_request 会中止——该状态由人工设置。
2. 只要有任何 ERROR 发现尚未解决，它就会中止。
3. 如果 law.wunsch_id != law.api_default_id，它就会中止，因为 API 无法设置 law_type，会按错误的法律提交申请。
4. 除非 confirmation_token 与人工写入草稿文件的令牌逐字节匹配，否则它就会中止。工具不得自行编造该令牌。
5. 每个红色工具的默认值都是 dry_run: bool = True。
6. 本地台账会在任何 POST 前检查 5/5min、6/6h、10/24h、20/7d，并且会清晰说明原因后中止，而不是重试。FragDenStaat 的使用条款 B.1.4 规定，试图规避限制会导致账户被锁定一个月。
7. 除非明确设置了 allow_write=True，否则 HTTP 客户端会拒绝所有非 GET 方法。整个包中只有一个函数会设置此项。

send_reply_via_browser 有自己的一组五条规则，列于 发送回复 下，并在 tests/test_browser_send.py 中有测试。它还有其他工具不需要的一个门槛：除非 FDS_MCP_BROWSER_SEND=1，否则根本不会注册此工具（规则 0）。

规则集

离线规则 R01–R19 重现了 froide 的网页表单所执行的检查——其检查内容远多于 REST API 的验证。实时规则 L01–L06 会对照 API 检查：主管机构是否存在且名称未变、更希望使用的法律是否确实可选、重新计算的 API 默认值是否与草稿中的声明一致、是否存在重复申请、你的文本中是否已有句子出现在该法律自身的信函模板中，以及最终信函是否包含所有应有内容。

值得注意的规则：

• R06 会拒绝正文中的电子邮件地址和 IBAN。公开申请采用 CC0 许可，所有人都能看到——不要在其中写入他人的信息。
• 当 full_text=false 时，R10 会将称呼或结束语视为错误：froide 会用法律的 letter_start/letter_end 为正文添加框架，因此如果你自己写了其中任何一项，就会出现重复问候语。
• 对于 submit_via: api，R12 属于错误；对于 submit_via: web_form，它只是提示——网页表单可以选择法律类型，API 则不能。
• R18 和 L06 检查的是主管机构收到的信函，而不是你写的正文。当 full_text=false 时，该法律的 letter_start/letter_end 会提供部分文本，因此某项内容可以来自任一部分；L06 会获取信函框架，并报告两部分都未提供的内容。共六项：法律依据（唯一的 ERROR）、费用预先通知、费用上限、截止期限、正文不由该主管机构负责时的转交请求、电子回复。

费用上限正是设置这条规则的原因。曾有一份真实申请在未注明费用上限的情况下发出，因为 LTranspG 的 letter_end 确实要求告知预计费用，但既没有写明上限，也没有说明可改为免费现场查阅。模板涵盖了其他所有内容，这正是仅查看正文时什么都没发现的原因。

• R19 与 R10 相反，且仅适用于后续跟进——请参阅 发送回复。

服务允许写入的位置

三个工具参数是由模型选择的文件路径，而同一个模型还会读取官方回复和附件中的内容——这些文本由第三方撰写。因此，这些路径受到约束，而非可信：

• 草稿路径必须以 .yaml/.yml 结尾；检查前会先解析路径（符号链接按其目标判断），且 save() 拒绝覆盖本身不是草稿的文件；
• download_attachment 不会创建目录，附件文件名会被剥离为基本名称，并将 [A-Za-z0-9._ -] 以外的所有字符替换掉；
• 附件只会从 fragdenstaat.de 和 media.frag-den-staat.de 获取，且绝不会在其他地方发送 bearer token。

四个环境变量可以进一步收紧限制；建议在无人值守运行服务时设置：

变量	作用
FDS_MCP_DRAFT_DIR	每个草稿路径都必须位于此目录内（以 : 分隔的列表）
FDS_MCP_DOWNLOAD_DIR	每个 download_attachment 目标都必须位于此目录内
FDS_MCP_BROWSER_SEND	1 会注册 send_reply_via_browser。其他任何值（包括未设置）都会使该工具不存在
FDS_MCP_BROWSER_PROFILE	该工具使用的浏览器配置目录。将其指向一个已登录 fragdenstaat.de 且不登录其他任何网站的配置目录

携带第三方文本的结果（get_messages、get_request、 list_attachments、download_attachment）会在 untrusted_content 键中标明这些字段。它们是数据，不会决定文件路径、URL、工具调用 或确认令牌。

草稿生命周期

draft ──validate_draft──▶ validated ──a human edits the file──▶ approved ──submit_request──▶ submitted

回复草稿有自己的状态流转，终点是 sent 而非 submitted；只有 send_reply_via_browser 能使其到达该状态，而且必须先由 API 确认存在新消息。

只有人工才能将草稿移至 approved，且只能通过编辑 YAML 文件来完成。

请了解这句话的局限。 Gate 1（status: approved）和 Gate 4 （confirmation_token）是磁盘上文件中的两个值。此服务中的任何工具都无法设置它们——create_request_draft 始终会写入 status: draft 和占位令牌，而且没有任何工具可以提升草稿状态。但大多数 MCP 宿主也会为模型提供通用的文件写入工具；而能够写入文件的模型也能写入 status: approved 和自行选择的令牌。如果再结合来自官方回复的提示注入，就可能导致实际提交。

因此，如果你同时运行文件系统工具：

• 完全不要启用 submit_request：配置作用域时不包含 make:request——这样，此服务持有的任何令牌都无法 POST 请求；
• 或将 FDS_MCP_DRAFT_DIR 设置为其他工具无法写入的目录；
• 或保留建议的退出方式并使用 build_submit_url，这样发送按钮位于浏览器中，而不是工具调用里；
• 并保持 FDS_MCP_BROWSER_SEND 未设置。同样的道理也适用于 send_reply_via_browser，而且更为明显：你无法撤销它的任何作用域，只能控制自己拥有的浏览器会话。

Gate 2、3、5 和 7 不依赖文件，因此始终有效：规则集会针对实时 API 数据运行，法律检查会与重新计算的 API 默认值比较，限流记录是独立状态，而 HTTP 客户端在任何地方都拒绝非 GET 请求，唯独 submit_request 除外。

---

开发

pip install -e ".[dev]"
python -m pytest -m "not live"     # offline suite
python -m pytest -m live           # hits fragdenstaat.de

默认情况下，pytest-socket 会阻止网络访问；只有标记为 live 的测试才能访问 fragdenstaat.de。

实时测试套件只执行只读 GET 请求，仅有两个例外，且都位于 tests/test_api_contract.py 中；这两个例外都无法创建任何内容：消息 POST 请求携带无法解析的请求 URI，而网页表单 POST 请求携带空请求体。没有测试会打开浏览器，也没有测试会发送消息。 缺少 ~/.config/fds-mcp/tokens.json 时，需要令牌的测试会跳过，而不会失败。

无需 MCP 客户端也能使用 CLI：

fds-mcp validate examples/request-draft.yaml
fds-mcp validate examples/request-draft.yaml --live

---

事实及其来源

本服务对 API 的所有说明，均已于 2026-09-05 根据 fragdenstaat.de、okfde/froide@bc6c2fa 和 okfde/fragdenstaat_de@88bfbba 进行核实。源代码引用均在文档字符串中，精确到文件和行号。如果你发现某项说明有误或已过时，那就是一个 Bug——请提交 issue。

API 文档位于 https://fragdenstaat.de/api/，OpenAPI 3.0.3 架构位于 https://fragdenstaat.de/api/v1/schema/，Swagger UI 位于 https://fragdenstaat.de/api/v1/schema/swagger-ui/。（froide 自身文档提到的 /api/v1/docs/ 会返回 404。）

---

请负责任地使用

FragDenStaat 由一家非营利组织运营，资金来自捐赠。你提交的每项申请都会占用公共机构的实际工作时间。每 5 分钟最多 5 次请求、每周最多 20 次请求，这些限制都是有原因的。本服务旨在帮助你提交更好的申请，而不是提交更多申请。

使用 public: true（默认值）提交的申请，会将全部电子邮件往来、所有获批的附件以及所有上传的文档以 CC0 许可向全世界公开。

---

免责声明

本项目与 Open Knowledge Foundation Deutschland e.V.、FragDenStaat 或 froide 项目无任何关联，未获其认可，也与其无关。 这是一个独立的第三方客户端，通过公开 API 进行通信。所有商标均归其所有者所有。

本项目不提供法律建议。

许可证

MIT——详见 LICENSE。版权所有 2026 Dirk Wolbeck。