gov-notice-mcp

gov-notice-mcp는 정부 및 공공기관 공고를 수집, 저장, 검색, 추천하는 범용 MCP 서버와 REST API입니다. 특정 기업 전용 로직 없이 user_profile.yaml의 사용자 프로필을 기준으로 공고 적합도를 분석합니다.

Features

• FastAPI REST API
• MCP Python SDK 기반 Tool 서버
• Connector 패턴 기반 기관 확장
• SQLite 개발 DB, PostgreSQL 운영 DB 지원
• APScheduler 기반 주기 수집
• Rule 기반 추천 점수
• pytest 기본 테스트

Project Structure

app/
  api/          REST routers
  connectors/   기관별 수집기
  jobs/         scheduler
  mcp/          MCP server/tools
  models/       SQLAlchemy models
  schemas/      Pydantic schemas
  services/     business logic
  utils/        parsing helpers
tests/

Install

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env

OpenAPI Keys

.env에 키를 등록합니다. 저장소에는 실제 키를 커밋하지 마십시오.

G2B_API_BASE_URL=https://apis.data.go.kr/1230000/ad/BidPublicInfoService
G2B_SERVICE_KEY=your-data-go-kr-service-key

NTIS_API_BASE_URL=https://www.ntis.go.kr/rndopen/openApi/public_project
NTIS_SERVICE_KEY=your-ntis-key

Run REST API

uvicorn app.main:app --reload

기본 문서:

• http://127.0.0.1:8000/docs
• http://127.0.0.1:8000/health

REST API Examples

curl "http://127.0.0.1:8000/notices?keyword=AI&only_open=true"
curl -X POST "http://127.0.0.1:8000/collect?keyword=AI&limit=10"
curl "http://127.0.0.1:8000/recommended"
curl "http://127.0.0.1:8000/profile"

Run Web UI

cd web
npm install
npm run dev

기본 Web UI 주소는 http://localhost:3000입니다. 백엔드가 다른 주소에서 실행 중이면 NEXT_PUBLIC_API_BASE_URL을 설정합니다.

NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000 npm run dev

OpenAPI Test Console

OpenAPI Test 화면은 개발자가 실제 OpenAPI Key 발급 후 connector가 정상 동작하는지 검증하기 위한 개발/테스트용 기능입니다.

화면에서 source를 선택하면 백엔드가 서버의 .env 값을 읽어 해당 OpenAPI의 Base URL과 API Key를 자동으로 채웁니다. API Key 입력칸은 기본적으로 마스킹되며, 값은 DB나 브라우저 localStorage에 저장되지 않습니다. Load .env 버튼으로 현재 선택된 source의 .env 값을 다시 불러올 수 있습니다.

사용 순서:

1. Web UI 접속
2. OpenAPI Test 메뉴 선택
3. source 선택
4. Base URL 입력
5. API Key 입력
6. keyword 입력
7. 연결 테스트 실행
8. raw response와 normalized notice 확인

테스트 API:

curl -X POST "http://127.0.0.1:8000/openapi/test" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "g2b",
    "base_url": "https://apis.data.go.kr/1230000/ad/BidPublicInfoService",
    "service_key": "your-key",
    "keyword": "AI",
    "from_date": "2026-01-01",
    "to_date": "2026-12-31",
    "limit": 10
  }'

보안 원칙:

• API Key는 로그에 남기지 않습니다.
• API Key는 DB에 저장하지 않습니다.
• API Key는 브라우저 localStorage에 저장하지 않습니다.
• 테스트 요청 후 서버 메모리에 영구 저장하지 않습니다.
• 운영환경에서는 .env, Secret Manager, 컨테이너 secret 등으로 API Key를 관리하십시오.

Run MCP

python -m app.mcp.server

MCP client 설정 예:

{
  "mcpServers": {
    "gov-notice-mcp": {
      "command": "python",
      "args": ["-m", "app.mcp.server"],
      "cwd": "/path/to/gov-notice-mcp"
    }
  }
}

MCP Tools

• search_notices: 공고 검색
• get_notice_detail: 공고 상세 조회
• summarize_notice: 공고 요약
• analyze_fit_for_user: 사용자 프로필 기준 적합도 분석
• watch_new_notices: 신규 공고 조회
• get_user_profile: 사용자 프로필 조회
• update_user_profile: 사용자 프로필 수정
• collect_notices: 수집 실행

Recommendation Rules

• 관심 키워드: +20
• 선호 기관: +15
• 선호 지역: +10
• 지원금액 이상: +10
• 제외 키워드: -30
• 마감 7일 이하: -10

최종 점수는 0~100 범위로 보정됩니다.

Docker

docker compose up --build

서비스:

• postgres: PostgreSQL 16
• api: FastAPI application

Migrations

개발 중에는 앱 시작 시 SQLite 테이블을 자동 생성합니다. 운영 DB에서는 Alembic을 사용할 수 있습니다.

alembic upgrade head

Tests

pytest

Adding a New Institution

1. app/connectors/base.py의 BaseConnector를 상속합니다.
2. fetch_notices(), normalize(), get_source_name()을 구현합니다.
3. CollectorService의 connector 목록에 추가합니다.
4. normalization 테스트를 추가합니다.

새 기관 추가 시 REST API와 MCP Tool은 같은 service 계층을 쓰므로 별도 라우터 변경 없이 검색/추천 흐름에 포함됩니다.