# tapansreesailam/ai-study-assistant-mcp architecture

> Architecture diagram of the GitHub repository tapansreesailam/ai-study-assistant-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tapansreesailam/ai-study-assistant-mcp
- Repository: https://github.com/tapansreesailam/ai-study-assistant-mcp

## Overview

#### 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`

Main entry points: [`server.py`](https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/server.py) (FastMCP Server), [`tools/ai.py`](https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/tools/ai.py) (ask_ai Tool), [`.gitignore`](https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/.gitignore) (Local File Exclusions), [`tools/notes.py`](https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/tools/notes.py) (Notes Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP Service"]
  node_client(("MCP Client / Inspector<br/>MCP consumer"))
  node_server["FastMCP Server<br/>server entry point<br/>[server.py]"]
  node_hello["hello<br/>connection tool<br/>[server.py]"]
end

subgraph group_domains["Tool Domains"]
  node_notes["Notes Tools<br/>MCP tool module<br/>[notes.py]"]
  node_ai["ask_ai Tool<br/>MCP tool module<br/>[ai.py]"]
  node_tool_init["Tool Package<br/>module package<br/>[__init__.py]"]
end

subgraph group_local["Local Runtime"]
  node_sqlite[("Notes SQLite DB<br/>embedded persistence")]
  node_env_contract["Environment Contract<br/>secret configuration<br/>[.env.example]"]
  node_dependencies["Python Dependencies<br/>runtime manifest<br/>[requirements.txt]"]
  node_gitignore["Local File Exclusions<br/>source-control policy<br/>[.gitignore]"]
end

subgraph group_external["External Service"]
  node_gemini{{"Google Gemini API<br/>model API"}}
end

node_client -->|"STDIO MCP"| node_server
node_server -->|"dispatches"| node_hello
node_server -->|"imports"| node_tool_init
node_server -->|"registers tools"| node_notes
node_server -->|"registers tool"| node_ai
node_notes -->|"CRUD and search"| node_sqlite
node_ai -.->|"reads API key"| node_env_contract
node_ai -->|"SDK/API request"| node_gemini
node_dependencies -.->|"provides runtime"| node_server
node_gitignore -.->|"excludes local DB"| node_sqlite
node_gitignore -.->|"excludes .env"| node_env_contract

click node_server "https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/server.py"
click node_hello "https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/server.py"
click node_notes "https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/tools/notes.py"
click node_ai "https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/tools/ai.py"
click node_tool_init "https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/tools/__init__.py"
click node_env_contract "https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/.env.example"
click node_dependencies "https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/requirements.txt"
click node_gitignore "https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/.gitignore"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_server,node_hello toneBlue
class node_notes,node_ai,node_tool_init toneAmber
class node_sqlite,node_env_contract,node_dependencies,node_gitignore toneMint
class node_gemini toneRose
```

## Components

### MCP Service

Local STDIO tool provider.

- **MCP Client / Inspector**: MCP consumer · Launches and invokes the local server over STDIO.
- [FastMCP Server](https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/server.py): server entry point · Configures tools and starts STDIO transport. · `server.py`
- [hello](https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/server.py): connection tool · `server.py`

### Tool Domains

- [Notes Tools](https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/tools/notes.py): MCP tool module · Creates, retrieves, searches, and deletes notes. · `tools/notes.py`
- [ask_ai Tool](https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/tools/ai.py): MCP tool module · Generates study assistance without note retrieval context. · `tools/ai.py`
- [Tool Package](https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/tools/__init__.py): module package · Provides the tool-module integration package. · `tools/__init__.py`

### Local Runtime

- **Notes SQLite DB**: embedded persistence · Runtime-generated durable note storage.
- [Environment Contract](https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/.env.example): secret configuration · Defines the required GEMINI_API_KEY. · `.env.example`
- [Python Dependencies](https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/requirements.txt): runtime manifest · `requirements.txt`
- [Local File Exclusions](https://github.com/tapansreesailam/ai-study-assistant-mcp/blob/main/.gitignore): source-control policy · Keeps local database and environment files out of source control. · `.gitignore`

### External Service

- **Google Gemini API**: model API · Sole remote dependency for generated answers.

## Connections

- MCP Client / Inspector → FastMCP Server: STDIO MCP
- FastMCP Server → hello: dispatches
- FastMCP Server → Tool Package: imports
- FastMCP Server → Notes Tools: registers tools
- FastMCP Server → ask_ai Tool: registers tool
- Notes Tools → Notes SQLite DB: CRUD and search
- ask_ai Tool → Environment Contract: reads API key
- ask_ai Tool → Google Gemini API: SDK/API request
- Python Dependencies → FastMCP Server: provides runtime
- Local File Exclusions → Notes SQLite DB: excludes local DB
- Local File Exclusions → Environment Contract: excludes .env