Gyeongbuk MCP

A FastMCP server that provides Gyeongbuk regional and public data to AI agents.

It currently provides hospitals, bus stops, traditional markets, age-group population ratios, regional safety ratings, and a market-centered living-area recommendation tool for elderly people without cars. In the default execution mode, public data source files are converted to SQLite and queried, so no API authentication key or external server connection is required. For each tool's inputs and outputs and data limitations, see docs/.

Quick Start

Python 3.12 or later and uv are required.

make sync
make data-setup
make run

make data-setup downloads the official sources pinned in data/sources.toml, verifies their SHA-256 and file format, and then creates a local SQLite database. No API authentication key is required. The source files and the generated DB are not included in Git or GitHub Releases.

The snapshot generated from the currently downloaded sources includes 3,415 hospitals and clinics in Gyeongbuk, 16,031 medical department entries, 29,735 bus stops in Gyeongbuk, 53 Pohang routes and 196 route patterns, 51 Pohang routes for which dispatch intervals can be determined, 132 traditional markets, 3,949 age-group entries, and 138 regional safety ratings.

Copy the example configuration if needed. File mode does not require an authentication key.

cp .env.example .env

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

Set DATA_MODE=api and DATA_GO_KR_SERVICE_KEY only when using API mode temporarily. API mode applies only to hospital, bus stop, and market lookups; population and safety tools continue to use the local SQLite database. .env is excluded from Git, and shell/CI environment variables with the same name take precedence over .env.

Related MCP server: power-plan-db

Registering an MCP Client

Register it in the stdio MCP configuration as follows. Replace /absolute/path/gyeongbuk-mcp with the absolute path of your actual repository.

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

Commands

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 훅 실행

Each command can also be run directly with uv run ....

To contribute, see CONTRIBUTING.md; to report vulnerabilities, see SECURITY.md.

Structure

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

License

The source code is distributed under the MIT License. The MIT license does not apply to the public data sources, the generated SQLite database, or the derived review materials in data/reference/, which are subject to each provider's terms of use. See DATA_LICENSES.md for detailed attribution and redistribution policies.