University Course Catalog MCP Server

An MCP (Model Context Protocol) server that exposes a university course catalog as a set of tools, resources, and prompts. The intended consumer is an AI academic advisor — a language model that needs to answer questions about courses, prerequisites, and instructors without hallucinating data. The server gives that model a structured, queryable interface backed by a real database.

---

Architecture

graph LR
    Client["MCP Client (LLM / Inspector)"]

    subgraph Docker["Docker Container (port 8080)"]
        subgraph Server["FastMCP"]
            T["Tools\nsearch_courses\nget_prerequisites\nlookup_instructor\nget_prerequisite_graph"]
            R["Resources\ncourse_descriptions\ndepartment_directory"]
            P["Prompts\ncourse_comparison_template"]
        end
        ORM["SQLAlchemy ORM"]
        DB["SQLite\ndata/catalog.db"]
    end

    Client -- "HTTP /mcp" --> Server
    Client -- "HTTP /health" --> Server
    T --> ORM
    R --> ORM
    ORM --> DB

---

Tech Stack

Component	Library / Tool
Language	Python 3.12
MCP layer	mcp < 2.0.0 (FastMCP, streamable-http transport)
ORM	SQLAlchemy 2
Validation	Pydantic v2
Graph traversal	NetworkX
Database	SQLite
Container	Docker + Docker Compose

---

Project Structure

.
├── README.md
├── Dockerfile
├── docker-compose.yml
├── .dockerignore
├── .env.example
├── .gitignore
├── requirements.txt
├── data/
│   ├── catalog.db          # seeded SQLite file, committed to git
│   └── seed.py
├── src/
│   ├── __init__.py
│   ├── main.py             # FastMCP instance, health route, entrypoint
│   ├── database.py         # SQLAlchemy engine/session/Base
│   ├── models.py           # Department, Instructor, Course, Prerequisite ORM models
│   ├── schemas.py          # Pydantic input/output models for all 4 tools
│   ├── tools.py            # tool implementations
│   ├── resources.py        # course_descriptions / department_directory
│   └── prompts.py          # course_comparison_template
└── scripts/
    └── verify_server.py    # repeatable smoke-test script

---

Setup & Run

Docker (recommended)

docker compose up --build

The server starts on port 8080. The MCP endpoint is at http://localhost:8080/mcp, health check at http://localhost:8080/health.

Local dev

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Seed the database (idempotent — safe to run multiple times)
python data/seed.py

# Start the server
python src/main.py

The server reads DATABASE_URL from the environment. Copy .env.example to .env if you want to override the default (sqlite:///./data/catalog.db).

---

Database Schema

departments

Column	Type	Constraints
id	INTEGER	PRIMARY KEY
name	TEXT	NOT NULL
code	TEXT	NOT NULL, UNIQUE

instructors

Column	Type	Constraints
id	INTEGER	PRIMARY KEY
name	TEXT	NOT NULL
email	TEXT	NOT NULL
office	TEXT
department_id	INTEGER	NOT NULL, FK → departments.id

courses

Column	Type	Constraints
id	INTEGER	PRIMARY KEY
course_code	TEXT	NOT NULL, UNIQUE
title	TEXT	NOT NULL
description	TEXT	NOT NULL
credits	INTEGER	NOT NULL
instructor_id	INTEGER	NOT NULL, FK → instructors.id
department_id	INTEGER	NOT NULL, FK → departments.id

prerequisites

Column	Type	Constraints
course_id	INTEGER	PRIMARY KEY, FK → courses.id
prerequisite_id	INTEGER	PRIMARY KEY, FK → courses.id

---

MCP Tools

Name	Purpose	Input	Output
search_courses	Case-insensitive substring search over course title and description	query: str, department_code: str | None	[{course_code, title, credits}, ...] — empty list if no matches
get_prerequisites	Returns direct prerequisites (one level) for a course	course_code: str	{course_code, prerequisites: [{course_code, title}]} or {error}
lookup_instructor	Returns contact and department info for an instructor by name	instructor_name: str	{name, email, department_name} or {error}
get_prerequisite_graph	Builds a full transitive prerequisite graph using NetworkX	course_code: str	{nodes: [{id}], edges: [{source, target}]} or {error}

---

MCP Resources

Name	URI	Content
course_descriptions	catalog://course_descriptions	One line per course: [CS101] Introduction to Programming: <description>
department_directory	catalog://department_directory	One line per department: Computer Science (CS)

Both resources are generated dynamically from the database on each read.

---

MCP Prompts

Name	Description
course_comparison_template	A comparison table template with literal {{course_code_1}} and {{course_code_2}} placeholders for two courses

Template text:

Create a table comparing the following two courses: {{course_code_1}} and {{course_code_2}}. Include columns for Title, Credits, Description, and Prerequisites.

---

Example Queries

These are the kinds of natural-language questions a connected LLM could answer using the tools above:

1. "What courses do I need to take before I can enroll in Artificial Intelligence (CS401)?"
2. "Show me all the courses offered by the Mathematics department."
3. "How do I contact Dr. Sarah Chen, and what department is she in?"
4. "I want to take Database Systems — what's the full chain of prerequisites I need to complete first?"
5. "Compare Introduction to Programming and Calculus I — what are the differences in credits and content?"

---

Design Note: FastMCP over FastAPI

The server uses FastMCP from the MCP Python SDK directly, running with transport="streamable-http". I did not mount the MCP app inside a separate FastAPI application. Doing so (via FastAPI's .mount() applied to mcp.streamable_http_app()) is a known routing bug in the SDK where the MCP endpoint stops responding correctly after mounting. Using FastMCP.run() with its built-in Uvicorn runner avoids the issue entirely — the health endpoint is added with @mcp.custom_route("/health"), which registers it on the same Starlette app that FastMCP manages internally. One port, one process, no wrapper.

---

Verification

Run the smoke-test script against a locally running server:

python src/main.py &
python scripts/verify_server.py

The script uses the MCP Python client library directly (no shelling out to the inspector) and prints real JSON results for all tools, both resources, and the prompt template.