MCP 작업 서버

프로그래밍 IV 과제 1 프로젝트입니다. 로컬 JSON 파일에서 작업을 관리하는 Model Context Protocol(MCP) 서버를 구현하며, 리소스 하나, 도구 두 개, 프롬프트 하나를 제공합니다.

기능

• Resource tasks://pending: 완료되지 않은 작업만 반환합니다.

• Tool add_task: 이름, 설명, 우선순위(alta, media 또는 baja)로 작업을 추가합니다.

• Tool complete_task: ID로 기존 작업을 완료 처리합니다.

• Prompt daily_summary: 현재 상태를 바탕으로 일일 요약을 생성하기 위한 템플릿을 구성합니다.

서버는 stdio 전송 방식을 사용합니다. 호스트 또는 클라이언트가 서버를 하위 프로세스로 시작하며, MCP 메시지는 stdin과 stdout을 통해 전송됩니다.

Related MCP server: TaskTrek MCP Server

요구 사항

• Python 3.11 이상.

• 터미널 접근.

• Claude Desktop, MCP Inspector 또는 호환되는 MCP 클라이언트.

설치

Windows(PowerShell)

cd C:\RUTA\mcp-todo-server
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

macOS 또는 Linux

cd /RUTA/mcp-todo-server
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

실행

stdio 서버는 클라이언트가 첫 번째 메시지를 보내기를 기다립니다. 따라서 직접 실행하면 메뉴가 출력되지 않고 포트도 열리지 않습니다:

python server.py

Ctrl+C를 눌러 중지합니다.

데모 클라이언트

client_demo.py는 공식 SDK로 구축된 호환 MCP 클라이언트입니다. stdio로 연결하여 기능을 탐색하고 요청된 모든 작업을 실행합니다:

python client_demo.py --reset

UTF-8 기록을 저장하려면:

python client_demo.py --reset --output evidence/client_demo_output.txt

--reset 옵션은 테스트 전에 초기 레코드 두 개를 복원합니다. 데모는 Resource를 조회하고, 작업 두 개를 추가하고, 하나를 완료하고, Prompt를 가져온 다음 Resource를 다시 조회합니다.

자동화된 테스트

python -m pytest -q

테스트 스위트는 다음을 확인합니다:

1. Resource, Tools 및 Prompt 검색.

2. 완료되지 않은 작업만 읽기.

3. 작업 생성 및 완료.

4. daily_summary의 동적 콘텐츠.

5. 존재하지 않는 ID 완료 시 오류 처리.

MCP Inspector

Node.js가 설치된 상태에서 공식 인터페이스를 열 수 있습니다:

npx @modelcontextprotocol/inspector .venv/Scripts/python.exe server.py

macOS 또는 Linux에서는 실행 파일을 .venv/bin/python으로 변경하세요.

Claude Desktop 설정

1. claude_desktop_config.example.json을 엽니다.

2. C:\\RUTA\\mcp-todo-server를 프로젝트의 절대 경로로 바꿉니다.

3. mcpServers 항목을 Claude Desktop 설정 파일에 복사합니다. Windows에서는 일반적으로 다음 위치에 있습니다: %APPDATA%\Claude\claude_desktop_config.json.

4. Claude Desktop을 완전히 종료했다가 다시 엽니다.

예시:

{
  "mcpServers": {
    "todo-server": {
      "command": "C:\\RUTA\\mcp-todo-server\\.venv\\Scripts\\python.exe",
      "args": ["C:\\RUTA\\mcp-todo-server\\server.py"]
    }
  }
}

상대 경로를 사용하지 마세요: 호스트는 다른 디렉터리에서 서버를 시작할 수 있습니다.

구조

mcp-todo-server/
  server.py
  client_demo.py
  tasks.json
  requirements.txt
  claude_desktop_config.example.json
  tests/
    test_server.py
  diagramas/
    arquitectura_mcp_ecommerce.mmd
    flujo_consulta_inventario.mmd
  evidence/
    client_demo_output.txt
    01_inspector_connected.png
    02_add_task_result.png
    03_complete_task_result.png
    04_resource_pending.png
    05_daily_summary_prompt.png

Git 게시

git init
git add .
git commit -m "Implementar servidor MCP de tareas"
git branch -M main
git remote add origin URL_DEL_REPOSITORIO
git push -u origin main

최종 저장소 URL은 제출 전에 보고서에 추가해야 합니다.

기술 참고 자료

• MCP Python SDK

• MCP Specification

• MCP Inspector