学生架构 (Students Architecture)

一个实现 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

在 json 和 sqlite 之间更改 REPO_TYPE 即可选择持久化实现方式。

注意：更改 .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 的兼容性处理。
如果在 v2 版本中使用 orm_mode，Pydantic 会显示警告；建议在迁移到 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)