Integrar um aplicativo do Serviço de Aplicativo como servidor MCP para o GitHub Copilot Chat (Python)

Neste tutorial, você aprenderá a expor a funcionalidade de um aplicativo FastAPI por meio do protocolo MCP (Protocolo de Contexto de Modelo), adicioná-lo como uma ferramenta ao GitHub Copilot e interagir com seu aplicativo usando linguagem natural no modo de agente do Copilot Chat.

Captura de tela mostrando que a resposta da chamada da ferramenta MCP na janela de Chat do GitHub Copilot.

Se o seu aplicativo Web já tiver recursos úteis, como compras, reserva de hotéis ou gerenciamento de dados, é fácil tornar essas funcionalidades disponíveis para:

Qualquer aplicativo que dê suporte à integração do MCP, como o modo de agente do GitHub Copilot Chat no Visual Studio Code ou no GitHub Codespaces.
Um agente personalizado que acessa ferramentas remotas usando um cliente MCP.

Ao adicionar um servidor MCP ao seu aplicativo Web, você permite que um agente entenda e use os recursos do aplicativo quando ele responder aos prompts do usuário. Isso significa que tudo o que seu aplicativo pode fazer, o agente também pode fazer.

Adicione um servidor MCP ao seu aplicativo Web.
Teste o servidor MCP localmente no modo de agente do GitHub Copilot Chat.
Implante o servidor MCP no Serviço de Aplicativo do Azure e conecte-se a ele no GitHub Copilot Chat.

Pré-requisitos

Este tutorial pressupõe que você esteja trabalhando com o exemplo usado na implantação de um aplicativo Web Python FastAPI com PostgreSQL no Azure.

No mínimo, abra o aplicativo de exemplo no GitHub Codespaces e implante o aplicativo executando azd up.

Adicionar o servidor MCP ao seu aplicativo Web

No gerenciador de codespaces, abra src/pyproject.toml e adicione mcp[cli] à lista de dependências, conforme mostrado no exemplo a seguir:
```
dependencies = [
    ...
    "mcp[cli]",
]
```

No src/fastapi_app, crie um arquivo chamado mcp_server.py e cole o seguinte código de inicialização do servidor MCP no arquivo:

import asyncio
import contextlib
from contextlib import asynccontextmanager

from mcp.server.fastmcp import FastMCP
from sqlalchemy.sql import func
from sqlmodel import Session, select

from .models import Restaurant, Review, engine

# Create a FastMCP server. Use stateless_http=True for simple mounting. Default path is .../mcp
mcp = FastMCP("RestaurantReviewsMCP", stateless_http=True)

# Lifespan context manager to start/stop the MCP session manager with the FastAPI app
@asynccontextmanager
async def mcp_lifespan(app):
    async with contextlib.AsyncExitStack() as stack:
        await stack.enter_async_context(mcp.session_manager.run())
        yield

# MCP tool: List all restaurants with their average rating and review count
@mcp.tool()
async def list_restaurants_mcp() -> list[dict]:
    """List restaurants with their average rating and review count."""

    def sync():
        with Session(engine) as session:
            statement = (
                select(
                    Restaurant,
                    func.avg(Review.rating).label("avg_rating"),
                    func.count(Review.id).label("review_count"),
                )
                .outerjoin(Review, Review.restaurant == Restaurant.id)
                .group_by(Restaurant.id)
            )
            results = session.exec(statement).all()
            rows = []
            for restaurant, avg_rating, review_count in results:
                r = restaurant.dict()
                r["avg_rating"] = float(avg_rating) if avg_rating is not None else None
                r["review_count"] = review_count
                r["stars_percent"] = (
                    round((float(avg_rating) / 5.0) * 100) if review_count > 0 and avg_rating is not None else 0
                )
                rows.append(r)
            return rows

    return await asyncio.to_thread(sync)

# MCP tool: Get a restaurant and all its reviews by restaurant_id
@mcp.tool()
async def get_details_mcp(restaurant_id: int) -> dict:
    """Return the restaurant and its related reviews as objects."""

    def sync():
        with Session(engine) as session:
            restaurant = session.exec(select(Restaurant).where(Restaurant.id == restaurant_id)).first()
            if restaurant is None:
                return None
            reviews = session.exec(select(Review).where(Review.restaurant == restaurant_id)).all()
            return {"restaurant": restaurant.dict(), "reviews": [r.dict() for r in reviews]}

    return await asyncio.to_thread(sync)

# MCP tool: Create a new review for a restaurant
@mcp.tool()
async def create_review_mcp(restaurant_id: int, user_name: str, rating: int, review_text: str) -> dict:
    """Create a new review for a restaurant and return the created review dict."""

    def sync():
        with Session(engine) as session:
            review = Review()
            review.restaurant = restaurant_id
            review.review_date = __import__("datetime").datetime.now()
            review.user_name = user_name
            review.rating = int(rating)
            review.review_text = review_text
            session.add(review)
            session.commit()
            session.refresh(review)
            return review.dict()

    return await asyncio.to_thread(sync)

# MCP tool: Create a new restaurant
@mcp.tool()
async def create_restaurant_mcp(restaurant_name: str, street_address: str, description: str) -> dict:
    """Create a new restaurant and return the created restaurant dict."""

    def sync():
        with Session(engine) as session:
            restaurant = Restaurant()
            restaurant.name = restaurant_name
            restaurant.street_address = street_address
            restaurant.description = description
            session.add(restaurant)
            session.commit()
            session.refresh(restaurant)
            return restaurant.dict()

    return await asyncio.to_thread(sync)

O inicializador FastMCP() cria um servidor MCP usando o padrão de modo sem estado no SDK do Python do MCP. Por padrão, seu ponto de extremidade HTTP transmitível é definido como o subcaminho /mcp.

O decorador @mcp.tool() adiciona uma ferramenta ao servidor MCP com sua implementação.
A descrição da função de ferramenta ajuda o agente de chamada a entender como usar a ferramenta e seus parâmetros.

As ferramentas duplicam a funcionalidade de revisões de restaurante existentes no aplicativo Web FastAPI baseado em formulário. Se desejar, você pode adicionar mais ferramentas para atualizar e excluir a funcionalidade.

Em src/fastapi_app/app.py, localize a linha para app = FastAPI() (linha 24) e substitua-a pelo seguinte código:
```
from .mcp_server import mcp, mcp_lifespan
app = FastAPI(lifespan=mcp_lifespan)
app.mount("/mcp", mcp.streamable_http_app())
```
Esse código monta o ponto de extremidade HTTP transmitível do servidor MCP para o aplicativo FastAPI existente no caminho /mcp. Junto com o caminho padrão do ponto de extremidade HTTP transmitível, o caminho completo é /mcp/mcp.

Testar o servidor MCP localmente

No terminal do codespace, execute o aplicativo com os seguintes comandos:

python3 -m venv .venv
source .venv/bin/activate
pip install -r src/requirements.txt
pip install -e src
python3 src/fastapi_app/seed_data.py
python3 -m uvicorn fastapi_app:app --reload --port=8000

Selecione Abrir no Navegador e, em seguida, adicione alguns restaurantes e avaliações.

Deixe uvicorn em execução. Seu servidor MCP está em execução em http://localhost:8000/mcp/mcp agora.
De volta ao codespace, abra o Copilot Chat e, em seguida, selecione o modo de agente na caixa de prompt.
Selecione o botão Ferramentas e, em seguida, selecione o ícone Adicionar Servidor MCP no canto superior direito do pop-up.
Selecione HTTP (eventos enviados por HTTP ou servidor).
Em Inserir URL do Servidor, digite http://localhost:8000/mcp/mcp.
Em Inserir ID do Servidor, digite restaurant_ratings ou qualquer nome que você quiser.
Selecione Configurações do workspace.
Em uma nova janela do Copilot Chat, digite algo como "Mostre-me as avaliações do restaurante".
Por padrão, o GitHub Copilot mostra uma confirmação de segurança quando você invoca um servidor MCP. Selecione Continuar.

Agora você deve ver uma resposta que indica que a chamada à ferramenta MCP foi bem-sucedida.

Implantar o servidor MCP no Serviço de Aplicativo

De volta ao terminal do codespace, implante suas alterações confirmando suas alterações (método GitHub Actions) ou execute azd up (método Azure Developer CLI).

Na saída do AZD, localize a URL do seu aplicativo. O URL fica assim na saída do AZD:

 Deploying services (azd deploy)

   (✓) Done: Deploying service web
   - Endpoint: <app-url>

Após a conclusão azd up, abra .vscode/mcp.json. Altere a URL para <app-url>/mcp/mcp.
Acima da configuração do servidor MCP modificado, selecione Iniciar.
Inicie uma nova janela do GitHub Copilot Chat. Você deverá conseguir ver as avaliações de restaurantes, bem como criar novos restaurantes e novas avaliações no agente do Copilot.

Melhores práticas de segurança

Quando o servidor MCP for chamado por um agente alimentado por LLM (grandes modelos de linguagem), esteja ciente dos ataques de injeção de prompt. Considere as seguintes práticas recomendadas de segurança:

Autenticação e autorização: proteja seu servidor MCP com a autenticação do Microsoft Entra para garantir que somente usuários ou agentes autorizados possam acessar suas ferramentas. Confira Chamadas do protocolo de contexto de modelo seguro para o Serviço de Aplicativo do Azure a partir do Visual Studio Code com autenticação do Microsoft Entra para um guia passo a passo.
Validação e sanitização de entrada: sempre valide os dados de entrada para evitar entradas inválidas ou mal-intencionadas. Para aplicativos Python, use bibliotecas como Pydantic para impor regras de validação de dados com modelos de entrada dedicados (como RestaurantCreate e ReviewCreate). Consulte a documentação deles para obter melhores práticas e detalhes de implementação.
HTTPS: o exemplo depende do Serviço de Aplicativo do Azure, que impõe HTTPS por padrão e fornece certificados TLS/SSL gratuitos para criptografar dados em trânsito.
Princípio do privilégio mínimo: exponha apenas as ferramentas e os dados necessários para seu caso de uso. Evite expor operações confidenciais, a menos que seja necessário.
Limitação de taxa e limitação: use o Gerenciamento de API ou middleware personalizado para evitar ataques de abuso e negação de serviço.
Registro em log e monitoramento: acesso de log e uso de pontos de extremidade MCP para auditoria e detecção de anomalias. Monitore atividades suspeitas.
Configuração do CORS Configuration: restrinja solicitações entre origens a domínios confiáveis se o servidor MCP for acessado de navegadores. Para obter mais informações, consulte Habilitar CORS.
Atualizações regulares: mantenha suas dependências atualizadas para atenuar vulnerabilidades conhecidas.

Mais recursos

Integrar a IA aos seus aplicativos do Serviço de Aplicativo do Azure

Comentários

Esta página foi útil?

Last updated on 2025-11-21