Daraja MCP

Integre aplicações de IA com a API Daraja da Safaricom para interação contínua com os serviços M-Pesa.

GitHub
14
Experimente este MCPPatrocinado

Documentação

Daraja MCP

🚨 Aviso Importante: Repositório Movido

Este projeto foi movido para um novo repositório. Se você deseja contribuir ou acessar a versão mais recente, visite:

https://github.com/paylinkmcp/paylink

Um servidor Model Context Protocol (MCP) projetado para integrar aplicações de IA com a API Daraja da Safaricom, permitindo interação perfeita com os serviços M-Pesa.

⚠️ Aviso: Não Pronto para Produção

Este projeto está atualmente em desenvolvimento e não é recomendado para uso em produção. Ele foi projetado para:

  • Aprendizado e experimentação
  • Ambientes de desenvolvimento e teste
  • Implementações de prova de conceito

Para uso em produção, certifique-se de:

  • Testes de segurança completos
  • Tratamento adequado de erros
  • Implementação completa de todos os recursos planejados
  • Conformidade com os requisitos de produção da Safaricom

O que é um Servidor MCP?

Servidores MCP (Model Context Protocol) fornecem capacidades para LLMs interagirem com sistemas externos. Servidores MCP podem fornecer três tipos principais de capacidades:

  • Recursos: Dados semelhantes a arquivos que podem ser lidos por clientes (como respostas de API)
  • Ferramentas: Funções que podem ser chamadas pelo LLM (com aprovação do usuário)
  • Prompts: Modelos pré-escritos que ajudam os usuários a realizar tarefas específicas

O Daraja MCP especificamente aproveita essa arquitetura para conectar sistemas de IA com a API Daraja M-Pesa da Safaricom.

Visão Geral

O Daraja MCP é uma ponte entre IA, fintech e M-Pesa, tornando a automação financeira orientada por IA acessível e eficiente. Ao padronizar a conexão entre LLMs (Large Language Models) e transações financeiras, o Daraja MCP permite que aplicações orientadas por IA processem pagamentos, recuperem dados de transações e automatizem fluxos de trabalho financeiros sem esforço.

Principais Capacidades

  • ✅ Transações M-Pesa com IA – Permite que LLMs lidem com pagamentos B2C, C2B e B2B
  • ✅ Integração Padronizada – MCP garante compatibilidade com múltiplas ferramentas de IA
  • ✅ Seguro e Escalável – Implementa autenticação OAuth e suporta manipulação de transações de nível empresarial
  • ✅ Automação Flexível – Agentes de IA podem consultar saldos de contas, gerar faturas e automatizar conciliações

Requisitos

  • Python 3.12
  • Credenciais da API Daraja da Safaricom (Consumer Key e Secret)

Instalação

Passo 1: Configurando Seu Ambiente

  1. Instale o Gerenciador de Pacotes uv

    Para Mac/Linux:

    curl -LsSf https://astral.sh/uv/install.sh | sh

    Para Windows (PowerShell):

    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  2. Clone o Repositório

    git clone https://github.com/jameskanyiri/DarajaMCP.git
cd DarajaMCP

  3. Crie e Ative um Ambiente Virtual

    uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

    ✅ Saída Esperada: O prompt do seu terminal deve mudar, indicando que o ambiente virtual está ativado.

  4. Instale as Dependências

    uv sync

Passo 2: Configurando Variáveis de Ambiente

  1. Copie o arquivo de ambiente de exemplo:

    cp .env.example .env

  2. Atualize o arquivo .env com suas credenciais e valores de configuração reais.

Nota: Para desenvolvimento, use o ambiente sandbox. Mude para a URL de produção quando estiver pronto.

Uso

Testando com Claude Desktop

  1. Instale o Claude Desktop

    • Baixe e instale a versão mais recente do Claude Desktop
    • Certifique-se de estar executando a versão mais recente

  2. Configure o Claude Desktop

    • Abra o arquivo de configuração do Claude Desktop:

      # On MacOS/Linux
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# On Windows
code %APPDATA%\Claude\claude_desktop_config.json

    • Crie o arquivo se ele não existir

  3. Adicione a Configuração do Servidor Escolha uma das seguintes configurações:

    Formato Recomendado pela Anthropic

    {
  "mcpServers": {
    "daraja": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/DarajaMCP",
        "run",
        "main.py"
      ]
    }
  }
}

    Configuração Funcional (Testada)

    {
  "mcpServers": {
    "DarajaMCP": {
      "command": "/ABSOLUTE/PATH/TO/PARENT/.local/bin/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/DarajaMCP",
        "run",
        "main.py"
      ]
    }
  }
}

    Nota:

    • Substitua /ABSOLUTE/PATH/TO/PARENT pelo seu caminho real
    • Para encontrar o caminho completo para uv, execute:
    # On MacOS/Linux
which uv

# On Windows
where uv

  4. Verifique a Configuração

    • Salve o arquivo de configuração
    • Reinicie o Claude Desktop
    • Procure pelo ícone de martelo 🔨 na interface
    • Clique nele para ver as ferramentas disponíveis:
      • generate_access_token
      • stk_push (Implementação Futura)
      • query_transaction_status (Implementação Futura)
      • b2c_payment (Implementação Futura)
      • account_balance (Implementação Futura)

Ferramentas e Prompts

Ferramentas de Pagamento

stk_push

Inicie uma solicitação de push STK do M-Pesa para solicitar que o cliente autorize um pagamento em seu dispositivo móvel.

Entradas:

  • amount (int): O valor a ser pago
  • phone_number (int): O número de telefone do cliente

Retorna: Resposta da API M-PESA formatada em JSON

generate_qr_code

Gere um código QR para uma solicitação de pagamento que os clientes podem escanear para fazer pagamentos.

Entradas:

  • merchant_name (str): Nome da empresa/Nome do Comerciante M-Pesa
  • transaction_reference_no (str): Número de referência da transação
  • amount (int): O valor total da venda/transação
  • transaction_type (Literal["BG", "WA", "PB", "SM", "SB"]): Tipo de transação
  • credit_party_identifier (str): Identificador da Parte Credora (Número de Celular, Número Comercial, Till de Agente, Paybill ou Merchant Buy Goods)

Retorna: Resposta da API M-PESA formatada em JSON contendo os dados do código QR

Prompts de Pagamento

stk_push_prompt

Gere um prompt para iniciar uma solicitação de pagamento push STK do M-Pesa.

Entradas:

  • phone_number (str): O número de telefone do cliente
  • amount (int): O valor a ser pago
  • purpose (str): O propósito do pagamento

Retorna: String de prompt formatada para solicitação de push STK

generate_qr_code_prompt

Gere um prompt para criar uma solicitação de pagamento com código QR do M-Pesa.

Entradas:

  • merchant_name (str): Nome do comerciante/negócio
  • amount (int): Valor a ser pago
  • transaction_type (str): Tipo de transação (BG para Buy Goods, WA para Wallet, PB para Paybill, SM para Send Money, SB para Send to Business)
  • identifier (str): O identificador do destinatário (número do till, paybill, número de telefone)
  • reference (str, opcional): Número de referência da transação. Se não for fornecido, um padrão será usado.

Retorna: String de prompt formatada para geração de código QR

Ferramentas de Processamento de Documentos

create_source

Crie um conector da fonte de dados para o servidor não estruturado para processamento.

Entradas:

  • connector_name (str): O nome do conector de origem a ser criado

Retorna: Detalhes do conector de origem, incluindo nome e ID

create_destination

Crie um conector do servidor não estruturado para o destino para armazenamento de dados.

Entradas:

  • connector_name (str): O nome do conector de destino a ser criado

Retorna: Detalhes do conector de destino, incluindo nome e ID

create_workflow

Crie um fluxo de trabalho para processar dados do conector de origem para o conector de destino.

Entradas:

  • workflow_name (str): O nome do fluxo de trabalho a ser criado
  • source_id (str): O ID do conector de origem
  • destination_id (str): O ID do conector de destino

Retorna: Detalhes do fluxo de trabalho, incluindo nome, ID, status, tipo, origens, destinos e agendamento

run_workflow

Execute um fluxo de trabalho.

Entradas:

  • workflow_id (str): O ID do fluxo de trabalho a ser executado

Retorna: Status de execução do fluxo de trabalho

get_workflow_details

Obtenha informações detalhadas sobre um fluxo de trabalho.

Entradas:

  • workflow_id (str): O ID do fluxo de trabalho para obter detalhes

Retorna: Detalhes do fluxo de trabalho, incluindo nome, ID e status

fetch_documents

Busque documentos analisados durante a execução do fluxo de trabalho.

Entradas: Nenhuma

Retorna: Lista de documentos analisados

Prompts

create_and_run_workflow_prompt

Gere um prompt para criar e executar um fluxo de trabalho para processamento de documentos.

Entradas:

  • user_input (str): Os requisitos de processamento do usuário

Retorna: Prompt formatado para criação e execução de fluxo de trabalho

Exemplo:

# Example usage
prompt = await create_and_run_workflow_prompt(
    user_input="Process all PDF invoices from the invoices folder and store them in the processed folder"
)
# Returns: "The user wants to achieve Process all PDF invoices from the invoices folder and store them in the processed folder. Assist them by creating a source connector and a destination connector, then setting up the workflow and executing it."

Recursos

Atualmente, nenhum recurso está disponível.

Licença

Licença MIT

Agradecimentos

  • Safaricom por fornecer a API Daraja
  • Anthropic pelo framework MCP
  • Contribuidores do projeto

Contato

Para quaisquer dúvidas, abra uma issue no repositório do GitHub.