ghiblimcp.vercel.app

O MCP do Studio Ghibli cataloga as pessoas, lugares e coisas encontrados nos mundos de Ghibli. Foi criado para ajudar agentes a descobrir recursos, consumi-los por meio de solicitações MCP e interagir com eles da maneira que fizer sentido.

GitHubExperimente este MCPPatrocinado

Documentação

Ghibli REST → MCP POC

Página inicial

A URL raiz contém uma página inicial atmosférica em Three.js com instruções de conexão, o catálogo de ferramentas, status ao vivo de /health, controles de copiar para a área de transferência, agradecimentos e a ponte de navegador WebMCP.

A página inicial assume que um vídeo local existe em public/media/background.mp4. Ele é servido como /media/background.mp4 e preenche todo o viewport usando object-fit: cover; uma sobreposição leve de chuva em Three.js e a interface do site são renderizadas acima dele. O MP4 não está intencionalmente incluído neste arquivo.

Os recursos estáticos da página inicial estão em:

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

O módulo Three.js é carregado no lado do cliente a partir do jsDelivr, portanto nenhuma etapa de build de frontend é necessária e o Vercel Framework Preset pode permanecer como Other.

Uma pequena prova de conceito que expõe a API REST pública do Studio Ghibli como ferramentas MCP.

Ela demonstra duas camadas diferentes:

  1. Conversão mecânica — operações GET são descobertas a partir do documento Swagger 2.0 focado incluído e registradas como ferramentas MCP.
  2. Design semântico de MCP — search_films é uma ferramenta projetada manualmente, otimizada para um agente, em vez de espelhar um endpoint HTTP.

A API upstream é https://ghibliapi.vercel.app e não requer autenticação.

Ferramentas geradas

A especificação Swagger incluída produz estas ferramentas automaticamente:

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

O POC então adiciona:

  • search_films

search_films aceita texto, diretor, produtor, intervalo de anos, pontuação mínima do Rotten Tomatoes e limite de resultados. Ele busca o pequeno catálogo de filmes e aplica a filtragem semântica no adaptador MCP.

Requisitos

  • Node.js 22.7.5+
  • npm ou pnpm

O MCP SDK v2 é usado, que implementa o protocolo MCP 2026-07-28 e também pode atender clientes stateless da era 2025 através do caminho de compatibilidade do SDK.

Execute a página inicial completa localmente

Mantenha public/media/background.mp4 no lugar e execute o runtime de desenvolvimento da Vercel:

pnpm install
pnpm dlx vercel dev

Abra http://localhost:3000/. O vídeo de fundo deve ser solicitado diretamente de /media/background.mp4.

Execute o servidor MCP standalone com pnpm

pnpm install
pnpm start

pnpm start serve apenas o servidor HTTP standalone de MCP/health; use vercel dev ao testar a página inicial.

Ou com npm:

npm install
npm start

O endpoint Streamable HTTP é:

http://127.0.0.1:3000/mcp

Endpoint de health:

curl http://127.0.0.1:3000/health

Execute com Docker Compose

docker compose up --build

Em seguida, conecte um cliente MCP a:

http://127.0.0.1:3000/mcp

MCP Inspector

Inicie o servidor MCP primeiro e depois execute:

npx @modelcontextprotocol/inspector

No Inspector, escolha Streamable HTTP e use:

http://127.0.0.1:3000/mcp

Um mcp.json pronto também está incluído.

Modo stdio

Para um cliente que inicia servidores MCP como processos filhos:

pnpm stdio

Configuração equivalente do cliente:

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

Exemplos de solicitações de agente

Estes exercitam tanto as superfícies geradas quanto as semânticas:

List Studio Ghibli films directed by Hayao Miyazaki.

Um cliente capaz deve 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 da chamada de ferramenta:

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

E o acesso direto no formato REST permanece disponível:

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

que mapeia para get_film({ id: "58611129-2dbc-4a81-a72f-77ddfc1b1b49" }).

Arquitetura

                         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 que o DAB não é usado neste POC

O Microsoft Data API Builder é uma forte ponte banco de dados → REST/GraphQL/MCP. Este POC parte de uma API REST de terceiros já existente. O DAB não atua como um proxy genérico REST/OpenAPI → MCP, então inserir o DAB aqui adicionaria um banco de dados e uma etapa desnecessária de replicação.

Para este problema, o adaptador MCP fino é o ponto de comparação correto.

Se a fonte fosse, em vez disso, tabelas/views/procedures armazenados do SQL Server, o DAB valeria a pena ser testado como a própria camada MCP.

O que este POC prova

A parte mecânica é pequena: ler o contrato da API, transformar parâmetros em esquemas de entrada MCP e despachar a chamada de ferramenta para o endpoint HTTP.

O importante trabalho de design começa depois disso. Uma ferramenta list_films gerada mecanicamente é válida, mas search_films é muito melhor para um LLM porque captura diretamente a intenção do usuário e evita que o modelo busque uma grande coleção e raciocine sobre ela por conta própria.

Isso sugere uma arquitetura de produção com duas camadas:

OpenAPI-generated MCP tools
          +
curated semantic MCP tools

A camada gerada oferece ampla cobertura a baixo custo; a camada curada contém as operações que merecem alta confiabilidade na seleção de ferramentas, esquemas mais fortes, regras de autorização, agregação ou fluxos de trabalho com múltiplas solicitações.

Limitações do POC

  • Somente leitura por design, pois a API Ghibli upstream é somente leitura.
  • Apenas operações GET do Swagger são geradas.
  • Definições de parâmetros $ref do Swagger e composição avançada de esquemas OpenAPI não são implementadas. O contrato incluído é uma cópia JSON focada dos metadados de endpoint/parâmetros necessários para o POC, com base na documentação Swagger upstream.
  • Sem autenticação porque a API upstream não possui nenhuma.
  • O POC HTTP intencionalmente não adiciona um servidor de recursos OAuth. Adicione autenticação e política explícita de Host/Origin antes de expô-lo além de um ambiente de teste confiável.
  • search_films filtra localmente porque o catálogo é pequeno. Para uma API real, busca/filtragem normalmente deve ser delegada ao serviço de origem.

Implantar na Vercel

Este repositório contém um ponto de entrada de Function nativo da Vercel em api/mcp.js. O ponto de entrada normal src/http.js ainda está disponível para Docker, VM, Cloud Run ou qualquer outro host onde um processo Node de longa duração seja apropriado.

Por que um ponto de entrada separado para a Vercel é necessário

src/http.js chama o httpServer.listen(...) do Node. Isso é apropriado para um contêiner ou VM, mas as Functions da Vercel são manipuladores de solicitação em vez de ouvintes HTTP persistentes. api/mcp.js portanto exporta o manipulador padrão Web do MCP em vez de abrir uma porta.

Implantar

A partir da raiz do projeto:

pnpm install
npx vercel

Para produção:

npx vercel --prod

Ou envie o repositório para o GitHub e importe-o para a Vercel. Nenhum comando de build é necessário. A Vercel deve detectar as functions em api/.

Os endpoints públicos são então:

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

/ é apenas uma pequena página de status. /health é adequado para verificações em navegador/curl. /mcp é o endpoint MCP Streamable HTTP e normalmente deve ser aberto por um cliente MCP em vez de navegação no navegador.

Testar a implantação

Health:

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

Forma esperada:

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

Em seguida, abra o MCP Inspector e conecte usando Streamable HTTP a:

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

Roteamento da Vercel

vercel.json reescreve os caminhos públicos amigáveis para as Functions geradas:

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

A function MCP também inclui explicitamente spec/** em seu bundle porque o POC carrega o documento Swagger focado do sistema de arquivos em tempo de execução.

Ponte de navegador WebMCP

Esta versão também expõe a mesma superfície de ferramentas MCP do backend através da API de navegador experimental WebMCP.

A decisão de design importante é que o navegador não contém uma segunda cópia codificada das ferramentas Ghibli. public/webmcp.js espelha dinamicamente o 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

Isso significa que adicionar ou alterar uma ferramenta MCP do backend automaticamente altera a superfície WebMCP após o recarregamento da página.

Teste local de WebMCP no Chrome

WebMCP é experimental. Para desenvolvimento local com uma versão compatível do Chrome:

  1. Abra chrome://flags/#enable-webmcp-testing.
  2. Defina WebMCP testing como Enabled.
  3. Reinicie o Chrome.
  4. Inicie o projeto com:
pnpm install
pnpm dlx vercel dev
  1. Abra http://localhost:3000/.

O cartão WebMCP da página inicial deve mudar para ativo e relatar o número de ferramentas espelhadas.

Você também pode inspecionar as ferramentas diretamente do DevTools:

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

E executar manualmente a busca semântica de filmes:

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 de ponte independentes do suporte do navegador WebMCP:

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

Teste de origem em produção

Em agosto de 2026, o WebMCP ainda é experimental. O Chrome o expõe através de um teste de origem (a partir do Chrome 149), o Edge tem seu próprio teste de origem, e o Brave tem integração experimental com Leo. Uma implantação em produção, portanto, precisa do teste de navegador aplicável habilitado.

Para o Chrome, registre a origem de produção e adicione o token emitido perto do topo de public/index.html:

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

O projeto já envia estes cabeçalhos na Vercel:

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

A detecção de recursos é intencional: navegadores sem WebMCP mantêm a página inicial normal e o endpoint /mcp do backend continua funcionando normalmente.

Cartões de crédito ilustrados

Os cartões de agradecimento para Hayao Miyazaki, Isao Takahata e Toshio Suzuki usam fundos de retrato ilustrados incluídos localmente em public/media/credits/. A página inicial também vincula as referências públicas de retratos do Wikimedia Commons usadas para pesquisa visual.