MCP와 Skill 실습 자료

기본 경로는 업무 기록 조회 MCP → 팀 주간 보고서 Skill입니다. Google credential이나 Colab 연결 토큰은 포함하지 않습니다.

기본 실습 파일

1. 업무 기록 조회

압축을 푼 폴더는 uv 프로젝트로 준비되어 있습니다. .python-version은 Python 3.13을 선택하며, pyproject.toml과 uv.lock으로 MCP SDK 2.1.1 및 필요한 패키지를 준비합니다. Claude Code 또는 OpenCode로 이 폴더를 열고 먼저 요청합니다.

이 폴더를 uv로 실행할 수 있게 준비해 줘. Python과 패키지 버전도 확인하자.

uv가 없다면 공식 설치 안내를 먼저 따릅니다. 압축을 푼 폴더에서 실행합니다.

uv sync --locked
uv run --locked python --version
uv run --locked python -c "import sys; from importlib.metadata import version; print(sys.executable); print(version('mcp'))"

uv sync는 이 프로젝트의 .venv를 준비하고 잠금 파일에 맞춰 패키지를 설치합니다. --locked는 프로젝트 설정과 잠금 파일이 어긋나면 자동으로 잠금 파일을 바꾸지 않고 알려 줍니다. uv run은 준비한 프로젝트 환경에서 명령을 실행하므로 가상환경 활성화가 필요하지 않습니다. 이미 프로젝트 파일이 있으므로 uv init을 다시 실행하지 않습니다.

그다음 MCP 연결을 요청합니다.

이 폴더의 업무 기록 서버를 uv로 실행하는 MCP로 연결해 줘. 첫 주 기록이 나오는지 확인하자.

서버 이름은 weekly-records, 도구는 get_weekly_records, 입력은 {"week": "week-one"}입니다. 반환값의 records에 4건이 있는지 확인합니다. 이 서버는 원래 기록만 읽습니다. ‘개발 완료’를 팀 보고서의 ‘완료’로 판단하는 일은 서버 코드에 넣지 않았습니다.

아래는 uv로 위 환경 준비를 마친 상태입니다. /압축을/푼/실제폴더를 실제 절대 경로로 바꿉니다. 이미 등록된 다른 서버 설정은 유지합니다.

Claude Code

claude mcp add --transport stdio --scope project weekly-records -- uv --directory "/압축을/푼/실제폴더" run --locked mcp run weekly_records_server.py --transport stdio

OpenCode V1 — opencode.json 또는 opencode.jsonc의 기존 mcp 안에 추가합니다.

{
  "mcp": {
    "weekly-records": {
      "type": "local",
      "command": ["uv", "--directory", "/압축을/푼/실제폴더", "run", "--locked", "mcp", "run", "weekly_records_server.py", "--transport", "stdio"],
      "enabled": true
    }
  }
}

OpenCode V2는 위 weekly-records 객체를 mcp.servers 아래에 넣고 enabled를 제거합니다. type과 command 배열은 유지합니다. V2의 disabled 기본값은 false, codemode 기본값은 true입니다. V2 공식 등록 안내를 함께 확인합니다.

호스트가 설정을 다시 읽게 한 뒤 연결 상태와 호출을 확인합니다. Python 환경은 호스트가 실행한 환경과 같아야 합니다.

2. 실제 보고서에서 필요한 규칙 찾기

Skill 설치 전 첫 주 기록과 team-weekly-report/references/team-rules.md를 일반 자료로 제공해 보고서를 요청합니다. 먼저 학생이 기록과 팀 규칙을 읽고 업무의 분류를 판단한 뒤, AI의 초안과 비교합니다. 개발이 끝난 일과 배포·운영 확인까지 끝난 일, 보고 기준일과 기한이 같은 일을 구분해 봅니다.

잘못된 부분이 있다면 원본과 규칙을 근거로 수정합니다. 처음부터 정확하면 어떤 기준이 적용됐는지 확인합니다. 첫 보고서는 first-week-report.md, 판단 근거와 수정 이유는 report-work-notes.md 같은 파일에 남길 수 있습니다. 특정 주의 정답과 다음 주에도 쓸 팀 기준을 구분해 봅니다.

3. 규칙을 Skill로 재사용

team-weekly-report는 참고할 완성 예제입니다. 팀 규칙을 직접 바꿨다면 그 기준으로 자신의 Skill을 만들고 예제와 비교합니다.

방금 사용한 팀 보고 기준을 스킬로 만들어 줘. 다음 주에도 같은 방식으로 쓰고 싶어.

Skill을 설치할 때는 SKILL.md 하나만 옮기지 말고 폴더 전체를 복사합니다. 본문에서 사용하는 references/team-rules.md도 필요합니다.

• Claude Code 프로젝트: .claude/skills/team-weekly-report/

• OpenCode 프로젝트: .opencode/skills/team-weekly-report/

위 폴더 안에 SKILL.md와 references/team-rules.md가 있도록 복사합니다. 두 호스트를 함께 쓴다면 OpenCode가 지원하는 .claude/skills 경로를 공유할 수도 있습니다. 설치 후 새 대화를 시작합니다.

Claude Code에서는 /team-weekly-report로 명시 호출할 수 있습니다. OpenCode에서는 “team-weekly-report 스킬로 둘째 주 보고서를 작성해 줘”라고 요청할 수 있습니다. 자연어 자동 선택을 관찰할 때에는 스킬 이름을 생략해 봅니다.

공식 안내: Agent Skills 형식, Claude Code Skills, OpenCode Skills.

새 대화에서 요청합니다.

둘째 주 팀 진행 보고서를 작성해 줘.

실제 Skill·팀 규칙 파일 로드, week-two 조회, 작성 결과를 확인합니다. MCP 없이도 data/week-two.json의 로컬 파일 경로를 주면 같은 보고서를 만들 수 있습니다. Skill이 MCP 연결에 종속되지 않는다는 것을 비교할 수 있습니다. 사용한 호스트에서 로드 기록을 볼 수 없으면 관찰하지 못한 것으로 표시합니다.

report-checks.md를 보고 분류와 건수를 대조합니다. 둘째 주에는 배포했지만 검증을 기다리는 일과, 첫 주 이후 실제로 완료된 일이 있습니다. 첫 주 답변을 복사하는 대신 새 기록에 같은 기준을 적용해야 합니다.

기본 산출물

업무 조회 도구의 실제 입력·결과 한 건, 자신이 만든 SKILL.md와 사용한 팀 규칙, 첫째·둘째 주 Markdown 보고서, Skill 인식과 분류 결과의 관찰 기록을 남깁니다. 서버 구현을 직접 했다면 weekly_records_server.py와 데이터 파일도 함께 제출합니다. 인증 정보는 제출하지 않습니다.

Related MCP server: WeDaka MCP Server

프로젝트 설정과 추가 의존성

pyproject.toml이 설치 요구 사항의 기준이며 uv.lock은 그 요구 사항을 만족하는 직접·간접 패키지 버전을 기록합니다. .python-version의 3.13은 기본 실행 버전이고 requires-python = ">=3.10"은 코드가 허용하는 범위입니다. 잠금 파일은 패키지 버전을 고정하며 Python의 패치 버전까지 고정하지는 않습니다.

Google 실습에서는 uv sync --locked --extra google로 같은 환경에 추가 패키지를 준비합니다. Google 프로그램을 실행할 때에도 uv run --locked --extra google ...처럼 해당 묶음을 명시합니다. 자세한 인증 절차와 MCP 등록은 GOOGLE_AUTH_README.md를 따릅니다. Colab MCP는 별도 공개 프로그램이므로 교안의 uvx 경로를 사용하며 이 프로젝트의 기본 의존성에 넣지 않았습니다.

기존 requirements.txt와 requirements-google.txt는 이전 pip 방식의 직접 의존성 목록을 참고할 수 있도록 보관했습니다. 현재 실습은 uv 프로젝트 경로로 진행합니다. 학생이 기능을 추가해 의존성을 바꿀 때에는 AI에게 pyproject.toml과 uv.lock도 함께 갱신하도록 요청합니다. .venv와 캐시는 공유하지 않고 프로젝트 파일과 잠금 파일을 함께 전달합니다.