mcp-abfall

英語 · ドイツ語

ドイツの都市と郡のごみ収集カレンダーを提供するMCPサーバー。指定された住所について、収集日（残余廃棄物、生ごみ、紙、包装材、粗大ごみ、有害廃棄物の収集場所）を検索します。

address ──▶ Nominatim ──▶ municipality + district ──▶ provider search (995)
                                                              │
                       collection dates ◀── portal ◀── resolve arguments

なぜこれは簡単ではないのか

ドイツの廃棄物管理は自治体単位で運営されています。全国規模のAPIは存在しません。約400の公的廃棄物当局がそれぞれ独自のポータルを運営しており、その背後には少数のソフトウェアプラットフォーム（Abfall.IO/AbfallPlus、AbfallNavi、Jumomind、AWIDO、C-Trace、Müllmax、その他多数の単純なICSエクスポート）があります。

このサーバーは、データソースとして mampfes/hacs_waste_collection_schedule (MIT) を使用しています。これは950以上のソースモジュールを備え、活発にメンテナンスされているプロジェクトです。その内部パッケージはHome Assistantから独立しており、ここではGitサブモジュールとして組み込まれています。

このプロジェクトの実際の作業は、住所を担当の廃棄物当局とその内部パラメータに変換することです。Home Assistantでは人間が一度クリックするだけで済みますが、MCPサーバーはそれを自力で行わなければなりません。

Related MCP server: fds-mcp

インストール

このサーバーは、インストールされたパッケージとしてではなくリポジトリのチェックアウトから実行されます。vendor/ ディレクトリのデータソースと data/ ディレクトリのレジストリが必要で、どちらもプロジェクトルートからの相対パスで解決されます。これがPyPIにない理由でもあります。wheelは正常にインストールされるでしょうが、それでも動作しません。

git clone --recurse-submodules https://github.com/AlpayC/mcp-abfall.git
cd mcp-abfall
uv sync
uv run pytest

data/providers.json はリポジトリにチェックインされているので、サーバーはすぐに起動します。サブモジュールを更新したら、再構築してください:

uv run python scripts/build_registry.py

接続方法

ローカルではstdio経由 — claude_desktop_config.json または .mcp.json で:

{
  "mcpServers": {
    "abfall": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-abfall", "run", "mcp-abfall"]
    }
  }
}

HTTPサービスとして:

uv run mcp-abfall --http --host 127.0.0.1 --port 8000

すべてのHTTPリクエストが当局のポータルとNominatimに負荷をかけることに注意してください。個人利用を超える用途では、前面にキャッシュを置き、その背後に独自のNominatimインスタンスを配置してください（MCP_ABFALL_NOMINATIM_URL）。

ツール

ツール名と応答はドイツ語です。ドメインとユーザーがドイツ語だからです。

さらに、当局の完全なリストを持つリソース abfall://traeger があります。

推測より尋ねる

値が一意に決定できない場合、サーバーは推測する代わりに、具体的な選択肢のリストとともに status: "rueckfrage" を返します。これは意図的な設計です。町を誤って推測すると、隣接する自治体のカレンダーが平然と返ってきます。それは正しい答えのように見える間違った答えです。

カバレッジ（実測値）

scripts/build_registry.py は、150のソースモジュールから995の廃棄物当局を収集します。

scripts/smoke.py は実際のポータルに対して実際の住所を照会します。ドイツ全土の21の住所での実行（2026年8月時点）:

これは推定ではなく実測値です。そして、ここでその数字を述べる理由でもあります。「すべてのドイツの都市をカバーしている」というのは、当局リストについては真実ですが、素の住所から完全に自動で解決することについては真実ではありません。

独自のIDルックアップを持つ当局

一部のポータルは、住所から導出できない内部識別子を必要とします。これらのために、ポータルの住所ダイアログが lookup.py に再実装されています:

アップストリーム側のハンブルク用ウィザードは、現在では古くなっています。ポータルがフォームをJavaScriptコンポーネントに移行したため、ここではその住所エンドポイントをページから読み出しています。

残りのケースが失敗する場所

• ルックアップパスがない追加のID引数: ドレスデンの standort、ライプツィヒの idHouseNumber、シュトゥットガルトの streetnr。それぞれ、上記3つと同じパターンに従うリゾルバがもう1つ必要です。

• 異なる綴りを使用し、候補リストを提供しないポータル（エアフルト、キール）。

• 当局側の障害、レート制限、不正なレスポンス（ザールブリュッケンはICSの代わりにHTMLを返します）。

レイアウト

レジストリは実行時に構築されません。data/providers.json はスクリプトによって生成され、サーバー起動時に150のモジュールをインポートしないようにしています。サブモジュールの更新後は再構築してください。

データソースと利用方法

収集日は各廃棄物当局のポータルから取得され、住所解決は Nominatim (OpenStreetMap) から取得されます。Nominatimには利用ポリシーがあり、1秒あたり最大1リクエストまでです。サーバーはこれを尊重し、結果を ~/.cache/mcp-abfall/ にキャッシュします。

粗大ごみや有害廃棄物の収集など、日程に依存する用事がある場合は、各レスポンスに含まれるポータルアドレスを確認する価値があります。

コントリビューション

最も有用なコントリビューションは、ある当局が動作しないという報告です。適切な質問がまとめられた issueテンプレート があります。当局リゾルバの追加方法は CONTRIBUTING.md にあります。セキュリティ上の問題は非公開の報告に含めるべきです。SECURITY.md を参照してください。変更履歴は CHANGELOG に記載されています。このリポジトリで作業するエージェントは AGENTS.md を読むべきです。

プロジェクト全体に通じる一つの原則は、コントリビューションにも適用されます。疑わしいときは推測せず、尋ねること。 町を誤って推測すると、隣接する自治体のカレンダーが平然と返ってきます。それは正しい答えのように見える間違った答えです。

ライセンス

MITライセンスです。LICENSE を参照してください。サブモジュール vendor/hacs_waste_collection_schedule は独自のMITライセンスの下にあります。Copyright (c) 2020 Steffen Zimmermann — このリポジトリはそれを参照するだけで、コードを同梱しません。第三者の帰属表示は NOTICE にまとめられています。