Students Architecture MCP Server

Архитектура студентов

Пример проекта, реализующего REST API и интерфейс MCP для управления студентами.

Автор: Магистр Фелипе Буйтраго Кармона

Аффилиация: Департамент систем и информатики, Факультет искусственного интеллекта и инженерии, Университет Кальдас

Описание:

• Многоуровневая архитектура: presentation (REST + MCP), business (сервис), data (репозитории), models (DTO и сущности).

• Поддержка сохранения данных в JSON и SQLite с динамическим выбором через .env.

Требования

• Python 3.12+ (рекомендуется виртуальное окружение)

• Зависимости, перечисленные в requirements.txt.

Быстрая установка

1. Создать и активировать виртуальное окружение:

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

2. Установить зависимости:

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) и видите TypeError, связанный с loop_factory, запуск содержит совместимость для asyncio.run в main_api_rest_server.py.

• Pydantic выдает предупреждение при использовании orm_mode в версии v2; рекомендуется использовать from_attributes при миграции на Pydantic v2.

Конфигурация 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
  }
}

Контакты Магистр Фелипе Буйтраго Кармона felipe.buitrago@ucaldas.edu.co Департамент систем и информатики Университет Кальдас