mcp-abfall

English · Deutsch

독일 도시와 구역의 폐기물 수거 일정을 위한 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: vnbdigital-mcp

설치

서버는 설치된 패키지가 아니라 저장소 체크아웃에서 실행됩니다. vendor/ 아래의 데이터 소스와 data/ 아래의 레지스트리가 필요하며, 둘 다 프로젝트 루트 기준으로 확인됩니다. 이것이 PyPI에 없는 이유이기도 합니다. 휠은 깔끔하게 설치되지만 여전히 작동하지 않을 것이기 때문입니다.

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. 위의 세 가지와 같은 패턴을 따르는 각각 하나의 리졸버가 더 필요합니다.

• 제안 목록을 제공하지 않는 다른 철자를 사용하는 포털 (에르푸르트, 킬).

• 당국 측의 장애, 속도 제한 및 잘못된 형식의 응답 (자르브뤼켄은 ICS 대신 HTML을 반환합니다).

레이아웃

레지스트리는 런타임에 빌드되지 않습니다. data/providers.json은 스크립트로 생성되므로 서버를 시작할 때 150개 모듈을 가져오지 않습니다. 서브모듈 업데이트 후 다시 빌드하세요.

데이터 소스 및 사용

수거 날짜는 각 폐기물 당국의 포털에서, 주소 해석은 Nominatim(OpenStreetMap)에서 가져옵니다. Nominatim에는 사용 정책이 있습니다. 초당 최대 1회 요청이며, 서버는 이를 준수하고 결과를 ~/.cache/mcp-abfall/에 캐시합니다.

무언가가 의존하는 날짜(대형 폐기물, 유해 폐기물 수거 지점)의 경우 모든 응답에 포함된 포털 주소를 확인해 볼 가치가 있습니다.

기여

가장 유용한 기여는 특정 당국이 작동하지 않는다는 보고입니다. 올바른 질문을 담은 이슈 템플릿이 있습니다. 당국 리졸버를 추가하는 방법은 CONTRIBUTING.md에 있습니다. 보안 문제는 비공개 보고에 해당하며, SECURITY.md를 참조하세요. 변경 사항은 CHANGELOG에 나열됩니다. 이 저장소에서 작업하는 에이전트는 AGENTS.md를 읽어야 합니다.

하나의 원칙이 프로젝트 전체에 흐르며 기여에도 적용됩니다. 의심스러우면 묻고, 추측하지 마세요. 잘못 추측된 도시는 기꺼이 이웃 지방자치단체의 일정표를 반환합니다. 옳은 것처럼 보이는 틀린 답변입니다.

라이선스

MIT, LICENSE 참조. 서브모듈 vendor/hacs_waste_collection_schedule는 자체 MIT 라이선스(저작권 (c) 2020 Steffen Zimmermann)를 따릅니다. 이 저장소는 해당 코드를 참조만 할 뿐 포함하지 않습니다. 타사 저작자 표시는 NOTICE에 정리되어 있습니다.