Skip to content
BranchesTags

Repository files navigation

Captain's Navigator

An AI-Ready Campus Data Platform for CNU

Captain's Navigator is an open-source Model Context Protocol (MCP) server that gives Christopher Newport University students and faculty AI-powered access to campus data -- class schedules across all departments, major requirements, faculty directories, campus events, and more.

Ask your AI assistant "What CPSC classes are open on Tuesdays after 10am?" or "Show me Dr. Perkins' schedule this semester" and get real answers from real CNU data.

For CNU Students and Faculty

Quick Start

You do not need to install anything or write any code. Just point your AI tool at the server and sign in.

  1. Open your preferred AI tool (Claude, Codex CLI, Gemini CLI, or any MCP-compatible client)
  2. Add https://captainsnavigator.com/mcp as an MCP server
  3. Sign in with your @cnu.edu Google account
  4. Start asking questions about campus data

That's it. No API keys to copy, no config files to edit, no terminal commands to run.

Setup Guides by Client

AI Tool Guide
Claude (Desktop, Web, Mobile, CLI) docs/setup-claude.md
Codex CLI docs/setup-chatgpt.md
Gemini CLI docs/setup-gemini.md

Available Tools

Once connected, your AI assistant has access to the following tools:

Tool Description
search_classes Search the CNU class schedule by semester, discipline, course number, instructor, day, time range, building, or seat availability. Covers all departments.
get_instructor_schedule Get a professor's complete teaching schedule for a semester, including all courses, times, and locations.
find_major_requirements Look up required courses for a CNU major, including core requirements, electives, and prerequisite chains. Students follow the catalog year they entered under.
lookup_faculty Search the faculty and staff directory by name or department. Returns office location, phone, email, title, and current teaching schedule.
campus_events List upcoming campus events including lectures, career fairs, club meetings, sports, and performances. Filter by date range or category.
academic_calendar Get academic calendar dates: registration periods, add/drop deadlines, holidays, breaks, finals, commencement, and more.
room_availability Check whether a specific room or building is available at a given time slot. Useful for finding open study spaces or meeting rooms.
library_resources Search CNU library resources including databases, research guides, hours, and availability information.

Example Questions

  • "What Computer Science classes are open next semester?"
  • "When is the last day to drop a class this semester?"
  • "Is Dr. Perkins teaching C++ on Tuesdays?"
  • "What are the major requirements for Physics?"
  • "Are there any career fairs coming up this month?"
  • "Is LUTR 258 free at 2pm on Wednesdays?"

Architecture

Captain's Navigator is built on AWS using CDK (Infrastructure as Code) and designed to be cheap to run at scale.

CNU Users (Claude, Codex CLI, Gemini CLI, and other MCP-compatible clients)
    |
    | HTTPS (Streamable HTTP + MCP OAuth 2.1)
    v
CloudFront (captainsnavigator.com)
    |
    v
API Gateway (HTTP API)
    |
    |--> /mcp   --> MCP Lambda (public tools)
    |--> /auth  --> Auth Lambda (OAuth flow, Google sign-in)
    |--> /admin --> Admin Lambda (admin-tier auth, maintainer use)
    |
    v
DynamoDB (single-table) + S3 + Secrets Manager

Authentication

The server implements MCP OAuth 2.1 with Google sign-in. Users authenticate with their @cnu.edu Google account. The OAuth flow is handled natively by MCP-compatible AI tools -- users just click "Sign in with Google" in their browser and the AI tool receives tokens automatically. No manual token management required.

Project Structure

captains-navigator/
├── bin/                    # CDK app entry point
├── lib/
│   └── stacks/             # CDK stacks (auth, api, data, compute, certificate)
├── lambda/
│   ├── mcp/                # Public MCP server
│   │   ├── index.ts        # Lambda handler
│   │   ├── tools/          # One file per MCP tool
│   │   └── protocol/       # MCP Streamable HTTP implementation
│   ├── auth/               # OAuth flow handler
│   ├── admin/              # Admin MCP server (data uploads)
│   └── shared/             # Shared DB helpers and types
├── skills/                 # LLM scraping instructions (local use)
├── docs/                   # Client setup guides
└── test/                   # Jest tests

For Developers

Prerequisites

  • Node.js 18 or later
  • AWS CDK CLI (npm install -g aws-cdk)
  • An AWS account with credentials configured
  • TypeScript (installed as a dev dependency)

Installation

git clone https://github.com/gemisis/captains-navigator.git
cd captains-navigator
npm install

Build and Test

# Compile TypeScript
npm run build

# Run tests
npm test

# Lint
npm run lint

# Synthesize CloudFormation templates (does not deploy)
npm run synth

Deployment

The default domain is captainsnavigator.com. To deploy with your own domain, pass it as a CDK context variable:

# Deploy with the default domain (captainsnavigator.com)
npm run deploy

# Deploy with a custom domain
npm run deploy -- -c domainName=yourdomain.com

Your domain must have a Route 53 hosted zone in the same AWS account. CDK will automatically create the ACM certificate, DNS validation records, and a CloudFront alias record.

This deploys the full infrastructure: CloudFront distribution, API Gateway, Lambda functions, DynamoDB table, S3 buckets, and Secrets Manager entries. You will need to configure the OAuth credentials in Secrets Manager after the first deploy.

Adding a New Tool

Each public MCP tool lives in its own file under lambda/mcp/tools/. See CONTRIBUTING.md for detailed instructions on adding tools.

Admin: Data Scraping

Campus data (courses, majors, faculty, events) is updated each semester using a combination of LLM-powered scraping and the admin MCP server.

The skills/ directory contains scraping instructions that an LLM (e.g., Claude Code) follows to gather data from CNU websites. These are plain Markdown files -- not code -- that describe step-by-step how to navigate the site, extract data, and format it for upload.

The admin MCP server (/admin endpoint) provides privileged tools for uploading scraped data to DynamoDB:

Admin Tool Description
upload_courses Bulk upload course schedule data for a semester
upload_major_requirements Upload major requirement sheets
update_faculty Update the faculty and staff directory
update_events Upload campus events

The admin endpoint requires admin-tier authentication.

Connecting to the Admin Server

Add the admin MCP server to your AI tool using https://yourdomain.com/admin as the server URL. For Claude Code:

claude mcp add cnu-admin --transport http https://yourdomain.com/admin

Promoting a User to Admin

Admin tools are restricted to users with admin tier. After a user has signed in at least once (which creates their USER# record), promote them by updating the DynamoDB table directly:

aws dynamodb update-item \
  --table-name CaptainsNavigator \
  --key '{"PK": {"S": "USER#yourname@cnu.edu"}, "SK": {"S": "PROFILE"}}' \
  --update-expression 'SET tier = :t' \
  --expression-attribute-values '{":t": {"S": "admin"}}'

Replace yourname@cnu.edu with the user's CNU email. Only promote trusted maintainers — admin tools can write directly to the database.

Contributing

Contributions are welcome, especially from CNU students. See CONTRIBUTING.md for guidelines on setting up local development, code style, adding tools, and the pull request process.

License

This project is licensed under the MIT License. See LICENSE for details.

Author

Gerald McAlister -- captainsnavigator.com

About

No description, website, or topics provided.

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages