Querido Diário MCP Server

Querido Diário MCP サーバー

ローカル優先のModel Context Protocolサーバーです。Querido Diárioがインデックス化したブラジルの自治体の官報に、AI クライアントから構造化された読み取り専用アクセスを提供します。

API キー不要 · ローカルで実行 · 読み取り専用 · テレメトリーなし · オープンソース

🇧🇷 ポルトガル語版

このパッケージはPyPIとMCP Registryで公開されています。

概要

Querido Diário は、公開 API を通じて検索可能な自治体の官報を提供します。このサーバーは、その API 上に小規模で型付きの MCP インターフェースを公開し、MCP クライアントが次の操作を行えるようにします。

• ブラジルの自治体とその IBGE 地域 ID を特定する。
• インデックス化された官報を、テキスト、自治体、日付範囲で検索する。
• エージェントが確認し、他のツールと組み合わせやすい構造化された結果を受け取る。

このサーバーはローカルの stdio サブプロセスとして動作し、公開 Querido Diário API への読み取り専用 HTTPS リクエストのみを実行します。

クイックスタート

Python 3.12 以降と uv が必要です。

リポジトリをクローンする必要はありません。

uvx querido-diario-mcp-server

これにより、MCP サーバーが stdio で起動します。対話型のターミナルアプリケーションとして使うのではなく、MCP クライアントから起動することを想定しています。

クライアントの設定

対応するすべてのクライアントで同じコマンドを使用します。

uvx querido-diario-mcp-server

Claude Desktop / Claude Code

{
  "mcpServers": {
    "querido-diario": {
      "command": "uvx",
      "args": ["querido-diario-mcp-server"]
    }
  }
}

Claude Desktop では claude_desktop_config.json に、Claude Code ではプロジェクトレベルの .mcp.json にこれを使用します。

Cursor

{
  "mcpServers": {
    "querido-diario": {
      "command": "uvx",
      "args": ["querido-diario-mcp-server"]
    }
  }
}

.cursor/mcp.json または Cursor のグローバル MCP 設定に追加します。

Codex CLI

[mcp_servers.querido-diario]
command = "uvx"
args = ["querido-diario-mcp-server"]

ローカルの stdio サーバーに対応する他の MCP クライアントでも、同じコマンドを起動できます。

ツール

このサーバーが公開するツールは、意図的に小規模な読み取り専用のものに限定されています。

ツール	目的
search_cities	ブラジルの自治体を名前で検索し、7 桁の IBGE 地域 ID を特定します。州による任意の絞り込みにも対応しています。
get_city	正確な 7 桁の IBGE 地域 ID を指定して、自治体を 1 件取得します。
search_gazettes	自治体、発行日、ページネーション、並べ替えの各フィルターを使って、インデックス化された官報を全文検索します。

search_gazettes は、上流の検索 API がサポートする simple-query-string 構文を使用します。例として、+required、-excluded、"exact phrase" があります。

使用例

ユーザーは次のように依頼できます。

Find mentions of ACME Ltda in Porto Alegre gazettes
from January through July 2026.

その後、MCP クライアントは次の処理を実行できます。

1. search_cities(city_name="Porto Alegre")
   -> territory_id: "4314902"

2. search_gazettes(
       query='"ACME Ltda"',
       territory_ids=["4314902"],
       published_since="2026-01-01",
       published_until="2026-07-31",
   )

結果は構造化されたツール出力として返され、クライアントは要約、絞り込み、または他のツールとの組み合わせを行えます。

アーキテクチャ

MCP client
   |
   | stdio / MCP
   v
server.py
   |
   | validated tool arguments
   v
client.py
   |
   | typed read-only HTTPS requests
   v
Querido Diário public API

この実装では、プロトコルの境界と HTTP 連携を分離しています。

src/querido_diario_mcp_server/
    __init__.py   package version and CLI entry point
    config.py     environment-driven configuration
    errors.py     integration error hierarchy
    models.py     typed Pydantic domain models
    client.py     async HTTP client with no MCP dependency
    server.py     MCP lifespan, validation and tool definitions

単一の httpx.AsyncClient 接続プールがサーバーのライフサイクル中に作成され、ツール呼び出し全体で再利用されます。HTTP クライアントは MCP とは独立してテストでき、統合テストでは実際の MCP サーバーをプロセス内で実行します。

設計原則

• 設計上、読み取り専用です。 この統合機能は、固定された一連の上流 GET エンドポイントのみを呼び出します。
• ローカルファーストです。 ホスト型ミドルウェア、独自のバックエンド、アカウント登録は必要ありません。
• 型付きの境界です。 API のレスポンスと MCP の出力には、明示的な Pydantic モデルを使用します。
• ツールの範囲は小規模です。 サーバーが公開するのは、都市の検索と官報の検索に必要な操作のみです。
• エラーを明示します。 上流のエラーは、生のトレースバックや HTML レスポンスではなく、簡潔な MCP ツールエラーに変換されます。
• 任意の URL の取得はできません。 ツールの呼び出し元が、サーバーを汎用 HTTP または SSRF の手段として利用することはできません。
• テレメトリーはありません。 サーバーは利用状況データを収集しません。

セキュリティ

サーバーは、上流 API から返された官報の URL を自動的にたどることはなく、ツールの呼び出し元から任意のターゲット URL を受け付けません。地域 ID、日付、ページネーション、並べ替えオプションは使用前に検証されます。

脆弱性の報告方法とサポート対象のセキュリティ範囲については、SECURITY.md を参照してください。

設定

変数	デフォルト	用途
QD_API_BASE_URL	https://api.queridodiario.org.br	Querido Diário API のベース URL です。ローカル環境またはステージング環境向けに上書きできます。

通常、ユーザーが環境変数を設定する必要はありません。

開発

貢献する場合、または実装に取り組む場合にのみ、リポジトリをクローンしてください。

git clone https://github.com/lucaspmgomess/querido-diario-mcp-server.git
cd querido-diario-mcp-server
uv sync

CI で実行されるチェックと同じものを実行します。

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest --cov

チェックアウトしたリポジトリからサーバーを実行します。

uv run querido-diario-mcp-server

MCP ツールを対話的に確認します。

uv run mcp dev src/querido_diario_mcp_server/server.py:mcp

テスト戦略

ユニットテストでは httpx.MockTransport を使って HTTP 境界をモックするため、自動テストスイートは公開 API に依存しません。

テストでは次の項目を網羅しています。

• 都市および官報の検索の成功
• クエリのシリアライズと、繰り返し指定される地域 ID
• 日付範囲、ページネーション、並べ替え
• 結果が空の場合
• 上流の 4xx および 5xx エラー
• 不正なレスポンス
• 接続エラーとタイムアウト
• MCP ツールの検出、スキーマ、構造化出力
• MCP 境界での検証エラーと上流エラー

実際の本番 API と、MCP から API までの全経路を検証するための手動スモークテストスクリプトを利用できます。

uv run python scripts/smoke_test_api.py
uv run python scripts/smoke_test_mcp.py

プロジェクトの状況

プロジェクトは現在ベータ版です。MCP ツールの範囲は意図的に小さく保たれており、変更は慎重に行われます。リリース履歴は CHANGELOG.md に記載されています。

次の項目は、現在の対象範囲に意図的に含めていません。

• 任意の URL の取得
• PDF または全文の自動ダウンロード
• OCR
• 書き込み操作
• クロールとバックグラウンドジョブ
• LLM による組み込みの要約
• Web インターフェース

Querido Diário との関係

これはコミュニティによって開発された非公式プロジェクトです。

Querido Diário は、Open Knowledge Brasil とそのコミュニティによって運営されています。このリポジトリは Open Knowledge Brasil の公式プロジェクトではなく、同組織による推奨や保守を受けていません。また、同プロジェクトの公開 API のみを利用します。

関連する上流リポジトリ：

• okfn-brasil/querido-diario
• okfn-brasil/querido-diario-api
• okfn-brasil/querido-diario-deployment

上流エンドポイントの履歴に関する補足は、docs/upstream-api-history.md に記載されています。

貢献

Issue とプルリクエストを歓迎します。開発ワークフロー、プロジェクトの対象範囲、レビュー用チェックリストについては、CONTRIBUTING.md を参照してください。

ライセンス

MIT