tapansreesailam/ai-study-assistant-mcp

Purpose and Runtime

This is a lightweight Python Model Context Protocol (MCP) server for study-note management and Gemini-backed study assistance. It runs as a local STDIO MCP service, intended to be launched by an MCP client or FastMCP Inspector.

Entry point: server.py

Dependencies and runtime contract: requirements.txt, .env.example

MCP Server Composition

server.py creates/configures the FastMCP server, exposes a connection-test tool (hello), imports the domain tool modules, and starts the STDIO transport. Tool registration is the key integration boundary: MCP clients invoke server-exposed Python functions rather than HTTP endpoints.

Paths: server.py, tools/__init__.py

Notes Tool Domain

The notes capability manages persistent study-note records: creation, retrieval, text search, and deletion by title. These operations are exposed as MCP tools and form the local stateful portion of the service.

Paths: tools/notes.py, server.py

Control flow: MCP client → FastMCP tool dispatch → note operation → SQLite database → structured tool response. The database is local persistent storage; the README identifies its expected runtime location as data/notes.db, though that directory is not present in the provided tree.

SQLite Persistence Boundary

SQLite separates note-management logic from durable storage. Note data is expected to include subject, title, and content, supporting search across those fields. The database is runtime-generated/local and deliberately excluded from source control.

Paths: tools/notes.py, .gitignore, README.md

Gemini AI Tool Domain

The AI study-assistant tool accepts a study question and delegates generation to Google Gemini. It is stateless relative to local notes: the described architecture does not indicate retrieval or note context being sent to Gemini.

Paths: tools/ai.py, server.py

Control flow: MCP client → ask_ai tool → Gemini SDK/API request → generated explanation/answer → MCP response.

Secrets and External-Service Boundary

Gemini access requires GEMINI_API_KEY, loaded from environment configuration. .env.example defines the expected developer-facing secret contract; actual .env files must remain local. The Google Gemini API is the sole described remote dependency, while SQLite is embedded local infrastructure.

Paths: .env.example, tools/ai.py, .gitignore

Architectural Constraints

The server is a tool provider, not a web application: its primary interface is MCP over STDIO. Notes and AI tools are separate modules, enabling independent evolution of local persistence and external model integration. Current scope is intentionally direct CRUD plus question answering; RAG, vector storage, remote transport, and UI are future—not current—architecture.

Paths: server.py, tools/notes.py, tools/ai.py