MCP 워크숍

이 프로젝트는 The Developers Life Weekend 이벤트의 워크숍 기간 동안 우무아라마(PR)에서 (온라인으로) 개발되었습니다.

워크숍 소개

Model Context Protocol (MCP) 기반의 첫 번째 서버를 구축하기 위한 단계별 가이드, 소스 코드 및 연습 문제가 포함된 저장소입니다.

워크숍에서는 다음 내용이 소개되었습니다:

• MCP 프로토콜의 클라이언트-서버 아키텍처;

• LLM을 위한 도구(tools)의 생성 및 노출;

• 리소스(resources) 및 동적 프롬프트 관리;

• 서버를 실제 AI 클라이언트에 연결하는 방법.

주요 프로젝트는 Python과 FastMCP로 제작되었습니다. 날씨 예보를 조회하기 위한 도구와 리소스를 제공하며, 초대장을 보내기 전에 확인을 요청하는 작업을 시연합니다.

Related MCP server: Weather MCP Server

요구 사항

• Python 3.14 이상;

• uv 설치;

• Auth0에 구성된 애플리케이션;

• https://wttr.in 조회를 위한 인터넷 접속;

• OpenCode 또는 MCP Inspector와 같은 호환 MCP 클라이언트.

이 프로젝트는 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를 엽니다.

사용 가능한 기능

Tools

• Tempo(cidade): 도시의 현재 날씨를 조회합니다;

• Temperatura(cidade): 도시의 현재 온도를 조회합니다;

• Enviar_Convites(quantidade): 확인을 요청하고 각 항목의 진행 상황을 보고하며 전송을 시뮬레이션합니다.

기상 조회는 wttr.in/<cidade>?format=%t를 사용합니다.

Resources

• workshop://oque-o-mcp-nao-e: MCP에 대한 소개 텍스트;

• previsao://{cidade}: URI에 지정된 도시의 예보.

Prompt

• 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의 Debug 모드 또는 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 프로토콜 사양