enable-nz-mcp

공개적으로 호스팅되는 MCP 서버로, enable.co.nz의 콘텐츠를 검색 가능한 도구로 노출합니다. Copilot Studio, VS Code Copilot, Claude Desktop 또는 모든 MCP 클라이언트에서 연결할 수 있습니다.

개인 포트폴리오 프로젝트입니다. Enable New Zealand 또는 어떤 고용주와도 관련이 없으며, 공개 웹사이트의 공개 콘텐츠만 읽습니다.

• 서버: https://enable-nz-mcp.duckdns.org/mcp (Streamable HTTP)

• 상태 확인: https://enable-nz-mcp.duckdns.org/health

아키텍처

GitHub Actions (weekly cron)
  └─ crawl enable.co.nz → build index.db.new
     └─ rsync over SSH → droplet:/opt/enable-nz-mcp/data/index.db.new
        └─ atomic mv → index.db

DigitalOcean droplet (Ubuntu 24.04, Sydney)
  ├─ Caddy  → TLS termination + reverse proxy on enable-nz-mcp.duckdns.org
  └─ pm2    → node dist/server.js  (port 8081, localhost only)
                └─ opens a fresh SQLite read connection per query

서버는 인덱스를 메모리에 캐시하지 않습니다. 모든 도구 호출은 디스크의 index.db에 대해 새롭고 읽기 전용인 연결을 엽니다. 주간 크롤링이 인덱스를 재구축하고 단일 원자적 mv로 교체하므로, 인덱스는 다운타임 없이 재시작 없이 새로고침됩니다.

모든 방향에서 읽기 전용입니다: 크롤러는 enable.co.nz만 읽고, MCP 도구는 로컬 SQLite 인덱스만 읽습니다. 어떤 종류의 쓰기 작업도 없습니다.

Related MCP server: MCP Knowledge Base Server

도구

search_enable_nz

enable.co.nz 전체 텍스트 검색.

관련성 순으로 정렬된 일치 페이지를 반환하며, 각 페이지에는 url, title, section 및 강조 표시된 스니펫이 포함됩니다.

get_page

URL로 한 페이지의 전체 텍스트를 검색합니다.

url, title, section, description, content, crawled_at을 반환합니다. 콘텐츠가 ~15,000자를 초과하면 잘리며, 응답에 truncated: true가 포함됩니다.

list_sections

입력 없음. 사이트의 최상위 섹션을 페이지 수와 함께 나열하고, 인덱스의 crawled_at 타임스탬프도 표시합니다. 검색 전 방향을 잡거나 데이터의 최신 상태를 확인하는 데 유용합니다.

예시 쿼리

연결 후 MCP 클라이언트에 다음과 같이 요청해 보세요:

• "enable.co.nz에서 휠체어 자금 지원 정보를 검색해 줘."

• "enable.co.nz 인덱스가 다루는 섹션은 무엇인가요?"

• "https://www.enable.co.nz/services의 전체 콘텐츠를 가져와서 요약해 줘."

MCP 클라이언트 연결

Copilot Studio

1. 에이전트 열기 → 도구 → 도구 추가 → 새 도구 → Model Context Protocol.

2. 서버 이름: enable-nz-mcp (또는 원하는 이름 — 라벨일 뿐입니다).

3. 서버 URL: https://enable-nz-mcp.duckdns.org/mcp

4. 인증: 인증 없음 (서버에 API_KEY가 설정되어 있지 않으면 그대로 두고, 설정되어 있으면 API 키/베어러 인증 옵션을 선택하여 제공).

5. 만들기 → Copilot Studio가 Streamable HTTP를 통해 연결하고(2025년 8월 SSE를 제거한 이후 지원하는 유일한 전송 방식) search_enable_nz, get_page, list_sections을 나열합니다. 도구를 에이전트에 추가하고 "enable.co.nz에서 휠체어 자금 지원 검색" 같은 프롬프트로 테스트하세요.

VS Code Copilot

1. 명령 팔레트 열기 → MCP: Add Server.

2. HTTP 선택 후 https://enable-nz-mcp.duckdns.org/mcp 입력.

3. 연결되면 VS Code가 search_enable_nz, get_page, list_sections을 사용 가능한 도구로 나열합니다.

Claude Desktop

1. 설정 → 커넥터 → 사용자 지정 커넥터 추가.

2. URL: https://enable-nz-mcp.duckdns.org/mcp.

3. Claude가 Streamable HTTP 전송을 자동으로 협상합니다.

기타 MCP 클라이언트

Streamable HTTP 전송을 사용하여 https://enable-nz-mcp.duckdns.org/mcp를 가리키세요. 서버에 API_KEY가 설정되어 있으면 Authorization: Bearer <key>를 보내세요.

로컬 개발

npm ci
cp .env.example .env        # edit as needed

npm run crawl                # builds data/index.db.new
mv data/index.db.new data/index.db

npm run dev                  # starts the server with tsx, reading .env

MCP Inspector로 실행 중인 서버를 테스트하세요:

npx @modelcontextprotocol/inspector
# connect to http://127.0.0.1:8081/mcp

또는 수동으로 스모크 테스트:

curl http://127.0.0.1:8081/health

curl -X POST http://127.0.0.1:8081/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

테스트 스위트 실행:

npm test

배포

서버는 기존 DigitalOcean 드롭릿에서 자체 비특권 시스템 사용자(mcpsvc)로 실행되며, 같은 박스의 다른 서비스와 격리됩니다. mcpsvc는 sudo가 없고 /opt/enable-nz-mcp 외부에 대한 읽기 권한도 없습니다. pm2 프로세스 구성은 deploy/ecosystem.config.cjs, 리버스 프록시 블록은 deploy/Caddyfile.example를 참조하세요.

pm2와 Caddy 구성 변경 모두 root 권한이 필요하므로, mcpsvc는 자체적으로 pm2 save까지만 할 수 있습니다. 관리자가 pm2 startup(재부팅 후 프로세스 유지)을 실행하고 Caddy 사이트 블록을 설치/리로드해야 합니다. 현재 Caddy 계층에는 속도 제한이 적용되지 않습니다. 이 박스의 Caddy 빌드에 없는 타사 caddy-ratelimit 플러그인이 필요하기 때문입니다.

.github/workflows/refresh-index.yml 워크플로는 주간(일요일 02:00 UTC, 또는 workflow_dispatch로 수동) 사이트를 다시 크롤링하고, 최소 페이지 수/크기를 기준으로 검증하며, rsync + SSH를 통한 원자적 mv로 새 인덱스를 배포합니다. DEPLOY_SSH_KEY, DEPLOY_HOST, DEPLOY_USER 세 가지 저장소 시크릿이 필요합니다. authorized_keys의 command= 지시문으로 제한된 전용 배포 키페어를 사용하여 rsync/mv만 실행할 수 있고 임의 셸은 실행할 수 없습니다.

v1 범위 밖

• 임베딩 / 의미 검색 (마케팅 사이트 하나에는 SQLite FTS5를 통한 키워드 검색으로 충분)

• 헤드리스 브라우저 렌더링

• 다중 사이트 지원

• 모든 종류의 쓰기 작업

• 사용자 수준 인증 또는 테넌트별 격리