Pular para o conteúdo principal

Endpoint MCP

Visão geral​

Agradecimentos especiais ao XiaoZhi AI Chatbot por suas contribuições de código aberto que tornaram este projeto possível.

MCP (Model Context Protocol) é um framework poderoso que estende as capacidades da IA ao permitir controle remoto, computação, operações de e-mail, pesquisas de conhecimento e muito mais.

O MCP permite que servidores exponham ferramentas chamáveis para modelos de linguagem por meio de um protocolo bem definido. Essas ferramentas permitem que o modelo interaja com sistemas externos, como consultar bancos de dados, invocar APIs ou realizar cálculos complexos. Cada ferramenta é identificada exclusivamente por um nome e descrita por metadados que definem sua funcionalidade.

O Endpoint MCP serve como ponte entre o seu serviço MCP local e o modelo Xiaozhi AI. Ele fornece uma interface para dispositivos com voz e outros terminais aproveitarem perfeitamente essas capacidades externas.

Obter o Endpoint MCP​

  1. Acesse a SenseCraft AI Platform

  2. Para acessar o Painel de Controle, clique em Watcher Agent no canto superior direito da página.

  1. Abra a configuração do agent
  1. Clique em MCP Setting e Get MCP Endpoint
  1. Obtenha o endereço do Endpoint e o Status da Conexão

Exemplo de MCP​

Agradecimentos especiais ao XiaoZhi AI Chatbot por suas contribuições de código aberto que tornaram este projeto possível.

Você pode obter o seguinte código no MCP Example Code Github

Exemplo de código de servidor MCP​

  # server.py
  from mcp.server.fastmcp import FastMCP
  import logging
  logger = logging.getLogger('test_mcp')

  import math
  import random

  # Create an MCP server
  mcp = FastMCP("Calculator")

  # Add an addition tool
  @mcp.tool()
  def calculator(python_expression: str) -> dict:
      """For mathamatical calculation, always use this tool to calculate the result of a python expression. `math` and `random` are available."""
      result = eval(python_expression)
      logger.info(f"Calculating formula: {python_expression}, result: {result}")
      return {"success": True, "result": result}

  # Start the server
  if __name__ == "__main__":
      mcp.run(transport="stdio")

Explicação do código​

Abaixo está uma explicação detalhada de algumas partes principais do exemplo de servidor MCP:

  • @mcp.tool() : Registra a função seguinte como uma ferramenta MCP que pode ser chamada remotamente pelo modelo de IA.

  • def calculator(python_expression: str) -> dict: Define uma ferramenta que recebe uma expressão matemática do modelo.

  • result = eval(python_expression) : Usa o eval() do Python para avaliar a expressão. Bibliotecas como math e random podem ser usadas porque foram importadas acima.

  • mcp.run(transport="stdio") : Inicia o servidor. O transporte stdio permite que ele se comunique com o Watcher Agent ou com o seu cliente MCP.

Início rápido​

  • Requisitos

    • MCP Example Code Github
    • Python 3.7+
    • websockets>=11.0.3
    • python-dotenv>=1.0.0
    • mcp>=1.8.1
    • pydantic>=2.11.4
    • mcp-proxy>=0.8.2

  • Passo 1. Clone o repositório e navegue até a pasta do projeto

    git clone https://github.com/78/mcp-calculator.git
    cd mcp-calculator

  • Passo 2. Instale as dependências

    pip install -r requirements.txt

  • Passo 3. Configure as variáveis de ambiente

    • Para Linux/macOS 
      export MCP_ENDPOINT=<your_mcp_endpoint>
    • Para Windows (PowerShell) 
      $env:MCP_ENDPOINT="<your_mcp_endpoint>"
    • Para Windows (CMD) 
      set MCP_ENDPOINT=<your_mcp_endpoint>

  • Passo 4. Execute o exemplo da calculadora

    python mcp_pipe.py calculator.py

  • Ou execute todos os servidores configurados

    python mcp_pipe.py
    nota

    Isso requer um arquivo de configuração mcp_config.json definindo as configurações do servidor.

Resultado da execução​

export MCP_ENDPOINT=<mcp_endpoint_address_get_from_your_agent_configuration>
python mcp_pipe.py calculator.py
2025-05-16 09:07:09,009 - MCP_PIPE - INFO - Connecting to WebSocket server...
2025-05-16 09:07:09,096 - MCP_PIPE - INFO - Successfully connected to WebSocket server
2025-05-16 09:07:09,097 - MCP_PIPE - INFO - Started test.py process
Processing request of type ListToolsRequest
Processing request of type CallToolRequest
Calculating formula: 3.14159 * (8 / 2) ** 2, result: 50.26544
Processing request of type CallToolRequest
Calculating formula: math.comb(10, 3), result: 120

Status do Endpoint MCP​

  • Connection Status: Mostra se a sua conexão MCP está funcionando corretamente.
  • Ícone de atualização: Atualiza o status da sua conexão MCP.
  • Enabled Services: Lista todos os serviços MCP que o seu watcher pode usar.
  • Endpoint Address: Seu mcp_endpoint_address (não compartilhe isso com ninguém, a menos que seja exigido pelo suporte técnico oficial)

Log de conversas​

Precauções​

1. Nomeação de ferramentas e parâmetros no MCP​

Os nomes das ferramentas e de seus parâmetros devem ser claros para que o modelo grande entenda seu propósito. Evite usar abreviações sempre que possível e forneça um comentário explicando a função da ferramenta e quando ela deve ser usada.

Por exemplo, uma ferramenta chamada calculator permite que o modelo saiba que se trata de uma calculadora, e o parâmetro python_expression indica que o modelo deve inserir uma expressão Python.

Se você estiver escrevendo uma ferramenta bing_search, o nome do parâmetro deve ser keywords.

2. Orientação via docstring da função​

A docstring (usando """...""") orienta o modelo sobre quando usar a ferramenta.

Ela também pode mencionar que funções das bibliotecas math e random podem ser usadas na expressão.

Essas duas bibliotecas já foram importadas no código de exemplo.

3. Fazer log em vez de imprimir​

Como a entrada/saída padrão neste exemplo de Servidor MCP é usada para transmissão de dados, você não pode usar print para exibir informações.

Use logger para depuração e registro em log.

4. Valores de retorno​

Os valores de retorno MCP geralmente são uma string ou JSON. No exemplo, o resultado do cálculo é retornado em um campo JSON chamado result.

O comprimento dos valores de retorno costuma ser limitado, semelhante a comandos de dispositivos IoT, normalmente dentro de 1024 bytes.

5. Limite da lista de ferramentas​

A lista de ferramentas MCP possui um limite máximo.

Mais tarde, ela será exibida na página de configuração, calculada com base na contagem de tokens.

Observação: Ter ferramentas demais pode afetar a eficiência de agendamento do dispositivo.

6. Limite de conexão​

Cada endpoint MCP possui um número máximo de conexões simultâneas.

Observação: Exceder esse limite ou ter conexões simultâneas em excesso pode reduzir o desempenho do dispositivo.

Selecionar serviços MCP pré-fornecidos​

Os quatro serviços MCP a seguir estão disponíveis para você escolher em MCP Setting, mencionado anteriormente.

Depois de salvar a configuração e reiniciar o dispositivo, os serviços selecionados entrarão em vigor automaticamente.

Você pode remover o serviço clicando em ×

Suporte técnico​

Loading Comments...