University Course Catalog MCP Server

A production-grade Model Context Protocol server that exposes a university course catalog through structured tools, resources, and prompt templates. Built with Python 3.12, FastAPI, SQLAlchemy 2.x, and the official MCP SDK.

Project Overview

This MCP server provides intelligent access to a university course catalog with the following capabilities:

• Full-text course search with optional department filtering
• Prerequisite dependency tracking with cycle prevention
• Instructor lookups with contact information and department associations
• Prerequisite graph analysis for understanding course dependencies
• Course catalog resource with complete course descriptions
• Department directory resource for department information
• Course comparison prompt template for structured LLM analysis

The server is designed to work seamlessly with Claude, ChatGPT, and other LLM clients through the MCP protocol.

Architecture

Design Principles

• Clean Separation of Concerns: Service layer abstraction decouples MCP tools from database operations
• Production Quality: Full logging, error handling, type hints, and docstrings throughout
• Scalability: SessionLocal factory pattern for thread-safe database access
• Maintainability: Centralized configuration, structured schemas, and comprehensive tests

Layer Structure

MCP Tools/Resources/Prompts (src/tools, src/resources, src/prompts)
                ↓
Pydantic Schemas (src/schemas) - Input/output validation
                ↓
Service Layer (src/services) - Business logic, database queries
                ↓
SQLAlchemy ORM (src/models) - Database mapping
                ↓
SQLite Database (data/catalog.db)

Data Flow

1. MCP Client sends request with validated input
2. Tool/Resource Handler validates input via Pydantic schema
3. Service Layer queries database using SQLAlchemy 2.x with select()
4. ORM marshals database results to Python objects
5. Response returned as typed Pydantic model for JSON serialization

Folder Structure

university-mcp-server/
├── src/
│   ├── config.py                 # Environment configuration (Pydantic BaseSettings)
│   ├── database.py               # SQLAlchemy engine and SessionLocal
│   ├── mcp_app.py                # Shared FastMCP instance
│   ├── server.py                 # FastAPI application with MCP transport mounting
│   ├── models/                   # SQLAlchemy ORM models
│   │   ├── course.py
│   │   ├── department.py
│   │   ├── instructor.py
│   │   └── prerequisite.py
│   ├── schemas/                  # Pydantic validation schemas
│   │   └── course.py
│   ├── services/                 # Business logic and database queries
│   │   ├── course_service.py
│   │   ├── department_service.py
│   │   ├── graph_service.py
│   │   └── instructor_service.py
│   ├── tools/                    # MCP tools (registered via @mcp.tool)
│   │   ├── search_courses.py
│   │   ├── get_prerequisites.py
│   │   ├── lookup_instructor.py
│   │   └── get_prerequisite_graph.py
│   ├── resources/                # MCP resources (registered via @mcp.resource)
│   │   ├── course_descriptions.py
│   │   └── department_directory.py
│   └── prompts/                  # MCP prompts (registered via @mcp.prompt)
│       └── course_comparison.py
├── data/
│   ├── seed.py                   # Database seeding script
│   └── catalog.db                # SQLite database (created at runtime)
├── tests/                        # Pytest test suite
│   ├── conftest.py               # Fixtures and test configuration
│   ├── test_mcp_app.py
│   ├── test_endpoints.py
│   ├── test_tools.py
│   ├── test_resources.py
│   └── test_prompts.py
├── Dockerfile                    # Container image definition
├── docker-compose.yml            # Multi-container orchestration
├── .env.example                  # Environment variable template
├── requirements.txt              # Python dependencies
├── pytest.ini                    # Pytest configuration
└── README.md                     # This file

Installation

Prerequisites

• Python 3.12+
• pip or conda package manager
• Docker and Docker Compose (optional, for containerized deployment)

Local Setup

1. Clone the repository

   cd university-mcp-server
   

2. Create and activate virtual environment

   # Windows
   python -m venv venv
   .\venv\Scripts\Activate.ps1
   
   # macOS/Linux
   python3 -m venv venv
   source venv/bin/activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Initialize database

   # Windows
   .\venv\Scripts\python.exe data/seed.py
   
   # macOS/Linux
   python data/seed.py
   

5. Configure environment (optional)

   # Copy template and customize if needed
   cp .env.example .env
   

Docker Setup

1. Build and start with Docker Compose

   docker-compose up --build
   

The container bootstraps the SQLite schema and seed data on startup, so a fresh checkout works without a prebuilt database file.

2. Verify server is running

   curl http://localhost:8080/health
   # Response: {"status": "healthy"}
   

3. Stop the service

   docker-compose down
   

Environment Variables

Configure via .env file (see .env.example):

Variable	Default	Description
DATABASE_URL	sqlite:///./data/catalog.db	SQLAlchemy database connection string; supports sqlite, PostgreSQL, MySQL
HOST	0.0.0.0	Server binding address; use 127.0.0.1 for localhost-only
PORT	8080	Server port number (1-65535)

Docker Environment

Docker Compose automatically sets all environment variables. Override in docker-compose.yml:

environment:
  DATABASE_URL: sqlite:///./data/catalog.db
  HOST: 0.0.0.0
  PORT: 8080

Running Locally

Start the server

# Windows
.\venv\Scripts\python.exe -m src.server

# macOS/Linux
python -m src.server

Server will start on http://0.0.0.0:8080 with logging output.

Health check

curl http://localhost:8080/health

Expected response:

{"status": "healthy"}

Access MCP endpoints

• HTTP (Streamable): http://localhost:8080/mcp
• SSE (Server-Sent Events): http://localhost:8080/sse
• SSE message endpoint: http://localhost:8080/sse/messages/

Docker Notes

• The image runs create_db.py and data/seed.py on startup before launching the API.
• The build excludes the local virtual environment and cache directories with .dockerignore.
• The container exposes port 8080 and uses the same DATABASE_URL, HOST, and PORT settings as local runs.

Testing

Run the full pytest suite:

# All tests
pytest

# Verbose output
pytest -v

# Specific test file
pytest tests/test_tools.py

# Specific test class
pytest tests/test_tools.py::TestSearchCoursesTool

# With coverage
pip install pytest-cov
pytest --cov=src --cov-report=html

Test Structure

• test_mcp_app.py: Startup smoke tests for FastAPI app composition and MCP registration (2 tests)
• test_endpoints.py: Health endpoint validation (3 tests)
• test_tools.py: MCP tool functionality (18 tests)
  • search_courses: keyword search, filtering, no results, case insensitivity
  • get_prerequisites: with/without prerequisites, error handling
  • lookup_instructor: success, not found, whitespace handling
  • get_prerequisite_graph: graph generation, structure validation
• test_resources.py: MCP resource generation (12 tests)
  • course_descriptions: format, field inclusion, multiple courses
  • department_directory: format, codes, alphabetical ordering
• test_prompts.py: Prompt template rendering (10 tests)

Coverage: 45 test cases covering app wiring, success paths, and failure paths.

Available MCP Tools

1. search_courses

Search the university course catalog by keyword with optional department filtering.

Input Schema

{
  "query": "string (required, non-empty)",
  "department_code": "string (optional, e.g., 'CS', 'AI')"
}

Output Schema

{
  "root": [
    {
      "course_code": "CS101",
      "title": "Introduction to Computer Science",
      "credits": 3
    }
  ]
}

Example Queries

• "Find all programming courses"
• "Search for data science courses in the DS department"
• "What computer science courses are available?"

2. get_prerequisites

Retrieve all direct prerequisite courses for a given course code.

Input Schema

{
  "course_code": "string (required, e.g., 'CS201')"
}

Output Schema

{
  "course_code": "CS201",
  "prerequisites": [
    {
      "course_code": "CS101",
      "title": "Introduction to Computer Science"
    }
  ]
}

Example Queries

• "What are the prerequisites for CS201?"
• "Can I take AI101 without any prerequisites?"
• "What courses do I need to complete before taking CS301?"

3. lookup_instructor

Find instructor contact information and department assignment.

Input Schema

{
  "instructor_name": "string (required, e.g., 'Dr. Alice Smith')"
}

Output Schema

{
  "name": "Dr. Alice Smith",
  "email": "alice@university.edu",
  "department_name": "Computer Science"
}

Example Queries

• "How can I contact Dr. Alice Smith?"
• "What department is Dr. Bob Johnson in?"
• "Find the email for Dr. Carol White"

4. get_prerequisite_graph

Build a complete prerequisite dependency graph for a course, showing all direct and transitive prerequisites.

Input Schema

{
  "course_code": "string (required, e.g., 'CS301')"
}

Output Schema

{
  "nodes": [
    {"id": "CS101"},
    {"id": "CS201"},
    {"id": "CS301"}
  ],
  "edges": [
    {"source": "CS101", "target": "CS201"},
    {"source": "CS201", "target": "CS301"}
  ]
}

Example Queries

• "Show me the prerequisite chain for CS301"
• "What's the full dependency graph for AI301?"
• "Create a graph of all prerequisites needed for DS301"

Available MCP Resources

course_descriptions

A comprehensive text resource listing all university courses with complete descriptions.

URI: resource://course_descriptions

Format

[CODE] Title
Credits: N
Description: ...
------------------------------------

Example Response

[CS101] Introduction to Computer Science
Credits: 3
Description: Fundamentals of programming and computational thinking
------------------------------------
[CS201] Data Structures and Algorithms
Credits: 4
Description: Advanced programming concepts and algorithm design
------------------------------------

department_directory

A formatted text resource containing all university departments.

URI: resource://department_directory

Format

Name (Code)
Name (Code)
...

Example Response

Artificial Intelligence (AI)
Computer Science (CS)
Data Science (DS)

Prompt Template

course_comparison_template

A reusable prompt template for comparing two courses, useful for generating structured LLM analysis.

Parameters

• course_code_1: First course code (e.g., "CS101")
• course_code_2: Second course code (e.g., "CS201")

Generated Prompt The template instructs the LLM to create a comparison table with:

• Course titles
• Credit hours
• Course descriptions
• Instructors
• Departments
• Prerequisites
• Recommendations for student types

Example Usage

Compare CS101 vs CS201 to understand which course would be better for a beginner programmer

Example Natural Language Queries

Course Discovery

• "What programming courses are available in the CS department?"
• "Find all courses about machine learning"
• "Show me the data science curriculum"
• "What courses can I take without prerequisites?"

Prerequisite Planning

• "What do I need to take CS301?"
• "Show me the full prerequisite chain for AI301"
• "Can I take DS201 if I've completed CS101?"
• "Map out all the required courses for the AI track"

Instructor Information

• "Who teaches CS201?"
• "How do I contact Dr. Alice Smith?"
• "What courses are taught by the Data Science department?"
• "Find all instructors in the Computer Science department"

Course Comparison

• "Compare CS101 and CS201 to decide which to take"
• "What's the difference between AI101 and DS101?"
• "Should I take the AI course or the DS course?"

Curriculum Planning

• "Create a 2-semester course plan for CS major"
• "What's the recommended order to take CS courses?"
• "Show me all prerequisites needed to take the advanced AI courses"

Technology Stack

Core Framework

• FastAPI 0.139.0 - Async web framework for Python
• Uvicorn - ASGI server for FastAPI

Database & ORM

• SQLAlchemy 2.x - Modern Python ORM with select() queries
• SQLite - Lightweight embedded database (default; easily swappable)

MCP & LLM Integration

• mcp 1.28.1 - Official Model Context Protocol SDK
• Pydantic v2 - Data validation and serialization

Utilities

• httpx - HTTP client for health checks
• NetworkX 3.x - Graph algorithms for prerequisite dependency analysis

Development & Testing

• pytest - Testing framework
• Docker & Docker Compose - Containerization and orchestration

Python Version

• Python 3.12 - Latest stable Python version with improved performance

Future Improvements

Phase 2: Enhanced Features

• [ ] Course enrollment management (add/drop functionality)
• [ ] Student transcript tracking
• [ ] GPA calculation and academic standing
• [ ] Course schedule/timetable queries
• [ ] Room and building location resources
• [ ] Instructor office hours and availability

Phase 3: Advanced Analytics

• [ ] Course recommendation engine based on student history
• [ ] Prerequisite conflict detection and resolution suggestions
• [ ] Workload analysis (credits per semester)
• [ ] Course difficulty ratings and student feedback
• [ ] Prerequisite weakness identification

Phase 4: Integration & Deployment

• [ ] PostgreSQL support for production environments
• [ ] Authentication and authorization (OAuth2)
• [ ] Rate limiting and API key management
• [ ] WebSocket support for real-time updates
• [ ] Kubernetes deployment manifests
• [ ] AWS/Azure cloud deployment guides

Phase 5: UX Improvements

• [ ] Multi-language support (Spanish, Chinese, etc.)
• [ ] Accessibility enhancements (screen reader optimization)
• [ ] Interactive prerequisite tree visualization
• [ ] Course planning calendar with drag-and-drop
• [ ] Mobile-friendly response formatting

License

This project is provided as-is for educational and demonstration purposes. Modify and distribute freely with attribution.

---

Questions or Issues?

For bugs, feature requests, or questions, refer to the project documentation or contact the development team.

Happy course planning! 🎓