ghiblimcp.vercel.app

El MCP de Studio Ghibli cataloga a las personas, lugares y cosas que se encuentran en los mundos de Ghibli. Fue creado para ayudar a los agentes a descubrir recursos, consumirlos mediante solicitudes MCP e interactuar con ellos de la manera que tenga sentido.

GitHubPrueba este MCPPatrocinado

Documentación

Ghibli REST → MCP POC

Página de inicio

La URL raíz contiene una página de inicio atmosférica con Three.js que incluye instrucciones de conexión, el catálogo de herramientas, estado en vivo de /health, controles de copiar al portapapeles, agradecimientos y el puente de navegador WebMCP.

La página de inicio asume que existe un video local en public/media/background.mp4. Se sirve como /media/background.mp4 y llena todo el viewport usando object-fit: cover; una superposición ligera de lluvia con Three.js y la interfaz del sitio se renderizan encima. El MP4 no está incluido intencionalmente en este archivo.

Los recursos estáticos de la página de inicio viven en:

public/index.html
public/styles.css
public/app.js

El módulo de Three.js se carga desde el cliente vía jsDelivr, por lo que no se requiere un paso de compilación del frontend y el Vercel Framework Preset puede permanecer en Other.

Una pequeña prueba de concepto que expone la API REST pública de Studio Ghibli como herramientas MCP.

Demuestra dos capas diferentes:

  1. Conversión mecánica — Las operaciones GET se descubren desde el documento Swagger 2.0 enfocado incluido y se registran como herramientas MCP.
  2. Diseño semántico MCP — search_films es una herramienta diseñada a mano y optimizada para un agente, en lugar de reflejar un endpoint HTTP.

La API upstream es https://ghibliapi.vercel.app y no requiere autenticación.

Herramientas generadas

La especificación Swagger incluida produce estas herramientas automáticamente:

  • list_films
  • get_film
  • list_people
  • get_person
  • list_locations
  • get_location
  • list_species
  • get_species
  • list_vehicles
  • get_vehicle

El POC luego agrega:

  • search_films

search_films acepta texto, director, productor, rango de años, puntuación mínima de Rotten Tomatoes y límite de resultados. Obtiene el pequeño catálogo de películas y aplica el filtrado semántico en el adaptador MCP.

Requisitos

  • Node.js 22.7.5+
  • npm o pnpm

Se usa el MCP SDK v2, que implementa el protocolo MCP 2026-07-28 y también puede servir clientes stateless de la era 2025 a través de la ruta de compatibilidad del SDK.

Ejecutar la página de inicio completa localmente

Mantén public/media/background.mp4 en su lugar, luego ejecuta el runtime de desarrollo de Vercel:

pnpm install
pnpm dlx vercel dev

Abre http://localhost:3000/. El video de fondo debería solicitarse directamente desde /media/background.mp4.

Ejecutar el servidor MCP independiente con pnpm

pnpm install
pnpm start

pnpm start sirve solo el servidor HTTP independiente de MCP/salud; usa vercel dev al probar la página de inicio.

O con npm:

npm install
npm start

El endpoint Streamable HTTP es:

http://127.0.0.1:3000/mcp

Endpoint de salud:

curl http://127.0.0.1:3000/health

Ejecutar con Docker Compose

docker compose up --build

Luego conecta un cliente MCP a:

http://127.0.0.1:3000/mcp

MCP Inspector

Inicia el servidor MCP primero, luego ejecuta:

npx @modelcontextprotocol/inspector

En el Inspector elige Streamable HTTP y usa:

http://127.0.0.1:3000/mcp

También se incluye un mcp.json listo para usar.

Modo stdio

Para un cliente que lanza servidores MCP como procesos hijos:

pnpm stdio

Configuración equivalente del cliente:

{
  "mcpServers": {
    "ghibli": {
      "command": "node",
      "args": ["/absolute/path/to/ghibli-mcp-poc/src/stdio.js"]
    }
  }
}

Ejemplos de solicitudes de agente

Estos ejercitan tanto las superficies generadas como las semánticas:

List Studio Ghibli films directed by Hayao Miyazaki.

Un cliente capaz debería preferir search_films({ director: "Hayao Miyazaki" }).

Show me Studio Ghibli films from 1990 through 2000 with an RT score of at least 90.

Forma esperada de la llamada a la herramienta:

{
  "year_from": 1990,
  "year_to": 2000,
  "min_rt_score": 90
}

Y el acceso directo con forma REST sigue disponible:

Get film 58611129-2dbc-4a81-a72f-77ddfc1b1b49.

que se mapea a get_film({ id: "58611129-2dbc-4a81-a72f-77ddfc1b1b49" }).

Arquitectura

                         MCP client / agent
                                |
                     Streamable HTTP or stdio
                                |
                         +------v-------+
                         |  MCP server  |
                         +------+-------+
                                |
              +-----------------+------------------+
              |                                    |
      generated Swagger tools                 semantic tools
 list_films/get_film/...                     search_films
              |                                    |
              +-----------------+------------------+
                                |
                         GhibliClient
                                |
                                | HTTPS JSON
                                v
                  https://ghibliapi.vercel.app

Por qué no se usa DAB en este POC

Microsoft Data API Builder es un puente sólido de base de datos → REST/GraphQL/MCP. Este POC parte de una API REST de terceros ya existente. DAB no actúa como un proxy genérico de REST/OpenAPI → MCP, por lo que insertar DAB aquí agregaría una base de datos y un paso de replicación innecesario.

Para este problema, el adaptador MCP delgado es el punto de comparación correcto.

Si la fuente fueran tablas/vistas/procedimientos almacenados de SQL Server, DAB valdría la pena probarlo como la propia capa MCP.

Qué demuestra este POC

La parte mecánica es pequeña: leer el contrato de la API, convertir parámetros en esquemas de entrada MCP y despachar la llamada de la herramienta al endpoint HTTP.

El trabajo de diseño importante comienza después. Una herramienta list_films generada mecánicamente es válida, pero search_films es mucho mejor para un LLM porque captura directamente la intención del usuario y evita que el modelo obtenga una gran colección y razone sobre ella por sí mismo.

Eso sugiere una arquitectura de producción con dos capas:

OpenAPI-generated MCP tools
          +
curated semantic MCP tools

La capa generada brinda una cobertura amplia a bajo costo; la capa curada contiene las operaciones que merecen una alta confiabilidad en la selección de herramientas, esquemas más sólidos, reglas de autorización, agregación o flujos de trabajo de múltiples solicitudes.

Limitaciones del POC

  • Solo lectura por diseño, porque la API upstream de Ghibli es de solo lectura.
  • Solo se generan operaciones GET de Swagger.
  • Las definiciones de parámetros $ref de Swagger y la composición avanzada de esquemas OpenAPI no están implementadas. El contrato incluido es una copia JSON enfocada de los metadatos de endpoint/parámetros que necesita el POC, basada en la documentación Swagger upstream.
  • Sin autenticación porque la API upstream no tiene ninguna.
  • El POC HTTP intencionalmente no agrega un servidor de recursos OAuth. Agrega autenticación y una política explícita de Host/Origin antes de exponerlo más allá de un entorno de prueba confiable.
  • search_films filtra localmente porque el catálogo es pequeño. Para una API real, la búsqueda/filtrado normalmente debería delegarse al servicio de origen.

Desplegar en Vercel

Este repositorio contiene un punto de entrada de Function nativo de Vercel en api/mcp.js. El punto de entrada normal src/http.js sigue disponible para Docker, una VM, Cloud Run o cualquier otro host donde un proceso Node de larga duración sea apropiado.

Por qué se requiere un punto de entrada separado para Vercel

src/http.js llama a httpServer.listen(...) de Node. Eso es apropiado para un contenedor o VM, pero las Functions de Vercel son manejadores de solicitudes en lugar de listeners HTTP persistentes. api/mcp.js por lo tanto exporta el manejador estándar web de MCP en lugar de abrir un puerto.

Desplegar

Desde la raíz del proyecto:

pnpm install
npx vercel

Para producción:

npx vercel --prod

O sube el repositorio a GitHub e impórtalo en Vercel. No se requiere comando de compilación. Vercel debería detectar las functions bajo api/.

Los endpoints públicos son entonces:

https://YOUR-PROJECT.vercel.app/
https://YOUR-PROJECT.vercel.app/health
https://YOUR-PROJECT.vercel.app/mcp

/ es solo una pequeña página de estado. /health es adecuado para verificaciones desde navegador/curl. /mcp es el endpoint MCP Streamable HTTP y normalmente debería abrirlo un cliente MCP en lugar de navegarlo directamente.

Probar el despliegue

Salud:

curl https://YOUR-PROJECT.vercel.app/health

Forma esperada:

{
  "ok": true,
  "service": "ghibli-rest-mcp-poc",
  "transport": "streamable-http",
  "mcp": "/mcp"
}

Luego abre MCP Inspector y conéctate usando Streamable HTTP a:

https://YOUR-PROJECT.vercel.app/mcp

Enrutamiento de Vercel

vercel.json reescribe las rutas públicas amigables a las Functions generadas:

/mcp    -> /api/mcp
/health -> /api/health

La function MCP también incluye explícitamente spec/** en su bundle porque el POC carga el documento Swagger enfocado desde el sistema de archivos en tiempo de ejecución.

Puente de navegador WebMCP

Esta versión también expone la misma superficie de herramientas MCP del backend a través de la API experimental WebMCP del navegador.

La decisión de diseño importante es que el navegador no contiene una segunda copia codificada de las herramientas de Ghibli. public/webmcp.js refleja dinámicamente el servidor backend:

browser agent
    |
    v
document.modelContext
    |
    | registerTool(...)
    v
public/webmcp.js
    |
    +-- POST /mcp  tools/list   -> discover current tool schemas
    |
    +-- POST /mcp  tools/call   -> execute the same backend tool

Esto significa que agregar o cambiar una herramienta MCP del backend cambia automáticamente la superficie WebMCP después de que la página se recarga.

Pruebas locales de WebMCP en Chrome

WebMCP es experimental. Para desarrollo local con una compilación de Chrome compatible:

  1. Abre chrome://flags/#enable-webmcp-testing.
  2. Configura WebMCP testing en Enabled.
  3. Relanza Chrome.
  4. Inicia el proyecto con:
pnpm install
pnpm dlx vercel dev
  1. Abre http://localhost:3000/.

La tarjeta WebMCP de la página de inicio debería cambiar a active e informar el número de herramientas reflejadas.

También puedes inspeccionar las herramientas directamente desde DevTools:

const tools = await document.modelContext.getTools()
tools.map(tool => tool.name)

Y ejecutar manualmente la búsqueda semántica de películas:

const tools = await document.modelContext.getTools()
const search = tools.find(tool => tool.name === 'search_films')

await document.modelContext.executeTool(
  search,
  JSON.stringify({
    director: 'Hayao Miyazaki',
    min_rt_score: 90,
    limit: 5
  })
)

Para diagnósticos del puente independientes del soporte del navegador WebMCP:

await window.ghibliWebMcp.listBackendTools()
await window.ghibliWebMcp.call('search_films', {
  director: 'Hayao Miyazaki',
  min_rt_score: 90,
  limit: 5
})

Prueba de origen en producción

A partir de agosto de 2026, WebMCP sigue siendo experimental. Chrome lo expone a través de una prueba de origen (comenzando con Chrome 149), Edge tiene su propia prueba de origen y Brave tiene integración experimental con Leo. Por lo tanto, un despliegue en producción necesita la prueba de navegador aplicable habilitada.

Para Chrome, registra el origen de producción y agrega el token emitido cerca de la parte superior de public/index.html:

<meta http-equiv="origin-trial" content="YOUR_TOKEN">

El proyecto ya envía estos encabezados en Vercel:

Permissions-Policy: tools=(self)
Origin-Agent-Cluster: ?1

La detección de características es intencional: los navegadores sin WebMCP mantienen la página de inicio normal y el endpoint /mcp del backend continúa funcionando normalmente.

Tarjetas de crédito ilustradas

Las tarjetas de agradecimiento para Hayao Miyazaki, Isao Takahata y Toshio Suzuki usan fondos de retratos ilustrados incluidos localmente bajo public/media/credits/. La página de inicio también enlaza las referencias públicas de retratos de Wikimedia Commons utilizadas para la investigación visual.