Ejemplos MCP

Los ejemplos no contienen credenciales. Sustituye https://mcp.example.com por el origen comprobado de tu instalación. El dominio reservado es un marcador, no un servicio de Wookcom. No se prueba compatibilidad con aplicaciones externas mediante estos ejemplos.

Consulta pública con curl

Con curl instalado y un servidor configurado, este intercambio no requiere cuenta ni token. El transporte es sin sesión: las solicitudes usan el mismo endpoint y no necesitan Mcp-Session-Id.

export MCP_ORIGIN='https://mcp.example.com'
curl --fail-with-body "$MCP_ORIGIN/.well-known/oauth-protected-resource/api/mcp"
curl --fail-with-body "$MCP_ORIGIN/.well-known/oauth-authorization-server"
curl --fail-with-body "$MCP_ORIGIN/api/mcp" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"ejemplo-documentacion","version":"1.0.0"}}}'
curl --fail-with-body "$MCP_ORIGIN/api/mcp" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
curl --fail-with-body "$MCP_ORIGIN/api/mcp" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"builder_get_capabilities","arguments":{}}}'

El cliente debe respetar la versión negociada en initialize; 2025-11-25 coincide con los intercambios de las pruebas. También puedes invocar builder_list_components con {"query":"texto","limit":5} y usar un ID devuelto para builder_get_component.

Registro y consentimiento

El registro no usa credenciales, pero sí crea un registro de cliente. Usa una URL callback que controle tu aplicación; el ejemplo loopback es válido para desarrollo.

curl --fail-with-body "$MCP_ORIGIN/oauth/register" \
  -H 'Content-Type: application/json' \
  --data '{"client_name":"Ejemplo local","redirect_uris":["http://127.0.0.1:8765/callback"],"token_endpoint_auth_method":"none"}'

El cliente genera un verificador aleatorio de 43–128 caracteres y su desafío SHA256 base64url; no uses un verificador fijo. Este comando Node solo genera valores locales de prueba:

node -e 'const c=require("node:crypto");const v=c.randomBytes(32).toString("base64url");console.log(JSON.stringify({code_verifier:v,code_challenge:c.createHash("sha256").update(v).digest("base64url")}))'

Abre una URL con los parámetros codificados como query string: /oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_CODIFICADO&code_challenge=DESAFIO&code_challenge_method=S256&resource=RECURSO_CODIFICADO&scope=projects%3Aread&state=ESTADO_ALEATORIO. La aplicación muestra consentimiento; el callback debe comprobar state e iss. Intercambia el código con grant_type=authorization_code, client_id, resource, code, redirect_uri y code_verifier. No sustituir ese paso por un token Firebase ni pegar tokens en documentación.

Secuencia de borrador (plantillas JSON-RPC)

Las plantillas privadas requieren una conexión OAuth ya autorizada y cabecera Authorization: Bearer TOKEN_MCP; TOKEN_MCP es un marcador, no una credencial funcional. No se ejecutan sin autenticación. Solicita ambos alcances projects:read projects:write y permiso de creación para esta secuencia.

{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"builder_create_project","arguments":{"name":"Sitio de ejemplo","expectedRevision":0,"idempotencyKey":"ejemplo-crear-001"}}}

Guarda structuredContent.project.id y structuredContent.revision. Sustituye PROYECTO_ID y REVISION_ACTUAL por esos valores; la revisión debe ser un número JSON, sin comillas. Antes de una edición posterior consulta builder_get_project con {"projectId":"PROYECTO_ID"}.

{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"builder_apply_operations","arguments":{"projectId":"PROYECTO_ID","expectedRevision":1,"idempotencyKey":"ejemplo-metadata-001","operations":[{"op":"update_metadata","metadata":{"siteName":"Mi sitio de ejemplo","language":"es"}}]}}}

El 1 es ilustrativo: usa la revisión real obtenida. Ante respuesta perdida repite exactamente la petición; ante revision_conflict, lee de nuevo y prepara una edición nueva con clave nueva. Obtén el enlace con builder_get_links. Para publicar, espera petición explícita y una conexión con sites:publish; invoca builder_publish_project con ID, revisión actual y otra clave. Este ejemplo termina en borrador.

Formulario y curso sin publicación del sitio

Argumentos válidos para builder_save_form (sustituye el ID del proyecto autorizado):

{"projectId":"PROYECTO_ID","form":{"id":"contacto","title":"Contacto","description":"Solicitud de información","presentation":"standard","published":false,"welcomeTitle":"Contacto","welcomeText":"Cuéntanos qué necesitas","endingTitle":"Gracias","endingText":"Solicitud recibida","completionUrl":"","questions":[{"id":"correo","title":"Correo electrónico","description":"","type":"email","required":true,"placeholder":"nombre@example.com","options":[],"branches":[]}]}}

Argumentos para builder_save_course:

{"projectId":"PROYECTO_ID","courseId":"introduccion","title":"Introducción","summary":"Contenido introductorio","published":false,"order":0}

Después de crear el curso, builder_save_course_lesson acepta:

{"projectId":"PROYECTO_ID","courseId":"introduccion","lessonId":"bienvenida","title":"Bienvenida","body":"Contenido real de la primera lección.","videoUrl":"","materials":[],"order":0}

Guardar metadatos no inserta bloques: coloca form-widget o course-widget mediante operaciones con content.formId o content.courseId. Lee la estructura actual antes de escoger página y sección. No invites miembros ni actives acceso sin una orden del usuario.

Verificación local sin credenciales productivas

Las pruebas unitarias MCP usan dependencias de prueba; las de integración necesitan emuladores locales. Desde una instalación con dependencias disponibles:

npm run test:mcp
npm run test:mcp:runtime
npm run test:mcp:integration

La suite de integración usa el proyecto de prueba demo-nexusbuilder, nunca un proyecto productivo. Consulta fixtures, pruebas de formularios y cursos para flujos reproducibles en memoria. Estos comandos son instrucciones de reproducción, no una afirmación de que se ejecutaron durante esta edición documental.