Frappe MCP Server

Um servidor MCP para o Frappe Framework, permitindo que assistentes de IA interajam com a API REST do Frappe para gerenciamento de documentos e operações de esquema.

GitHub
1

Documentação

Servidor MCP Frappe

Um servidor Model Context Protocol (MCP) para o Frappe Framework que expõe a funcionalidade do Frappe a assistentes de IA por meio da API REST oficial, com foco em operações CRUD de documentos, manipulação de esquemas e instruções detalhadas de API.

Visão Geral

Este servidor MCP permite que assistentes de IA interajam com aplicações Frappe por meio de uma interface padronizada usando a API REST oficial do Frappe. Ele fornece ferramentas para:

  • Operações de documentos (criar, ler, atualizar, excluir, listar)
  • Manipulação de esquemas e metadados
  • Descoberta e exploração de DocTypes
  • Instruções detalhadas de uso da API e exemplos

O servidor inclui tratamento abrangente de erros, validação e respostas úteis para facilitar o trabalho de assistentes de IA com o Frappe.

Instalação

Pré-requisitos

  • Node.js 18 ou superior
  • Uma instância Frappe em execução (versão 15 ou superior)
  • Chave e segredo de API do Frappe (obrigatório)

Configuração

  1. Instale via npm:
npm install -g frappe-mcp-server

Alternativamente, execute diretamente com npx:

npx frappe-mcp-server

(sem necessidade de instalação)

Configuração

O servidor é configurado usando variáveis de ambiente:

  • FRAPPE_URL: A URL da sua instância Frappe (padrão: http://localhost:8000)
  • FRAPPE_API_KEY: Sua chave de API do Frappe (obrigatório)
  • FRAPPE_API_SECRET: Seu segredo de API do Frappe (obrigatório)

Importante: A autenticação por chave/segredo de API é o único método de autenticação suportado. Tanto FRAPPE_API_KEY quanto FRAPPE_API_SECRET devem ser fornecidos para que o servidor funcione corretamente. A autenticação por nome de usuário/senha não é suportada.

Autenticação

Este servidor MCP suporta apenas autenticação por chave/segredo de API via API REST do Frappe. A autenticação por nome de usuário/senha não é suportada.

Obtendo Credenciais de API

Para obter credenciais de API da sua instância Frappe:

  1. Vá para Usuário > Acesso à API > Nova Chave de API
  2. Selecione o usuário para quem deseja criar a chave
  3. Clique em "Gerar Chaves"
  4. Copie a Chave de API e o Segredo de API

Solução de Problemas de Autenticação

Se você encontrar erros de autenticação:

  1. Verifique se ambas as variáveis de ambiente FRAPPE_API_KEY e FRAPPE_API_SECRET estão configuradas corretamente
  2. Garanta que a chave de API esteja ativa e não expirada na sua instância Frappe
  3. Verifique se o usuário associado à chave de API tem as permissões necessárias
  4. Verifique se a URL do Frappe está correta e acessível

O servidor fornece mensagens de erro detalhadas para ajudar a diagnosticar problemas de autenticação.

Uso

Iniciando o Servidor

npx frappe-mcp-server

Ou com variáveis de ambiente:

FRAPPE_URL=https://your-frappe-instance.com FRAPPE_API_KEY=your_api_key FRAPPE_API_SECRET=your_api_secret npx frappe-mcp-server

Integrando com Assistentes de IA

Para usar este servidor MCP com um assistente de IA, você precisa configurar o assistente para se conectar a este servidor. A configuração exata depende da plataforma do assistente de IA que você está usando.

Para Claude, adicione o seguinte ao seu arquivo de configuração de configurações MCP:

{
  "mcpServers": {
    "frappe": {
      "command": "npx",
      "args": ["frappe-mcp-server"], // Assumes frappe-mcp-server is in MCP server path
      "env": {
        "FRAPPE_URL": "https://your-frappe-instance.com",
        "FRAPPE_API_KEY": "your_api_key", // REQUIRED
        "FRAPPE_API_SECRET": "your_api_secret" // REQUIRED
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Nota: Ambas as variáveis de ambiente FRAPPE_API_KEY e FRAPPE_API_SECRET são obrigatórias. O servidor iniciará sem elas, mas a maioria das operações falhará com erros de autenticação.

Ferramentas Disponíveis

Operações de Documentos

  • create_document: Criar um novo documento no Frappe
  • get_document: Recuperar um documento do Frappe
  • update_document: Atualizar um documento existente no Frappe
  • delete_document: Excluir um documento do Frappe
  • list_documents: Listar documentos do Frappe com filtros

Operações de Esquema

  • get_doctype_schema: Obter o esquema completo para um DocType, incluindo definições de campos, validações e DocTypes vinculados
  • get_field_options: Obter opções disponíveis para um campo Link ou Select
  • get_frappe_usage_info: Obter informações combinadas sobre um DocType ou fluxo de trabalho, incluindo metadados de esquema, dicas estáticas e orientações de uso fornecidas pelo aplicativo

Ferramentas Auxiliares

  • find_doctypes: Encontrar DocTypes no sistema que correspondam a um termo de pesquisa
  • get_module_list: Obter uma lista de todos os módulos no sistema
  • get_doctypes_in_module: Obter uma lista de DocTypes em um módulo específico
  • check_doctype_exists: Verificar se um DocType existe no sistema
  • check_document_exists: Verificar se um documento existe
  • get_document_count: Obter uma contagem de documentos que correspondem aos filtros
  • get_naming_info: Obter informações da série de nomenclatura para um DocType
  • get_required_fields: Obter uma lista de campos obrigatórios para um DocType
  • get_api_instructions: Obter instruções detalhadas para usar a API do Frappe

Recursos Disponíveis

Recursos de Esquema

  • schema://{doctype}: Informações de esquema para um DocType
  • schema://{doctype}/{fieldname}/options: Opções disponíveis para um campo Link ou Select
  • schema://modules: Lista de todos os módulos no sistema
  • schema://doctypes: Lista de todos os DocTypes no sistema

Recursos

Aprimoramento de Informações de Uso

O servidor fornece informações abrangentes de uso combinando três fontes:

  1. Metadados do Frappe: Informações de esquema recuperadas diretamente da API do Frappe
  2. Dicas Estáticas: Contexto suplementar armazenado em arquivos JSON dentro do diretório static_hints/
  3. Introspecção de Aplicativos Personalizados: Instruções de uso fornecidas diretamente por aplicativos Frappe personalizados

Este aprimoramento permite que assistentes de IA entendam melhor os módulos do Frappe, tornando-os mais eficazes ao ajudar usuários com aplicações baseadas em Frappe.

Para mais detalhes, consulte Aprimoramento de Informações de Uso.

Exemplos

Criando um Documento

// Example of using the create_document tool
const result = await useToolWithMcp("frappe", "create_document", {
  doctype: "Customer",
  values: {
    customer_name: "John Doe",
    customer_type: "Individual",
    customer_group: "All Customer Groups",
    territory: "All Territories",
  },
});

Obtendo um Documento

// Example of using the get_document tool
const customer = await useToolWithMcp("frappe", "get_document", {
  doctype: "Customer",
  name: "CUST-00001",
  fields: ["customer_name", "customer_type", "email_id"], // Optional: specific fields
});

Listando Documentos com Filtros

// Example of using the list_documents tool with filters
const customers = await useToolWithMcp("frappe", "list_documents", {
  doctype: "Customer",
  filters: {
    customer_type: "Individual",
    territory: "United States",
  },
  fields: ["name", "customer_name", "email_id"],
  limit: 10,
  order_by: "creation desc",
});

Encontrando DocTypes

// Example of using the find_doctypes tool
const salesDocTypes = await useToolWithMcp("frappe", "find_doctypes", {
  search_term: "Sales",
  module: "Selling",
  is_table: false,
});

Obtendo Campos Obrigatórios

// Example of using the get_required_fields tool
const requiredFields = await useToolWithMcp("frappe", "get_required_fields", {
  doctype: "Sales Order",
});

Obtendo Instruções da API

// Example of using the get_api_instructions tool
const instructions = await useToolWithMcp("frappe", "get_api_instructions", {
  category: "DOCUMENT_OPERATIONS",
  operation: "CREATE",
});

Obtendo Informações de Uso

// Example of using the get_frappe_usage_info tool
const salesOrderInfo = await useToolWithMcp("frappe", "get_frappe_usage_info", {
  doctype: "Sales Order",
});

// Example of getting workflow information
const workflowInfo = await useToolWithMcp("frappe", "get_frappe_usage_info", {
  workflow: "Quote to Sales Order Conversion",
});

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas com contexto para ajudar a diagnosticar problemas:

  • Parâmetros obrigatórios ausentes
  • Valores de campo inválidos
  • Erros de permissão
  • Problemas de rede
  • Erros do servidor

Cada erro inclui:

  • Uma mensagem descritiva
  • Código de status HTTP (quando aplicável)
  • Informações do endpoint
  • Detalhes adicionais do servidor Frappe

Melhores Práticas

  1. Verifique o Esquema do DocType Primeiro: Antes de criar ou atualizar documentos, obtenha o esquema para entender os campos obrigatórios e validações.

  2. Use Paginação: Ao listar documentos, use os parâmetros limit e limit_start para paginar os resultados.

  3. Especifique Campos: Solicite apenas os campos que você precisa para melhorar o desempenho.

  4. Valide Antes de Criar: Use get_required_fields para garantir que você tenha todos os campos obrigatórios antes de criar um documento.

  5. Verifique a Existência: Use check_document_exists antes de atualizar ou excluir para garantir que o documento exista.

Licença

ISC