KallistoX/mcp-unifi-applications

UniFi 애플리케이션 API 문서(Network, Protect, Site Manager)를 Claude Desktop, Claude Code (VS Code / JetBrains) 또는 기타 MCP 호환 클라이언트에서 쿼리 가능한 도구로 노출하는 MCP (Model Context Protocol) 서버입니다.

JS로 렌더링되는 SPA (Single Page Application) 문서를 구조화된 JSON 파일로 변환하는 Playwright 기반의 스크레이퍼(Scraper)와 이를 제공하는 Python MCP 서버를 포함하고 있습니다.

"UniFi의 network API를 사용하여 Go 언어로 네트워크를 생성하는 방법과 관리형 IPv4 DHCP 게이트웨이 설정과 관련하여 어떤 옵션이 있는지 알려줄 수 있나요?"

Claude는 자동으로 MCP 서버를 쿼리하여 엔드포인트(Endpoints)를 검색하고, 스키마(Schemas)를 가져오며, 디스크리미네이터(Discriminator) 변형을 상세히 분석한 후, 전체 API 상세 정보와 작동하는 Go 예제와 함께 응답합니다.

스크레이퍼는 Docker 내부에서 실행됩니다 (Playwright/Chromium 필요):

# 스크레이퍼 이미지 빌드
docker build -t unifi-scraper .
# Network API 문서 스크레이핑 (기본값, 최신 버전)
...

Network API v10.1.84에 대해 미리 스크레이핑된 문서가 docs/network/에 포함되어 있습니다.

python -m venv .venv
source .venv/bin/activate # 또는: source .venv/bin/activate.fish
pip install .

Claude Code (VS Code / JetBrains) - 프로젝트 루트에 .mcp.json을 추가하세요 (추가 후 Window Reload 필요):

{
"mcpServers": {
"unifi-docs": {
...

Claude Desktop - ~/.config/Claude/claude_desktop_config.json (Linux) 또는 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)에 추가하세요:

{
"mcpServers": {
"unifi-docs": {
...

애플리케이션	URL	로컬/원격	비고
Network	developer.ui.com/network	둘 다	기본 앱
Protect	developer.ui.com/protect	둘 다
Site Manager	developer.ui.com/site-manager	원격 전용	로컬/원격 전환 없음

세 애플리케이션 모두 버전 드롭다운, 엔드포인트 페이지, 가이드 페이지를 포함하는 동일한 문서 SPA 구조를 공유합니다.

도구 (Tool)	설명 (Description)
list_endpoints	모든 API 엔드포인트 (API endpoints) 목록을 나열하며, 선택적으로 HTTP 메서드(HTTP method)나 애플리케이션(app)으로 필터링할 수 있음
search_endpoints	이름, 경로(path), 메서드(method) 또는 설명(description)을 통한 퍼지 검색 (이름(name)으로 필터링 가능)
get_endpoint	엔드포인트에 대한 전체 스키마 (summary 또는 raw JSON)
get_endpoint_group	리소스(resource)에 대한 모든 CRUD 작업 (예: "networks")
get_example	curl, Go, Node.js, Python 또는 Ansible 형식의 코드 예제 (로컬/원격)
get_response_sample	엔드포인트에 대한 예시 JSON 응답
find_field	모든 엔드포인트 스키마에서 필드 이름(field name) 검색
get_field_schema	특정 필드의 서브트리(subtree) 상세 탐색 (예: management[GATEWAY].dhcpV4)
get_guide	API 가이드 페이지 (필터링 구문(filtering syntax), 에러 처리(error handling), 시작하기(getting started))

여러 결과를 반환하는 도구들은 애플리케이션별로 필터링하기 위해 선택적 app 파라미터 (network, protect, site-manager)를 허용합니다.

변수 (Variable)	기본값 (Default)	설명 (Description)
DOCS_DIR	./docs (mcp_server.py 기준 상대 경로)	스크래핑된 JSON 문서가 포함된 디렉토리. 애플리케이션 하위 디렉토리(network/, protect/, site-manager/)를 기대함.

node scrape.mjs [options] [slug...]
Options:
--app <name> 애플리케이션: network (기본값), protect, site-manager.
...

슬러그(slug)는 문서 URL의 마지막 경로 세그먼트입니다:
https://developer.ui.com/network/v10.1.84/createnetwork

-> createnetwork

출력은 <output>/<app>/에 작성됩니다 (예: docs/network/, docs/protect/).

전체 스캔은 재개 가능합니다 - 이미 스크래핑된 페이지는 건너뜁니다. 다시 스크래핑하려면 --force를 사용하세요.

mcp-unifi-applications/
├── scrape.mjs # Playwright 스크래퍼 (Docker에서 실행)
├── mcp_server.py # MCP 서버 (Python, stdio 전송 방식)
...

{
"h1": "Create Network",
"method": "POST",
...

{
"h1": "Filtering",
"type": "guide",
...

{
"name": "management",
"required": true,
...

discriminator.schema

discriminator.schema

해당 옵션이 활성화되었을 때 보이는 형제 필드(sibling fields)를 포함합니다 (discriminator 필드 자체는 제외) - 중첩(Nesting)은 재귀적(recursive)입니다 - 변체(variants) 내의 discriminator는 완전히 확장됩니다.

children

정적으로 확장된 객체 필드(object fields)를 캡처합니다.

MIT