Protocolo de contexto de modelo (MCP): Um guia com projeto de demonstração

O protocolo Protocolo de contexto de modelo (MCP) é um padrão aberto que permite que grandes modelos de linguagem interajam dinamicamente com ferramentas externas, bancos de dados e APIs por meio de uma interface padronizada.

Neste blog, vou orientar você na criação de um servidor de revisão de RP com tecnologia MCP que se integra ao Claude Desktop. Esse servidor irá:

• Obter detalhes de PR e arquivos alterados do GitHub
• Analise as alterações de código usando o aplicativo Claude Desktop
• Gerar resumos e sugestões de revisão de RP
• Salvar comentários no Notion

Usaremos o MCP (Model Context Protocol) para padronizar a comunicação entre o servidor e o Claude Desktop, tornando-o modular e dimensionável.

O que é o protocolo de contexto de modelo (MCP)?

O protocolo de contexto de modelo (MCP) é um padrão aberto desenvolvido pela Anthropic para permitir a integração fácil e padronizada entre modelos de IA e ferramentas externas. Ele atua como um conector universal, permitindo que grandes modelos de linguagem (LLMs) interajam dinamicamente com APIs, bancos de dados e aplicativos comerciais.

Originalmente criado para melhorar a capacidade do Claude de interagir com sistemas externos, a Anthropic decidiu abrir o código aberto do MCP no início de 2024 para incentivar a adoção em todo o setor. Ao disponibilizar o MCP publicamente, eles pretendiam criar uma estrutura padronizada para a comunicação entre IA e ferramenta, reduzindo a dependência de integrações proprietárias e permitindo maior modularidade e interoperabilidade entre aplicativos de IA.

O MCP segue uma arquitetura cliente-servidor em que:

• Clientes MCP (por exemplo, o Claude Desktop) solicitam informações e executam tarefas.
• Os servidores MCP fornecem acesso a ferramentas e fontes de dados externas.
• Os aplicativos host usam o MCP para se comunicar entre modelos e ferramentas.

Fonte: Modelo de protocolo de contexto

Veja por que você deve usar a MCP em seus projetos:

• Integração padronizada de IA: O MCP oferece uma maneira estruturada de conectar modelos de IA a ferramentas.
• Flexibilidade: Ele permite alternar facilmente entre diferentes modelos e fornecedores de IA.
• Segurança: Ele mantém seus dados em sua infraestrutura enquanto interage com a IA.
• Escalabilidade: O MCP oferece suporte a vários transportes, como stdio, WebSockets, HTTP SSE e soquetes UNIX.

Visão geral do projeto de demonstração do MCP: Servidor de revisão de RP

O sistema de revisão de PR automatiza a análise e a documentação do código usando o Claude Desktop e o Notion.

Aqui está uma análise concisa do pipeline:

1. Configuração do ambiente: Carregue as credenciais do GitHub e do Notion.
2. Inicialização do servidor: Inicie um servidor MCP para se comunicar com o Claude Desktop.
3. Obtenção de dados de RP: Recupere as alterações de PR e os metadados do GitHub.
4. Análise de código: O Claude Desktop analisa diretamente as alterações de código (não é necessária nenhuma ferramenta separada).
5. Documentação de noções: Salve os resultados da análise no Notion para que você possa fazer o acompanhamento.

Etapa 1: Configuração do ambiente

Antes de começarmos, certifique-se de que você tenha o Python 3.10+ instalado. Em seguida, configuramos nosso ambiente e começamos a instalar o gerenciador de pacotes uv. Para Mac ou Linux: 

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

Para Windows (PowerShell):

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

Em seguida, criamos um novo diretório de projeto e o inicializamos com uv:

uv init pr_reviewer
cd pr_reviewer

Agora podemos criar e ativar um ambiente virtual. Para Mac ou Linux:

uv venv
source .venv/bin/activate

Para Windows:

.venv\Scripts\activate

Agora, vamos instalar as dependências necessárias:

uv add "mcp[cli]" requests python-dotenv notion-client

Para este projeto, usaremos o uv em vez do conda porque ele é mais rápido, mais leve e mais voltado para o gerenciamento de pacotes Python. Vamos recapitular o que acabamos de fazer:

• Configuramos um ambiente de desenvolvimento do servidor MCP do GitHub PR Review usando o gerenciador de pacotes uv
• Inicializamos um novo diretório de projeto chamado pr_reviewer e navegamos até ele.
• Criamos um ambiente virtual e o ativamos para garantir que as instalações de pacotes sejam isoladas.

Etapa 2: Instalar dependências

Depois que nosso ambiente estiver configurado, definimos nossas dependências com as chaves de API e outros requisitos. Crie um arquivo requirements.txt e adicione os seguintes pacotes Python a ele:

# Core dependencies for PR Analyzer
requests>=2.31.0          # For GitHub API calls
python-dotenv>=1.0.0      # For environment variables
mcp[cli]>=1.4.0          # For MCP server functionality
notion-client>=2.3.0      # For Notion integration

# Optional: Pin versions for stability
# requests==2.31.0
# python-dotenv==1.0.0
# mcp[cli]==1.4.0
# notion-client==2.3.0

O arquivo requirements.txt contém todas as dependências principais necessárias para o projeto. Para configurar as dependências, execute um dos seguintes comandos (use uv se você o tiver instalado anteriormente).

uv pip install -r requirements.txt
pip install -r requirements.txt

Agora, seu ambiente tem todas as dependências necessárias instaladas.

Etapa 3: Configuração das variáveis de ambiente

Em seguida, criamos um arquivo .env que contém todas as chaves e tokens necessários para este projeto. 

Geração de tokens do GitHub

Para gerar tokens do GitHub:

• Faça login na sua conta do GitHub e navegue até as configurações.
• Vá para Configurações do desenvolvedor → Tokens de acesso pessoal.
• Clique em Gerar novo token e selecione a versão clássica.
• Forneça um nome para o token e ative as seguintes permissões:
• read:org
• read:repo_hook
• repositório
• Clique em Gerar para criar o token.
• Copie e armazene o token de forma segura, pois ele será usado para autenticação em solicitações de API.

Integrações do Notion

• Faça login em: https://www.notion.so/profile/integrations
• Crie uma nova integração e preencha o formulário. Mantenha "type" em Internal e adicione-o ao seu espaço de trabalho .

• Salve a integração e copie o link de integração https://www.notion.so/profile/integrations/internal/UUID. O UUID no final do URL é o Universally Unique Identifier que você precisa anotar e usar como o Notion Page ID.
• Depois que a integração for criada, clique nela e, em Configuração, copie o Segredo de integração interna, que será sua chave da chave da API do Notion.

Criando um .env arquivo

Agora, crie um arquivo .env e adicione o seguinte texto junto com as chaves de API e o token que geramos acima.

GITHUB_TOKEN=your_github_token
NOTION_API_KEY=your_notion_api_key
NOTION_PAGE_ID=your_notion_page_id

Etapa 4: Integração com o GitHub

Vamos configurar nosso módulo de integração do GitHub para gerenciar e recuperar alterações de PR de um repositório do GitHub.

Crie um arquivo github_integration.py e escreva o seguinte código (explicaremos em breve).

import os
import requests
import traceback
from dotenv import load_dotenv

# Load environment variables
load_dotenv()
GITHUB_TOKEN = os.getenv('GITHUB_TOKEN')

def fetch_pr_changes(repo_owner: str, repo_name: str, pr_number: int) -> list:
    """Fetch changes from a GitHub pull request.
    
    Args:
        repo_owner: The owner of the GitHub repository
        repo_name: The name of the GitHub repository
        pr_number: The number of the pull request to analyze
        
    Returns:
        A list of file changes with detailed information about each change
    """
    print(f" Fetching PR changes for {repo_owner}/{repo_name}#{pr_number}")
    
    # Fetch PR details
    pr_url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/pulls/{pr_number}"
    files_url = f"{pr_url}/files"
    headers = {'Authorization': f'token {GITHUB_TOKEN}'}
    
    try:
        # Get PR metadata
        pr_response = requests.get(pr_url, headers=headers)
        pr_response.raise_for_status()
        pr_data = pr_response.json()
        
        # Get file changes
        files_response = requests.get(files_url, headers=headers)
        files_response.raise_for_status()
        files_data = files_response.json()
        
        # Combine PR metadata with file changes
        changes = []
        for file in files_data:
            change = {
                'filename': file['filename'],
                'status': file['status'],  # added, modified, removed
                'additions': file['additions'],
                'deletions': file['deletions'],
                'changes': file['changes'],
                'patch': file.get('patch', ''),  # The actual diff
                'raw_url': file.get('raw_url', ''),
                'contents_url': file.get('contents_url', '')
            }
            changes.append(change)
        
        # Add PR metadata
        pr_info = {
            'title': pr_data['title'],
            'description': pr_data['body'],
            'author': pr_data['user']['login'],
            'created_at': pr_data['created_at'],
            'updated_at': pr_data['updated_at'],
            'state': pr_data['state'],
            'total_changes': len(changes),
            'changes': changes
        }
        
        print(f"Successfully fetched {len(changes)} changes")
        return pr_info
        
    except Exception as e:
        print(f"Error fetching PR changes: {str(e)}")
        traceback.print_exc()
        return None

# Example usage for debugging
# pr_data = fetch_pr_changes('owner', 'repo', 1)
# print(pr_data) 

A função fetch_pr_changes() recupera e retorna alterações de um determinado pull request do GitHub. Ele recebe três parâmetros, a saber, repo_owner, repo_name e pr_number, e retorna uma lista estruturada de alterações de arquivos juntamente com metadados de PR.

O código usa a biblioteca requests para enviar solicitações HTTP GET autenticadas, obtendo metadados gerais de PR e alterações detalhadas no nível do arquivo:

• A primeira solicitação de API recupera informações de alto nível do PR, incluindo título, descrição, detalhes do autor, registros de data e hora e estado atual.
• A segunda solicitação de API obtém detalhes sobre cada arquivo alterado no PR, como nome do arquivo, status de modificação, número de linhas adicionadas ou removidas e URLs para acessar o conteúdo do arquivo.

Depois que os dados são recuperados, a função estrutura e combina os metadados do PR com as alterações do arquivo em um dicionário. As alterações de arquivo são armazenadas em uma lista, com cada entrada contendo informações detalhadas sobre um arquivo. A estrutura de dados final inclui o título do PR, a descrição, o autor, os carimbos de data/hora, o estado, a contagem total de arquivos alterados e uma análise detalhada das modificações de arquivos.

Etapa 5: Implementar o servidor MCP

Agora que temos todas as dependências e funções extras instaladas, configuramos nosso servidor MCP. Criamos um arquivo pr_anayzer.py, que será usado por você:

• Inicializar um servidor MCP.
• Definir ferramentas para buscar detalhes de RP, analisar o código e armazenar os resultados no Notion.
• Exponha essas ferramentas ao Claude Desktop para que você possa resumir, encontrar possíveis soluções e muito mais.

Primeiro, vamos adicionar o código e explicá-lo depois 

import sys
import os
import traceback
from typing import Any, List, Dict
from mcp.server.fastmcp import FastMCP
from github_integration import fetch_pr_changes
from notion_client import Client
from dotenv import load_dotenv

class PRAnalyzer:
    def __init__(self):
        # Load environment variables
        load_dotenv()
        
        # Initialize MCP Server
        self.mcp = FastMCP("github_pr_analysis")
        print("MCP Server initialized", file=sys.stderr)
        
        # Initialize Notion client
        self._init_notion()
        
        # Register MCP tools
        self._register_tools()
    
    def _init_notion(self):
        """Initialize the Notion client with API key and page ID."""
        try:
            self.notion_api_key = os.getenv("NOTION_API_KEY")
            self.notion_page_id = os.getenv("NOTION_PAGE_ID")
            
            if not self.notion_api_key or not self.notion_page_id:
                raise ValueError("Missing Notion API key or page ID in environment variables")
            
            self.notion = Client(auth=self.notion_api_key)
            print(f"Notion client initialized successfully", file=sys.stderr)
            print(f"Using Notion page ID: {self.notion_page_id}", file=sys.stderr)
        except Exception as e:
            print(f"Error initializing Notion client: {str(e)}", file=sys.stderr)
            traceback.print_exc(file=sys.stderr)
            sys.exit(1)
    
    def _register_tools(self):
        """Register MCP tools for PR analysis."""
        @self.mcp.tool()
        async def fetch_pr(repo_owner: str, repo_name: str, pr_number: int) -> Dict[str, Any]:
            """Fetch changes from a GitHub pull request."""
            print(f"Fetching PR #{pr_number} from {repo_owner}/{repo_name}", file=sys.stderr)
            try:
                pr_info = fetch_pr_changes(repo_owner, repo_name, pr_number)
                if pr_info is None:
                    print("No changes returned from fetch_pr_changes", file=sys.stderr)
                    return {}
                print(f"Successfully fetched PR information", file=sys.stderr)
                return pr_info
            except Exception as e:
                print(f"Error fetching PR: {str(e)}", file=sys.stderr)
                traceback.print_exc(file=sys.stderr)
                return {}
        
        @self.mcp.tool()
        async def create_notion_page(title: str, content: str) -> str:
            """Create a Notion page with PR analysis."""
            print(f"Creating Notion page: {title}", file=sys.stderr)
            try:
                self.notion.pages.create(
                    parent={"type": "page_id", "page_id": self.notion_page_id},
                    properties={"title": {"title": [{"text": {"content": title}}]}},
                    children=[{
                        "object": "block",
                        "type": "paragraph",
                        "paragraph": {
                            "rich_text": [{
                                "type": "text",
                                "text": {"content": content}
                            }]
                        }
                    }]
                )
                print(f"Notion page '{title}' created successfully!", file=sys.stderr)
                return f"Notion page '{title}' created successfully!"
            except Exception as e:
                error_msg = f"Error creating Notion page: {str(e)}"
                print(error_msg, file=sys.stderr)
                traceback.print_exc(file=sys.stderr)
                return error_msg
    
    def run(self):
        """Start the MCP server."""
        try:
            print("Running MCP Server for GitHub PR Analysis...", file=sys.stderr)
            self.mcp.run(transport="stdio")
        except Exception as e:
            print(f"Fatal Error in MCP Server: {str(e)}", file=sys.stderr)
            traceback.print_exc(file=sys.stderr)
            sys.exit(1)

if __name__ == "__main__":
    analyzer = PRAnalyzer()
    analyzer.run() 

O código acima configura um servidor MCP para buscar alterações no GitHub PR e armazena os resultados da análise no Notion. Vamos examinar os principais componentes:

1. Configuração e inicialização do ambiente
• O módulo dotenv carrega variáveis de ambiente, garantindo que as chaves e credenciais da API sejam acessadas com segurança. 
• Em seguida, a classe PRAnalyzer inicializa um servidor MCP usando a função FastMCP() que inicializa o servidor MCP com o nome github_pr_analysis e permite a interação com o aplicativo Claude Desktop.
• O cliente Notion também é configurado usando o pacote notion-client, que utiliza a chave da API do Notion e o ID da página armazenados no arquivo .env.
2. Ferramenta MCP: buscar alterações de PR
• A função fetch_pr() recupera metadados de pull request do GitHub usando o método fetch_pr_changes() do arquivo github_integration.py. Se for bem-sucedido, ele retornará um dicionário contendo detalhes do PR.
• Você pode automatizar esse processo usando os Webhooks incorporada no GitHub, de modo que qualquer novo PR criado em seu repositório seja processado automaticamente pelo servidor.
3. Ferramenta MCP: criar uma página Notion
• A função create_notion_page() gera uma página Notion com os resultados da análise de RP.
• Ele usa a API do Notion para criar uma nova página no espaço de trabalho do Notion especificado.
4. Execução do servidor
• O método run() inicia o servidor MCP usando mcp.run(transport="stdio"), permitindo a interação entre o Claude Desktop e as ferramentas de revisão de BP.

Etapa 6: Executar o servidor MCP

Agora que temos todas as partes do código no lugar, executamos nosso servidor com o seguinte comando no terminal:

python pr_analyzer.py

Quando o servidor estiver instalado e funcionando, abra o aplicativo Claude Desktop e você verá um ícone de plugue (🔌) na caixa de texto. Esse plugue indica a presença de um MCP no ambiente Claude. Na mesma caixa de texto, você notará um ícone semelhante a um martelo (🔨) que exibe todos os MCPs disponíveis, conforme mostrado abaixo.

Agora, passe o link para o PR que você deseja analisar e o Claude fará o resto das coisas para você.

Claude primeiro analisará o PR e, em seguida, fornecerá um resumo e uma revisão dele. Ele perguntará aos usuários se eles desejam carregar os detalhes na página do Notion. Embora você possa automatizar esse processo, o código atual permite que você revise o resumo antes de criar uma nova página do Notion.

A página atualizada do Notion tem a seguinte aparência:

Conclusão

Nosso servidor baseado no PR Review MCP melhora a análise e a documentação do código, aprimorando o processo de revisão para obter eficiência e organização. Ao usar o MCP, a API do GitHub e a integração do Notion, esse sistema oferece suporte à análise automatizada de PR, colaboração fácil e documentação estruturada. Com essa configuração, os desenvolvedores podem recuperar rapidamente detalhes de PR, analisar alterações de código usando o Claude e armazenar insights no Notion para referência futura.

Para explorar ferramentas de IA mais recentes, recomendo estes blogs:

• Como configurar e executar o Gemma 3 localmente com o Ollama
• Mistral OCR: Um guia com exemplos práticos
• Tutorial do SDK do OpenAI Agents: Criando sistemas de IA que tomam medidas
• ERNIE 4.5 e X1 da Baidu: Recursos, acesso, comparação com o DeepSeek