AGENTS.md

Guidance for coding agents working on LMSSEP Chat MCP Server, the domain-driven chat backend.

Project Overview

The server combines a Python backend, MCP client integration, Gemini/Ollama provider switching, WebSocket streaming, sessions, and multi-user isolation. It follows a domain-driven layout rather than one large server file.

Key paths:

• mcp_server/README.md: architecture and usage.
• mcp_server/server.py: entrypoint.
• mcp_server/requirements.txt: dependencies.
• mcp_server/backend/shared/: config, logging, performance, and shared models.
• mcp_server/backend/chat/: REST chat, WebSocket streaming, queue, and workers.
• mcp_server/backend/mcp/: Gemini/Ollama clients, unified client, tool conversion.
• mcp_server/backend/session/: session manager and repository.
• mcp_server/backend/user/: user manager, auth service, auth routes, and repository.
• mcp_server/data/: SQLite persistence.

Setup Commands

bashcd <project-root>/mcp_server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 server.py

Use <GEMINI_API_KEY>, <OLLAMA_BASE_URL>, <MODEL_NAME>, and <SERVER_ORIGIN> placeholders in docs.

Domain Rules

• Keep chat routing and WebSocket logic in the chat domain.
• Keep MCP provider clients and tool conversion under the MCP domain.
• Keep session persistence in the session domain.
• Keep user isolation and auth under the user domain.
• Keep shared logging, config, models, and monitoring under shared.

Testing

• Test provider switching without leaking provider credentials.
• Test WebSocket streaming and request queue behavior under concurrent sessions.
• Test SQLite session and user isolation before changing repository logic.
• Test auth routes with missing, invalid, and expired credentials.

Security

• Do not commit .env, SQLite user/session databases, logs with prompts, or provider API keys.
• Do not publish local server origins or private MCP config.
• Redact chat transcripts before using them in public examples.