MCP 工作坊

本项目是在 The Developers Life Weekend 活动的工作坊期间开发的，活动地点位于乌穆阿拉马 - 巴拉那州（线上）。

关于工作坊

本仓库包含分步指南、源代码和练习，用于构建您第一个基于 模型上下文协议（MCP） 的服务器。

在工作坊期间，我们介绍了：

• MCP 协议的客户端-服务器架构；

• 为 LLM 创建和暴露工具（tools）；

• 资源（resources）和动态提示词的管理；

• 将服务器连接到真实 AI 客户端。

主项目使用 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 提供了一个 Web 界面，用于测试工具、资源和提示词。

在第一个终端中，启动服务器：

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)：指导在天气工具之间进行选择。

项目结构

.
├── 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 运行程序，避免在依赖仅安装在 .venv 中时使用全局 Python。

认证错误

检查四个 Auth0 变量是否已在服务器同一环境中导出，以及域名是否包含预期的协议。

天气查询失败

测试连接性：

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

8000 端口被占用

释放端口或在服务器和 opencode.json 中调整端口，保持两端地址一致。

文档和参考

• uv 官方文档

• HTTPX 官方文档

• FastMCP 官方文档

• Python 版 MCP SDK 官方仓库

• MCP 官方文档

• MCP 协议规范