# MCP-USV: Faculty Administration System

A comprehensive Model Context Protocol (MCP) server for university faculty administration, built with Next.js, Prisma, PostgreSQL, and Gemini AI.

**Features:**
- 🛠️ **50+ MCP Tools** for managing students, faculty, courses, grades, documents, and more
- 🤖 **AI-Powered Chat** interface with Gemini for natural language queries
- 🔗 **Multiple Access Patterns**: HTTP API, MCP protocol, and direct database queries
- 📄 **Certificate Generation** with PDF export and email delivery
- 🏫 **Academic Management** covering students, specializations, courses, and appointments
- 🔒 **Type-Safe** with TypeScript, Zod validation, and Prisma ORM

---

## 📚 Documentation

Start here based on your role:

| Document | Purpose | For |
|----------|---------|-----|
| **[MCP_ARCHITECTURE.md](docs/MCP_ARCHITECTURE.md)** | System design & how everything works together | Architects, Senior Developers |
| **[MCP_ARCHITECTURE_DIAGRAMS.md](docs/MCP_ARCHITECTURE_DIAGRAMS.md)** | Visual flows and interactions | All technical readers |
| **[DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)** | How to add tools and extend the project | Developers, Contributors |
| **[DOCUMENTATION_PROCESS.md](docs/DOCUMENTATION_PROCESS.md)** | How to maintain and improve documentation | Documentation maintainers |
| **This README** | Getting started & quick reference | Everyone (START HERE) |

### Quick Navigation by Role

**👤 New Team Member:**
1. Read: [README.md](#getting-started) (this file)
2. Follow: Setup instructions below
3. Reference: [DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)

**👨‍💻 Want to Add a New Tool:**
→ See [DEVELOPER_GUIDE.md#adding-a-new-tool](docs/DEVELOPER_GUIDE.md#adding-a-new-tool)

**🏗️ Want to Understand the Architecture:**
→ See [MCP_ARCHITECTURE.md](docs/MCP_ARCHITECTURE.md) and [MCP_ARCHITECTURE_DIAGRAMS.md](docs/MCP_ARCHITECTURE_DIAGRAMS.md)

**🧪 Want to Test an API:**
→ See [DEVELOPER_GUIDE.md#api-endpoint-examples](docs/DEVELOPER_GUIDE.md#api-endpoint-examples)

**❓ Something Not Working?**
→ See [DEVELOPER_GUIDE.md#common-debugging](docs/DEVELOPER_GUIDE.md#common-debugging)

---

## Environment Variables

1. Copy `.env.example` to `.env`.
2. Update `DATABASE_URL` to point at your Postgres instance (the same value is used by Prisma, the MCP server, and the Next.js API routes).
3. Set `GEMINI_API_KEY` (and optionally `GEMINI_MODEL`, default `gemini-1.5-pro`) so the chat agent can call Gemini.
4. Adjust `MCP_SERVER_COMMAND` / `MCP_SERVER_PATH` if the compiled MCP binary lives elsewhere.
5. Configure SMTP for certificate delivery: `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, optional `SMTP_FROM`.

## Getting Started

First, run the development server:

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.

You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.

This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.

## MCP Server

Build the TypeScript MCP server and start it against the same datastore:

```bash
npm run build:mcp
node dist/mcp-server.js
```

## Students API

The React app now exposes the MCP student tools over HTTP:

- `GET /api/students` accepts the same optional filters as the `list_students` tool.
- `POST /api/students` validates payloads with Zod and creates a student via the shared Prisma service.

The API handlers import the exact same business logic that powers the MCP tools, so data written by the React UI is immediately visible to MCP clients.

## Faculties API

- `GET /api/faculties` returns all faculties with only `id` and `name`.
- `GET /api/faculties/[facultyId]/specializations` returns all specializations for that faculty with only `id` and `name`.

## Certificate Requests API

- `POST /api/certificate-requests` validates student certificate request payloads.
- `GET /api/certificate-requests` returns certificate requests (newest first); optional `status` query filter, e.g. `/api/certificate-requests?status=pending`.
- Expected body: `lastName`, `firstName`, `fatherInitial`, `faculty`, `specialization`, `studyYear`, `purpose`, `otherPurpose`.
- `faculty` and `specialization` are received as IDs in the request, validated against student/faculty/specialization data, then stored as names in `CertificateRequest`.
- `firstName`, `lastName`, and `fatherInitial` are validated at POST time and resolved from the related `Student` record on GET responses.
- On invalid data the endpoint returns `valid: false` with `reasons`; on success it stores the request with `status: "pending"`.
- `POST /api/certificate-requests/[requestId]/approve` approves one request, generates:
  - JSON snapshot in `generated-certificates/`
  - PDF file in `generated-certificates/pdf/`
  - `Document` row with `filePath` set to the generated PDF path
  - Email with PDF attachment to the linked student's email
- If SMTP fails, approval still completes and API response includes `email.sent: false` with an error message.

For PDF generation with Playwright, install Chromium once:

```bash
npx playwright install chromium
```

## Secretariat Appointments API

- `GET /api/secretariat-appointments` returns appointments ordered by `date` + `time`.
- `GET /api/secretariat-appointments?studentEmail=...&dateFrom=YYYY-MM-DD&dateTo=YYYY-MM-DD` filters appointments.
- `POST /api/secretariat-appointments` creates a new appointment.
- `GET /api/secretariat-appointments/[appointmentId]` fetches one appointment.
- `PATCH /api/secretariat-appointments/[appointmentId]` updates one or more fields.
- `DELETE /api/secretariat-appointments/[appointmentId]` removes one appointment.
- Expected body fields: `studentName`, `studentEmail`, `date` (`YYYY-MM-DD`), `time` (`HH:mm`), optional `durationMinutes`, `meetingMode`, `location`, `notes`.

## MCP Tool Proxy

External apps can now discover and invoke any MCP tool via HTTP:

- `GET /api/tools` – returns every tool name plus its description so you can build pickers in another UI.
- `POST /api/tools/[toolName]` – validates the request body with the tool’s Zod schema, spins up the MCP server (`node dist/mcp-server.js` by default), and returns the `CallToolResult` JSON.

Environment tweaks:

1. Run `npm run build:mcp` whenever tool code changes so `dist/mcp-server.js` stays in sync.
2. Override `MCP_SERVER_COMMAND` / `MCP_SERVER_PATH` if the binary lives elsewhere (see `.env.example`).

Each HTTP invocation launches the MCP server via stdio, executes a single tool, and shuts it down—ideal for React clients that can only speak HTTP.

## Chat Agent API

`POST /api/chat` accepts `{ "message": "..." }`, sends the prompt to Gemini with the MCP tool catalog, executes the tool Gemini selects, and replies with:

- `reply`: Gemini's final answer after the tool call (if any).
- `toolCalls`: arguments plus raw MCP output so clients can audit what happened.

You can exercise the endpoint via the simple chat UI on the home page.

## Internal Auth API

- `POST /internal/auth/secretary-check` checks whether an email is allowed to use secretary-only flows.
- Expected JSON body: `{ "email": "user@gmail.com" }`.
- Success response shape: `{ "allowed": true }` (or `false`).
- Configure allowed emails with `SECRETARY_EMAILS` as a comma-separated list.

## Students UI

Visit the home page to:

- Send prompts that flow through `/api/chat`.
- Watch Gemini's replies plus any MCP tool traces for debugging.