MCP Server

# Tarefas de Implementação do Servidor MCP Este ficheiro detalha as tarefas passo-a-passo para a implementação do servidor MCP, destinado a ser seguido por uma IA. Assume-se o uso de Python e FastAPI conforme definido no `planning.md`. ## Fase 1: Configuração do Projeto e API Básica 1. **[ ] Criar Estrutura do Projeto:** * Criar diretório raiz do projeto. * Inicializar ambiente virtual Python: `python -m venv venv` * Ativar ambiente virtual: `source venv/bin/activate` (Linux/macOS) ou `venv\Scripts\activate` (Windows). 2. **[ ] Instalar Dependências Iniciais:** * `pip install fastapi uvicorn[standard] python-dotenv` * Criar `requirements.txt`: `pip freeze > requirements.txt` 3. **[ ] Criar Ficheiro Principal da API (`main.py`):** * Importar `FastAPI`. * Instanciar a app: `app = FastAPI()` * Criar um endpoint de health check `/health`: ```python @app.get("/health") async def health_check(): return {"status": "ok"} ``` 4. **[ ] Definir Endpoint Principal (`/generate_mcp`):** * Criar um endpoint `GET /generate_mcp`: ```python from fastapi import Query, HTTPException @app.get("/generate_mcp") async def generate_mcp_endpoint(topic: str = Query(..., min_length=3)): # Placeholder: Retornar dados estáticos por agora print(f"Received request for topic: {topic}") # TODO: Implementar lógica de geração # Temporariamente, retornar uma resposta simples ou o JSON exemplo (hardcoded) return {"message": "MCP generation in progress for topic", "topic": topic} ``` 5. **[ ] Configurar Uvicorn para Execução Local:** * Executar o servidor localmente: `uvicorn main:app --reload` * Testar os endpoints `/health` e `/generate_mcp?topic=teste` no browser ou com `curl`. 6. **[ ] Definir Modelos Pydantic (Schema JSON):** * Criar um ficheiro `schemas.py`. * Definir modelos Pydantic que espelhem **exatamente** a estrutura JSON fornecida no pedido inicial (incluindo `MCP`, `Node`, `Resource`, `Metadata`, `Quiz`, `Question`, etc.). Aninhar os modelos conforme necessário. * Atualizar o endpoint `/generate_mcp` para usar o modelo `MCP` como `response_model`. ## Fase 2: Implementação do Content Sourcing Module 1. **[ ] Criar Módulo `content_sourcing.py`:** * Criar um ficheiro `content_sourcing.py`. * Definir uma função principal, e.g., `find_resources(topic: str) -> list[schemas.Resource]`. 2. **[ ] Integrar API de Busca (Exemplo: DuckDuckGo):** * Instalar biblioteca: `pip install -U duckduckgo_search` * Implementar função para buscar diferentes tipos de conteúdo usando `ddg` ou similar. Exemplo: ```python from duckduckgo_search import DDGS def search_web(query: str, max_results: int = 5): results = [] with DDGS() as ddgs: for r in ddgs.text(query, max_results=max_results): results.append({"title": r.get('title'), "url": r.get('href')}) # Simplificado return results ``` * Na função `find_resources`, chamar `search_web` com queries variadas (e.g., "`{topic}` tutorial", "`{topic}` documentation", "`{topic}` exercises", "`{topic}` video"). * Mapear os resultados para o modelo `schemas.Resource`, definindo o `type` com base na query ou análise simples da URL/título (e.g., se 'youtube.com' na URL, type='video'). Definir valores default para campos como `duration`, `readTime`, `difficulty`. 3. **[ ] Implementar Web Scraping Básico (Opcional, mas Recomendado):** * Instalar bibliotecas: `pip install requests beautifulsoup4 lxml` * Identificar 1-2 sites *confiáveis* e *estáveis* relevantes para muitos tópicos de programação (e.g., `flutter.dev/docs`, `developer.mozilla.org`). * Criar funções específicas de scraping para esses sites (e.g., `scrape_flutter_docs(topic)`). * Usar `requests` para obter o HTML e `BeautifulSoup` para extrair títulos, links e talvez descrições de secções relevantes. * **Importante:** Incluir `User-Agent` nos headers do `requests`. Respeitar `robots.txt` (requer biblioteca adicional ou verificação manual). Implementar tratamento de erros (timeouts, erros HTTP). * Adicionar os resultados do scraping à lista de recursos encontrados. 4. **[ ] Unificar e Limpar Recursos:** * Na função `find_resources`, agregar resultados de todas as fontes (busca, scraping). * Remover duplicados (baseado na URL). * Limitar o número total de recursos para evitar sobrecarga. * Retornar a lista final de `schemas.Resource`. 5. **[ ] Integrar com API Principal:** * No `main.py`, importar e chamar `content_sourcing.find_resources(topic)` dentro do endpoint `/generate_mcp`. * Por agora, retornar a lista de recursos encontrados como parte da resposta JSON para teste. ## Fase 3: Implementação do Path Generation Module 1. **[ ] Criar Módulo `path_generator.py`:** * Criar um ficheiro `path_generator.py`. * Definir uma função principal, e.g., `generate_learning_path(topic: str, resources: list[schemas.Resource]) -> schemas.MCP`. 2. **[ ] Implementar Lógica de Estruturação (Heurística Simples V1):** * Dentro de `generate_learning_path`: * **Criar Metadados Globais:** Gerar `id` (e.g., `topic.lower().replace(' ', '_')`), `title` (e.g., `f"Fundamentos de {topic.title()}"`), `description`, `metadata` (com valores default/estimados para `difficulty`, `estimatedHours`, `tags`). * **Agrupar Recursos:** Tentar agrupar recursos por palavras-chave no título/descrição (e.g., "introdução", "básico", "widgets", "avançado", "projeto", "exercício", "quiz"). Criar categorias simples. * **Criar Nós (`nodes`):** Para cada categoria/grupo, criar um `schemas.Node`. * Gerar `id` único para cada nó (e.g., `intro_{topic_id}`). * Definir `title` e `description` para o nó. * Atribuir os `resources` correspondentes a este nó. * Definir o `type` do nó (e.g., 'lesson', 'exercise_set', 'project_idea'). Se encontrar recursos tipo 'exercise', pode criar um nó 'lesson' com esses exercícios, ou um nó 'quiz' placeholder. * Definir `state` como 'available' por default. * Definir `visualPosition` com valores placeholder (e.g., `{"x": 0, "y": level, "level": level}`). * **Definir Pré-requisitos (`prerequisites`):** Estabelecer uma sequência linear simples. O nó 2 requer o nó 1, o nó 3 requer o nó 2, etc. O primeiro nó (root) tem `prerequisites` vazio. Atribuir o `id` do primeiro nó ao `rootNodeId` do MCP. * **Gerar Quizzes Placeholder:** Se a lógica identificar um ponto adequado (e.g., após um conjunto de lições), criar um nó do tipo `quiz` com título, descrição, mas sem `questions` detalhadas (lista vazia ou com 1-2 perguntas placeholder). Definir `passingScore` default. * **Gerar Projeto Placeholder:** Adicionar um nó final do tipo `project` se apropriado, com descrição do que se espera. 3. **[ ] Construir Objeto MCP:** * Montar o objeto `schemas.MCP` completo com todos os metadados, `rootNodeId`, e o dicionário `nodes`. * Retornar o objeto `MCP`. 4. **[ ] Integrar com API Principal:** * No `main.py`, após obter os `resources`, chamar `path_generator.generate_learning_path(topic, resources)`. * Retornar o objeto `MCP` resultante como resposta do endpoint `/generate_mcp`. Utilizar `response_model=schemas.MCP` para garantir a formatação correta. ## Fase 4: Refinamento, Tratamento de Erros e Logging 1. **[ ] Implementar Tratamento de Erros:** * No `content_sourcing`: Adicionar `try...except` blocos para falhas de rede, erros de parsing, limites de API. Retornar lista vazia ou levantar exceções customizadas. * No `path_generator`: Lidar com o caso de não haver recursos suficientes para gerar um caminho significativo. * No `main.py`: Usar `try...except` para capturar exceções dos módulos e retornar `HTTPException` do FastAPI com status codes apropriados (e.g., 404 se nenhum recurso encontrado, 500 para erros internos). 2. **[ ] Adicionar Logging Básico:** * Instalar `loguru` (opcional, mas bom): `pip install loguru` * Configurar logging básico no `main.py` para registar pedidos recebidos, tópicos, número de recursos encontrados, e quaisquer erros. 3. **[ ] Limpeza e Comentários:** * Rever todo o código. Adicionar type hints em todas as funções. * Adicionar comentários explicando a lógica complexa, especialmente nas heurísticas de sourcing e path generation. * Garantir que os nomes das variáveis e funções são claros. 4. **[ ] Testar Exaustivamente:** * Testar com vários tópicos (comuns, específicos, obscuros). * Verificar se o JSON de saída é sempre válido e corresponde ao schema. * Testar casos de erro (e.g., tópico muito curto, falha na busca). ## Fase 5: Preparação para Deployment 1. **[ ] Atualizar `requirements.txt`:** * `pip freeze > requirements.txt` 2. **[ ] Configurar Variáveis de Ambiente:** * Se usar API keys, movê-las para um ficheiro `.env`. Usar `python-dotenv` para carregá-las localmente. `pip install python-dotenv`. * No código, aceder às keys via `os.getenv("API_KEY_NAME")`. * **NUNCA** commitar o ficheiro `.env` ou as keys diretamente no código. Adicionar `.env` ao `.gitignore`. 3. **[ ] (Opcional, Recomendado para Fly.io) Criar `Dockerfile`:** * Criar um `Dockerfile` básico para a aplicação Python/FastAPI. Exemplo: ```dockerfile FROM python:3.9-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . # PORT é geralmente fornecido pelo ambiente de alojamento ENV PORT=8080 EXPOSE 8080 CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"] ``` 4. **[ ] Adicionar `Procfile` (Para Heroku/Render sem Docker):** * Criar ficheiro `Procfile` (sem extensão) na raiz: ``` web: uvicorn main:app --host 0.0.0.0 --port $PORT ``` ## Fase 6: Deployment no Provedor Gratuito 1. **[ ] Escolher Provedor:** Selecionar Render.com, Fly.io, ou outro. 2. **[ ] Criar Conta e Configurar Aplicação:** * Seguir a documentação do provedor escolhido para criar um novo "Web Service" (Render) ou "App" (Fly.io). * Ligar ao repositório Git. * Configurar o ambiente (Python, ou Docker se usar Dockerfile). * Definir comandos de build e start (ver Fase 5). * Configurar variáveis de ambiente necessárias (e.g., API keys) na interface do provedor. 3. **[ ] Realizar o Deploy:** Iniciar o processo de build e deploy. 4. **[ ] Testar Endpoint Público:** Aceder à URL fornecida pelo provedor (e.g., `https://<app-name>.onrender.com/generate_mcp?topic=flutter`) e verificar a resposta. 5. **[ ] Monitorizar:** Observar logs e métricas de uso para garantir que se mantém dentro dos limites do free tier.