Documentação

MCP Fusion/Integrations and federation/Geradores OpenAPI e Prisma

Geradores OpenAPI e Prisma

Pergunte à IA sobre a Vinkius

Transforme esquemas existentes em conectores MCP seguros: endpoints OpenAPI ou Swagger tornam-se ferramentas e Presenters, enquanto anotações do Prisma geram segurança em nível de campo e código consciente do tenant.

A maioria das equipes já tem uma fonte de verdade. Os geradores OpenAPI e Prisma permitem trazer essa fonte para o MCP Fusion sem copiar manualmente cada endpoint. Ambos geram código no formato MVA, então a saída começa dentro do mesmo modelo de segurança e governança das ferramentas escritas à mão.

OpenAPI e Swagger

Instale o pacote do gerador e execute o binário:

bash
npm install @mcpfusion/openapi-gen
openapi-gen generate \
  --input ./openapi.yaml \
  --output ./src/mcp \
  --base-url https://api.example.com \
  --server-name billing

A CLI aceita -i/--input, -o/--output, -c/--config, --base-url, --context e --server-name. Filtros de tags são configurados na configuração do gerador com includeTags e excludeTags.

Programaticamente, o pipeline é explícito:

typescript
import {
  parseOpenAPI,
  mapEndpoints,
  mergeConfig,
  emitFiles,
} from '@mcpfusion/openapi-gen';

const spec = parseOpenAPI(await readFile('./openapi.yaml', 'utf8'));
const mapped = mapEndpoints(spec);
const files = emitFiles(mapped, mergeConfig({
  features: { tags: true, presenters: true, toonDescription: true },
}));

O gerador resolve $refs, converte Swagger 2.0 para OpenAPI 3, compila esquemas de entrada e resposta para Zod, infere anotações e emite arquivos para Models, Presenters, ferramentas, um registro e uma entrada de servidor. O servidor gerado é um ponto de partida: adicione middleware de autenticação, resolução de tenant, declarações de credenciais e regras específicas do domínio antes da produção.

A superfície de configuração inclui features (tags, anotações, presenters, descrições, tratamento de deprecated, descrições TOON e arquivo de servidor), naming (snake_case ou camelCase e deduplicação), context.import, configurações de server e filtros de tags. O runtime exporta loadOpenAPI e buildHandler quando você precisa de uma operação gerada dentro de um servidor existente.

Os esquemas gerados descrevem a API, não sua política de autorização. Revise cada allowlist de Presenter gerada, adicione restrições de tenant e conecte a autenticação antes de implantar o conector.

Prisma

A geração do Prisma é um gerador Prisma real, não um comando separado executado contra um banco arbitrário. Registre-o em schema.prisma:

prisma
generator mcp {
  provider = "@mcpfusion/prisma-gen"
  output   = "../src/tools/database"
}

Anote os campos do modelo que precisam de uma regra de percepção ou tenancy:

prisma
model User {
  id        String @id @default(cuid())
  email     String /// @mcpfusion.hide
  tenantId  String /// @mcpfusion.tenantKey
  name      String /// @mcpfusion.describe("Display name for the agent")
}

Execute npx prisma generate. O gerador analisa o DMMF do Prisma com parseAnnotations e depois emite arquivos de Presenter e ferramentas com emitPresenter e emitTool. O pacote inclui helpers de nomenclatura como toSnakeCase, toPascalCase e pluralize.

As anotações de origem são o contrato: @mcpfusion.hide remove um campo da superfície do agente, @mcpfusion.describe(...) torna-se orientação do esquema e @mcpfusion.tenantKey marca o campo que o código gerado deve delimitar. Verifique a versão do parser que você instala antes de copiar exemplos antigos de README que usam a grafia obsoleta @fusion.*.

O que os dois geradores não sabem

Nenhum gerador consegue inferir quais registros uma função pode ver, quais erros upstream podem ser repetidos ou quais ações são destrutivas no seu negócio. Trate o código gerado como um scaffold seguro e adicione a camada de política:

  1. inspecione os esquemas de Presenter gerados
  2. conecte requireJwt ou requireApiKey
  3. resolva o contexto do tenant antes do handler
  4. adicione .redactPII(), limites e indicações de invalidação
  5. gere e verifique mcpfusion.lock

Próximos passos