convez.ai
MCP ServerProdutividadeAvançado
MiniatureJourney

Notely — Plataforma de Notas Acadêmicas com IA

MiniatureJourney/notely-agent

Agente IA que busca, resume e questiona notas acadêmicas com memória de desempenho

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP Server que potencializa um agente acadêmico para estudantes indianos. Integra Gemini 2.5 Flash com busca vetorial no MongoDB Atlas, permitindo que alunos façam upload de notas, recebam resumos inteligentes, quizzes adaptativos e flashcards gerados por IA, com histórico de aprendizado personalizado.

Instalação

$npx convez-ai MiniatureJourney/notely-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Estudantes buscando notas por semântica em vez de palavras-chave
  • Geração automática de flashcards e quizzes personalizados
  • Rastreamento adaptativo de lacunas de aprendizado do aluno

Veredito

Projeto robusto que combina busca vetorial, function calling e estado de usuário em um MCP Server. Bem arquitetado para hackathon, mas ainda específico ao contexto indiano — generalização para outras regiões exigiria rework do domínio educacional.

README

A tradução para o português deste README ainda está na fila.

📚 Notely — AI-Powered Academic Notes Platform

The intelligent study companion for Indian college students.

Live Demo Full Technical Walkthrough License: MIT MongoDB Atlas Vertex AI Cloud Run

Google Cloud Rapid Agent Hackathon 2026 — MongoDB Partner Track


🎯 The Problem

India has 40 million+ college students with no centralized platform to share academic notes. Notes get lost in WhatsApp groups and private drives — with zero quality control, no semantic search, and no personalized study assistance.

✅ The Solution

Notely is a full-stack agentic platform where:

  • Students upload notes (text or photo) and they are automatically scored, embedded, and searchable
  • NoteBot — a Gemini 2.5 Flash AI agent — searches notes semantically, generates flashcards, quizzes, and summaries
  • The agent remembers each student's academic strengths and weaknesses and adapts over time
  • A gamified leaderboard drives community contribution

🌐 Live Demo

→ https://notely-287509159734.us-central1.run.app

No login required — create a quick profile and start exploring.



🎥 Full Technical Walkthrough

→ https://youtu.be/J0GMxIIXiWc


🏗️ Architecture

Student Message
      │
      ▼
┌─────────────────────────────────────────────────────┐
│          FastAPI Backend  (Google Cloud Run)         │
│                                                     │
│  POST /api/chat                                     │
│      │                                              │
│      ├─► Gemini 2.5 Flash (Vertex AI)               │
│      │     Function Calling Loop (up to 8 rounds)   │
│      │          │                                   │
│      │          ├─► search_notes ──► MCP Server ──► MongoDB Atlas $vectorSearch
│      │          ├─► generate_summary ──────────────► fetch full_content
│      │          ├─► generate_flashcards ──────────► Gemini Q&A pairs
│      │          ├─► generate_quiz ────────────────► Gemini MCQ + answers
│      │          ├─► record_quiz_score ────────────► user_memory collection
│      │          ├─► get_leaderboard ──────────────► users collection
│      │          └─► get_forum_posts / get_requests ► forum / requests
│      │                                              │
│      └─► Response + Activity Feed (live tool log)  │
│                                                     │
└─────────────────────────────────────────────────────┘
      │
      ▼
MongoDB Atlas (notely_db)
  ├── notes          (embeddings + full content)
  ├── users          (profiles + points + memory)
  ├── user_memory    (strong / weak topics per student)
  ├── forum_posts
  ├── requests
  └── comments

✨ Features

🤖 NoteBot AI Agent

FeatureDescription
Semantic SearchMongoDB Atlas $vectorSearch via official MCP Server — finds notes by meaning, not just keywords
SummarizationExam-ready concise summary from any note
FlashcardsGenerates N Q&A pairs in structured format
Practice QuizzesMultiple-choice questions with answers and explanations
Academic MemoryTracks each student's weak/strong topics, updated after every quiz
Learning PatternsAI observes and records how a student learns over time
Emergency Exam ModePulls weak topics → searches best notes → generates a timed 24-hour study plan
MCP Activity FeedLive display of every tool call (name, args, timestamp, whether it used MCP)

📝 Note Management

FeatureDescription
Manual UploadRich text form — title, subject, college, dept, semester, chapter, teacher
OCR Image UploadPhoto of handwritten notes → Gemini Vision auto-extracts text, classifies subject/chapter/semester
Image CompressionClient-side Canvas compression before OCR (10MB → ~1MB, 85% quality — non-destructive)
Quality ScoringGemini evaluates every note on 4 criteria — Completeness, Clarity, Examples, Exam Usefulness (0–100)
Strengths & WeaknessesPer-note AI feedback stored in MongoDB and displayed on cards
Vector Embeddingtext-embedding-005 (768-dim) embedded at upload for semantic search

🏘️ Community

FeatureDescription
Home FeedNotes sorted by quality score, with filter chips (All / Trending / Newest / My College)
Browse NotesFull semantic search + filters for college, department, semester
LeaderboardGlobal + college-filtered rankings by points, with medal badges
College ForumDiscussion board with upvotes and "Ask NoteBot" integration
Note RequestsRequest missing notes; fulfill requests for bonus points
CommentsComment on any note

🎮 Gamification

ActionPoints
Upload a note (text)+50 pts
Upload via OCR (image)+100 pts
Post a comment+5 pts
Upvote a note+1 pt
Fulfill a note request+100 pts

⚡ Performance (Production Optimizations)

  • MongoDB Compound Index on (college, department, semester) — query latency from ~50ms → ~2ms
  • Exact-match queries replace regex scans across all collections
  • Strict data projections — full_content and embedding excluded from feed endpoints (~90% payload reduction)
  • Independent async fetches — all dashboard API calls fire concurrently, each updates the DOM independently
  • Optimistic UI — upvotes (notes + forum) update instantly, revert silently on failure
  • Cold-start auto-retry — home feed shows friendly message and retries automatically after 4 seconds

🧰 Tech Stack

LayerTechnology
AI AgentGemini 2.5 Flash (Vertex AI) — function calling loop
Embeddingstext-embedding-005 (Vertex AI) — 768 dimensions
OCRGemini 2.5 Flash Vision API
Quality ScoringGemini 2.5 Flash — 4-criterion academic rubric
DatabaseMongoDB Atlas — operational + vector search
MCP@mongodb-js/mongodb-mcp-server (official, stdio transport)
BackendFastAPI (Python 3.11) + Pydantic
FrontendVanilla HTML / CSS / JavaScript (single-file SPA)
HostingGoogle Cloud Run (us-central1)
ContainerDocker + uvicorn

📡 API Reference

AI & Agent

MethodEndpointDescription
POST/api/chatNoteBot agentic chat (Gemini + MCP tool loop)
POST/api/exam-modeGenerate a personalized 24-hour study plan

Notes

MethodEndpointDescription
GET/api/notesBrowse notes — filter by college, department, semester, sort
GET/api/notes/search?q=Semantic vector search with optional filters
GET/api/notes/{id}Fetch full note by ID
POST/api/upload-noteUpload text note (JSON body)
POST/api/ocr-noteUpload image note (multipart/form-data)
POST/api/notes/{id}/upvoteUpvote a note
GET/api/notes/{id}/commentsGet comments on a note
POST/api/commentsPost a comment

Community

MethodEndpointDescription
GET/api/forumGet forum posts (filter by college)
POST/api/forumCreate a forum post
POST/api/forum/{id}/upvoteUpvote a post
GET/api/requestsGet open note requests
POST/api/requestsPost a note request
POST/api/requests/{id}/fulfillMark a request as fulfilled
GET/api/leaderboardGet top contributors

Users

MethodEndpointDescription
POST/api/usersCreate / update user profile
GET/api/users/{user_id}Get user profile + points
GET/api/user/{user_id}/notesGet all notes by a user

Platform & Infrastructure

MethodEndpointDescription
GET/api/platform-statsLive counts of notes, users, open requests
GET/api/collegesDistinct college names (for dynamic dropdowns)
GET/api/departmentsDistinct department names (for dynamic dropdowns)
GET/healthService health check
POST/mcpMCP JSON-RPC transport (Google AI Agent Builder)
GET/mcp/healthMCP server connection health
GET/api/mcp/toolsList all MongoDB MCP tools
POST/api/mcp/executeExecute any MCP tool via REST

🗄️ MongoDB Atlas Setup

Vector Search Index

Create this index in Atlas under notely_db.notes:

{
  "name": "notes_vector_index",
  "type": "vectorSearch",
  "fields": [
    {
      "type": "vector",
      "path": "embedding",
      "numDimensions": 768,
      "similarity": "cosine"
    },
    { "type": "filter", "path": "college" },
    { "type": "filter", "path": "department" },
    { "type": "filter", "path": "semester" },
    { "type": "filter", "path": "subject" }
  ]
}

Compound Index (Performance)

db.notes.createIndex({ college: 1, department: 1, semester: 1 })

💻 Local Development

# 1. Clone the repository
git clone https://github.com/MiniatureJourney/notely-agent.git
cd notely-agent

# 2. Create a virtual environment
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

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

# 4. Set environment variables
# Create a .env file with:
MONGODB_URI=mongodb+srv://<user>:<password>@<cluster>.mongodb.net/
GOOGLE_CLOUD_PROJECT=your-gcp-project-id
VERTEX_REGION=us-central1

# 5. Run the development server
uvicorn main:app --host 0.0.0.0 --port 8080 --reload

# 6. Open the app
# Visit http://localhost:8080 in your browser

# 7. (Optional) Seed the database with sample notes
python seed_data.py

🚀 Deploy to Google Cloud Run

gcloud run deploy notely \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --port 8080 \
  --memory 2Gi \
  --timeout 300 \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID,VERTEX_REGION=us-central1,MONGODB_URI=YOUR_MONGODB_URI"

🔌 Google AI Agent Builder — MCP Connection

  1. Open Google AI Studio → Agent Platform → Your Agent → Tools
  2. Under MCP, click + Add MCP Server
  3. Enter the server URL:
    https://notely-287509159734.us-central1.run.app/mcp
    
  4. The agent automatically discovers all 28 MongoDB Atlas tools

📁 Project Structure

notely-agent/
├── main.py              # FastAPI app — all REST endpoints + Gemini agentic loop
├── database.py          # All MongoDB Atlas operations (27+ functions)
├── agent_tools.py       # 11 Gemini tool implementations + async dispatcher
├── embeddings.py        # Vertex AI text-embedding-005 wrapper with caching
├── rules_engine.py      # Gemini-powered 4-criterion note quality scorer
├── mcp_bridge.py        # Official MongoDB MCP Server bridge (stdio transport)
├── seed_data.py         # Database seeding script for sample notes
├── requirements.txt     # Python dependencies
├── Dockerfile           # Production container definition
├── docs/
│   └── index.html       # Entire frontend (single-file SPA)
└── tests/
    ├── test_all.py
    ├── test_chat_memory.py
    ├── test_gemini.py
    ├── test_ocr.py
    ├── test_ocr_api.py
    ├── test_regex.py
    ├── test_rules.py
    └── test_system_rigorous.py

🧪 Running Tests

# Run the full test suite
pytest tests/

# Run a specific test file
pytest tests/test_system_rigorous.py -v

# Run OCR tests
pytest tests/test_ocr.py -v

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.


Built with ❤️ for the Google Cloud Rapid Agent Hackathon 2026 — MongoDB Partner Track

Live Demo · Report an Issue

Ver o original no GitHub

Bom para

Relacionados