Students Architecture

学生を管理するためのREST APIおよびMCPインターフェースを実装したサンプルプロジェクト。

著者: MsC Felipe Buitrago Carmona

所属: カルダス大学、人工知能・工学部、システム・情報学科

説明:

レイヤードアーキテクチャ: 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をインストールし、左下のユーザー名が表示されている箇所から 設定 セクションへ移動し、デベロッパー セクションの 設定を編集 を選択して、以下の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 カルダス大学システム・情報学科