학생 아키텍처

학생 관리를 위한 REST API 및 MCP 인터페이스를 구현하는 예제 프로젝트입니다.

저자: MsC Felipe Buitrago Carmona

소속: 칼다스 대학교(Universidad de Caldas), 인공지능 및 공학 학부, 시스템 및 정보학과

설명:

계층형 아키텍처: presentation (REST + MCP), business (서비스), data (리포지토리), models (DTO 및 엔티티).
JSON 및 SQLite 지속성을 지원하며 .env를 통해 동적으로 선택 가능합니다.

요구 사항

Python 3.12+ (가상 환경 권장)
requirements.txt에 나열된 종속성.

빠른 설치

가상 환경 생성 및 활성화:

python -m venv venv
& venv\Scripts\Activate.ps1

종속성 설치:

pip install -r requirements.txt

구성 (.env)

루트 디렉토리에 .env 파일을 복사하거나 생성하고 다음과 같은 값을 설정합니다:

FASTMCP_STATELESS_HTTP=true
REPO_TYPE=json      # o sqlite
JSON_PATH=students.json
SQLITE_PATH=students.db
API_PORT=5000
MCP_PORT=9000

REPO_TYPE을 json과 sqlite 사이에서 변경하여 지속성 구현을 선택합니다.

참고: .env를 변경한 후에는 리포지토리 팩토리가 이를 읽을 수 있도록 서버를 재시작하십시오.

REST API 실행 (개발용)

venv\Scripts\python.exe -m uvicorn main_api_rest_server:app --reload --port 5000

MCP 서버 실행

venv\Scripts\python.exe main_mcp_server.py

주요 경로 (REST)

GET /students — 학생 목록 조회
POST /students — 학생 생성
GET /students/{id} — 학생 정보 조회
PUT /students/{id} — 업데이트
DELETE /students/{id} — 삭제

학생 생성을 위한 curl 예제:

curl -X POST http://localhost:5000/students -H "Content-Type: application/json" -d '{"name":"Ana","email":"ana@example.com","age":21,"career":"Ingenieria","semester":4}'

유용한 참고 사항

디버거(예: PyCharm)를 사용 중이고 loop_factory와 관련된 TypeError가 발생하면, main_api_rest_server.py에 asyncio.run에 대한 호환성 코드가 포함되어 있습니다.
Pydantic v2에서 orm_mode를 사용하면 경고가 표시됩니다. Pydantic v2로 마이그레이션할 때는 from_attributes를 사용하는 것이 좋습니다.

Claude Desktop 구성 Claude Desktop을 설치한 후, 왼쪽 하단 사용자 이름이 표시되는 곳으로 이동하여 설정(Configuración), 개발자(Desarrollador), 구성 편집(Editar Configuración) 섹션으로 이동한 다음 아래 JSON을 붙여넣으십시오.

{
  "mcpServers": {
    "students_architecture": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:9000/mcp",
        "--allow-http"
      ],
      "env": {
        "MCP_TRANSPORT_STRATEGY": "http-only"
      }
    }
  },
  "preferences": {
    "coworkScheduledTasksEnabled": false,
    "sidebarMode": "chat",
    "coworkWebSearchEnabled": true,
    "ccdScheduledTasksEnabled": false
  }
}

연락처 MsC Felipe Buitrago Carmona felipe.buitrago@ucaldas.edu.co 시스템 및 정보학과 칼다스 대학교(Universidad de Caldas)