Projet MCP Server-Client

Uma implementação do Model Context Protocol (MCP) para comunicação entre modelos de IA e ferramentas externas, com exemplos de servidor e cliente em Python e Spring Boot.

GitHubExperimente este MCPPatrocinado

Documentação

Projet MCP Server-Client

Apresentação do projeto

Este projeto é uma implementação do protocolo MCP (Model Context Protocol) que permite a comunicação entre modelos de IA e ferramentas externas. A aplicação é composta por três componentes principais:

  1. Servidor MCP Python - Um servidor MCP leve escrito em Python usando a biblioteca FastMCP
  2. Servidor MCP Spring Boot - Um servidor MCP baseado em Spring Boot usando o protocolo SSE (Server-Sent Events)
  3. Cliente MCP Spring Boot - Um cliente que se conecta aos servidores MCP e usa a API Anthropic Claude para funcionalidades de IA

image

image

Estrutura do projeto

mcp-server-client-spring-ai-main/
│
├── python-mcp-server/            # Serveur MCP Python
│   ├── server.py                 # Point d'entrée du serveur MCP Python
│   └── main.py                   # Fichier Python principal
│
├── sse-mcp-server/               # Serveur MCP Spring Boot
│   ├── pom.xml                   # Configuration Maven
│   └── src/                      # Code source Java
│
├── mcp-client/                   # Client MCP Spring Boot
│   ├── pom.xml                   # Configuration Maven
│   ├── src/                      # Code source Java
│   └── resources/                # Fichiers de configuration
│       ├── application.properties        # Configuration principale
│       ├── application-secrets.properties # Clés API (non versionnées)
│       └── mcp-servers.json              # Configuration des serveurs MCP
│
└── run-all.bat                   # Script pour démarrer tous les composants

Pré-requisitos

  • Java 21 ou superior
  • Python 3.10 ou superior
  • Maven (incluído via os wrappers mvnw)
  • Chave da API Anthropic Claude

Instalação

  1. Instalação das dependências Python
cd python-mcp-server
pip install fastmcp
  1. Configuração da chave da API Anthropic (OBRIGATÓRIO)

A aplicação requer uma chave da API Anthropic Claude válida para funcionar. Sem essa chave, você receberá um erro de autenticação (HTTP 401 - invalid x-api-key).

Veja como configurar a chave da API:

a) Crie um arquivo application-secrets.properties na pasta mcp-client/src/main/resources/ com base no modelo fornecido:

# Clé API Anthropic
spring.ai.anthropic.api-key=sk-ant-api03-VOTRE_CLÉ_API_ICI

b) Alternativamente, você pode definir uma variável de ambiente do sistema chamada CLAUDE_API_KEY com sua chave da API como valor.

IMPORTANTE: Nunca compartilhe sua chave da API e não a publique no GitHub ou em qualquer outro repositório público. O arquivo application-secrets.properties é automaticamente ignorado pelo Git para proteger sua chave.

Inicialização da aplicação

Pré-requisitos antes da inicialização

  1. Certifique-se de que você configurou corretamente sua chave da API Anthropic (veja a seção anterior)
  2. Verifique se o Python está instalado e se a biblioteca FastMCP está disponível
  3. Se você usar o servidor filesystem, verifique se o Node.js está instalado e acessível

Método 1: Inicialização automatizada (recomendada)

Use o script batch que inicia todos os componentes na ordem correta com os intervalos apropriados:

run-all.bat

Este script:

  • Inicia primeiro o servidor MCP Python em uma janela separada
  • Aguarda 3 segundos para a inicialização
  • Inicia o servidor MCP Spring Boot em uma segunda janela
  • Aguarda 5 segundos para a inicialização
  • Executa o cliente MCP na janela atual

Método 2: Inicialização manual dos componentes

Se você preferir um controle mais preciso, pode iniciar cada componente manualmente nesta ordem:

  1. Iniciar o servidor MCP Python
cd python-mcp-server
python server.py
  1. Iniciar o servidor MCP Spring Boot
cd sse-mcp-server
./mvnw spring-boot:run  # Sous Windows: mvnw.cmd spring-boot:run
  1. Iniciar o cliente MCP
cd mcp-client
./mvnw spring-boot:run  # Sous Windows: mvnw.cmd spring-boot:run

Acesso à aplicação

Uma vez iniciada, a aplicação cliente é acessível em:

  • URL: http://localhost:8080
  • O servidor Python MCP executa na porta 8878
  • O servidor Spring Boot MCP executa na porta 8877

Arquitetura

O sistema usa o protocolo MCP (Model Context Protocol) para permitir a comunicação entre diferentes componentes:

  • O Servidor MCP Python fornece ferramentas simples como a recuperação de informações sobre funcionários
  • O Servidor MCP Spring Boot fornece serviços adicionais via Spring Boot
  • O Cliente MCP se conecta a esses servidores para acessar suas ferramentas e as expõe através de uma interface web

Configuração

Configuração do cliente MCP

O arquivo application.properties contém a configuração principal:

# Configuration du client MCP
spring.ai.mcp.client.type=sync
spring.ai.mcp.client.connection-timeout=60000
spring.ai.mcp.client.read-timeout=60000
spring.ai.mcp.client.sse.connections.server1.url=http://localhost:8877

Configuração dos servidores MCP

O arquivo mcp-servers.json define os servidores MCP disponíveis:

{
  "mcpServers": {
    "filesystem": {
      "command": "C:/Program Files/nodejs/npx.cmd",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "chemin/vers/dossier"
      ]
    },
    "Python-MCP-Server": {
      "command": "python",
      "args": [
        "chemin/vers/server.py"
      ]
    }
  }
}

Segurança

As chaves de API sensíveis são armazenadas em um arquivo application-secrets.properties que é excluído do controle de versão Git. Nunca compartilhe este arquivo e não o inclua em seus commits.

Solução de problemas

  1. Erro "Invalid x-api-key"

    • Verifique se sua chave da API Anthropic está configurada corretamente em application-secrets.properties

  2. Erro "Cannot run program 'npx'"

    • Verifique se o Node.js está instalado ou desative o servidor filesystem adicionando:
    • spring.ai.mcp.client.stdio.filesystem.auto-initialization.enabled=false em application.properties

  3. Problemas de conexão com o servidor MCP

    • Verifique se os servidores MCP estão em execução
    • Verifique os parâmetros de timeout em application.properties

Contribuição

Para contribuir com este projeto, por favor:

  1. Faça um fork do repositório
  2. Crie uma branch para sua funcionalidade (git checkout -b nouvelle-fonctionnalite)
  3. Faça commit das suas alterações (git commit -am 'Ajouter une nouvelle fonctionnalité')
  4. Envie para a branch (git push origin nouvelle-fonctionnalite)
  5. Crie uma Pull Request

Licença

Este projeto é distribuído sob a licença MIT.