# Greenfield Public School — MCP Teaching & AI Chatbox Example

> A **comprehensive, classroom-ready demonstration** of the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) using a realistic school database as the domain. Designed for **undergraduate students** learning how AI systems connect to external tools and data sources via standard input/output (`stdio`) pipes and JSON-RPC 2.0 messaging.

---

## What Is MCP?

**Model Context Protocol (MCP)** is an open standard by Anthropic that defines how AI assistants (clients) communicate with external data sources and tools (servers). Think of it like a standardized API specifically designed for AI applications.

```text
┌─────────────────────┐     JSON-RPC 2.0      ┌─────────────────────────┐
│   AI Application    │ ◄──────────────────── ► │     MCP Server          │
│   (MCP Client)      │     over stdio/HTTP     │  • Tools (functions)    │
│                     │                         │  • Resources (data)     │
│  e.g. OpenAI GPT,   │                         │  • Prompts (templates)  │
│  Claude, Cursor     │                         │                         │
└─────────────────────┘                         └─────────────────────────┘
```

**Real-world MCP clients:** Claude Desktop, Cursor IDE, Windsurf, custom AI apps (`ai_chatbox.py`).

---

## Project Overview

This project simulates a **school MCP server** that manages:
- **Student marks** (30 students × 5 subjects)
- **Enrollment records** (roll numbers, admission dates)
- **School rules** (norms and regulations document)
- **Awards policy** (rank 1–5 award definitions)
- **Class statistics** (class average, pass/fail breakdown, subject toppers)

The MCP server allows AI clients to query this data through a well-defined protocol.

---

## Active Project Structure

```text
c:\Satish_Files\MCP_Server\
├── data/
│   ├── students_marks.json     # Marks for 30 students across 5 subjects
│   ├── enrollment.json         # Roll numbers, admission dates, grade sections
│   ├── awards_policy.json      # Rank-based (1-5) and subject-based awards policy
│   └── school_rules.txt        # 10-section school norms and regulations document
│
├── server/
│   └── school_mcp_server.py    # Core MCP Server (exposes 7 tools, 4 resources, 2 prompts)
│
├── ai_chatbox.py               # AI Chatbox using OpenAI gpt-4o-mini function calling + MCP client
├── mcp_logger.py               # Centralized, instant-flushing protocol logger (writes to logs/)
├── requirements.txt            # Python dependencies (mcp, colorama, openai)
├── README.md                   # Setup guide, capabilities, and instructions (this file)
├── Project_structure.md        # Architecture, component map, and execution flow
└── old_files.zip               # Zip archive of legacy/redundant files
```

---

## Setup & Installation

### Step 1: Install Python 3.10+
Make sure you have Python 3.10 or newer:
```bash
python --version
```

### Step 2: Create a Virtual Environment (Recommended)
```bash
cd c:\Satish_Files\MCP_Server
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # macOS / Linux
```

### Step 3: Install Dependencies
```bash
pip install -r requirements.txt
```
> Installed packages include `mcp[cli]` (v2.x), `openai` (v1.x), and `colorama`.

---

## Running the AI Chatbox

Run the main AI-powered Chatbox (OpenAI GPT-4o-mini + MCP Client):

```powershell
python -X utf8 ai_chatbox.py
```

### Example Queries to Ask in Plain English:
- *"How many students are in the class?"*
- *"What are Meera Iyer's marks?"*
- *"Who are the top 3 students in Mathematics?"*
- *"Who are the top 3 students in Computer Science?"*
- *"Who are the top 3 students overall?"*
- *"When did Harshit Yadav enroll?"*
- *"What award does rank 1 get?"*
- *"What is the attendance policy?"*

### Inspect Converted OpenAI Tool Schemas:
Inside the interactive prompt of `ai_chatbox.py`, type:
```text
You: tools
```
or
```text
You: schemas
```
It will pretty-print the exact converted OpenAI function schemas (`mcp_tools_to_openai`) in the terminal.

---

## Testing with MCP Inspector

The MCP SDK includes a built-in web-based inspector for testing server capabilities interactively:

```powershell
mcp dev server/school_mcp_server.py
```
This opens a browser UI where you can invoke tools and inspect resource URIs directly.

---

## MCP Server Capabilities

### 🛠️ Tools (Callable Actions)

| Tool Name | Arguments | What It Does |
|-----------|-----------|--------------|
| `get_student_marks` | `student_name: str` | Returns marks, aggregate (out of 500), percentage, grade |
| `get_top_rankers` | `count: int = 5` | Returns top N students by overall percentage |
| `get_top_students_by_subject` | `subject_name: str, count: int = 5` | Returns top N students in a subject or total |
| `get_class_statistics` | *(none)* | Returns class summary, average (79.99%), pass/fail rates, grade breakdown |
| `get_student_enrollment` | `student_name: str` | Returns enrollment number and date of admission |
| `get_school_awards` | *(none)* | Returns complete rank and subject awards policy |
| `search_school_rules` | `keyword: str` | Searches 10 sections of school norms document |

### 📂 Resources (Readable Data)

| URI | Content Type | What It Contains |
|-----|-------------|-----------------|
| `school://students/all` | JSON | All 30 students with full marks data |
| `school://enrollment/all` | JSON | All enrollment records |
| `school://rules` | Text | Full school norms document |
| `school://awards/policy` | JSON | Complete awards policy |

### 💬 Prompts (Reusable Templates)

| Prompt Name | Arguments | Purpose |
|-------------|-----------|---------|
| `student_report_prompt` | `student_name: str` | Generates a student analysis prompt template |
| `class_summary_prompt` | *(none)* | Generates a class overview prompt template |

---

## Real-Time Protocol Logging

Every session generates an instant-flushing log file in `logs/mcp_session_<timestamp>.log`.

### To View the Latest Session Log:
```powershell
Get-ChildItem logs\ | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content
```

The log records:
1. **User Query**
2. **AI Intent Reasoning** (Why GPT selected a specific tool and arguments)
3. **JSON-RPC Protocol Request** (`tools/call`)
4. **Server Execution Result** from school database
5. **Final AI Answer**

---

## Connecting to Claude Desktop

To connect this server to Claude Desktop, add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "greenfield-school": {
      "command": "python",
      "args": ["c:/Satish_Files/MCP_Server/server/school_mcp_server.py"]
    }
  }
}
```

---

## Further Reading

- [MCP Official Docs](https://modelcontextprotocol.io)
- [MCP Python SDK on GitHub](https://github.com/modelcontextprotocol/python-sdk)
- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)

---

*Built for teaching MCP to undergraduate students | Greenfield Public School Example*