nod-mcp-server

Así es como los agentes de IA interactuarán con las empresas: no mediante scraping, sino leyendo manifiestos estructurados. Este servidor MCP de referencia enseña a cualquier cliente compatible con MCP (Claude Desktop, frameworks de agentes, IDEs) a leer el manifiesto nod.json de una empresa en https://{domain}/.well-known/nod.json y a responder preguntas reales sobre lo que la empresa puede hacer: pedir comida, reservar una cita, buscar productos, consultar precios y más.

Expone dos herramientas — lookup_nod y check_capability — e incluye cuatro manifiestos de demostración servidos localmente para que la demo funcione de inmediato sin dependencias externas.

Instalación

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

Requiere Node.js 20+.

Ejecutar el servidor de manifiestos de demostración

Casi ningún sitio real publica nod.json todavía, por lo que este repositorio incluye cuatro ejemplos de manifiestos (restaurante, comercio electrónico, SaaS, atención médica) y los sirve localmente.

npm run demo:manifests

Deberías ver:

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

Deja esta terminal abierta durante la demostración. El servidor MCP redirige automáticamente cualquier dominio *.localhost a este servidor.

Configurar Claude Desktop

Abre (o crea) ~/Library/Application Support/Claude/claude_desktop_config.json en macOS (o %APPDATA%\Claude\claude_desktop_config.json en Windows) y añade:

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

Reemplaza /ABSOLUTE/PATH/TO/nod-mcp-server con la ruta completa a este repositorio (por ejemplo, /Users/you/projects/nod-mcp-server). Reinicia Claude Desktop. Ahora deberías ver el servidor nod listado en el selector de herramientas de Claude con dos herramientas: lookup_nod y check_capability.

Guion de demostración de 60 segundos

Con el servidor de manifiestos de demostración ejecutándose en una terminal y Claude Desktop configurado, pega estos prompts en Claude uno tras otro.

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

Claude llama a lookup_nod({ domain: "demo-restaurant.localhost" }) y devuelve algo como:

# 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 llama a 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 llama a lookup_nod({ domain: "demo-shop.localhost" }) y resume: búsqueda de productos, precios, comprobaciones de inventario y realización de pedidos protegida por OAuth2 — con un umbral de confirmación humana de 500 $ y una política de devoluciones de 60 días.

Prompts adicionales

• "Book an appointment at demo-health.localhost — what does that flow require?" → devuelve el endpoint de reserva, los campos requeridos (patient_name, DOB, reason, provider_id, preferred_date), los alcances de OAuth2 y la política de cancelación.

• "Does demo-saas.localhost allow automated purchases?" → devuelve NO con la URL de respaldo humano, porque el manifiesto establece allow_automated_purchases: false.

Referencia de herramientas

lookup_nod

Obtiene https://{domain}/.well-known/nod.json, recurriendo a https://{domain}/nod.json si es necesario. Devuelve un resumen estructurado: identidad de la empresa, capacidades declaradas, acciones admitidas (con endpoints + autenticación), endpoints de API y métodos de contacto. Devuelve un mensaje claro de "no se encontró el manifiesto" en caso de error.

check_capability

Obtiene el manifiesto y verifica la acción contra transactions.capabilities, discovery.mcp_server.capabilities, support.contact.mcp_server.capabilities y los endpoints estructurales (transactions.purchase, discovery.search, information.pricing, etc.). Devuelve un veredicto de sí/no, la URL del endpoint, el método de autenticación y las restricciones de política (límites de tasa, umbrales de confirmación humana).

Cómo funciona el enrutamiento *.localhost

Cuando el servidor MCP recibe un dominio que termina en .localhost, realiza la petición a http://localhost:3456/{domain}/nod.json en lugar de la URL estándar. Esto hace que la demostración sea autónoma: puedes apuntar a Claude a demo-restaurant.localhost y obtener resultados reales sin ninguna configuración de DNS o HTTPS.

Variables de entorno:

• NOD_LOCAL_PORT — puerto en el que escucha el servidor de manifiestos de demostración (por defecto 3456)

• NOD_LOCAL_MANIFEST_SERVER — URL base que utiliza el servidor MCP para las búsquedas de .localhost (por defecto http://localhost:3456)

• NOD_FORCE_LOCAL=1 — redirige todos los dominios a través del servidor de manifiestos local (útil para colaboradores que prueban nuevos manifiestos de ejemplo)

¿Qué sigue?

Publica un nod.json para tu propia empresa utilizando la especificación del protocolo NOD en opennod.ai/protocol. Un manifiesto mínimo y válido toma unos 30 minutos en escribirse, y una vez que esté activo en https://yourdomain.com/.well-known/nod.json, cualquier agente que utilice este servidor MCP (o cualquier otro cliente compatible con NOD) podrá descubrir tu empresa y actuar según sus capacidades.

Licencia

MIT