учебный чат ассистент с mock mcp

что внутри

• backend на fastapi
• mock mcp service на fastapi
• jwt auth для rest и websocket
• postgresql через sqlalchemy
• alembic миграции
• хранение чатов и сообщений
• file artifact через отдельное сообщение
• suggested actions через отдельное websocket событие
• trace_id на один agent flow
• простой websocket test client
• pytest тесты без реального llm

быстрый запуск через docker compose

make docker-up

backend будет доступен на http://localhost:8000

swagger будет доступен на http://localhost:8000/docs

mock mcp будет доступен на http://localhost:8001

демо пользователь из миграции

email: demo@example.test
password: demo12345

демо пользователь, демо чат и демо сообщение создаются в alembic миграции 202604290001_initial_schema_and_demo.py

локальный запуск без docker

создай базу postgresql и экспортируй переменные окружения

export DATABASE_URL=postgresql+psycopg://chat:chat@localhost:5432/chat_assistant
export JWT_SECRET=dev-secret-change-me
export MCP_BASE_URL=http://localhost:8001

установи зависимости

make install

примени миграции

make migrate

запусти mock mcp

make run-mcp

в другом терминале запусти backend

make run-backend

make команды

make install
make migrate
make run-backend
make run-mcp
make test
make up
make down
make docker-ws

rest api

post /api/auth/register
post /api/auth/login
get /api/chats
post /api/chats
get /api/chats/{chat_id}
get /api/chats/{chat_id}/messages
get /api/chats/{chat_id}/messages/{message_id}/download

для rest ручек кроме register и login нужен header

authorization: bearer <token>

websocket api

ws /api/chats/{chat_id}/ws?token=<jwt>

сообщение клиента

{
  "content": "привет",
  "scenario": "get_case_summary"
}

события сервера

user_message
assistant_message
tool_message
file_message
suggested
system_event

сценарии fake llm

plain
get_case_summary
calculate_case_score
generate_case_file
suggest_next_steps
unknown_tool
timeout_tool_call
invalid_file_artifact
too_long_tool_loop

ручная проверка через curl

регистрация

curl -s -X POST http://localhost:8000/api/auth/register \
  -H 'content-type: application/json' \
  -d '{"email":"student@example.test","password":"secret123","name":"студент"}'

логин демо пользователя

curl -s -X POST http://localhost:8000/api/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"demo@example.test","password":"demo12345"}'

создание чата

curl -s -X POST http://localhost:8000/api/chats \
  -H 'authorization: bearer <token>' \
  -H 'content-type: application/json' \
  -d '{"title":"проверка","scenario":"generate_case_file"}'

получение сообщений

curl -s http://localhost:8000/api/chats/<chat_id>/messages \
  -H 'authorization: bearer <token>'

websocket test client

python scripts/ws_client.py --scenario get_case_summary
python scripts/ws_client.py --scenario generate_case_file
python scripts/ws_client.py --scenario suggest_next_steps

клиент логинится демо пользователем, создает чат если --chat-id не передан и печатает события до assistant_message

10 сценариев ручной проверки

1. register нового пользователя через /api/auth/register
2. login созданного пользователя через /api/auth/login
3. создать чат со сценарием plain
4. открыть websocket и получить user_message плюс assistant_message
5. создать чат со сценарием get_case_summary и получить tool_message
6. создать чат со сценарием generate_case_file и получить file_message
7. скачать file artifact через /download
8. создать чат со сценарием suggest_next_steps и получить отдельное событие suggested
9. подключиться к websocket без token и получить отказ подключения
10. создать чат одним пользователем и попробовать прочитать его вторым пользователем, должен вернуться 404

flow схема

user -> websocket /api/chats/{chat_id}/ws -> agent-service -> fake llm -> mock mcp /tools -> mock mcp /call_tool -> messages table -> websocket events -> frontend client

как устроен agent flow

1. websocket проверяет jwt token и владельца чата
2. user message сохраняется в messages
3. agent-service создает trace_id
4. agent-service загружает tools из mock mcp service
5. fake llm выбирает обычный ответ или tool call
6. agent-service вызывает mock mcp через /call_tool
7. результат tool сохраняется как tool, file или используется для события suggested
8. assistant message сохраняется в историю
9. websocket отправляет события клиенту
10. tool loop останавливается по MAX_TOOL_ITERATIONS

тесты

make test

покрыты auth, chats, websocket, tool call, file artifact, suggested actions, чужие чаты, отсутствие websocket token, unknown tool, timeout tool call, invalid file artifact и слишком длинный tool loop