Воркшоп MCP

Этот проект был разработан во время воркшопа мероприятия The Developers Life Weekend, в Умуараме - PR (онлайн).

О воркшопе

Репозиторий с пошаговым руководством, исходным кодом и упражнениями для создания вашего первого сервера на основе Model Context Protocol (MCP).

Во время воркшопа были представлены:

• Клиент-серверная архитектура протокола MCP;

• Создание и предоставление инструментов (tools) для LLM;

• Управление ресурсами (resources) и динамическими промптами;

• Подключение сервера к реальным ИИ-клиентам.

Основной проект создан на Python и FastMCP. Он предоставляет инструменты и ресурсы для получения прогноза погоды и демонстрирует операцию, которая запрашивает подтверждение перед отправкой приглашений.

Related MCP server: Weather MCP Server

Требования

• Python 3.14 или выше;

• установленный uv;

• приложение, настроенное в Auth0;

• доступ к интернету для запросов к https://wttr.in;

• совместимый MCP-клиент, например OpenCode или MCP Inspector.

Проект использует uv.lock для воспроизводимых версий зависимостей.

Установка

Клонируйте репозиторий и перейдите в папку проекта:

git clone https://github.com/marcelomarkus/tdlw-workshop-mcp.git
cd tdlw-workshop-mcp

Синхронизируйте зависимости. Команда автоматически создаёт или обновляет виртуальное окружение .venv:

uv sync

Проверьте выбранную версию Python:

python --version
uv python find

Настройка Auth0

Основной сервер использует Auth0Provider и требует следующие переменные окружения:

Создайте локальный файл конфигурации из шаблона:

cp .env_example .env

Заполните .env реальными значениями:

AUTH_DOMAIN=https://seu-dominio.auth0.com
CLIENT_ID=seu-client-id
CLIENT_SECRET=seu-client-secret
AUDIENCE=https://sua-api

Файл .env не загружается автоматически Python. Экспортируйте переменные перед запуском сервера:

set -a
source .env
set +a

Или задайте их непосредственно в том же вызове:

AUTH_DOMAIN="https://seu-dominio.auth0.com" \
CLIENT_ID="seu-client-id" \
CLIENT_SECRET="seu-client-secret" \
AUDIENCE="https://sua-api" \
uv run main.py

Никогда не делитесь CLIENT_SECRET и не включайте его в коммиты.

Запуск сервера

С загруженными переменными запустите основной сервер:

uv run main.py

MCP-эндпоинт доступен по адресу:

http://127.0.0.1:8000/mcp

Держите процесс запущенным, пока подключён MCP-клиент. Чтобы завершить его, нажмите Ctrl+C.

Запуск MCP Inspector

MCP Inspector предоставляет веб-интерфейс для тестирования tools, resources и prompts.

В первом терминале запустите сервер:

set -a
source .env
set +a
uv run main.py

В другом терминале запустите Inspector:

npx @modelcontextprotocol/inspector

Откройте http://localhost:6274 в браузере и настройте:

Нажмите Connect и протестируйте доступные инструменты и ресурсы. Переменные Auth0 должны быть в окружении процесса сервера.

Подключение через OpenCode

Файл opencode.json уже указывает на локальный эндпоинт:

{
  "mcp": {
    "Workshop": {
      "type": "remote",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

При запущенном сервере откройте OpenCode в этом проекте.

Доступные функции

Инструменты

• Tempo(cidade): запрашивает текущую погоду в городе;

• Temperatura(cidade): запрашивает текущую температуру в городе;

• Enviar_Convites(quantidade): запрашивает подтверждение и имитирует отправку, сообщая о прогрессе каждого элемента.

Метеорологические запросы используют wttr.in/<cidade>?format=%t.

Ресурсы

• workshop://oque-o-mcp-nao-e: вводный текст о MCP;

• previsao://{cidade}: прогноз для города, указанного в URI.

Промпт

• exemplo_prompt(pergunta): помогает выбрать между метеорологическими tools.

Структура проекта

.
├── main.py          # Servidor MCP principal
├── mcp_com_api.py   # Servidor MCP gerado a partir da API Petstore
├── exercises/       # Exercícios progressivos do workshop
│   ├── 01-mcp-server/
│   ├── 02-resources/
│   ├── 03-tools/
│   ├── 04-prompts/
│   ├── 05-Context/
│   ├── 06-auth/
│   └── 07-mcp-api/
├── slide/            # Material de apoio
│   └── TDLW-Umuarama.pdf
├── opencode.json    # Configuração do OpenCode
├── pyproject.toml   # Metadados e dependências
├── uv.lock          # Versões resolvidas
└── .env_example     # Modelo das variáveis do Auth0

Разработка

Вы можете запустить проект через режим отладки VS Code или через uv:

uv run main.py

Для проверки синтаксиса модулей:

python -m compileall main.py mcp_com_api.py exercises

Устранение неполадок

ModuleNotFoundError

Выполните uv sync и запустите программу с помощью uv run main.py, избегая глобального Python, если зависимости установлены только в .venv.

Ошибки аутентификации

Проверьте, что четыре переменные Auth0 экспортированы в том же окружении, что и сервер, и что домен включает ожидаемый протокол.

Сбой метеорологического запроса

Проверьте подключение с помощью:

curl "https://wttr.in/Sao%20Paulo?format=%t"

Порт 8000 занят

Освободите порт или измените порт на сервере и в opencode.json, сохраняя один и тот же адрес с обеих сторон.

Документация и ссылки

• Официальная документация uv

• Официальная документация HTTPX

• Официальная документация FastMCP

• Официальный репозиторий MCP SDK для Python

• Официальная документация MCP

• Спецификация протокола MCP