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	System design & how everything works together	Architects, Senior Developers
MCP_ARCHITECTURE_DIAGRAMS.md	Visual flows and interactions	All technical readers
DEVELOPER_GUIDE.md	How to add tools and extend the project	Developers, Contributors
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 (this file)
2. Follow: Setup instructions below
3. Reference: DEVELOPER_GUIDE.md

👨‍💻 Want to Add a New Tool: → See DEVELOPER_GUIDE.md#adding-a-new-tool

🏗️ Want to Understand the Architecture: → See MCP_ARCHITECTURE.md and MCP_ARCHITECTURE_DIAGRAMS.md

🧪 Want to Test an API: → See DEVELOPER_GUIDE.md#api-endpoint-examples

❓ Something Not Working? → See 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:

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

Open 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 to automatically optimize and load Geist, a new font family for Vercel.

MCP Server

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

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:

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.