fyi-mcp
This server provides local FYI/Alaveteli FOI request management, sync diagnostics, authority catalog handling, deadline calculation, demo search, and endorsed-route checks.
List and retrieve tracked requests plus stored correspondence.
Create, update, and delete local request records.
List and import public authority records by slug.
Monitor offline sync health, inspect sync status, list conflicts, and resolve conflict metadata.
Check SQLite health and request/correspondence record counts.
Compute statutory FOI/OIA deadlines using working-day or calendar-day rules.
Search a built-in sample FOI corpus for demonstration full-text search.
Evaluate operator-published endorsed-client capability status locally and fail-closed.
Enables OpenAI Codex agents to interact with FYI CLI for FOI/OIA request management.
FYI CLI
A multi-jurisdiction Freedom-of-Information (FOI) client for Alaveteli-based platforms — track, submit, and archive official information requests across New Zealand, Australia, the UK, and any other Alaveteli deployment (foi-repository, WhatDoTheyKnow, FragDenStaat, and more), from a single privacy-focused CLI.
The supported application is moving to the Rust workspace (fyi-core, fyi-cli,
fyi-mcp). The legacy Python package (fyi_system) is frozen for migration and
existing archive consumers. Rust command names do not yet imply feature parity:
unimplemented commands fail explicitly. See the migration inventory.
Where fyi-cli / fyi-mcp is listed
Registry / catalog | Package / server | Status | Link |
Official MCP Registry |
| Live | |
OpenAI plugin directory (Codex) |
| Assets ready — external submission pending | |
Anthropic Claude Connectors |
| Assets ready — hosted HTTPS deployment and external submission pending | |
Glama |
| Live | |
Smithery |
| Live (score pending) | |
PyPI |
| Live | |
Crates.io | Rust workspace crates | Blocked: | |
GitHub Releases | CLI + MCPB assets | Live | |
Awesome-MCP-Servers | Legal section entry | PR submitted | |
GitHub curated MCP ( | — | Blocked external (manual onboarding) | Tracked in #32 |
Draft / not yet submitted: Scoop, WinGet, Homebrew, Chocolatey, GHCR multi-arch publication, PulseMCP, mcp.so, Docker MCP Catalog, mcp-get, OpenTools, AUR, nixpkgs, Snap, private Flatpak, asdf/mise, Debian/PPA, Fedora/COPR.
Package review packets remain blocked on a coordinated, verified release and native installation evidence; see the submission runbook. Flathub is not applicable to this console product.
cargo-binstall is blocked by the same crate-name collision; its default strategies are disabled until crate identity and release assets are qualified. Codex and Anthropic packets are assets-ready but still require external submission.
Full status matrix (including planned channels): docs/registry-distribution-matrix.md.
🚀 Quick Start
# Install from a local clone of this Rust workspace
cargo install --path crates/fyi-cli --locked
# Initialize
fyi-cli init-db
# List configured jurisdictions
fyi-cli instancesRequest registration, reporting and archive capture are still being migrated. The legacy quick start describes Python, not the Rust CLI.
Related MCP server: Boston Core MCP
✨ Features
🌐 Multi-Jurisdiction: Works with any Alaveteli deployment — foi-repository (NZ), WhatDoTheyKnow (UK), FragDenStaat (Germany), righttoknow.org.au (Australia), and more, with jurisdiction-aware metadata and localization on the way
🔒 Privacy-First: All data stored locally, optional encryption, Tor support
📊 Request tracking and reports: Legacy Python features being migrated to Rust
🤖 Automated monitoring: Legacy Python feature being migrated to Rust
🔐 Secure Storage: Encrypted credentials, OS keyring integration
💻 CLI + MCP: Command-line tool and an MCP server for AI assistants
📦 Process-event export: Rust export of public-safe events
🗄️ Faithful archiving: WARC/WACZ capture remains in the legacy Python path until the archive cutover
📦 Installation
Full guide (Rust-first, all channels): INSTALL.md · version 0.1.2 · homepage github.com/edithatogo/fyi-cli
Path | Command / location | Notes |
Cargo (clone) |
| Recommended |
Cargo (crates.io) | Blocked | The existing |
cargo-binstall | Blocked | Requires an unambiguous published crate and matching release assets |
GitHub Releases | Prebuilt CLI / MCPB; check asset names per tag | |
PyPI (legacy) |
| Python |
MCP binary |
| Or MCPB from Releases |
MCP registries | Official / Glama / Smithery | live — see table above |
Containers |
| Blocked: public multi-arch pull unverified — docs/containers.md |
Scoop, WinGet, Homebrew, Chocolatey, AUR, nix, Snap, Flatpak, Debian, Fedora, asdf, mise | Review packets under | Blocked / not applicable — 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 --helpLive listings and draft status: Where fyi-cli / fyi-mcp is listed · full matrix: docs/registry-distribution-matrix.md · MCP catalog checklist: packaging/mcp-catalogs/SUBMISSION_CHECKLIST.md.
📖 Documentation
Document | Description |
Full documentation (Astro + Starlight) | |
Canonical cross-reference for Python CLI, Rust CLI, and Rust MCP surfaces | |
Alaveteli/instance operator etiquette and outreach log | |
MCP catalogs, package managers, containers status | |
Smithery score + GitHub MCP onboarding playbook | |
Draft package-manager install notes (Scoop, WinGet, brew, …) | |
| |
5-minute getting started guide | |
Comprehensive user documentation | |
Installation guide (Rust-first; all channels) | |
How to get and configure API key | |
Configuration reference | |
Troubleshooting guide | |
Frequently asked questions | |
Version history | |
How to contribute | |
Citation metadata for releases | |
Zenodo release metadata source |
📚 Citation and Zenodo
Release metadata is versioned in CITATION.cff, .zenodo.json, and
artifacts/release/zenodo-mirror-manifest.json. DOI fields remain unset until the live Zenodo
record is verified for the tagged release.
🛡️ Security
Reporting a Vulnerability
Please do NOT report security vulnerabilities through public GitHub issues.
Use GitHub's private vulnerability reporting: https://github.com/edithatogo/fyi-cli/security/advisories/new
Security Policy: SECURITY.md
Security Features
✅ AES-256-GCM encryption for sensitive data
✅ PBKDF2-HMAC-SHA256 key derivation
✅ OS keyring integration for credential storage
✅ Tamper-evident audit logging
✅ Secure session management
✅ Input validation and sanitization
✅ Security headers (CSP, HSTS, X-Frame-Options)
✅ Automated security scanning (CodeQL, pip-audit, bandit)
🧪 Testing
# 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.pyTest Coverage: Rust workspace checks are the release gate. Python support tests remain available for legacy docs and archive tooling.
🤝 Contributing
We welcome contributions! See CONTRIBUTING.md for guidelines.
Quick Start for Contributors
# 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-featureSee CONTRIBUTING.md for the full development setup, including the legacy
Python fyi_system package.
Code of Conduct
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
📊 Project Status
GitHub Projects
The project board for this repository is
fyi-cli Conductor Roadmap.
It mirrors the local .conductor/tracks.md registry and tracks completed
Conductor work, release-readiness items, and external MCP registry follow-ups.
The umbrella
Rare Insights on Open Policy from Aotearoa
project is synchronized at the item level. GitHub Projects does not support
nested projects, so synchronization is handled by
scripts/sync_github_projects.py and the
manual/scheduled project-sync workflow.
# 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.pyThe workflow requires a repository secret named PROJECT_SYNC_TOKEN with
GitHub Projects access for user-level ProjectsV2 writes. The sync is
conservative: it adds missing fyi-cli issue/PR items to RIOPA, copies shared
status values, sets the RIOPA mirror source to other unless a fyi-cli option
exists, and never deletes umbrella-board items.
Project Status
This project is actively evolving from an NZ-only tool into a multi-jurisdiction FOI/Alaveteli
platform built on the Rust workspace. Current work is tracked as
Conductor tracks under .conductor/tracks.md, mirrored to GitHub epic
issues (#37-#46) and their sub-issues. See the project board below for live status, and
CHANGELOG.md for released versions.
🔗 Compatible Platforms
FYI CLI works with any Alaveteli-based platform. The embedded jurisdiction catalog currently includes:
Platform | Region | URL |
foi-repository | New Zealand | foi-repository |
RightToKnow | Australia | |
WhatDoTheyKnow | United Kingdom | |
MyRightToKnow | Ireland | |
Ma Da Da (CADA) | France | |
Tu Derecho a Saber | Spain | |
FragDenStaat | Germany | |
Alaveteli | Any | Self-hosted instances |
See .conductor/tracks/jurisdiction-* for the rollout plan covering additional instances and
non-English localization.
📋 CLI Commands
Archive Discovery
The archive commands are read-only and do not require an API key.
# 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.jsonRead-only authority discovery
discover-bodies keeps --base-url as the instance/capture URL. Use the
separate --catalog-url option only when the authority CSV is hosted at an
explicit alternate 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.jsonlWith --format jsonl, each output line contains only the stable downstream
contract fields url_name, name, and tags[]. The default JSON format also
includes retrieval provenance for audit records. Both modes are read-only,
robots-aware, and use the configured shared limiter.
The JSON output includes the effective catalog URL, whether the default or an override was used, retrieval time, HTTP status, row count, and a SHA-256 of the raw CSV payload. The override is read-only and still uses the catalog host's robots policy, contactable User-Agent, retry backoff, and shared rate limiter. Treat an override URL as trusted configuration: it can redirect discovery to a different authority set and should be reviewed and recorded alongside archive provenance.
Discovery uses a contactable User-Agent, checks robots.txt, and backs off on
transient 429/5xx responses. Keep live runs polite: use small date windows,
resume with checkpoints, and coordinate archive work with the ethics guidance in
the sibling fyi-archive repo at docs/ethics-and-compliance.md.
The Rust fyi-core network path is the primary resource-aware implementation:
it parses RateLimit-*/Retry-After, adapts pacing, enforces request/bytes/time
guardrails, persists load memory, caches safe GETs, and can emit secret-redacted
JSONL traces. Python remains a deliberately compatible discovery/capture path
and follows the same identity and retry etiquette.
For concurrent workers, point discover and backfill at the same SQLite
database with --db. That enables the shared cross-worker limiter, which
reserves one aggregate request slot across processes and records both normal
reservations and transient-failure backoff events. Inspect the current state
with fyi rate-limit-status --db fyi_system.db.
CLI and MCP surfaces
The full command and server cross-reference is maintained in docs/cli-entrypoints-audit.md. It covers the Python CLI entrypoints (fyi, fyi-cli, fyi-system), the Rust CLI binary (fyi-cli), and the Rust MCP server (fyi-mcp) with its published registry pages.
Opt-in live smoke test:
FYI_LIVE_SMOKE=1 pytest -m smoke tests/test_discovery_smoke.pyThe AU RightToKnow smoke is bounded to one discovery page and at most five
request captures. It writes only to temporary test directories and remains
disabled unless FYI_LIVE_SMOKE=1 is explicitly set.
In the current live verification, RightToKnow returned HTTP 403 for the bounded JSON search request, so the smoke records an explicit external availability skip and does not attempt capture. This does not change default offline CI behavior or retry the denied request aggressively.
Faithful Archive Capture
fyi capture stores the public request JSON, rendered HTML, and attachments as
WARC records, deduplicates attachment bytes by SHA-256, and maintains a derived
request view for downstream dataset tooling.
fyi capture 12345 \
--data-dir data \
--dist-dir dist \
--max-bytes 500000000 \
--max-runtime-minutes 30Capture layout:
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>.waczEach daily WACZ is appendable: subsequent captures add another WARC segment under
archive/ and merge the resource metadata in datapackage.json. Replay tooling
that supports WACZ/WARC can open the package from dist/site_snapshots/; for
low-level inspection, unzip it and read the WARC segments with warcio.
# 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 verificationFull CLI reference: See fyi --help or USER_GUIDE.md
🏗️ Architecture
┌───────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────────────┘📜 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
Built on the Alaveteli platform by mySociety
Inspired by the transparency work of foi-repository
Uses cryptography for encryption
📞 Support
Documentation: https://edithatogo.github.io/fyi-cli/
Discussions: https://github.com/edithatogo/fyi-cli/discussions
Made with ❤️ for transparency and privacy
Available Tools
15 toolscheck_statusCheck StatusARead-onlyIdempotent
Check FYI MCP SQLite readiness and return record-count metrics for requests, correspondence, and optional sync totals. Use as a first health probe or liveness check; prefer sync_monitor for queue/offline depth and list_requests for request content. Read-only, idempotent, and safe to call repeatedly; does not write data or contact remote services.
Inputs: no named parameters. Returns: Database health summary.
compute_deadlineCompute DeadlineARead-onlyIdempotent
Compute a statutory FOI/OIA deadline from a start date and day count using the bleeding-edge fyi-core deadline engine. Use for local working-day or calendar-day deadline math; do not use for listing requests (list_requests) or sync health (sync_monitor). Read-only and idempotent; pure calculation with no database or network access. Returns a StatutoryDeadline JSON object (start_date, due_date, statutory_deadline_days, working_day_rule).
Inputs: days (required), start_date (required), calendar. Returns: Computed StatutoryDeadline.
create_requestCreate RequestA
Create a new local FYI/Alaveteli request row (draft or tracked) in SQLite. Use only when starting a new request; use update_request to change an existing ID and delete_request to remove one. Mutating and not idempotent: each call allocates a new ID. Does not submit to a remote authority, send email, or require network access; title and body are required.
Inputs: body (required), title (required), url, tags, +2 more. Returns: The created request.
delete_requestDelete RequestADestructive
Permanently delete a local request and all of its stored correspondence from SQLite. Use only after the agent confirms the ID should be discarded; prefer update_request for status/text edits and list_requests/retrieve_request for inspection. Destructive and irreversible in this database; does not delete anything on remote FYI/Alaveteli sites.
Inputs: id (required). Returns: Deletion result.
endorsed_route_statusEndorsed Route StatusBRead-onlyIdempotent
Evaluate an operator-published endorsed-client capability document locally. Read-only, fail-closed, and never enables a route or contacts a remote service.
Inputs: scopes (required), client_id (required), now_epoch (required), capabilities (required), +1 more. Returns: quotas, reason, scopes, status, +2 more
import_authoritiesImport AuthoritiesAIdempotent
Upsert local public authority reference records by slug for request routing and discovery. Use after list_authorities when seeding or refreshing the catalog; do not use for FOI request CRUD (create_request/update_request). Mutating but non-destructive and idempotent: same slug re-import updates name/url without creating duplicates; does not contact remote authority directories.
Inputs: authorities (required). Returns: Import summary.
list_authoritiesList AuthoritiesARead-onlyIdempotent
List imported public authority records (government/public bodies) used to route or classify FOI/OIA requests. Use to browse existing slugs/names before drafting; use import_authorities to add or upsert records, and list_requests for request data. Read-only and idempotent; returns the full local authority table (no pagination).
Inputs: no named parameters. Returns: A list of authorities.
list_requestsList RequestsARead-onlyIdempotent
List locally tracked FYI/Alaveteli official information requests, ordered newest first. Use for dashboards, triage, or finding an ID before retrieve_request; do not use when you already know the ID and need correspondence (use retrieve_request) or only need health metrics (use check_status). Read-only and idempotent; does not contact remote authorities.
Inputs: limit. Returns: A request list payload.
retrieve_requestRetrieve RequestARead-onlyIdempotent
Retrieve one locally tracked FYI/Alaveteli request and its stored correspondence by request ID. Use after list_requests when you need full text/history for a single request; do not use for bulk listing (list_requests) or database health (check_status). Read-only and idempotent; fails if the ID is missing; never contacts remote sites.
Inputs: id (required). Returns: A request payload with correspondence.
search_corpusSearch CorpusARead-onlyIdempotent
Search a built-in sample FOI document corpus with the bleeding-edge in-memory inverted index (demo). Use for experimental full-text search over sample titles/bodies; prefer list_requests/retrieve_request for real local SQLite requests. Read-only and idempotent; does not query the database or network. Returns ranked hits with id, score, and title.
Inputs: query (required), limit. Returns: Ranked search results over the demo corpus.
sync_conflictsSync ConflictsARead-onlyIdempotent
List locally tracked requests whose offline sync metadata is marked conflict. Use after sync_monitor shows conflict>0 to obtain IDs for review; use sync_resolve_conflict to clear a conflict, list_requests for all requests regardless of sync state. Read-only and idempotent; does not resolve conflicts or start network sync.
Inputs: limit. Returns: A conflict list payload.
sync_monitorSync MonitorARead-onlyIdempotent
Summarize offline synchronization health: clean/dirty/conflict request counts, outgoing queue depth, latest sync time, and offline degradation indicators. Use for an operations overview; prefer sync_status for one request, sync_conflicts to list conflicted rows, and check_status for database connectivity/record totals. Read-only and idempotent; does not start a sync job.
Inputs: no named parameters. Returns: Global synchronization monitor data.
sync_resolve_conflictResolve Sync ConflictAIdempotent
Resolve a local offline-sync conflict by updating only the request's sync metadata: mark_clean=true after the agent has reconciled local vs remote (status becomes clean); mark_clean=false keeps the row dirty for a later push. Prerequisite: the request should already appear in sync_conflicts. Side effects are local SQLite metadata only—no automatic merge of body text, no remote API calls, and no deletion of the request. Prefer sync_conflicts to list candidates and sync_status to inspect timestamps; do not use for ordinary field edits (update_request). Mutating, non-destructive, and idempotent for the same mark_clean value.
Inputs: request_id (required), mark_clean. Returns: Conflict resolution result.
sync_statusSync StatusARead-onlyIdempotent
Read offline-sync metadata either as aggregate counts (omit request_id) or for one request (provide request_id). Use when you need clean/dirty/pending/conflict numbers or per-request last_synced timestamps; use sync_monitor for queue depth + offline degradation, sync_conflicts for conflicted rows only, and check_status for database health. Read-only and idempotent; does not mutate state or trigger network sync.
Inputs: request_id. Returns: Synchronization metadata. Aggregate counts are returned when request_id is omit…
update_requestUpdate RequestAIdempotent
Replace editable fields on an existing local FYI/Alaveteli request by ID and mark the record dirty for offline sync. Use when the request already exists and fields changed; use create_request for a new ID and delete_request to remove. Requires id, title, and body (full replacement for those fields, not a sparse patch). Mutating but non-destructive; safe to re-run with the same values; does not call remote APIs.
Inputs: id (required), body (required), title (required), url, +3 more. Returns: The updated request.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool targets a distinct action and resource. Even similar-sounding tools like list_requests and retrieve_request are clearly differentiated by purpose (listing vs. full detail). Sync-related tools (sync_monitor, sync_status, sync_conflicts, sync_resolve_conflict) have distinct roles.
Most tools follow a clear verb_noun pattern with lowercase and underscores (e.g., create_request, list_authorities). The only outlier is 'endorsed_route_status', which uses a past participle instead of a verb, but it remains readable and consistent in style.
With 15 tools, the server covers request CRUD, authority management, sync operations, and utilities without being overloaded. Each tool serves a clear purpose within the domain.
The surface covers core request lifecycle (create, read, update, delete, list) and sync management. Minor gaps exist: no tool for adding or editing correspondence individually, and no submission capability, but these are plausible scope decisions.
Maintenance
Related MCP Connectors
Public services, guide/FAQ search and estimates. Inquiry drafts require scoped authentication.
SAM.gov contract opportunities and entity lookup (BYOK) plus USASpending federal award data.
Tax scenarios, quarterlies, and memos. Authenticated; OAuth 2.1 via Keycloak.
Company, sanctions, SEC and federal award lookups, document conversion, and requirement capture.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenancereference and citation validation, verification, enrichment, replacement and improvement1MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides safe, read-only access to Boston's open data portal, enabling natural language exploration of civic datasets.2GPL 3.0

deeptempo-mcp-serversofficial
FlicenseNot gradedqualityDmaintenanceProvides tools for DeepTempo AI SOC including findings and case management, investigation workflow orchestration, action approval workflows, and MITRE ATT&CK layer generation.2-- AlicenseAqualityDmaintenanceAn MCP server to find and fetch Norwegian open government data from data.norge.no. Enables search, metadata retrieval, and data download.54MIT