Gyeongbuk MCP

Это FastMCP-сервер, предоставляющий региональные и публичные данные Кёнбука AI-агентам.

В настоящее время предоставляет инструменты для поиска больниц, автобусных остановок, традиционных рынков, возрастного распределения населения, региональных классов безопасности и рекомендаций по рыночно-ориентированным жилым зонам для пожилых людей без автомобиля. Базовый режим работы преобразует исходные файлы публичных данных в SQLite для запросов, поэтому не требует API-ключей или подключения к внешним серверам. Подробности о вводе/выводе каждого инструмента и ограничениях данных см. в docs/.

Быстрый старт

Требуются Python 3.12 или новее и uv.

make sync
make data-setup
make run

make data-setup загружает официальные исходники, зафиксированные в data/sources.toml, проверяет SHA-256 и формат файлов, а затем создаёт локальную SQLite-базу. API-ключ не требуется. Исходники и созданная БД не включаются в Git и GitHub Release.

Текущий снимок, созданный из загруженных исходников, содержит 3 415 больниц и клиник Кёнбука, 16 031 записей о медицинских специальностях, 29 735 остановок Кёнбука, 53 маршрута Пхохана и 196 паттернов маршрутов, 51 маршрут Пхохана с возможностью определения интервалов движения, 132 традиционных рынка, 3 949 возрастных интервалов и 138 записей о региональных классах безопасности.

При необходимости скопируйте пример конфигурации. В файловом режиме ключ аутентификации не требуется.

cp .env.example .env

DATA_MODE=file
LOCAL_DATABASE_PATH=data/processed/gyeongbuk.sqlite3

Устанавливайте DATA_MODE=api и DATA_GO_KR_SERVICE_KEY только при временном использовании API-режима. API-режим применяется только к запросам больниц, автобусных остановок и рынков; инструменты по населению и безопасности продолжают использовать локальную SQLite. .env исключён из Git, а переменные окружения оболочки и CI с теми же именами имеют приоритет над .env.

Related MCP server: power-plan-db

Регистрация MCP-клиента

Зарегистрируйте в stdio MCP-конфигурации следующим образом. Замените /absolute/path/gyeongbuk-mcp на абсолютный путь к вашему репозиторию.

{
  "mcpServers": {
    "gyeongbuk": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/gyeongbuk-mcp",
        "run",
        "fastmcp",
        "run",
        "src/server.py"
      ]
    }
  }
}

Команды

make run          # stdio MCP 서버 실행
make data-fetch   # 고정된 공식 원본 다운로드·검증
make data-check   # 네트워크 없이 기존 원본 검증
make data         # 기존 원본에서 로컬 SQLite 재생성
make data-setup   # 원본 다운로드 후 SQLite 생성
make format       # Ruff로 포매팅
make format-check # 포맷 변경 없이 검사
make lint         # Ruff 린트
make typecheck    # mypy 타입 체크
make test         # pytest 테스트
make audit        # Python 의존성 취약점 검사
make check        # 포맷, 린트, 타입, 테스트 전체 검사
make pre-commit   # 모든 파일에 pre-commit 훅 실행

Каждую команду можно запускать напрямую через uv run ....

Для участия в разработке см. CONTRIBUTING.md, для сообщения об уязвимостях — SECURITY.md.

Структура

src/
├── server.py       # FastMCP 서버 진입점
├── tools/          # MCP 도구 정의
├── services/       # 비즈니스 로직
├── clients/        # 외부 API 클라이언트
└── models/         # 입력/출력 모델
tests/
docs/                 # 도구 계약, 데이터 출처, 구현 계획
data/
├── raw/              # 직접 내려받은 원본(커밋 제외)
├── reference/        # 출처가 명시된 작은 보조 매핑
└── processed/        # 생성된 SQLite(커밋 제외)
scripts/
└── build_snapshot.py # 파일 정규화 진입점

Лицензия

Исходный код распространяется под MIT License. MIT не применяется к исходникам публичных данных, созданной SQLite и производным проверочным материалам в data/reference/; на них распространяются условия использования соответствующих организаций-поставщиков. Подробнее об указании источников и политике распространения см. DATA_LICENSES.md.