Documentação

MCP Fusion/Reference/Migração

Migração

Pergunte à IA sobre a Vinkius

Migre um servidor MCP existente do SDK puro para o MCP Fusion de forma incremental: um domínio de tools por vez, das respostas com JSON.stringify para Presenters, redação e rules.

O MCP Fusion não exige uma reescrita. O SDK MCP puro e o MCP Fusion podem coexistir em um mesmo servidor, e a maioria das equipes migra um domínio de tools por vez, na ordem de 15 a 30 minutos por domínio. Esta página mostra o formato de um desses passos.

Antes: uma tool do SDK puro

typescript
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'get_invoice') {
    const invoice = await db.invoices.findUnique({
      where: { id: request.params.arguments.id },
    });
    return {
      content: [{ type: 'text', text: JSON.stringify(invoice) }],
    };
  }
});

Os problemas são estruturais. JSON.stringify(invoice) envia todas as colunas ao modelo, incluindo as que você esqueceu que existiam. As unidades vivem em conhecimento tribal, então o modelo chuta. Não há lugar onde redação, validação ou próximas ações pudessem sequer acontecer.

Depois: a mesma tool em MVA

typescript
const InvoicePresenter = createPresenter('Invoice')
  .schema({
    id: t.string,
    customer: t.string,
    amount_cents: t.number.describe('CENTS, divide by 100'),
    status: t.enum('draft', 'paid', 'overdue'),
  })
  .redactPII(['customer.email', 'customer.ssn'])
  .rules(['amount_cents is in CENTS. Divide by 100.']);

export default f.query('billing.get_invoice')
  .describe('Retrieve an invoice by ID')
  .withString('id', 'Invoice ID')
  .returns(InvoicePresenter)
  .handle(async (input) => {
    return db.invoices.findUnique({ where: { id: input.id } });
  });

A mesma lógica de handler. O que mudou:

PreocupaçãoSDK puroMCP Fusion
Forma da saídaJSON.stringify, todas as colunasSchema do Presenter, apenas os campos declarados
PIINa rede.redactPII() antes da serialização
Unidades e significadoFolclore de prompts.rules() como linhas de sistema
Próximas açõesNenhumaaffordances de .suggest()
ValidaçãoManualZod vindo do builder

O caminho incremental

  1. Instale lado a lado. npm install @mcpfusion/core não perturba os handlers existentes.
  2. Escolha um domínio de tools. Geralmente o que lida com os dados mais sensíveis.
  3. Escreva o Presenter primeiro. Declare os campos de que a tarefa precisa, aplique redaction ao resto e escreva as rules que o modelo costuma errar.
  4. Mova o handler. A lógica de query normalmente sobrevive inalterada.
  5. Ligue o autoDiscover. As tools novas vêm de src/tools/, e os handlers antigos continuam funcionando durante a transição.
  6. Trave e teste. Rode mcpfusion lock na nova superfície e adicione as asserções de egress de Testing.

Vindo de outros frameworks

  • De APIs HTTP simples. @mcpfusion/openapi-gen gera Models, Views e Agents a partir de uma spec OpenAPI ou Swagger existente, então envolver uma API interna começa quase todo gerado.
  • De um schema Prisma. @mcpfusion/prisma-gen gera tools e Presenters com segurança no nível de campo e isolamento de tenant a partir de anotações no schema.
  • Do n8n. @mcpfusion/n8n transforma webhooks do n8n em tools com filtragem por tags.
  • De internos da AWS. @mcpfusion/aws eleva funções Lambda e Step Functions a tools por meio de tags de recursos.

Próximos passos