FYI MCP

FYI CLI

适用于多司法辖区、基于 Alaveteli 平台的《信息自由法》（FOI）客户端——通过一个注重隐私的 CLI，在新西兰、澳大利亚、英国及其他任何 Alaveteli 部署平台（foi-repository、WhatDoTheyKnow、FragDenStaat 等）上跟踪、提交和归档官方信息请求。

项目核心是一个 Rust 工作区（fyi-core、fyi-cli、fyi-mcp）；旧版 Python 包（fyi_system）仍可作为参考实现使用，但不再继续扩展。

fyi-cli / fyi-mcp 收录平台

注册表 / 目录	包 / 服务	状态	链接
官方 MCP Registry	io.github.edithatogo/fyi-mcp @ 0.1.2	已上线	registry.modelcontextprotocol.io · server.json
OpenAI 插件目录（Codex）	fyi-mcp 插件包	资源已就绪——等待外部提交	packaging/ai-plugins/codex/
Anthropic Claude Connectors	fyi-mcp 连接器包	资源已就绪——等待部署托管 HTTPS 服务及外部提交	packaging/ai-plugins/anthropic/
Glama	edithatogo/fyi-cli（fyi-mcp）	已上线	glama.ai/mcp/servers/edithatogo/fyi-cli · 评分
Smithery	edithatogo/fyi-mcp	已上线（评分待定）	smithery.ai/server/@edithatogo/fyi-mcp
PyPI	fyi-cli（旧版 Python 包）	已上线	pypi.org/project/fyi-cli
Crates.io	fyi-cli / 工作区 crate	已发布 / 发布流程中	crates.io/crates/fyi-cli
GitHub Releases	CLI + MCPB 资源	已上线	发布版本
Awesome-MCP-Servers	法律板块条目	已提交 PR	PR #9693
GitHub 精选 MCP（github.com/mcp）	—	外部流程受阻（需人工入驻）	在 #32 中跟踪

草拟中 / 尚未提交： Scoop、WinGet、Homebrew、Chocolatey、GHCR 多架构工作流、PulseMCP、mcp.so、Docker MCP Catalog、mcp-get、OpenTools、AUR、nixpkgs、Snap、Flatpak、asdf/mise、Debian/PPA、Fedora/COPR。

cargo-binstall 已备好资源并接入仓库，但仍需等待匹配的 GitHub Release 资源，才能作为已上线的分发渠道。Codex 和 Anthropic 的包也已备好资源，但仍需外部提交。

完整状态矩阵（包括计划中的渠道）：docs/registry-distribution-matrix.md。

---

🚀 快速开始

# Install (Rust workspace, recommended)
cargo install --path crates/fyi-cli
# or: cargo install fyi-cli   (once published to crates.io)

# Initialize
fyi-cli init-db

# Create your first request
fyi-cli register-request ministry-of-justice "OIA Request" "Request body..." --status draft

# Track and manage requests
fyi-cli list-requests

完整指南： QUICKSTART.md

---

✨ 功能

• 🌐 多司法辖区：适用于任何 Alaveteli 部署——foi-repository（NZ）、WhatDoTheyKnow （UK）、FragDenStaat（Germany）、righttoknow.org.au（Australia）等，并将逐步支持司法辖区相关 元数据和本地化
• 🔒 隐私优先：所有数据均存储在本地，可选加密，支持 Tor
• 📊 跟踪请求：监控 FOI/OIA 请求从创建到完成的全过程
• 🤖 自动监控：自动监控实例更新
• 📈 报告与分析：生成仪表板、待关注报告和交接文档
• 🔐 安全存储：加密凭据，集成操作系统密钥环
• 💻 CLI + MCP：命令行工具和供 AI 助手使用的 MCP 服务
• 📦 导出选项：支持导出为 JSON、CSV、HTML
• 🗄️ 忠实归档：对请求、往来信件和附件进行 WARC/WACZ 捕获

---

📦 安装

完整指南（以 Rust 为先，涵盖所有渠道）： INSTALL.md · 版本 0.1.2 · 主页 github.com/edithatogo/fyi-cli

渠道	命令 / 位置	备注
Cargo（克隆）	cargo install --path crates/fyi-cli	推荐
Cargo（crates.io）	cargo install fyi-cli	发布后可用
cargo-binstall	cargo binstall fyi-cli	资源已就绪——需要匹配的发布资源
GitHub Releases	发布版本	预构建 CLI / MCPB；请按标签检查资源名称
PyPI（旧版）	pip install fyi-cli	Python fyi_system；不再扩展
MCP 二进制文件	cargo install --path crates/fyi-mcp	或从 Releases 获取 MCPB
MCP 注册目录	Official / Glama / Smithery	已上线——见上表
容器	ghcr.io/edithatogo/fyi-mcp	资源已就绪——docs/containers.md
Scoop、WinGet、Homebrew、Chocolatey、AUR、nix、Snap、Flatpak、Debian、Fedora、asdf、mise	packaging/ 下的草案	尚未声称已上线——docs/installation-package-managers.md

git clone https://github.com/edithatogo/fyi-cli.git
cd fyi-cli
cargo install --path crates/fyi-cli --locked
fyi-cli --help

已上线的列表和草案状态：fyi-cli / fyi-mcp 收录位置 · 完整矩阵：docs/registry-distribution-matrix.md · MCP 目录检查清单：packaging/mcp-catalogs/SUBMISSION_CHECKLIST.md。

---

📖 文档

文档	描述
文档站点	完整文档（Astro + Starlight）
docs/cli-entrypoints-audit.md	Python CLI、Rust CLI 和 Rust MCP 接口的规范交叉参考
docs/upstream-relations.md	Alaveteli/实例运营者礼仪与联系记录
docs/registry-distribution-matrix.md	MCP 目录、包管理器和容器状态
docs/external-registry-followups.md	Smithery 评分 + GitHub MCP 入门操作手册
docs/installation-package-managers.md	包管理器安装说明草案（Scoop、WinGet、brew 等）
docs/containers.md	fyi-mcp 容器 / GHCR
QUICKSTART.md	5 分钟快速入门指南
USER_GUIDE.md	全面的用户文档
INSTALL.md	安装指南（优先使用 Rust；涵盖所有渠道）
API_KEY_SETUP.md	如何获取和配置 API 密钥
CONFIGURATION.md	配置参考
TROUBLESHOOTING.md	故障排除指南
FAQ.md	常见问题
CHANGELOG.md	版本历史
CONTRIBUTING.md	如何参与贡献
CITATION.cff	发布版本的引用元数据
.zenodo.json	Zenodo 发布元数据源

---

📚 引用与 Zenodo

发布元数据在 CITATION.cff、.zenodo.json 和 artifacts/release/zenodo-mirror-manifest.json 中进行版本控制。只有在核实已标记发布版本对应的 Zenodo 在线记录后，才会填写 DOI 字段。

---

🛡️ 安全

漏洞报告

请勿通过公开的 GitHub issue 报告安全漏洞。

请使用 GitHub 的私密漏洞报告功能： https://github.com/edithatogo/fyi-cli/security/advisories/new

安全政策： SECURITY.md

安全功能

• ✅ 使用 AES-256-GCM 加密敏感数据
• ✅ 使用 PBKDF2-HMAC-SHA256 派生密钥
• ✅ 集成 OS 密钥环以存储凭据
• ✅ 防篡改审计日志
• ✅ 安全的会话管理
• ✅ 输入验证与净化
• ✅ 安全标头（CSP、HSTS、X-Frame-Options）
• ✅ 自动化安全扫描（CodeQL、pip-audit、bandit）

---

🧪 测试

# Rust release checks used by this repository
cargo +stable-x86_64-pc-windows-gnu fmt --all -- --check
cargo +stable-x86_64-pc-windows-gnu clippy --workspace --all-targets --all-features -- -D warnings
cargo +stable-x86_64-pc-windows-gnu test --workspace --all-features

# Python legacy/support checks
.\.venv\Scripts\python.exe -m pytest tests/test_release_readiness.py

# Opt-in live smoke test
FYI_LIVE_SMOKE=1 .\.venv\Scripts\python.exe -m pytest -m smoke tests/test_discovery_smoke.py

测试覆盖： Rust 工作区检查是发布门槛。Python 支持测试仍可用于旧版文档和归档工具。

---

🤝 贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

贡献者快速入门

# Fork and clone
git clone https://github.com/YOUR_USERNAME/fyi-cli.git
cd fyi-cli

# Build & test the Rust workspace
cargo build --workspace --all-features
cargo test --workspace --all-features

# Make your changes, then submit a PR
git commit -m "feat: Add awesome feature"
git push origin feature/awesome-feature

完整的开发环境设置说明（包括旧版 Python fyi_system 包）请参阅 CONTRIBUTING.md。

行为准则

请注意，本项目遵循贡献者行为准则。参与本项目即表示你同意遵守其中的条款。

---

📊 项目状态

GitHub Projects

此代码仓库的项目看板是 fyi-cli Conductor 路线图。 它与本地的 .conductor/tracks.md 注册表保持一致，用于跟踪已完成的 Conductor 工作、发布就绪事项以及外部 MCP 注册表的后续工作。

总项目 来自 Aotearoa 的开放政策罕见洞见 在项目条目层面进行同步。GitHub Projects 不支持嵌套项目，因此同步由 scripts/sync_github_projects.py 和 手动/定时运行的 project-sync 工作流负责。

# Preview synchronization without changing either project
.\.venv\Scripts\python.exe scripts\sync_github_projects.py --dry-run

# Apply synchronization from fyi-cli project 6 into RIOPA project 4
.\.venv\Scripts\python.exe scripts\sync_github_projects.py

该工作流需要一个名为 PROJECT_SYNC_TOKEN 的代码仓库机密，以便通过 GitHub Projects 访问用户级 ProjectsV2 写入操作。同步策略较为谨慎：将缺少的 fyi-cli issue/PR 条目添加到 RIOPA，复制共享状态值；除非存在 fyi-cli 选项，否则将 RIOPA 镜像来源设为 other；并且绝不删除总看板上的条目。

项目状态

此项目正积极从仅面向 NZ 的工具发展为基于 Rust 工作区、支持多个司法管辖区的 FOI/Alaveteli 平台。目前的工作通过 .conductor/tracks.md 中的 Conductor 任务进行跟踪，并同步到 GitHub 史诗 issue（#37-#46）及其子 issue。请查看下方项目看板了解实时状态，并参阅 CHANGELOG.md 了解已发布版本。

---

🔗 兼容平台

FYI CLI 适用于任何基于 Alaveteli 的平台。内置的司法管辖区目录目前包括：

平台	地区	URL
foi-repository	新西兰	foi-repository
RightToKnow	澳大利亚	https://www.righttoknow.org.au
WhatDoTheyKnow	英国	https://www.whatdotheyknow.com
MyRightToKnow	爱尔兰	https://www.myrighttoknow.org
Ma Da Da (CADA)	法国	https://www.madada.fr
Tu Derecho a Saber	西班牙	https://www.tuderechoasaber.es
FragDenStaat	德国	https://fragdenstaat.de
Alaveteli	任意	自托管实例

请参阅 .conductor/tracks/jurisdiction-*，了解新增实例和非英语本地化的推出计划。

---

📋 CLI 命令

档案发现

档案命令为只读命令，无需 API 密钥。

# Import the official FYI authority list into the local SQLite database
fyi import-authorities

# Walk the public search feed for a date window and save discovered requests
fyi discover --date-from 2024-01-01 --date-to 2024-02-01 \
  --checkpoint data/_state/discovery-2024-01.json \
  --output data/_state/discovered-2024-01.jsonl

# Probe a numeric request ID range for gaps
fyi discover --backfill-ids --id-from 1 --id-to 5000 \
  --output data/_state/backfill-1-5000.jsonl

# Compare feed discovery against the ID backfill
fyi discover-reconcile \
  --feed data/_state/discovered-2024-01.jsonl \
  --backfill data/_state/backfill-1-5000.jsonl \
  --output data/_state/discovery-reconciliation.json

只读权威机构发现

discover-bodies 将 --base-url 保留为实例／采集 URL。仅当权威机构 CSV 托管在明确指定的备用 URL 时，才使用单独的 --catalog-url 选项：

fyi discover-bodies --base-url https://www.righttoknow.org.au \
  --catalog-url https://catalog.example/au-authorities.csv \
  --rate-limit-name archive-discovery-au-rtk --format jsonl --output bodies.jsonl

使用 --format jsonl 时，每一行输出仅包含稳定的下游契约字段 url_name、name 和 tags[]。默认 JSON 格式还会包含用于审计记录的检索来源信息。两种模式都为只读、遵守 robots 规则，并使用已配置的共享限流器。

JSON 输出包含生效的目录 URL、是否使用默认值或覆盖值、检索时间、HTTP 状态、行数，以及原始 CSV 负载的 SHA-256。覆盖值仅用于只读操作，仍会遵守目录主机的 robots 策略、可联系的 User-Agent、重试退避机制和共享限速器。请将覆盖 URL 视为可信配置：它可能会将发现操作重定向到另一组权威机构，因此应与存档来源信息一同审核和记录。

发现操作会使用可联系的 User-Agent、检查 robots.txt，并在遇到暂时性 429／5xx 响应时进行退避。请礼貌地执行实时运行：使用较小的日期范围，通过检查点恢复，并根据同级 fyi-archive 仓库中的 docs/ethics-and-compliance.md 道德指南协调存档工作。

Rust fyi-core 网络路径是主要的资源感知实现：它会解析 RateLimit-*／Retry-After、动态调整请求节奏、实施请求数／字节数／时间护栏、持久化负载记忆、缓存安全的 GET 请求，并可生成脱敏后的 JSONL 跟踪记录。Python 仍是刻意保持兼容的发现／采集路径，并遵循相同的身份标识和重试礼仪。

对于并发工作进程，请让 discover 和 backfill 使用同一个 SQLite 数据库，并通过 --db 指定。这样便可启用跨工作进程共享限流器，它会在多个进程间预留一个聚合请求时段，并记录常规预留和暂时性故障退避事件。使用 fyi rate-limit-status --db fyi_system.db 检查当前状态。

CLI 和 MCP 接口

完整的命令和服务交叉引用维护在 docs/cli-entrypoints-audit.md 中。该文档涵盖 Python CLI 入口（fyi、fyi-cli、fyi-system）、Rust CLI 二进制文件（fyi-cli）和 Rust MCP 服务（fyi-mcp）及其已发布的注册表页面。

选择启用的实时冒烟测试：

FYI_LIVE_SMOKE=1 pytest -m smoke tests/test_discovery_smoke.py

AU RightToKnow 冒烟测试仅限一个发现页面，且最多采集五个请求。它只写入临时测试目录，并且只有在明确设置 FYI_LIVE_SMOKE=1 时才会启用。

在当前的实时验证中，RightToKnow 对受限的 JSON 搜索请求返回了 HTTP 403，因此冒烟测试会明确记录外部服务不可用并跳过，不会尝试采集。这不会改变默认的离线 CI 行为，也不会对被拒绝的请求进行激进重试。

忠实归档采集

fyi capture 会将公开请求 JSON、渲染后的 HTML 和附件存储为 WARC 记录，按 SHA-256 对附件字节进行去重，并维护供下游数据集工具使用的派生请求视图。

fyi capture 12345 \
  --data-dir data \
  --dist-dir dist \
  --max-bytes 500000000 \
  --max-runtime-minutes 30

采集目录结构：

data/
  warc/<runid>-<request>.warc.gz
  attachments/<sha-prefix>/<sha256>
  raw/requests/<authority>/<request_id>/
    request.json
    page.html
    attachments.json
    snapshot_meta.json
dist/
  site_snapshots/<YYYYMMDD>.wacz

每个每日 WACZ 都可以追加：后续采集会在 archive/ 下添加另一个 WARC 分段，并合并 datapackage.json 中的资源元数据。支持 WACZ／WARC 的回放工具可以从 dist/site_snapshots/ 打开软件包；若要进行底层检查，请解压软件包，并使用 warcio 读取 WARC 分段。

# Database
fyi init-db                    # Initialize database
fyi config show                # Show configuration

# Requests
fyi register-request ...       # Create new request
fyi list-requests              # List all requests
fyi request-detail <id>        # View request details
fyi set-status <id> <status>   # Update status

# Submission
fyi build-prefilled-url <id>   # Generate submission URL

# Monitoring
fyi ingest-feed <url>          # Ingest RSS/Atom feed
fyi scheduler <url>            # Run continuous monitoring
fyi discover                   # Discover public FYI requests
fyi discover-reconcile         # Compare discovery JSONL outputs

# Reports
fyi dashboard --output ...     # Generate dashboard
fyi attention-report           # Generate attention report
fyi handover --output ...      # Generate handover document

# Export
fyi export-requests            # Export all requests
fyi export-bundle <id>         # Export request bundle

# Security
fyi privacy-audit              # Privacy compliance check
fyi health-check               # System health verification

完整 CLI 参考： 请参阅 fyi --help 或 USER_GUIDE.md

---

🏗️ 架构

┌───────────────────────────────────────────────────────────────┐
│                         fyi-cli workspace                      │
├───────────────────┬───────────────────────┬───────────────────┤
│   fyi-cli (bin)   │   fyi-mcp (MCP server) │  legacy fyi_system │
│  CLI commands,     │  JSON-RPC over stdio,   │  (Python, reference │
│  TUI dashboard      │  tools for AI assistants│  implementation)   │
├───────────────────┴───────────────────────┴───────────────────┤
│                          fyi-core (lib)                         │
│   Alaveteli API client · Tor client · encryption/keyring ·       │
│   sync engine · jurisdiction/instance registry (in progress)     │
├─────────────────────────────────────────────────────────────────┤
│                        SQLite database                          │
│      (requests, correspondence, authorities, sync_metadata)     │
├─────────────────────────────────────────────────────────────────┤
│      Alaveteli instances: foi-repository · WhatDoTheyKnow ·      │
│      FragDenStaat · righttoknow.org.au · any self-hosted deploy  │
└─────────────────────────────────────────────────────────────────┘

---

📜 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

---

🙏 致谢

• 基于 mySociety 的 Alaveteli 平台构建
• 受到 foi-repository 在透明度方面工作的启发
• 使用 cryptography 进行加密

---

📞 支持

• 文档： https://edithatogo.github.io/fyi-cli/
• 问题反馈： https://github.com/edithatogo/fyi-cli/issues
• 讨论： https://github.com/edithatogo/fyi-cli/discussions

---

为透明与隐私倾心打造 ❤️