activities-mcp

공개 활동·공모전·경진대회 목록의 공개 메타데이터만 로컬 SQLite에 캐시하고, 읽기 전용 MCP 도구 5개로 STDIO에 제공하는 서버입니다. 수집은 명시적으로 실행하는 CLI 작업이며, MCP 서버는 이미 저장된 캐시만 읽습니다.

제공 MCP 도구

모든 도구는 읽기 전용입니다. 입력 오류는 invalid_input, 로컬 캐시 접근 실패는 storage_error, 존재하지 않는 항목은 not_found의 안정적인 응답 계약으로 반환하며, SQL·경로·로컬 예외 세부 정보는 노출하지 않습니다.

Related MCP server: paycoreDb

지원 소스와 수집 범위

현재 지원하는 소스는 아래 7개입니다. 모든 요청은 HTTPS, 허용 호스트·경로· 쿼리 정책, 수동 리다이렉트 검증, 응답 크기 제한, 지연, 제한된 재시도 아래에서 수행합니다. 401·403·429, CAPTCHA, 정책 위반, 파서 드리프트는 우회하지 않고 해당 소스를 저하 상태로 기록합니다.

세부 정책 근거와 점검 시각은 docs/source-policy.md를 참조하세요. 이 정책은 기술적 통제이며, 각 사이트의 약관·robots·법적 조건에 대한 허가를 주장하지 않습니다.

기술 구성

• 런타임: Python 3.13+, uv

• 서버·저장: MCP SDK (STDIO), SQLite, FTS5

• 수집: httpx2, BeautifulSoup4, defusedxml

• 설정·CLI: Pydantic, pydantic-settings, Typer

• 품질: pytest, Ruff, basedpyright

설치와 로컬 실행

uv sync
uv run activities-mcp --help

처음에는 데이터베이스를 만들고 7개 소스 상태를 시드합니다. 이 명령은 네트워크 수집을 실행하지 않습니다.

uv run activities-mcp init-db --db-path data/activities.db
uv run activities-mcp status  --db-path data/activities.db

refresh는 각 활성 소스의 보수적인 최신 목록 계획만 수행합니다.

uv run activities-mcp refresh --db-path data/activities.db

backfill은 운영자가 명시적으로 요청할 때만 사용합니다. 최대 3페이지의 지원되는 공개 GET 목록만 계획하며, POST 페이지네이션을 추측해서 만들지 않습니다.

uv run activities-mcp backfill --pages 1 --db-path data/activities.db

MCP 서버는 기존 데이터베이스가 있어야 하며 STDIO만 사용합니다.

uv run activities-mcp serve --db-path data/activities.db

status와 serve는 데이터베이스를 새로 만들지 않습니다. 실수로 MCP 조회가 수집 작업을 시작하지 않도록 하기 위한 경계입니다.

설정

환경변수는 검증된 기본값을 제공하고, 명시한 --db-path가 우선합니다.

예를 들어 별도 경로와 짧은 로컬 테스트 지연을 사용하려면 다음과 같이 실행합니다.

ACTIVITIES_MCP_DB_PATH=data/activities.db \
ACTIVITIES_MCP_DELAY_SECONDS=3 \
uv run activities-mcp refresh

MCP 클라이언트 등록

GUI 클라이언트는 셸의 PATH를 상속하지 않을 수 있으므로 command에는 uv의 절대 경로를 권장합니다. 아래의 /Users/me/.local/bin/uv, 프로젝트 경로, DB 경로를 실제 환경에 맞게 바꾸세요.

Claude Desktop

Claude Desktop의 MCP 설정 파일에 다음 서버를 추가합니다.

{
  "mcpServers": {
    "activities": {
      "command": "/Users/me/.local/bin/uv",
      "args": [
        "run", "--project", "/path/to/activities-mcp",
        "activities-mcp", "serve", "--db-path",
        "/path/to/activities-mcp/data/activities.db"
      ]
    }
  }
}

ChatGPT/Codex

ChatGPT/Codex의 로컬 MCP 서버 설정에 같은 STDIO 명령을 등록합니다.

{
  "mcpServers": {
    "activities": {
      "command": "/Users/me/.local/bin/uv",
      "args": [
        "run", "--project", "/path/to/activities-mcp",
        "activities-mcp", "serve", "--db-path",
        "/path/to/activities-mcp/data/activities.db"
      ]
    }
  }
}

Hermes

Hermes의 로컬 MCP 서버 설정에도 다음 STDIO 구성을 사용합니다.

{
  "mcpServers": {
    "activities": {
      "command": "/Users/me/.local/bin/uv",
      "args": [
        "run", "--project", "/path/to/activities-mcp",
        "activities-mcp", "serve", "--db-path",
        "/path/to/activities-mcp/data/activities.db"
      ]
    }
  }
}

세 클라이언트 모두 먼저 init-db를 한 번 실행하고, 캐시 파일 경로가 서버 프로세스에서 읽을 수 있는 위치인지 확인해야 합니다.

스케줄러와 GitHub Actions

이 프로그램에는 내부 스케줄러가 없습니다. 운영 환경의 cron, systemd timer, 워크플로, 컨테이너 스케줄러처럼 관리자가 선택한 저빈도 실행기로 refresh를 호출하세요.

0 3 * * 3 cd /path/to/activities-mcp && /Users/me/.local/bin/uv run activities-mcp refresh --db-path data/activities.db

저장소의 .github/workflows/refresh.yml은 수동 실행과 주간 cron을 제공합니다. 워크플로는 이전 activities.db 캐시를 복원한 뒤 init-db(멱등), refresh를 실행하고 새 캐시를 보관합니다. 모든 액션은 커밋 SHA로 고정되어 있으며 권한은 읽기 전용입니다. 운영 정책과 백필 지침은 docs/scheduler.md를 참조하세요.

캐시 보존과 실패 처리

수집 성공은 해당 소스의 유효한 공개 레코드를 upsert하고 안전 상태를 갱신합니다. 반대로 타임아웃, 차단, CAPTCHA, 파서 드리프트, 빈 파싱 결과, 개별 상세 실패는 기존 캐시를 삭제하지 않습니다. 소스 상태만 degraded와 안전 오류 코드로 바뀌며, 다른 소스의 수집은 계속 진행합니다. 따라서 일시적 외부 장애 중에도 MCP 클라이언트는 마지막으로 검증된 캐시를 계속 읽을 수 있습니다.

개인정보·비수집 원칙

이 프로젝트는 목록에서 공개된 제목, 주최자, 날짜, 상태, 카테고리, 태그, 위치, 공개 카운터와 정규 URL 등 최소 메타데이터만 저장합니다. 다음은 요청·저장·반환하지 않습니다.

• 로그인 세션, 계정, 프로필, 개인 연락처, 이메일, 전화번호

• 결제, 구매, 주문, 티켓, 제출물, 데이터셋, 첨부파일, 이미지, 본문

• API 키, Supabase 비밀값, 쿠키, 인증 헤더

• LLM 프롬프트, 대화 내용, 추천·랭킹을 위한 사용자 행동 데이터

테스트 파서 fixture도 키·이메일·전화번호·실제 비공개 응답을 포함하지 않도록 검사합니다.

MCP와 LLM의 책임 경계

MCP 서버의 책임은 로컬 캐시의 사실적 메타데이터 조회뿐입니다. 서버는 LLM을 호출하지 않고, 추천·판단·지원서 작성·일정 등록·자동 제출·외부 변경을 수행하지 않습니다. Claude, ChatGPT/Codex, Hermes 같은 클라이언트의 LLM은 반환된 사실을 어떻게 대화에 활용할지 결정할 수 있지만, 그 판단과 생성 결과는 이 서버의 수집· 저장·정책 경계 밖에 있습니다.