EstudIA

EstudIA MCP Server provides a classroom-focused knowledge base that ingests educational documents, extracts and embeds content, performs OCR on images, and enables context-aware conversations with a student profile that updates over time. It exposes MCP tools for agents and supports an optional HTTP API for quick testing, making it practical to build intelligent classroom assistants and search-driven educational workflows.

How to use

You interact with EstudIA MCP Server through MCP-compatible clients. In practice, you load classroom documents into storage, ingest and chunk them with embeddings, and then query the system to retrieve relevant fragments during a chat with a classroom-aware assistant. The assistant references internal fragments to answer questions while keeping your student profile updated through ongoing conversations.

Key usage patterns you can follow:

• Ingest documents for a classroom and populate a searchable chunk store.
• Use semantic search to retrieve relevant chunks during chat sessions.
• Engage a contextual assistant that pulls from both the document corpus and the evolving student profile.
• Update user context automatically as conversations unfold to improve personalization over time.

How to install

Prerequisites you need before installing:
- Python (for the MCP server tools and runtime)
- Node.js/npm (for optional HTTP server tooling and build steps)
- Access to a PostgreSQL-compatible environment (via Supabase or a compatible setup)
- Environment variables for the service and Gemini integration (see environment variables section)

Step-by-step installation steps:

• Clone the project repository
• Create and activate a Python virtual environment
• Install Python dependencies
• Optionally install FastAPI/uvicorn for the HTTP API
• Prepare environment variables in a .env file
• Run the MCP server or the HTTP API to start testing

# 1) Clone the project
git clone <repo-url>
cd estudIA-MCP

# 2) Create and activate virtualenv
python -m venv .venv
# Windows
.\.venv\Scripts\Activate.ps1
# macOS/Linux
source .venv/bin/activate

# 3) Install dependencies
pip install -r requirements.txt

# 4) Optional: install HTTP API dependencies
pip install fastapi uvicorn[standard]

# 5) Create .env with required keys (see environment variables section)

Additional setup notes

Configuration and runtime details rely on environment variables and the local setup. The server exposes two primary startup modes: a standard MCP mode for agents and an optional HTTP API for quick REST testing. Ensure your Supabase instance, Gemini API key, and embedding configurations are correctly set before starting the server.

Security considerations: keep sensitive keys confidential, use secret managers in production, and avoid exposing service roles or API keys in version control.

Troubleshooting and tips

If you encounter issues, verify that all required environment variables are present in your .env file, ensure the embedding and OCR components are reachable, and confirm the RPCs for chunk matching are available in your Supabase setup.

Common issues and quick checks:

• Missing variables -> review the environment variable section and populate your .env file.
• RPC not found -> ensure the classroom chunk matching RPCs exist in Supabase.
• OCR is empty -> check image quality and illumination; ensure Gemini Vision access is configured.

Notes on data model and flow

Data flows from uploaded documents to classroom_documents, then through store_document_chunks to create chunks with embeddings. You can search via search_similar_chunks during chat, with the chat integrating a contextual classroom assistant and the Gemini LLM.

Security and environment variables

Place sensitive values in a .env file and never commit them to version control. The key environment variables include the Supabase URL, the service role key, the Gemini API key, and various model and threshold settings that control embedding generation and similarity search.

Example run options

You can start the MCP mode with a direct Python run, or use an MCP runner to expose the server as a ready-to-use tool.

Appendix: Tools and endpoints

The server exposes tools for embedding generation, document chunk storage, semantic search, classroom-specific chat, and automatic user-context updates.

Available tools

generate_embedding

Obtain an embedding vector for a given text using Gemini services.

store_document_chunks

Ingest and process a classroom document: OCR for images, PDF text extraction, cleaning, chunking, and embedding generation.

search_similar_chunks

Retrieve relevant document chunks by semantic similarity for a given query within a classroom.

chat_with_classroom_assistant

Interact with a contextual RAG assistant that references document chunks and the user profile.

analyze_and_update_user_context

Analyze conversations to incrementally update the student context and profile.