nod-mcp-server

이것은 AI 에이전트가 비즈니스와 상호작용하는 방식입니다. 스크래핑이 아닌 구조화된 매니페스트를 읽는 방식입니다. 이 참조 MCP 서버는 모든 MCP 호환 클라이언트(Claude Desktop, 에이전트 프레임워크, IDE)가 https://{domain}/.well-known/nod.json에 있는 비즈니스의 nod.json 매니페스트를 읽고, 음식 주문, 예약, 제품 검색, 가격 확인 등 비즈니스가 수행할 수 있는 작업에 대한 실제 질문에 답할 수 있도록 합니다.

이 서버는 lookup_nod와 check_capability라는 두 가지 도구를 제공하며, 로컬에서 실행되는 4개의 데모 매니페스트를 포함하고 있어 외부 의존성 없이 즉시 데모를 실행할 수 있습니다.

설치

git clone <this repo> nod-mcp-server
cd nod-mcp-server
npm install
npm run build

Node.js 20+ 버전이 필요합니다.

데모 매니페스트 서버 실행

아직 nod.json을 게시하는 실제 사이트가 거의 없으므로, 이 저장소에는 4개의 예제 매니페스트(레스토랑, 전자상거래, SaaS, 헬스케어)가 포함되어 있으며 로컬에서 실행됩니다.

npm run demo:manifests

다음과 같이 표시되어야 합니다:

NOD demo manifest server listening on http://localhost:3456
  http://localhost:3456/demo-restaurant.localhost/nod.json
  http://localhost:3456/demo-shop.localhost/nod.json
  http://localhost:3456/demo-saas.localhost/nod.json
  http://localhost:3456/demo-health.localhost/nod.json

데모가 진행되는 동안 이 터미널을 계속 실행해 두세요. MCP 서버는 모든 *.localhost 도메인을 이 서버로 자동으로 라우팅합니다.

Claude Desktop 설정

macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json을(를) 열거나 생성하고(Windows의 경우 %APPDATA%\Claude\claude_desktop_config.json), 다음을 추가하세요:

{
  "mcpServers": {
    "nod": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/nod-mcp-server/dist/index.js"]
    }
  }
}

/ABSOLUTE/PATH/TO/nod-mcp-server를 이 체크아웃의 전체 경로(예: /Users/you/projects/nod-mcp-server)로 바꿉니다. Claude Desktop을 다시 시작하세요. 이제 Claude의 도구 선택기에서 lookup_nod와 check_capability라는 두 가지 도구가 포함된 nod 서버가 나열된 것을 볼 수 있습니다.

60초 데모 스크립트

한 터미널에서 데모 매니페스트 서버를 실행하고 Claude Desktop을 설정한 상태에서, 다음 프롬프트를 Claude에 차례대로 붙여넣으세요.

1. "Look up the NOD manifest for demo-restaurant.localhost"

Claude는 lookup_nod({ domain: "demo-restaurant.localhost" })를 호출하고 다음과 같은 결과를 반환합니다:

# Pike Place Noodle House  (restaurant)
Hand-pulled noodles, dumplings, and regional Chinese classics...

- URL: https://demo-restaurant.localhost
- Manifest: http://localhost:3456/demo-restaurant.localhost/nod.json

## Declared capabilities
  - purchase
  - booking
  - view_menu
  - order_food
  - book_table

## Supported actions
  - purchase → https://demo-restaurant.localhost/api/orders [auth: api_key]
  - booking  → https://demo-restaurant.localhost/api/reservations [auth: api_key]
  - search   → https://demo-restaurant.localhost/api/menu/search [auth: none]

2. "Can I order food from demo-restaurant.localhost?"

Claude는 check_capability({ domain: "demo-restaurant.localhost", action: "order_food" })를 호출합니다:

YES — demo-restaurant.localhost supports "order_food".
Manifest declares "order_food" under discovery.mcp_server.capabilities.

Endpoint: POST https://demo-restaurant.localhost/api/orders
Authentication: api_key
Matched via: discovery.mcp_server.capabilities

Constraints:
{ "require_human_confirmation": { "purchases_above": 150, ... },
  "rate_limits": { "transactions": { "requests": 10, "period": "minute" } },
  "allow_automated_purchases": true }

3. "What actions does demo-shop.localhost support?"

Claude는 lookup_nod({ domain: "demo-shop.localhost" })를 호출하고 제품 검색, 가격 책정, 재고 확인, OAuth2로 보호되는 주문 배치(500달러 이상의 인간 확인 임계값 및 60일 반품 정책 포함)를 요약합니다.

보너스 프롬프트

• "Book an appointment at demo-health.localhost — what does that flow require?" → 예약 엔드포인트, 필수 필드(patient_name, DOB, reason, provider_id, preferred_date), OAuth2 범위 및 취소 정책을 반환합니다.

• "Does demo-saas.localhost allow automated purchases?" → 매니페스트가 allow_automated_purchases: false로 설정되어 있으므로 인간 대체 URL과 함께 NO를 반환합니다.

도구 참조

lookup_nod

https://{domain}/.well-known/nod.json을 가져오고, 실패 시 https://{domain}/nod.json으로 대체합니다. 비즈니스 식별 정보, 선언된 기능, 지원되는 작업(엔드포인트 + 인증 포함), API 엔드포인트 및 연락처 방법을 포함한 구조화된 요약을 반환합니다. 실패 시 명확한 "매니페스트를 찾을 수 없음" 메시지를 반환합니다.

check_capability

매니페스트를 가져와 transactions.capabilities, discovery.mcp_server.capabilities, support.contact.mcp_server.capabilities 및 구조적 엔드포인트(transactions.purchase, discovery.search, information.pricing 등)에 대해 작업을 확인합니다. 예/아니오 판정, 엔드포인트 URL, 인증 방법 및 정책 제약 조건(속도 제한, 인간 확인 임계값)을 반환합니다.

*.localhost 라우팅 작동 방식

MCP 서버가 .localhost로 끝나는 도메인을 수신하면 일반적인 well-known URL 대신 http://localhost:3456/{domain}/nod.json에서 가져옵니다. 이를 통해 데모가 독립적으로 실행됩니다. DNS나 HTTPS 설정 없이도 Claude를 demo-restaurant.localhost로 지정하여 실제 결과를 얻을 수 있습니다.

환경 변수:

• NOD_LOCAL_PORT — 데모 매니페스트 서버가 수신 대기하는 포트(기본값 3456)

• NOD_LOCAL_MANIFEST_SERVER — MCP 서버가 .localhost 조회에 사용하는 기본 URL(기본값 http://localhost:3456)

• NOD_FORCE_LOCAL=1 — 모든 도메인을 로컬 매니페스트 서버를 통해 라우팅(새 예제 매니페스트를 테스트하는 기여자에게 유용)

다음 단계

opennod.ai/protocol의 NOD 프로토콜 사양을 사용하여 귀하의 비즈니스를 위한 nod.json을 게시하세요. 최소한의 유효한 매니페스트를 작성하는 데는 약 30분이 소요되며, https://yourdomain.com/.well-known/nod.json에 게시되면 이 MCP 서버(또는 다른 NOD 인식 클라이언트)를 사용하는 모든 에이전트가 귀하의 비즈니스를 발견하고 그 기능에 따라 행동할 수 있게 됩니다.

라이선스

MIT