CSE330 Wiki - User contributions [en]

Web Frameworks

2026-11-11T19:27:13Z

Todd:

''The following recommendations were last updated Fall 2026''

So far in this class, you have been using PHP, HTML, and JS to run your website. You may have found that PHP can become burdensome for larger applications and difficult to use in collaboration.

Web Frameworks are an alternative method for writing web applications. Frameworks exist to make writing code more maintainable, and scalable, as well as to introduce base functionality for the application you make.

There are ''hundreds'' of frameworks available. We've categorized and listed some of the more popular below to help you decide what's right for your application.

== Common Features of Frameworks ==

=== Routing ===

A '''key difference''' between PHP and web frameworks is how routing occurs.

In PHP, if you went to an address like http://www.example.com/welcome.php then Apache would run the script located at, for example, ''/var/www/html/welcome.php''.

With routers, however, you can set arbitrary URLs to run different controller files.

=== Less Code ===

Frameworks are designed to separate your application logic from your HTML and CSS. In fact, most web frameworks automatically generate all of the HTML and CSS that you need. So, you could write a fully functional (albeit bland-looking) website in a Web Framework without writing a single line of HTML or CSS!

=== MVC Architecture ===

In PHP, your code probably ended up jumbled together in various disorganized places. This is part of the reason why many Web Frameworks choose to use a Model-View-Controller architecture.

You learned about the Model-View-Controller architecture in CSE 132. If you need a review, [[wikipedia:Model–view–controller|read the article on Wikipedia]].

A directory structure for an MVC framework might look like the following:

* '''app''' (holds MVC components)
** '''models''' (contains models)
** '''controllers''' (contains controllers)
** '''views''' (contains views)
* '''config''' (holds global server configurations)
* '''lib''' (other assorted libraries)

With an MVC architecture, a request to the server typically follows the following path:

# The server routes the request to a certain controller.
# The controller interprets the request, loading requested information from the models.
# The controller passes the information from the models to a view.
# The final view is sent to the user.

== So what do I do? ==

=== Front-end Frameworks ===
=====React=====
Get started [https://react.dev/ Here]

React is the most popular front-end framework. React uses JS to create HTML (JSX), as opposed to updating HTML with JS. This makes manipulating the DOM more efficient and smoother.

=====Vue=====
Get started [https://vuejs.org/v2/guide/ Here]

A really good happy medium between React and Angular. Not fully contained, but separates/organizes your code very nicely. Don't have to use JSX or Angular-specific methods. The code structure is better organized than React, but not as opinionated as in Angular.

Vue is partnered with PHP Laravel so a lot of the integrations are very code-friendly.

=====Angular=====
Get started [https://angular.io/guide/quickstart Here]

Not to be confused with Angular.js (the old version), Angular is the Google-developed front-end framework that competes with React and Vue. Angular has its own more opinionated code practices, making it easy for developers to understand but with a higher initial learning curve.

=== Back-end Frameworks ===
=====Express (NodeJS)=====
Get started [https://expressjs.com/en/starter/generator.html Here]

If you're planning on using a NodeJS backend, Express is a great option. Other options include [https://hapijs.com/ Hapi.js] or [https://koajs.com/ KOA] if you're already familiar with Express and want to try something else.

=====Laravel (PHP)=====
Get started [https://laravel.com/docs/5.8 Here]

Laravel is certainly the most popular PHP back-end option. If you aren't sure you want to venture over to a Node, Python, or another back-end, I urge you to try Laravel instead of vanilla PHP. Super clean, super simple, and genuinely makes writing PHP enjoyable. As mentioned above, it's coupled extremely well with Vue.js, I would recommend searching for tutorials of the two together if that's the approach you'd like to take.

=====Django (Python)=====
Get started [https://docs.djangoproject.com/en/2.1/ Here]

Django's tagline is "The Web framework for perfectionists with deadlines". Take that as you will.

Django is a fairly opinionated full-stack framework, meaning both your front-end and back-end will be written and handled by Django (as opposed to, say Express, which can integrate with whatever sort of front-end you'd like). This doesn't mean it's more difficult to learn, but it does kind of force you to learn how Django does its front-end and back-end which is why it counts for both in terms of points.

=====Flask (Python)=====
Get started [http://flask.pocoo.org/ Here]

Flask is a micro back-end framework and is extremely easy to setup. Unlike Django, Flask won't handle your Front-end for you. This leaves you the option to use any of the recommended front-end frameworks or to just use regular HTML/JS.

=====Bottle (Python)=====
Get started [https://bottlepy.org/docs/dev/ Here]

Same gist as Flask, just an alternative.

=====FastAPI (Python)=====
Get started [https://fastapi.tiangolo.com/ Here]

FastAPI is a modern Python micro framework built for writing APIs. It uses standard Python type hints to validate requests and automatically generates interactive documentation for your endpoints at /docs. Like Flask, it won’t handle your front-end for you, so pair it with any of the recommended front-end frameworks or regular HTML/JS.

=== Other and Database Info ===
=====MongoDB=====
Get started [https://docs.mongodb.com/manual/ Here]

MongoDB is a very popular no-sql based database. It may seem like a hassle to learn another type of database querying, but as soon as you realize you don't have to mess with foreign keys and it's all essentially javascript objects, it becomes a pretty attractive option. They also have free cloud databases now which is awesome because you don't have to worry about hosting a database on your computer, but much of the security is handled on their end.

=====Firebase=====
Get started [https://firebase.google.com/ Here]

Firebase is another cloud-based no-sql option. Firebase provides everything from the database itself to real-time crash reporting and analytics. Very easy to integrate into your app and get started with.

=====Other SQL=====
[https://www.postgresql.org/ PostgreSQL]

[https://mariadb.org/ MariaDB]

=== Structuring Your Project ===
Once you've outlined your project and have chosen what languages and frameworks you'd like to use, knowing where to start can be a bit daunting. We recommend a straightforward file structure similar to the following:

<source lang="bash">
client/
server/
config/
entrypoint
</source>

Depending on what frameworks you're using, it's easy to just place your full front-end framework in the client folder, all of your back-end files in the server folder, and all of your database and other configurations in the config folder. Your entry point is just a file containing the command(s) to start everything. Whether this is a package.json file, or a python file that starts your Django server, it's nice to keep it in the root of your project.

Have fun!

[[Category:Module 5]]

Web Frameworks

2026-11-11T19:27:04Z

Todd: /* Back-end Frameworks */

''The following recommendations were last updated Fall 2024''

So far in this class, you have been using PHP, HTML, and JS to run your website. You may have found that PHP can become burdensome for larger applications and difficult to use in collaboration.

Web Frameworks are an alternative method for writing web applications. Frameworks exist to make writing code more maintainable, and scalable, as well as to introduce base functionality for the application you make.

There are ''hundreds'' of frameworks available. We've categorized and listed some of the more popular below to help you decide what's right for your application.

== Common Features of Frameworks ==

=== Routing ===

A '''key difference''' between PHP and web frameworks is how routing occurs.

In PHP, if you went to an address like http://www.example.com/welcome.php then Apache would run the script located at, for example, ''/var/www/html/welcome.php''.

With routers, however, you can set arbitrary URLs to run different controller files.

=== Less Code ===

Frameworks are designed to separate your application logic from your HTML and CSS. In fact, most web frameworks automatically generate all of the HTML and CSS that you need. So, you could write a fully functional (albeit bland-looking) website in a Web Framework without writing a single line of HTML or CSS!

=== MVC Architecture ===

In PHP, your code probably ended up jumbled together in various disorganized places. This is part of the reason why many Web Frameworks choose to use a Model-View-Controller architecture.

You learned about the Model-View-Controller architecture in CSE 132. If you need a review, [[wikipedia:Model–view–controller|read the article on Wikipedia]].

A directory structure for an MVC framework might look like the following:

* '''app''' (holds MVC components)
** '''models''' (contains models)
** '''controllers''' (contains controllers)
** '''views''' (contains views)
* '''config''' (holds global server configurations)
* '''lib''' (other assorted libraries)

With an MVC architecture, a request to the server typically follows the following path:

# The server routes the request to a certain controller.
# The controller interprets the request, loading requested information from the models.
# The controller passes the information from the models to a view.
# The final view is sent to the user.

== So what do I do? ==

=== Front-end Frameworks ===
=====React=====
Get started [https://react.dev/ Here]

React is the most popular front-end framework. React uses JS to create HTML (JSX), as opposed to updating HTML with JS. This makes manipulating the DOM more efficient and smoother.

=====Vue=====
Get started [https://vuejs.org/v2/guide/ Here]

A really good happy medium between React and Angular. Not fully contained, but separates/organizes your code very nicely. Don't have to use JSX or Angular-specific methods. The code structure is better organized than React, but not as opinionated as in Angular.

Vue is partnered with PHP Laravel so a lot of the integrations are very code-friendly.

=====Angular=====
Get started [https://angular.io/guide/quickstart Here]

Not to be confused with Angular.js (the old version), Angular is the Google-developed front-end framework that competes with React and Vue. Angular has its own more opinionated code practices, making it easy for developers to understand but with a higher initial learning curve.

=== Back-end Frameworks ===
=====Express (NodeJS)=====
Get started [https://expressjs.com/en/starter/generator.html Here]

If you're planning on using a NodeJS backend, Express is a great option. Other options include [https://hapijs.com/ Hapi.js] or [https://koajs.com/ KOA] if you're already familiar with Express and want to try something else.

=====Laravel (PHP)=====
Get started [https://laravel.com/docs/5.8 Here]

Laravel is certainly the most popular PHP back-end option. If you aren't sure you want to venture over to a Node, Python, or another back-end, I urge you to try Laravel instead of vanilla PHP. Super clean, super simple, and genuinely makes writing PHP enjoyable. As mentioned above, it's coupled extremely well with Vue.js, I would recommend searching for tutorials of the two together if that's the approach you'd like to take.

=====Django (Python)=====
Get started [https://docs.djangoproject.com/en/2.1/ Here]

Django's tagline is "The Web framework for perfectionists with deadlines". Take that as you will.

Django is a fairly opinionated full-stack framework, meaning both your front-end and back-end will be written and handled by Django (as opposed to, say Express, which can integrate with whatever sort of front-end you'd like). This doesn't mean it's more difficult to learn, but it does kind of force you to learn how Django does its front-end and back-end which is why it counts for both in terms of points.

=====Flask (Python)=====
Get started [http://flask.pocoo.org/ Here]

Flask is a micro back-end framework and is extremely easy to setup. Unlike Django, Flask won't handle your Front-end for you. This leaves you the option to use any of the recommended front-end frameworks or to just use regular HTML/JS.

=====Bottle (Python)=====
Get started [https://bottlepy.org/docs/dev/ Here]

Same gist as Flask, just an alternative.

=====FastAPI (Python)=====
Get started [https://fastapi.tiangolo.com/ Here]

FastAPI is a modern Python micro framework built for writing APIs. It uses standard Python type hints to validate requests and automatically generates interactive documentation for your endpoints at /docs. Like Flask, it won’t handle your front-end for you, so pair it with any of the recommended front-end frameworks or regular HTML/JS.

=== Other and Database Info ===
=====MongoDB=====
Get started [https://docs.mongodb.com/manual/ Here]

MongoDB is a very popular no-sql based database. It may seem like a hassle to learn another type of database querying, but as soon as you realize you don't have to mess with foreign keys and it's all essentially javascript objects, it becomes a pretty attractive option. They also have free cloud databases now which is awesome because you don't have to worry about hosting a database on your computer, but much of the security is handled on their end.

=====Firebase=====
Get started [https://firebase.google.com/ Here]

Firebase is another cloud-based no-sql option. Firebase provides everything from the database itself to real-time crash reporting and analytics. Very easy to integrate into your app and get started with.

=====Other SQL=====
[https://www.postgresql.org/ PostgreSQL]

[https://mariadb.org/ MariaDB]

=== Structuring Your Project ===
Once you've outlined your project and have chosen what languages and frameworks you'd like to use, knowing where to start can be a bit daunting. We recommend a straightforward file structure similar to the following:

<source lang="bash">
client/
server/
config/
entrypoint
</source>

Depending on what frameworks you're using, it's easy to just place your full front-end framework in the client folder, all of your back-end files in the server folder, and all of your database and other configurations in the config folder. Your entry point is just a file containing the command(s) to start everything. Whether this is a package.json file, or a python file that starts your Django server, it's nice to keep it in the root of your project.

Have fun!

[[Category:Module 5]]

Module 6

2026-11-03T14:59:18Z

Todd: /* Go to Developer Settings */

__NOTOC__
In Module 6, you will learn the fundamentals of Python, a widely used scripting language, and Regular Expressions, which provide powerful tools for text processing. You will also explore the Model Context Protocol (MCP), a framework that allows software tools to communicate with large language models (LLMs).

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 6]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user-controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
** <code>get_player_stats</code>: Retrieve and show batting averages for a player.
** <code>get_team_roster</code>: List all players from a given season.
** <code>get_top_players</code>: Sort and show the top hitters.
** <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''MCP Toolkit''' → '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
** <code>get_player_stats</code>: Show batting averages for one player
** <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
** <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
** <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import logging
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Configure logging to stderr
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
stream=sys.stderr,
)
logger = logging.getLogger("CardinalsMCP-server")

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

You can find an explanation of the hello function in the [[MCP_Fundamentals#Example MCP Tool: hello|MCP Fundamentals]]

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Desktop app''' tab in the left sidebar.
Then scroll all the way down to Extensions and select '''Manage'''.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run the hello tool in the chat of Claude Desktop:

<pre>"Use CardinalsMCP to say hello"</pre>

If everything is working correctly, you should see a "Hello CSE 3300 Student" response.

After you have implemented the MCP tools, you can run commands like this:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>

==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

Node.JS

2026-10-21T22:38:56Z

Todd: /* Installing Packages */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes in real-time? A PHP+AJAX approach could struggle without a lot of effort on your part.

It is situations like these that Node.js comes to the rescue.

Node.js is a '''JavaScript runtime''' (built on Chrome's V8 engine) that lets you run JavaScript outside the browser. Frameworks like Express run ''on top'' of Node.js.

In general, JavaScript frameworks are trendy; it can be hard to keep up with the new cool thing. In fact, there's a joke website https://dayssincelastjavascriptframework.com/ that "tracks" how long it's been since a new framework has come out.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.js uses this execution model at its core.

A simple way to think about Node:

* Node is designed to handle lots of connections efficiently.
* Instead of waiting for slow operations (network, file system, database) to finish, Node starts the work and continues doing other things.
* When the slow operation finishes, Node runs some code to handle the result.

Historically, the core idea was the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time.

''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server (or force you to provision much more hardware than you want).

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!''

The code occurs in two parts:

# Start the query.
# ''When the query is complete,'' run the callback function.

In Node.js, callback functions are usually passed one or more parameters.

=== Modern Node style: Promises and async/await ===

Callbacks are still important to understand (they explain why Node "works"), but modern Node code often uses '''Promises''' and '''async/await''' because they make programs easier to read and debug.

Conceptually:

<source lang="javascript">
// Promise + async/await pseudo-code

const data = await database.query("select * from news");
console.log(data[0].title);
</source>

This is still non-blocking behind the scenes—it's just nicer syntax for “start work now, continue later when it finishes.”

=== One thread? Concurrency? ===

You will often hear that Node “runs in one thread.” The key point for this course is:

* You can handle many concurrent connections without making a thread per client.
* The server remains responsive because it avoids blocking on slow I/O.

(There are deeper details in the real Node event loop model, but the above understanding will serve you well for CSE 3300.)

== Installing Node.js ==

We will install Node using '''nvm''' (Node Version Manager). This makes it easy to switch Node versions and consistently use the current LTS version.

Run the following commands:

<source lang="bash">
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
$ source ~/.bashrc
$ nvm install --lts
$ node -v
$ npm -v
</source>

'''Note:''' As of October 2026, Node 24 is the Active LTS line. Using `nvm install --lts` means you do not have to hardcode a specific major version in the instructions.

== Your First Node.js Application: Hello World ==

Let's try the classic HTTP server example.

=== Modern version (ES Modules) ===

Create a file named `hello.js`:

<source lang="javascript">
import http from "node:http";

http.createServer((req, res) => {
res.writeHead(200, { "Content-Type": "text/plain" });
res.end("Hello World\n");
}).listen(3456);

console.log("Server running at http://localhost:3456/");
</source>

To run it:

<source lang="bash">
$ node hello.js
</source>

'''Note:''' If you're running the code from your EC2 instance, you will need to open port 3456.

=== Enabling ES Modules (important!) ===

Modern Node supports both the older '''CommonJS''' module system (require) and the newer JavaScript standard '''ES Modules''' (import/export). ES Modules are the direction modern JavaScript has moved (and they match browser JavaScript).

To tell Node to treat `.js` files as ES Modules, add this to `package.json` in your project directory:

<source lang="javascript">
{
"type": "module"
}
</source>

If you do not do this, Node may treat `.js` files as CommonJS by default, and `import ...` may fail.

=== Walkthrough of the Hello World example ===

* <code>import http from "node:http";</code> enables us to use Node's built-in HTTP server library. Unlike PHP, Node does not automatically load lots of server features for you. You explicitly import what you need.
* <code>http.createServer((req, res) => { ... }).listen(3456);</code> listens for HTTP connections on port 3456. The callback function runs whenever a connection is made.
* <code>res.writeHead(200, { "Content-Type": "text/plain" });</code> sets the HTTP response code and headers.
* <code>res.end("Hello World\n");</code> writes the response body and ends the response.

Notice the use of non-blocking behavior even in this simple example: ''when a connection is made'', the callback runs with the parameters associated with that connection.

== A Static File Server Using Node.js ==

Node.js does not automatically serve up static files in the way that Apache/PHP does. We need to either:

* use a framework like Express (common in industry), or
* write a simple static file server ourselves (great for understanding how servers work)

We'll do the second option here.

=== Installing Packages ===

In order for the example code below to work, you need the '''mime''' package (it helps map filenames to Content-Type headers). The `mime` package is actively maintained.

In the directory where you will save your Node.js file:

<source lang="bash">
$ npm init -y
$ npm install mime
</source>

''npm'' is the package manager for Node.js. It installs dependencies locally (inside `node_modules`) by default, which is a good thing: it lets different projects use different versions of the same dependency.

'''Note:''' When using npm to install local dependencies, '''do not use sudo'''. It can break file permissions in your project directory.

=== Static Fileserver Code (Modern ESM + async/await) ===

The following code makes an HTTP server on port 3456 that serves all static files inside <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O.

<source lang="javascript">
import http from "node:http";
import path from "node:path";
import { readFile } from "node:fs/promises";
import { existsSync } from "node:fs";
import mime from "mime";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const STATIC_DIR = "<STATIC DIRECTORY NAME>";

const app = http.createServer(async (req, resp) => {
try {
// Parse the path the browser requested
const urlPath = new URL(req.url, "http://localhost").pathname;
const filename = path.join(__dirname, STATIC_DIR, decodeURIComponent(urlPath));

// If file doesn't exist, return 404
if (!existsSync(filename)) {
resp.writeHead(404, { "Content-Type": "text/plain" });
resp.end("Requested file not found: " + filename);
return;
}

// Read the file (non-blocking I/O via promises)
const data = await readFile(filename);

// Determine content type
const mimetype = mime.getType(filename) || "application/octet-stream";
resp.writeHead(200, { "Content-Type": mimetype });
resp.end(data);
} catch (err) {
// File exists but isn't readable or some other error occurred
resp.writeHead(500, { "Content-Type": "text/plain" });
resp.end("Internal server error: could not read file");
}
});

app.listen(3456);
</source>

==== A few important notes about the modern version ====

* We use <code>node:fs/promises</code> so we can write file I/O using async/await.
* In ES Modules, <code>__dirname</code> is not automatically defined, so we compute it using <code>import.meta.url</code>.
* This server is intentionally simple for instructional purposes.

'''Security note:''' A production static server must protect against directory traversal attacks (paths like <code>../</code>). For this course example, we focus on learning the mechanics first.

=== Port 3456 ===

We are running our server on port 3456 instead of port 80. We therefore need to open our Node.js application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work the first time. ''Why?''

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 back in Module 2? We need to do the same procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.js Security ==

Just because we're writing in JavaScript doesn't mean we can forget about the security practices you've been learning in CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

== Node.js Conventions ==

There ought to be a standard way to save metadata about your app, right? Node projects use a <code>package.json</code> file for this.

To create one quickly:

<source lang="bash">
$ npm init -y
</source>

One nice feature of <code>package.json</code> is that it automatically handles dependencies. For example:

<source lang="javascript">
"dependencies": {
"mime": "^4.1.0",
"socket.io": "^4.8.0"
}
</source>

Then when you run:

<source lang="bash">
$ npm install
</source>

npm installs the dependencies for you.

'''Tip:''' Modern npm automatically saves dependencies when you run <code>npm install package-name</code>. The older <code>--save</code> flag is no longer necessary.

[[Category:Module 5]]

Node.JS

2026-10-21T22:38:12Z

Todd: /* Installing Node.js */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes in real-time? A PHP+AJAX approach could struggle without a lot of effort on your part.

It is situations like these that Node.js comes to the rescue.

Node.js is a '''JavaScript runtime''' (built on Chrome's V8 engine) that lets you run JavaScript outside the browser. Frameworks like Express run ''on top'' of Node.js.

In general, JavaScript frameworks are trendy; it can be hard to keep up with the new cool thing. In fact, there's a joke website https://dayssincelastjavascriptframework.com/ that "tracks" how long it's been since a new framework has come out.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.js uses this execution model at its core.

A simple way to think about Node:

* Node is designed to handle lots of connections efficiently.
* Instead of waiting for slow operations (network, file system, database) to finish, Node starts the work and continues doing other things.
* When the slow operation finishes, Node runs some code to handle the result.

Historically, the core idea was the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time.

''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server (or force you to provision much more hardware than you want).

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!''

The code occurs in two parts:

# Start the query.
# ''When the query is complete,'' run the callback function.

In Node.js, callback functions are usually passed one or more parameters.

=== Modern Node style: Promises and async/await ===

Callbacks are still important to understand (they explain why Node "works"), but modern Node code often uses '''Promises''' and '''async/await''' because they make programs easier to read and debug.

Conceptually:

<source lang="javascript">
// Promise + async/await pseudo-code

const data = await database.query("select * from news");
console.log(data[0].title);
</source>

This is still non-blocking behind the scenes—it's just nicer syntax for “start work now, continue later when it finishes.”

=== One thread? Concurrency? ===

You will often hear that Node “runs in one thread.” The key point for this course is:

* You can handle many concurrent connections without making a thread per client.
* The server remains responsive because it avoids blocking on slow I/O.

(There are deeper details in the real Node event loop model, but the above understanding will serve you well for CSE 3300.)

== Installing Node.js ==

We will install Node using '''nvm''' (Node Version Manager). This makes it easy to switch Node versions and consistently use the current LTS version.

Run the following commands:

<source lang="bash">
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
$ source ~/.bashrc
$ nvm install --lts
$ node -v
$ npm -v
</source>

'''Note:''' As of October 2026, Node 24 is the Active LTS line. Using `nvm install --lts` means you do not have to hardcode a specific major version in the instructions.

== Your First Node.js Application: Hello World ==

Let's try the classic HTTP server example.

=== Modern version (ES Modules) ===

Create a file named `hello.js`:

<source lang="javascript">
import http from "node:http";

http.createServer((req, res) => {
res.writeHead(200, { "Content-Type": "text/plain" });
res.end("Hello World\n");
}).listen(3456);

console.log("Server running at http://localhost:3456/");
</source>

To run it:

<source lang="bash">
$ node hello.js
</source>

'''Note:''' If you're running the code from your EC2 instance, you will need to open port 3456.

=== Enabling ES Modules (important!) ===

Modern Node supports both the older '''CommonJS''' module system (require) and the newer JavaScript standard '''ES Modules''' (import/export). ES Modules are the direction modern JavaScript has moved (and they match browser JavaScript).

To tell Node to treat `.js` files as ES Modules, add this to `package.json` in your project directory:

<source lang="javascript">
{
"type": "module"
}
</source>

If you do not do this, Node may treat `.js` files as CommonJS by default, and `import ...` may fail.

=== Walkthrough of the Hello World example ===

* <code>import http from "node:http";</code> enables us to use Node's built-in HTTP server library. Unlike PHP, Node does not automatically load lots of server features for you. You explicitly import what you need.
* <code>http.createServer((req, res) => { ... }).listen(3456);</code> listens for HTTP connections on port 3456. The callback function runs whenever a connection is made.
* <code>res.writeHead(200, { "Content-Type": "text/plain" });</code> sets the HTTP response code and headers.
* <code>res.end("Hello World\n");</code> writes the response body and ends the response.

Notice the use of non-blocking behavior even in this simple example: ''when a connection is made'', the callback runs with the parameters associated with that connection.

== A Static File Server Using Node.js ==

Node.js does not automatically serve up static files in the way that Apache/PHP does. We need to either:

* use a framework like Express (common in industry), or
* write a simple static file server ourselves (great for understanding how servers work)

We'll do the second option here.

=== Installing Packages ===

In order for the example code below to work, you need the '''mime''' package (it helps map filenames to Content-Type headers). The `mime` package is actively maintained. :contentReference[oaicite:9]{index=9}

In the directory where you will save your Node.js file:

<source lang="bash">
$ npm init -y
$ npm install mime
</source>

''npm'' is the package manager for Node.js. It installs dependencies locally (inside `node_modules`) by default, which is a good thing: it lets different projects use different versions of the same dependency.

'''Note:''' When using npm to install local dependencies, '''do not use sudo'''. It can break file permissions in your project directory.

=== Static Fileserver Code (Modern ESM + async/await) ===

The following code makes an HTTP server on port 3456 that serves all static files inside <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O.

<source lang="javascript">
import http from "node:http";
import path from "node:path";
import { readFile } from "node:fs/promises";
import { existsSync } from "node:fs";
import mime from "mime";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const STATIC_DIR = "<STATIC DIRECTORY NAME>";

const app = http.createServer(async (req, resp) => {
try {
// Parse the path the browser requested
const urlPath = new URL(req.url, "http://localhost").pathname;
const filename = path.join(__dirname, STATIC_DIR, decodeURIComponent(urlPath));

// If file doesn't exist, return 404
if (!existsSync(filename)) {
resp.writeHead(404, { "Content-Type": "text/plain" });
resp.end("Requested file not found: " + filename);
return;
}

// Read the file (non-blocking I/O via promises)
const data = await readFile(filename);

// Determine content type
const mimetype = mime.getType(filename) || "application/octet-stream";
resp.writeHead(200, { "Content-Type": mimetype });
resp.end(data);
} catch (err) {
// File exists but isn't readable or some other error occurred
resp.writeHead(500, { "Content-Type": "text/plain" });
resp.end("Internal server error: could not read file");
}
});

app.listen(3456);
</source>

==== A few important notes about the modern version ====

* We use <code>node:fs/promises</code> so we can write file I/O using async/await.
* In ES Modules, <code>__dirname</code> is not automatically defined, so we compute it using <code>import.meta.url</code>.
* This server is intentionally simple for instructional purposes.

'''Security note:''' A production static server must protect against directory traversal attacks (paths like <code>../</code>). For this course example, we focus on learning the mechanics first.

=== Port 3456 ===

We are running our server on port 3456 instead of port 80. We therefore need to open our Node.js application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work the first time. ''Why?''

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 back in Module 2? We need to do the same procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.js Security ==

Just because we're writing in JavaScript doesn't mean we can forget about the security practices you've been learning in CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

== Node.js Conventions ==

There ought to be a standard way to save metadata about your app, right? Node projects use a <code>package.json</code> file for this.

To create one quickly:

<source lang="bash">
$ npm init -y
</source>

One nice feature of <code>package.json</code> is that it automatically handles dependencies. For example:

<source lang="javascript">
"dependencies": {
"mime": "^4.1.0",
"socket.io": "^4.8.0"
}
</source>

Then when you run:

<source lang="bash">
$ npm install
</source>

npm installs the dependencies for you.

'''Tip:''' Modern npm automatically saves dependencies when you run <code>npm install package-name</code>. The older <code>--save</code> flag is no longer necessary.

[[Category:Module 5]]

Node.JS

2026-10-21T22:36:45Z

Todd: /* Installing Node.js */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes in real-time? A PHP+AJAX approach could struggle without a lot of effort on your part.

It is situations like these that Node.js comes to the rescue.

Node.js is a '''JavaScript runtime''' (built on Chrome's V8 engine) that lets you run JavaScript outside the browser. Frameworks like Express run ''on top'' of Node.js.

In general, JavaScript frameworks are trendy; it can be hard to keep up with the new cool thing. In fact, there's a joke website https://dayssincelastjavascriptframework.com/ that "tracks" how long it's been since a new framework has come out.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.js uses this execution model at its core.

A simple way to think about Node:

* Node is designed to handle lots of connections efficiently.
* Instead of waiting for slow operations (network, file system, database) to finish, Node starts the work and continues doing other things.
* When the slow operation finishes, Node runs some code to handle the result.

Historically, the core idea was the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time.

''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server (or force you to provision much more hardware than you want).

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!''

The code occurs in two parts:

# Start the query.
# ''When the query is complete,'' run the callback function.

In Node.js, callback functions are usually passed one or more parameters.

=== Modern Node style: Promises and async/await ===

Callbacks are still important to understand (they explain why Node "works"), but modern Node code often uses '''Promises''' and '''async/await''' because they make programs easier to read and debug.

Conceptually:

<source lang="javascript">
// Promise + async/await pseudo-code

const data = await database.query("select * from news");
console.log(data[0].title);
</source>

This is still non-blocking behind the scenes—it's just nicer syntax for “start work now, continue later when it finishes.”

=== One thread? Concurrency? ===

You will often hear that Node “runs in one thread.” The key point for this course is:

* You can handle many concurrent connections without making a thread per client.
* The server remains responsive because it avoids blocking on slow I/O.

(There are deeper details in the real Node event loop model, but the above understanding will serve you well for CSE 3300.)

== Installing Node.js ==

We will install Node using '''nvm''' (Node Version Manager). This makes it easy to switch Node versions and consistently use the current LTS version.

Run the following commands:

<source lang="bash">
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
$ source ~/.bashrc
$ nvm install --lts
$ node -v
$ npm -v
</source>

'''Note:''' As of February 2026, Node 24 is the Active LTS line. Using `nvm install --lts` means you do not have to hardcode a specific major version in the instructions.

== Your First Node.js Application: Hello World ==

Let's try the classic HTTP server example.

=== Modern version (ES Modules) ===

Create a file named `hello.js`:

<source lang="javascript">
import http from "node:http";

http.createServer((req, res) => {
res.writeHead(200, { "Content-Type": "text/plain" });
res.end("Hello World\n");
}).listen(3456);

console.log("Server running at http://localhost:3456/");
</source>

To run it:

<source lang="bash">
$ node hello.js
</source>

'''Note:''' If you're running the code from your EC2 instance, you will need to open port 3456.

=== Enabling ES Modules (important!) ===

Modern Node supports both the older '''CommonJS''' module system (require) and the newer JavaScript standard '''ES Modules''' (import/export). ES Modules are the direction modern JavaScript has moved (and they match browser JavaScript).

To tell Node to treat `.js` files as ES Modules, add this to `package.json` in your project directory:

<source lang="javascript">
{
"type": "module"
}
</source>

If you do not do this, Node may treat `.js` files as CommonJS by default, and `import ...` may fail.

=== Walkthrough of the Hello World example ===

* <code>import http from "node:http";</code> enables us to use Node's built-in HTTP server library. Unlike PHP, Node does not automatically load lots of server features for you. You explicitly import what you need.
* <code>http.createServer((req, res) => { ... }).listen(3456);</code> listens for HTTP connections on port 3456. The callback function runs whenever a connection is made.
* <code>res.writeHead(200, { "Content-Type": "text/plain" });</code> sets the HTTP response code and headers.
* <code>res.end("Hello World\n");</code> writes the response body and ends the response.

Notice the use of non-blocking behavior even in this simple example: ''when a connection is made'', the callback runs with the parameters associated with that connection.

== A Static File Server Using Node.js ==

Node.js does not automatically serve up static files in the way that Apache/PHP does. We need to either:

* use a framework like Express (common in industry), or
* write a simple static file server ourselves (great for understanding how servers work)

We'll do the second option here.

=== Installing Packages ===

In order for the example code below to work, you need the '''mime''' package (it helps map filenames to Content-Type headers). The `mime` package is actively maintained. :contentReference[oaicite:9]{index=9}

In the directory where you will save your Node.js file:

<source lang="bash">
$ npm init -y
$ npm install mime
</source>

''npm'' is the package manager for Node.js. It installs dependencies locally (inside `node_modules`) by default, which is a good thing: it lets different projects use different versions of the same dependency.

'''Note:''' When using npm to install local dependencies, '''do not use sudo'''. It can break file permissions in your project directory.

=== Static Fileserver Code (Modern ESM + async/await) ===

The following code makes an HTTP server on port 3456 that serves all static files inside <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O.

<source lang="javascript">
import http from "node:http";
import path from "node:path";
import { readFile } from "node:fs/promises";
import { existsSync } from "node:fs";
import mime from "mime";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const STATIC_DIR = "<STATIC DIRECTORY NAME>";

const app = http.createServer(async (req, resp) => {
try {
// Parse the path the browser requested
const urlPath = new URL(req.url, "http://localhost").pathname;
const filename = path.join(__dirname, STATIC_DIR, decodeURIComponent(urlPath));

// If file doesn't exist, return 404
if (!existsSync(filename)) {
resp.writeHead(404, { "Content-Type": "text/plain" });
resp.end("Requested file not found: " + filename);
return;
}

// Read the file (non-blocking I/O via promises)
const data = await readFile(filename);

// Determine content type
const mimetype = mime.getType(filename) || "application/octet-stream";
resp.writeHead(200, { "Content-Type": mimetype });
resp.end(data);
} catch (err) {
// File exists but isn't readable or some other error occurred
resp.writeHead(500, { "Content-Type": "text/plain" });
resp.end("Internal server error: could not read file");
}
});

app.listen(3456);
</source>

==== A few important notes about the modern version ====

* We use <code>node:fs/promises</code> so we can write file I/O using async/await.
* In ES Modules, <code>__dirname</code> is not automatically defined, so we compute it using <code>import.meta.url</code>.
* This server is intentionally simple for instructional purposes.

'''Security note:''' A production static server must protect against directory traversal attacks (paths like <code>../</code>). For this course example, we focus on learning the mechanics first.

=== Port 3456 ===

We are running our server on port 3456 instead of port 80. We therefore need to open our Node.js application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work the first time. ''Why?''

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 back in Module 2? We need to do the same procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.js Security ==

Just because we're writing in JavaScript doesn't mean we can forget about the security practices you've been learning in CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

== Node.js Conventions ==

There ought to be a standard way to save metadata about your app, right? Node projects use a <code>package.json</code> file for this.

To create one quickly:

<source lang="bash">
$ npm init -y
</source>

One nice feature of <code>package.json</code> is that it automatically handles dependencies. For example:

<source lang="javascript">
"dependencies": {
"mime": "^4.1.0",
"socket.io": "^4.8.0"
}
</source>

Then when you run:

<source lang="bash">
$ npm install
</source>

npm installs the dependencies for you.

'''Tip:''' Modern npm automatically saves dependencies when you run <code>npm install package-name</code>. The older <code>--save</code> flag is no longer necessary.

[[Category:Module 5]]

Node.JS

2026-10-21T22:34:37Z

Todd: /* Enabling ES Modules (important!) */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes in real-time? A PHP+AJAX approach could struggle without a lot of effort on your part.

It is situations like these that Node.js comes to the rescue.

Node.js is a '''JavaScript runtime''' (built on Chrome's V8 engine) that lets you run JavaScript outside the browser. Frameworks like Express run ''on top'' of Node.js.

In general, JavaScript frameworks are trendy; it can be hard to keep up with the new cool thing. In fact, there's a joke website https://dayssincelastjavascriptframework.com/ that "tracks" how long it's been since a new framework has come out.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.js uses this execution model at its core.

A simple way to think about Node:

* Node is designed to handle lots of connections efficiently.
* Instead of waiting for slow operations (network, file system, database) to finish, Node starts the work and continues doing other things.
* When the slow operation finishes, Node runs some code to handle the result.

Historically, the core idea was the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time.

''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server (or force you to provision much more hardware than you want).

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!''

The code occurs in two parts:

# Start the query.
# ''When the query is complete,'' run the callback function.

In Node.js, callback functions are usually passed one or more parameters.

=== Modern Node style: Promises and async/await ===

Callbacks are still important to understand (they explain why Node "works"), but modern Node code often uses '''Promises''' and '''async/await''' because they make programs easier to read and debug.

Conceptually:

<source lang="javascript">
// Promise + async/await pseudo-code

const data = await database.query("select * from news");
console.log(data[0].title);
</source>

This is still non-blocking behind the scenes—it's just nicer syntax for “start work now, continue later when it finishes.”

=== One thread? Concurrency? ===

You will often hear that Node “runs in one thread.” The key point for this course is:

* You can handle many concurrent connections without making a thread per client.
* The server remains responsive because it avoids blocking on slow I/O.

(There are deeper details in the real Node event loop model, but the above understanding will serve you well for CSE 3300.)

== Installing Node.js ==

We will install Node using '''nvm''' (Node Version Manager). This makes it easy to switch Node versions and consistently use the current LTS version. :contentReference[oaicite:4]{index=4}

Run the following commands:

<source lang="bash">
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
$ source ~/.bashrc
$ nvm install --lts
$ node -v
$ npm -v
</source>

'''Note:''' As of February 2026, Node 24 is the Active LTS line. Using `nvm install --lts` means you do not have to hardcode a specific major version in the instructions. :contentReference[oaicite:6]{index=6}

== Your First Node.js Application: Hello World ==

Let's try the classic HTTP server example.

=== Modern version (ES Modules) ===

Create a file named `hello.js`:

<source lang="javascript">
import http from "node:http";

http.createServer((req, res) => {
res.writeHead(200, { "Content-Type": "text/plain" });
res.end("Hello World\n");
}).listen(3456);

console.log("Server running at http://localhost:3456/");
</source>

To run it:

<source lang="bash">
$ node hello.js
</source>

'''Note:''' If you're running the code from your EC2 instance, you will need to open port 3456.

=== Enabling ES Modules (important!) ===

Modern Node supports both the older '''CommonJS''' module system (require) and the newer JavaScript standard '''ES Modules''' (import/export). ES Modules are the direction modern JavaScript has moved (and they match browser JavaScript).

To tell Node to treat `.js` files as ES Modules, add this to `package.json` in your project directory:

<source lang="javascript">
{
"type": "module"
}
</source>

If you do not do this, Node may treat `.js` files as CommonJS by default, and `import ...` may fail.

=== Walkthrough of the Hello World example ===

* <code>import http from "node:http";</code> enables us to use Node's built-in HTTP server library. Unlike PHP, Node does not automatically load lots of server features for you. You explicitly import what you need.
* <code>http.createServer((req, res) => { ... }).listen(3456);</code> listens for HTTP connections on port 3456. The callback function runs whenever a connection is made.
* <code>res.writeHead(200, { "Content-Type": "text/plain" });</code> sets the HTTP response code and headers.
* <code>res.end("Hello World\n");</code> writes the response body and ends the response.

Notice the use of non-blocking behavior even in this simple example: ''when a connection is made'', the callback runs with the parameters associated with that connection.

== A Static File Server Using Node.js ==

Node.js does not automatically serve up static files in the way that Apache/PHP does. We need to either:

* use a framework like Express (common in industry), or
* write a simple static file server ourselves (great for understanding how servers work)

We'll do the second option here.

=== Installing Packages ===

In order for the example code below to work, you need the '''mime''' package (it helps map filenames to Content-Type headers). The `mime` package is actively maintained. :contentReference[oaicite:9]{index=9}

In the directory where you will save your Node.js file:

<source lang="bash">
$ npm init -y
$ npm install mime
</source>

''npm'' is the package manager for Node.js. It installs dependencies locally (inside `node_modules`) by default, which is a good thing: it lets different projects use different versions of the same dependency.

'''Note:''' When using npm to install local dependencies, '''do not use sudo'''. It can break file permissions in your project directory.

=== Static Fileserver Code (Modern ESM + async/await) ===

The following code makes an HTTP server on port 3456 that serves all static files inside <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O.

<source lang="javascript">
import http from "node:http";
import path from "node:path";
import { readFile } from "node:fs/promises";
import { existsSync } from "node:fs";
import mime from "mime";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const STATIC_DIR = "<STATIC DIRECTORY NAME>";

const app = http.createServer(async (req, resp) => {
try {
// Parse the path the browser requested
const urlPath = new URL(req.url, "http://localhost").pathname;
const filename = path.join(__dirname, STATIC_DIR, decodeURIComponent(urlPath));

// If file doesn't exist, return 404
if (!existsSync(filename)) {
resp.writeHead(404, { "Content-Type": "text/plain" });
resp.end("Requested file not found: " + filename);
return;
}

// Read the file (non-blocking I/O via promises)
const data = await readFile(filename);

// Determine content type
const mimetype = mime.getType(filename) || "application/octet-stream";
resp.writeHead(200, { "Content-Type": mimetype });
resp.end(data);
} catch (err) {
// File exists but isn't readable or some other error occurred
resp.writeHead(500, { "Content-Type": "text/plain" });
resp.end("Internal server error: could not read file");
}
});

app.listen(3456);
</source>

==== A few important notes about the modern version ====

* We use <code>node:fs/promises</code> so we can write file I/O using async/await.
* In ES Modules, <code>__dirname</code> is not automatically defined, so we compute it using <code>import.meta.url</code>.
* This server is intentionally simple for instructional purposes.

'''Security note:''' A production static server must protect against directory traversal attacks (paths like <code>../</code>). For this course example, we focus on learning the mechanics first.

=== Port 3456 ===

We are running our server on port 3456 instead of port 80. We therefore need to open our Node.js application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work the first time. ''Why?''

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 back in Module 2? We need to do the same procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.js Security ==

Just because we're writing in JavaScript doesn't mean we can forget about the security practices you've been learning in CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

== Node.js Conventions ==

There ought to be a standard way to save metadata about your app, right? Node projects use a <code>package.json</code> file for this.

To create one quickly:

<source lang="bash">
$ npm init -y
</source>

One nice feature of <code>package.json</code> is that it automatically handles dependencies. For example:

<source lang="javascript">
"dependencies": {
"mime": "^4.1.0",
"socket.io": "^4.8.0"
}
</source>

Then when you run:

<source lang="bash">
$ npm install
</source>

npm installs the dependencies for you.

'''Tip:''' Modern npm automatically saves dependencies when you run <code>npm install package-name</code>. The older <code>--save</code> flag is no longer necessary.

[[Category:Module 5]]

Node.JS

2026-10-21T22:34:24Z

Todd: /* Enabling ES Modules (important!) */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes in real-time? A PHP+AJAX approach could struggle without a lot of effort on your part.

It is situations like these that Node.js comes to the rescue.

Node.js is a '''JavaScript runtime''' (built on Chrome's V8 engine) that lets you run JavaScript outside the browser. Frameworks like Express run ''on top'' of Node.js.

In general, JavaScript frameworks are trendy; it can be hard to keep up with the new cool thing. In fact, there's a joke website https://dayssincelastjavascriptframework.com/ that "tracks" how long it's been since a new framework has come out.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.js uses this execution model at its core.

A simple way to think about Node:

* Node is designed to handle lots of connections efficiently.
* Instead of waiting for slow operations (network, file system, database) to finish, Node starts the work and continues doing other things.
* When the slow operation finishes, Node runs some code to handle the result.

Historically, the core idea was the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time.

''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server (or force you to provision much more hardware than you want).

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!''

The code occurs in two parts:

# Start the query.
# ''When the query is complete,'' run the callback function.

In Node.js, callback functions are usually passed one or more parameters.

=== Modern Node style: Promises and async/await ===

Callbacks are still important to understand (they explain why Node "works"), but modern Node code often uses '''Promises''' and '''async/await''' because they make programs easier to read and debug.

Conceptually:

<source lang="javascript">
// Promise + async/await pseudo-code

const data = await database.query("select * from news");
console.log(data[0].title);
</source>

This is still non-blocking behind the scenes—it's just nicer syntax for “start work now, continue later when it finishes.”

=== One thread? Concurrency? ===

You will often hear that Node “runs in one thread.” The key point for this course is:

* You can handle many concurrent connections without making a thread per client.
* The server remains responsive because it avoids blocking on slow I/O.

(There are deeper details in the real Node event loop model, but the above understanding will serve you well for CSE 3300.)

== Installing Node.js ==

We will install Node using '''nvm''' (Node Version Manager). This makes it easy to switch Node versions and consistently use the current LTS version. :contentReference[oaicite:4]{index=4}

Run the following commands:

<source lang="bash">
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
$ source ~/.bashrc
$ nvm install --lts
$ node -v
$ npm -v
</source>

'''Note:''' As of February 2026, Node 24 is the Active LTS line. Using `nvm install --lts` means you do not have to hardcode a specific major version in the instructions. :contentReference[oaicite:6]{index=6}

== Your First Node.js Application: Hello World ==

Let's try the classic HTTP server example.

=== Modern version (ES Modules) ===

Create a file named `hello.js`:

<source lang="javascript">
import http from "node:http";

http.createServer((req, res) => {
res.writeHead(200, { "Content-Type": "text/plain" });
res.end("Hello World\n");
}).listen(3456);

console.log("Server running at http://localhost:3456/");
</source>

To run it:

<source lang="bash">
$ node hello.js
</source>

'''Note:''' If you're running the code from your EC2 instance, you will need to open port 3456.

=== Enabling ES Modules (important!) ===

Modern Node supports both the older '''CommonJS''' module system (require) and the newer JavaScript standard '''ES Modules''' (import/export). ES Modules are the direction modern JavaScript has moved (and they match browser JavaScript).

To tell Node to treat `.js` files as ES Modules, add this to `package.json` in your project directory:

<source lang="javascript">
{
"type": "module"
}
</source>
:contentReference[oaicite:8]{index=8}

If you do not do this, Node may treat `.js` files as CommonJS by default, and `import ...` may fail.

=== Walkthrough of the Hello World example ===

* <code>import http from "node:http";</code> enables us to use Node's built-in HTTP server library. Unlike PHP, Node does not automatically load lots of server features for you. You explicitly import what you need.
* <code>http.createServer((req, res) => { ... }).listen(3456);</code> listens for HTTP connections on port 3456. The callback function runs whenever a connection is made.
* <code>res.writeHead(200, { "Content-Type": "text/plain" });</code> sets the HTTP response code and headers.
* <code>res.end("Hello World\n");</code> writes the response body and ends the response.

Notice the use of non-blocking behavior even in this simple example: ''when a connection is made'', the callback runs with the parameters associated with that connection.

== A Static File Server Using Node.js ==

Node.js does not automatically serve up static files in the way that Apache/PHP does. We need to either:

* use a framework like Express (common in industry), or
* write a simple static file server ourselves (great for understanding how servers work)

We'll do the second option here.

=== Installing Packages ===

In order for the example code below to work, you need the '''mime''' package (it helps map filenames to Content-Type headers). The `mime` package is actively maintained. :contentReference[oaicite:9]{index=9}

In the directory where you will save your Node.js file:

<source lang="bash">
$ npm init -y
$ npm install mime
</source>

''npm'' is the package manager for Node.js. It installs dependencies locally (inside `node_modules`) by default, which is a good thing: it lets different projects use different versions of the same dependency.

'''Note:''' When using npm to install local dependencies, '''do not use sudo'''. It can break file permissions in your project directory.

=== Static Fileserver Code (Modern ESM + async/await) ===

The following code makes an HTTP server on port 3456 that serves all static files inside <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O.

<source lang="javascript">
import http from "node:http";
import path from "node:path";
import { readFile } from "node:fs/promises";
import { existsSync } from "node:fs";
import mime from "mime";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const STATIC_DIR = "<STATIC DIRECTORY NAME>";

const app = http.createServer(async (req, resp) => {
try {
// Parse the path the browser requested
const urlPath = new URL(req.url, "http://localhost").pathname;
const filename = path.join(__dirname, STATIC_DIR, decodeURIComponent(urlPath));

// If file doesn't exist, return 404
if (!existsSync(filename)) {
resp.writeHead(404, { "Content-Type": "text/plain" });
resp.end("Requested file not found: " + filename);
return;
}

// Read the file (non-blocking I/O via promises)
const data = await readFile(filename);

// Determine content type
const mimetype = mime.getType(filename) || "application/octet-stream";
resp.writeHead(200, { "Content-Type": mimetype });
resp.end(data);
} catch (err) {
// File exists but isn't readable or some other error occurred
resp.writeHead(500, { "Content-Type": "text/plain" });
resp.end("Internal server error: could not read file");
}
});

app.listen(3456);
</source>

==== A few important notes about the modern version ====

* We use <code>node:fs/promises</code> so we can write file I/O using async/await.
* In ES Modules, <code>__dirname</code> is not automatically defined, so we compute it using <code>import.meta.url</code>.
* This server is intentionally simple for instructional purposes.

'''Security note:''' A production static server must protect against directory traversal attacks (paths like <code>../</code>). For this course example, we focus on learning the mechanics first.

=== Port 3456 ===

We are running our server on port 3456 instead of port 80. We therefore need to open our Node.js application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work the first time. ''Why?''

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 back in Module 2? We need to do the same procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.js Security ==

Just because we're writing in JavaScript doesn't mean we can forget about the security practices you've been learning in CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

== Node.js Conventions ==

There ought to be a standard way to save metadata about your app, right? Node projects use a <code>package.json</code> file for this.

To create one quickly:

<source lang="bash">
$ npm init -y
</source>

One nice feature of <code>package.json</code> is that it automatically handles dependencies. For example:

<source lang="javascript">
"dependencies": {
"mime": "^4.1.0",
"socket.io": "^4.8.0"
}
</source>

Then when you run:

<source lang="bash">
$ npm install
</source>

npm installs the dependencies for you.

'''Tip:''' Modern npm automatically saves dependencies when you run <code>npm install package-name</code>. The older <code>--save</code> flag is no longer necessary.

[[Category:Module 5]]

Node.JS

2026-10-21T22:33:58Z

Todd: /* Modern Node style: Promises and async/await */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes in real-time? A PHP+AJAX approach could struggle without a lot of effort on your part.

It is situations like these that Node.js comes to the rescue.

Node.js is a '''JavaScript runtime''' (built on Chrome's V8 engine) that lets you run JavaScript outside the browser. Frameworks like Express run ''on top'' of Node.js.

In general, JavaScript frameworks are trendy; it can be hard to keep up with the new cool thing. In fact, there's a joke website https://dayssincelastjavascriptframework.com/ that "tracks" how long it's been since a new framework has come out.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.js uses this execution model at its core.

A simple way to think about Node:

* Node is designed to handle lots of connections efficiently.
* Instead of waiting for slow operations (network, file system, database) to finish, Node starts the work and continues doing other things.
* When the slow operation finishes, Node runs some code to handle the result.

Historically, the core idea was the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time.

''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server (or force you to provision much more hardware than you want).

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!''

The code occurs in two parts:

# Start the query.
# ''When the query is complete,'' run the callback function.

In Node.js, callback functions are usually passed one or more parameters.

=== Modern Node style: Promises and async/await ===

Callbacks are still important to understand (they explain why Node "works"), but modern Node code often uses '''Promises''' and '''async/await''' because they make programs easier to read and debug.

Conceptually:

<source lang="javascript">
// Promise + async/await pseudo-code

const data = await database.query("select * from news");
console.log(data[0].title);
</source>

This is still non-blocking behind the scenes—it's just nicer syntax for “start work now, continue later when it finishes.”

=== One thread? Concurrency? ===

You will often hear that Node “runs in one thread.” The key point for this course is:

* You can handle many concurrent connections without making a thread per client.
* The server remains responsive because it avoids blocking on slow I/O.

(There are deeper details in the real Node event loop model, but the above understanding will serve you well for CSE 3300.)

== Installing Node.js ==

We will install Node using '''nvm''' (Node Version Manager). This makes it easy to switch Node versions and consistently use the current LTS version. :contentReference[oaicite:4]{index=4}

Run the following commands:

<source lang="bash">
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
$ source ~/.bashrc
$ nvm install --lts
$ node -v
$ npm -v
</source>

'''Note:''' As of February 2026, Node 24 is the Active LTS line. Using `nvm install --lts` means you do not have to hardcode a specific major version in the instructions. :contentReference[oaicite:6]{index=6}

== Your First Node.js Application: Hello World ==

Let's try the classic HTTP server example.

=== Modern version (ES Modules) ===

Create a file named `hello.js`:

<source lang="javascript">
import http from "node:http";

http.createServer((req, res) => {
res.writeHead(200, { "Content-Type": "text/plain" });
res.end("Hello World\n");
}).listen(3456);

console.log("Server running at http://localhost:3456/");
</source>

To run it:

<source lang="bash">
$ node hello.js
</source>

'''Note:''' If you're running the code from your EC2 instance, you will need to open port 3456.

=== Enabling ES Modules (important!) ===

Modern Node supports both the older '''CommonJS''' module system (require) and the newer JavaScript standard '''ES Modules''' (import/export). ES Modules are the direction modern JavaScript has moved (and they match browser JavaScript). :contentReference[oaicite:7]{index=7}

To tell Node to treat `.js` files as ES Modules, add this to `package.json` in your project directory:

<source lang="javascript">
{
"type": "module"
}
</source>
:contentReference[oaicite:8]{index=8}

If you do not do this, Node may treat `.js` files as CommonJS by default, and `import ...` may fail.

=== Walkthrough of the Hello World example ===

* <code>import http from "node:http";</code> enables us to use Node's built-in HTTP server library. Unlike PHP, Node does not automatically load lots of server features for you. You explicitly import what you need.
* <code>http.createServer((req, res) => { ... }).listen(3456);</code> listens for HTTP connections on port 3456. The callback function runs whenever a connection is made.
* <code>res.writeHead(200, { "Content-Type": "text/plain" });</code> sets the HTTP response code and headers.
* <code>res.end("Hello World\n");</code> writes the response body and ends the response.

Notice the use of non-blocking behavior even in this simple example: ''when a connection is made'', the callback runs with the parameters associated with that connection.

== A Static File Server Using Node.js ==

Node.js does not automatically serve up static files in the way that Apache/PHP does. We need to either:

* use a framework like Express (common in industry), or
* write a simple static file server ourselves (great for understanding how servers work)

We'll do the second option here.

=== Installing Packages ===

In order for the example code below to work, you need the '''mime''' package (it helps map filenames to Content-Type headers). The `mime` package is actively maintained. :contentReference[oaicite:9]{index=9}

In the directory where you will save your Node.js file:

<source lang="bash">
$ npm init -y
$ npm install mime
</source>

''npm'' is the package manager for Node.js. It installs dependencies locally (inside `node_modules`) by default, which is a good thing: it lets different projects use different versions of the same dependency.

'''Note:''' When using npm to install local dependencies, '''do not use sudo'''. It can break file permissions in your project directory.

=== Static Fileserver Code (Modern ESM + async/await) ===

The following code makes an HTTP server on port 3456 that serves all static files inside <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O.

<source lang="javascript">
import http from "node:http";
import path from "node:path";
import { readFile } from "node:fs/promises";
import { existsSync } from "node:fs";
import mime from "mime";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const STATIC_DIR = "<STATIC DIRECTORY NAME>";

const app = http.createServer(async (req, resp) => {
try {
// Parse the path the browser requested
const urlPath = new URL(req.url, "http://localhost").pathname;
const filename = path.join(__dirname, STATIC_DIR, decodeURIComponent(urlPath));

// If file doesn't exist, return 404
if (!existsSync(filename)) {
resp.writeHead(404, { "Content-Type": "text/plain" });
resp.end("Requested file not found: " + filename);
return;
}

// Read the file (non-blocking I/O via promises)
const data = await readFile(filename);

// Determine content type
const mimetype = mime.getType(filename) || "application/octet-stream";
resp.writeHead(200, { "Content-Type": mimetype });
resp.end(data);
} catch (err) {
// File exists but isn't readable or some other error occurred
resp.writeHead(500, { "Content-Type": "text/plain" });
resp.end("Internal server error: could not read file");
}
});

app.listen(3456);
</source>

==== A few important notes about the modern version ====

* We use <code>node:fs/promises</code> so we can write file I/O using async/await.
* In ES Modules, <code>__dirname</code> is not automatically defined, so we compute it using <code>import.meta.url</code>.
* This server is intentionally simple for instructional purposes.

'''Security note:''' A production static server must protect against directory traversal attacks (paths like <code>../</code>). For this course example, we focus on learning the mechanics first.

=== Port 3456 ===

We are running our server on port 3456 instead of port 80. We therefore need to open our Node.js application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work the first time. ''Why?''

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 back in Module 2? We need to do the same procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.js Security ==

Just because we're writing in JavaScript doesn't mean we can forget about the security practices you've been learning in CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

== Node.js Conventions ==

There ought to be a standard way to save metadata about your app, right? Node projects use a <code>package.json</code> file for this.

To create one quickly:

<source lang="bash">
$ npm init -y
</source>

One nice feature of <code>package.json</code> is that it automatically handles dependencies. For example:

<source lang="javascript">
"dependencies": {
"mime": "^4.1.0",
"socket.io": "^4.8.0"
}
</source>

Then when you run:

<source lang="bash">
$ npm install
</source>

npm installs the dependencies for you.

'''Tip:''' Modern npm automatically saves dependencies when you run <code>npm install package-name</code>. The older <code>--save</code> flag is no longer necessary.

[[Category:Module 5]]

Module 4

2026-10-04T20:23:57Z

Todd: /* Connect Four Debugging Exercise */

__NOTOC__

In Module 4, you will learn JavaScript, the dominant client-side web language. JavaScript is the second programming language you will learn in CSE 3300.

This article contains your assignments for Module 4.

'''Warning:'''

''This module takes students a while. It is strongly recommended that you start early and ask questions as they come up.''

=== Learning Goals ===
* JavaScript
* DOM Events
* AJAX
* JSON

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[JavaScript]]
* [[AJAX and JSON]]
* [[jQuery]]
* [[Web Application Security, Part 3]]
* [[FAQ - Mod 4]]
* [[FAQ - Mod 5]]

== Individual Assignments ==

'''''IMPORTANT:'' The individual assignments must be completed ''without'' using a JavaScript library like jQuery.''' However, you may use jQuery for the group portion.

=== JavaScript Calculator ===

In Module 2, you made a calculator using PHP. Now you will be making one using JavaScript.

* The web page should have two input fields and a radio button group for the operation, with the 4 basic math operations represented (add, subtract, multiply, divide).
* JavaScript should monitor all three fields and display the current result whenever the user changes any value in any field, without refreshing the page.
*: '''Tip 1:''' Consider using either the ''change'' or the ''keyup'' event on the text fields, and either the ''change'' or the ''click'' event on the radio buttons.
*: '''Tip 2:''' Re-read [[JavaScript|the JavaScript guide]] if you need help figuring our how to bind callback functions to events, or how to determine which radio button is currently selected. (There are examples for both of these!)
* The calculator should be completely self-contained; i.e., you should not be making any requests to any other server-side or client-side scripts or web pages after the initial page load.

'''Tip:''' You can embed JavaScript code into an HTML document like this:

<source lang="html4strict">
<script>
// your code here
</script>
</source>

'''Tip:''' If your code isn't working the way you expect, use a JavaScript error console. In Chrome, for example, press Ctrl-Shift-I (or Cmd-Option-I) to open the WebKit inspector.

'''Important:''' It is best practice to fully separate the content, appearance, and behavior. In previous modules, you may have lost points for using HTML tags that change the appearance of things <nowiki>(like <center> and <font>).</nowiki> In this module, make sure that you define your event listeners in JavaScript as in <code>document.getElementById("xyz").addEventListener(...)</code> and '''''not''''' in the HTML like <code><button onclick="badExample();">Bad Example</button></code>.

=== Weather Widget ===

In this section, you will make a web page that displays the weather forecast using AJAX requests to a weather server.

# Make an empty HTML document; name it '''weather.html'''
#: Refer to the [[HTML and CSS]] guide for the skeleton of an HTML document
# Define a function in JavaScript; call it '''fetchWeather()'''. You may write your JavaScript in an embedded script in your HTML document.
# Inside your '''fetchWeather()''' function, make an AJAX request to the weather server.
#: We have a server that outputs the current weather in JSON format. The format is documented in the [[#JSON Structure]] section below.

#: '''URL:''' https://classes.engineering.wustl.edu/cse330/content/weather_json.php
#* '''IMPORTANT:''' Under normal circumstances, AJAX requests ''cannot'' be performed cross-domain for security reasons. We have set the <code>Access-Control-Allow-Origin</code> header on our server to allow requests from your EC2 instances, or from localhost. '''You will therefore need to upload your code to your EC2, or access it via localhost, in order for the AJAX requests to work.''' This means that you cannot, for example, complete this part of the individual portion in JSFiddle.
# In your callback, process the JSON and use JavaScript to manipulate the HTML DOM to display the following information on your page:
#* Location
#** City, in a <nowiki><strong></nowiki> tag
#** State, not in any tag
#* Humidity
#* Current Temperature
#* Image for Tomorrow's Forecast (see [[#Weather Condition Images]] below for more information)
#* Image for the Day After Tomorrow's Forecast
# Finally, bind '''fetchWeather()''' to the DOMContentLoaded event so that your weather widget is automatically initialized when the page is loaded:
#: <source lang="javascript">document.addEventListener("DOMContentLoaded", fetchWeather, false);</source>
# In addition, add a button that runs your ''fetchWeather'' function when clicked. This should update your widget with the current weather conditions.

Use the following HTML:

<source lang="html4strict">
<div class="weather" id="weatherWidget">
<div class="weather-loc"></div>
<div class="weather-humidity"></div>
<div class="weather-temp"></div>
<img class="weather-tomorrow" />
<img class="weather-dayaftertomorrow" />
</div>
</source>

Include the CSS file from here: https://classes.engineering.wustl.edu/cse330/content/weather.css

When everything is working, the weather widget should look something like this:

[[File:WeatherWidget.png]]

'''Important:''' The widget in this section needs to work in only Firefox and Chrome. It does '''''not''''' need to work Internet Explorer.

==== Tips ====

===== JSON Structure =====

The JSON from our server looks like this:

<source lang="javascript">
{
"updated": "Thu, 11 Oct 2025 5:54 pm CDT",
"location": {
"city": "St. Louis",
"state": "MO"
},
"wind": {
"chill": "62",
"direction": "150",
"speed": "3 mph"
},
"atmosphere": {
"humidity": "50",
"visibility": "10",
"pressure": "30.12 in"
},
"current": {
"code": "28",
"text": "Mostly Cloudy",
"temp": "62°F",
"date": "Thu, 11 Oct 2025 5:54 pm CDT"
},
"tomorrow": {
"code": "29",
"text": "Clouds Early/Clearing Late",
"low": "45°F",
"high": "61°F"
},
"dayafter": {
"code": "30",
"text": "Partly Cloudy",
"low": "53°F",
"high": "65°F"
},
"credit": "http://us.rd.yahoo.com/dailynews/rss/weather/St._Louis__MO/*http://weather.yahoo.com/forecast/USMO0170_f.html"
}
</source>

===== Weather Condition Images =====

Each day's forecast has a code. There are images associated with these codes.

One place to get the images is from here: <nowiki>http://us.yimg.com/i/us/nws/weather/gr/</nowiki>'''##'''<nowiki>ds.png</nowiki>

Replace the '''##''' with the forecast code. For example, for code 32, the URL would be: http://us.yimg.com/i/us/nws/weather/gr/32ds.png

=== Connect Four Debugging Exercise ===

As a short debugging exercise for Module 4, you will be given a broken Connect Four implementation (located in the repository and named `connect4`). You may also download the files [https://research.engineering.wustl.edu/~todd/cse3300-wiki/connect4/ here].

The goals of this assignment are to complete the following:

* Run the provided program and observe failures or incorrect behavior.
* Produce a list of all bugs you find. For each bug include:
** The file and function (or approximate line) where it appears
** A short description of why it is a bug and what symptom it causes (crash, wrong output, missing feature)
** A suggested fix (one or two sentences)
* Use GitHub Copilot in "Agent" mode to assist you in writing and testing fixes. When you use Copilot Agent, document the prompts you issued, any code the agent generated, and what changes you applied or rejected after code review.
* Produce a corrected version of the program that can demonstrate the following:
** A horizontal, vertical, or diagonal win is detected correctly
** A draw (full-board) is detected correctly

A video of the working Connect Four app can be found
[https://wustl.app.box.com/s/e3t8layy3vqp4wm75dcxn9yyip9dsbdp here]

Documentation to include in your repository:
* The bug list (as described above) is inserted as a comment at the top of the connect4.js file
* The Copilot Agent prompts you used and a short evaluation of the suggestions (what was helpful, what you changed) in the AI Reflection
* The corrected file(s) committed to your GitHub repo

To receive full credit, you must complete the following:
* Identifying and explaining each real bug
* Correct fixes that produce a working game (wins + draw)
* Proper documentation of Copilot Agent usage and critical review

This exercise is intended to teach debugging, careful code review, and responsible use of AI coding assistants (reviewing and accepting/rejecting suggestions). Keep your commits small and descriptive so the instructor can follow your reasoning.

== Group Project ==

=== Calendar ===

Build a simple calendar that allows users to add and remove events dynamically.

You will use JavaScript to process user interactions at the web browser, without ever refreshing the browser after the initial web page load. You may use a JavaScript library of your choice, so long as that JavaScript library does not defeat the purpose of the assignment. If you have questions about this, ask. In particular, libraries like FullCalendar are unacceptable.

Your application should utilize AJAX to run server-side scripts that query your database to save and retrieve information, including user accounts and events.

We have also written some functions to help you get started: [[JavaScript Calendar Library]]

==== Examples ====

* https://calendar.google.com/
* http://www.zoho.com/calendar/

==== Server Side Language ====

Additionally, you may use a database of your choice. MySQL is probably the logical choice since you have been using it since Module 2, but you are free to explore other databases if you like.
==== Calendar Requirements ====

* Support a month-by-month view of the calendar.
*: Show one month at a time, with buttons to move forward or backward.
*: There should be no limit to how far forward or backward the user can go.
* Users can register and log in to the website.
*: You may leverage your MySQL project code and database from module 3 to get started.
* Unregistered users should see no events on the calendar.
* Registered users can add events.
*: All events should have a date and time, but do not need to have a duration.
*: You do ''not'' need to support recurring events (where you add an event that repeats, for example, every Monday).
* Registered users see only events that they have added.
*: Your AJAX should not ask the server for events from a certain username. Instead, your AJAX should ask the server for events, and the server should respond with the events for only the currently-logged-in user (from the session). Can you think of why?
* Registered users can edit and delete their own events, but not the events of others.
*: Again, the server should edit and delete events based on the username present in the session, not based on a username or event ID provided by the user. (If it deletes only based on an Event ID, an attacker could feed any arbitrary Event ID to your server, even if he/she didn't own that event.)
* All user and event data should be kept in a database.
* At no time should the main page need to be reloaded.
*: User registration, user authentication, event addition, and event deletion should all be handled by JavaScript and AJAX requests to your server.
* Your page needs to work in the versions of Firefox and Chrome installed on the lab computers.

'''Tip:''' Run your database schema by a TA before implementing it.

=== Web Security and Validation ===

Your project needs to demonstrate that thought was put into web security and best practice. For more information, see this week's Web Application Security guide: [[Web Application Security, Part 3]]

In particular:

* '''Your application needs to prevent XSS attacks.''' Be careful when transmitting data over JSON that will be reflected in an event title! (Note: JSON data should be sanitized on the client side, not the server side.)
* '''Perform precautionary measures to prevent session hijacking attacks.'''
*: You should specify your session cookie to be HTTP-Only. However, for the means of this module, you need not test for user agent consistency.

You should continue the practices that you have learned in past weeks:

* Pass tokens in forms to prevent CSRF attacks.
*: '''Hint:''' You will need to send your CSRF tokens in your AJAX requests. Remember that AJAX still submits forms and runs server-side scripts, just like the vanilla forms you've been using in Modules 2 and 3.
* Use prepared queries to prevent SQL Injection attacks.
* If storing passwords in a database, always store them salted and encrypted.
* Your page should validate with no errors or warnings through the W3C validator.

=== AI Security Audit with GitHub Copilot ===

For this module, you will use GitHub Copilot to perform a security audit of your calendar application. This exercise is designed to help you learn how to leverage AI tools for code security analysis while maintaining critical thinking about the results.

* Code Generation: Use GitHub Copilot to help implement core calendar features if needed
* Security Review: Use Copilot's code analysis capabilities to:
** Identify potential security vulnerabilities in your JavaScript and PHP code
** Check for common web security issues (XSS, CSRF, SQL injection, etc.)
**Review authentication and authorization logic
*Vulnerability Assessment: Ask Copilot to analyze specific security aspects:
**Input validation and output escaping
**Session management security
**AJAX request security
**Database query safety

Required Tasks:
#Use GitHub Copilot to generate at least 3 security-focused code reviews for different parts of your application
#Implement fixes for at least 2 identified security issues (real or potential)
#Document the security audit process and findings

* Documentation Requirements
**Examples of security-focused prompts you used with Copilot
**Security issues identified (both real and false positives)
**Changes made based on the security audit
**Your assessment of Copilot's effectiveness as a security review tool

== Grading ==

We will be grading the following aspects of your work. There are 125 points in total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

If you do not include a link to your individual and group portion running on your instance in the respective README.md, you will receive a 0 for the missing portion

_________

# '''JavaScript Calculator (10 Points):'''
#* Calculator successfully adds, subtracts, multiplies, and divides numbers (3 points)
#* The result is automatically computed when a value in either field is changed (3 points)
#* Calculator is written entirely in pure, conventional JavaScript with no external libraries (4 points)*
#*: ''Note: be sure to fully separate content, appearance, and behavior. This means that you should '''not''' use the event attributes on the HTML elements like onclick, onchange, and onkeyup.''
# '''Weather Widget (15 Points):'''
#* Widget performs an AJAX request to fetch the current weather (4 points)
#* The HTML template is filled with the correct information, including an image (4 points)
#* Button to reload the weather widget (2 points)
#* Widget is written entirely in pure, conventional JavaScript with no external libraries (5 points)*
# '''Connect Four Debugging Exercise (15 Points):'''
#* Identify and explain bugs in the provided `connect4.js` (5 points)
#** For each bug, include location (function/lines), description of the symptom, and the root cause.
#* Correct the program so it reliably detects wins and draws and handles invalid input (5 points)
#* Completion of the AI Reflections for the individual portion of the assignment following the AI Best Practices (5 points)
#**Include the prompts used, what Copilot suggested, and what you changed or rejected.
# '''AJAX Calendar (60 Points):'''
#* '''''Calendar View (10 Points):'''''
#** The calendar is displayed as a table grid with days as the columns and weeks as the rows, one month at a time (5 points)
#** The user can view different months as far in the past or future as desired (5 points)
#* '''''User and Event Management (25 Points):'''''
#** Events can be added, modified, and deleted (5 points)
#** Events have a title, date, and time (2 points)
#** Users can log into the site, and they cannot view or manipulate events associated with other users (8 points)
#**: ''Don't fall into the Abuse of Functionality trap! Check user credentials on the server side as well as on the client side.''
#** All actions are performed over AJAX, without ever needing to reload the page (7 points)
#** Refreshing the page does not log a user out (3 points)
#* '''''Best Practices (20 Points):'''''
#** Code is well formatted and easy to read, with proper commenting (2 points)
#** If storing passwords, they are stored salted and hashed (2 points)
#** All AJAX requests that either contain sensitive information or modify something on the server are performed via POST, not GET (3 points)
#** Safe from XSS attacks; that is, all content is escaped on output (3 points)
#** Safe from SQL Injection attacks (2 points)
#** CSRF tokens are passed when adding/editing/deleting events (3 points)
#** Session cookie is HTTP-Only (3 points)
#** Page passes the W3C validator (2 points)
#* '''''Usability (5 Points):'''''
#** Site is intuitive to use and navigate (4 points)
#** Site is visually appealing (1 point)
# '''Creative Portion & AI Security Audit (25 Points)'''
#* '''''AI Security Audit Implementation (15 Points):'''''
#** Used GitHub Copilot for security analysis of at least 3 different code components (4 points)
#** Documented security audit process and findings in README.md (3 points)
#** Completion of the AI Reflections for the group portion of the assignment following the AI Best Practices (5 points)
#** Implemented fixes for identified security issues (3 points)
#** We recommend you to use "Agent" Mode of Copilot to implement this feature
#** Be sure to create a new branch before implement this in case any of your original code being changed.
#* '''Additional Calendars Features (worth 10 points):''' Develop some additional features for the calendar, a few examples are provided below.
#** Users can tag an event with a particular category and enable/disable those tags in the calendar view. (5 points)
#** Users can share their calendar with additional users. (5 points)
#** Users can create group events that display on multiple users calendars (5 points)
#** Feature enhances user experience and calendar functionality
#* '''''Make sure to save a description of your creative portion, AI security audit process, and a link to your server in your README.md file.'''''

''* These points can be earned only if at least 3 other points have been earned in that category. This is to prevent these points from being "free."''

[[Category:Module 4]]
[[Category:Modules]]

Module 4

2026-10-04T20:21:29Z

Todd: /* Connect Four Debugging Exercise */

__NOTOC__

In Module 4, you will learn JavaScript, the dominant client-side web language. JavaScript is the second programming language you will learn in CSE 3300.

This article contains your assignments for Module 4.

'''Warning:'''

''This module takes students a while. It is strongly recommended that you start early and ask questions as they come up.''

=== Learning Goals ===
* JavaScript
* DOM Events
* AJAX
* JSON

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[JavaScript]]
* [[AJAX and JSON]]
* [[jQuery]]
* [[Web Application Security, Part 3]]
* [[FAQ - Mod 4]]
* [[FAQ - Mod 5]]

== Individual Assignments ==

'''''IMPORTANT:'' The individual assignments must be completed ''without'' using a JavaScript library like jQuery.''' However, you may use jQuery for the group portion.

=== JavaScript Calculator ===

In Module 2, you made a calculator using PHP. Now you will be making one using JavaScript.

* The web page should have two input fields and a radio button group for the operation, with the 4 basic math operations represented (add, subtract, multiply, divide).
* JavaScript should monitor all three fields and display the current result whenever the user changes any value in any field, without refreshing the page.
*: '''Tip 1:''' Consider using either the ''change'' or the ''keyup'' event on the text fields, and either the ''change'' or the ''click'' event on the radio buttons.
*: '''Tip 2:''' Re-read [[JavaScript|the JavaScript guide]] if you need help figuring our how to bind callback functions to events, or how to determine which radio button is currently selected. (There are examples for both of these!)
* The calculator should be completely self-contained; i.e., you should not be making any requests to any other server-side or client-side scripts or web pages after the initial page load.

'''Tip:''' You can embed JavaScript code into an HTML document like this:

<source lang="html4strict">
<script>
// your code here
</script>
</source>

'''Tip:''' If your code isn't working the way you expect, use a JavaScript error console. In Chrome, for example, press Ctrl-Shift-I (or Cmd-Option-I) to open the WebKit inspector.

'''Important:''' It is best practice to fully separate the content, appearance, and behavior. In previous modules, you may have lost points for using HTML tags that change the appearance of things <nowiki>(like <center> and <font>).</nowiki> In this module, make sure that you define your event listeners in JavaScript as in <code>document.getElementById("xyz").addEventListener(...)</code> and '''''not''''' in the HTML like <code><button onclick="badExample();">Bad Example</button></code>.

=== Weather Widget ===

In this section, you will make a web page that displays the weather forecast using AJAX requests to a weather server.

# Make an empty HTML document; name it '''weather.html'''
#: Refer to the [[HTML and CSS]] guide for the skeleton of an HTML document
# Define a function in JavaScript; call it '''fetchWeather()'''. You may write your JavaScript in an embedded script in your HTML document.
# Inside your '''fetchWeather()''' function, make an AJAX request to the weather server.
#: We have a server that outputs the current weather in JSON format. The format is documented in the [[#JSON Structure]] section below.

#: '''URL:''' https://classes.engineering.wustl.edu/cse330/content/weather_json.php
#* '''IMPORTANT:''' Under normal circumstances, AJAX requests ''cannot'' be performed cross-domain for security reasons. We have set the <code>Access-Control-Allow-Origin</code> header on our server to allow requests from your EC2 instances, or from localhost. '''You will therefore need to upload your code to your EC2, or access it via localhost, in order for the AJAX requests to work.''' This means that you cannot, for example, complete this part of the individual portion in JSFiddle.
# In your callback, process the JSON and use JavaScript to manipulate the HTML DOM to display the following information on your page:
#* Location
#** City, in a <nowiki><strong></nowiki> tag
#** State, not in any tag
#* Humidity
#* Current Temperature
#* Image for Tomorrow's Forecast (see [[#Weather Condition Images]] below for more information)
#* Image for the Day After Tomorrow's Forecast
# Finally, bind '''fetchWeather()''' to the DOMContentLoaded event so that your weather widget is automatically initialized when the page is loaded:
#: <source lang="javascript">document.addEventListener("DOMContentLoaded", fetchWeather, false);</source>
# In addition, add a button that runs your ''fetchWeather'' function when clicked. This should update your widget with the current weather conditions.

Use the following HTML:

<source lang="html4strict">
<div class="weather" id="weatherWidget">
<div class="weather-loc"></div>
<div class="weather-humidity"></div>
<div class="weather-temp"></div>
<img class="weather-tomorrow" />
<img class="weather-dayaftertomorrow" />
</div>
</source>

Include the CSS file from here: https://classes.engineering.wustl.edu/cse330/content/weather.css

When everything is working, the weather widget should look something like this:

[[File:WeatherWidget.png]]

'''Important:''' The widget in this section needs to work in only Firefox and Chrome. It does '''''not''''' need to work Internet Explorer.

==== Tips ====

===== JSON Structure =====

The JSON from our server looks like this:

<source lang="javascript">
{
"updated": "Thu, 11 Oct 2025 5:54 pm CDT",
"location": {
"city": "St. Louis",
"state": "MO"
},
"wind": {
"chill": "62",
"direction": "150",
"speed": "3 mph"
},
"atmosphere": {
"humidity": "50",
"visibility": "10",
"pressure": "30.12 in"
},
"current": {
"code": "28",
"text": "Mostly Cloudy",
"temp": "62°F",
"date": "Thu, 11 Oct 2025 5:54 pm CDT"
},
"tomorrow": {
"code": "29",
"text": "Clouds Early/Clearing Late",
"low": "45°F",
"high": "61°F"
},
"dayafter": {
"code": "30",
"text": "Partly Cloudy",
"low": "53°F",
"high": "65°F"
},
"credit": "http://us.rd.yahoo.com/dailynews/rss/weather/St._Louis__MO/*http://weather.yahoo.com/forecast/USMO0170_f.html"
}
</source>

===== Weather Condition Images =====

Each day's forecast has a code. There are images associated with these codes.

One place to get the images is from here: <nowiki>http://us.yimg.com/i/us/nws/weather/gr/</nowiki>'''##'''<nowiki>ds.png</nowiki>

Replace the '''##''' with the forecast code. For example, for code 32, the URL would be: http://us.yimg.com/i/us/nws/weather/gr/32ds.png

=== Connect Four Debugging Exercise ===

As a short debugging exercise for Module 4, you will be given a broken Connect Four implementation (located in the repository and named `connect4`). You may also download the files [https://research.engineering.wustl.edu/~todd/cse3300-wiki/connect4/ here].

The goals of this assignment are to complete the following:

* Run the provided program and observe failures or incorrect behavior.
* Produce a list of all bugs you find. For each bug include:
** The file and function (or approximate line) where it appears
** A short description of why it is a bug and what symptom it causes (crash, wrong output, missing feature)
** A suggested fix (one or two sentences)
* Use GitHub Copilot in "Agent" mode to assist you in writing and testing fixes. When you use Copilot Agent, document the prompts you issued, any code the agent generated, and what changes you applied or rejected after code review.
* Produce a corrected version of the program that can demonstrate the following:
** A horizontal, vertical, or diagonal win is detected correctly
** A draw (full-board) is detected correctly

A video of the working Connect Four app can be found
[https://wustl.box.com/shared/static/e3t8layy3vqp4wm75dcxn9yyip9dsbdp.mp4 here]

Documentation to include in your repository:
* The bug list (as described above) is inserted as a comment at the top of the connect4.js file
* The Copilot Agent prompts you used and a short evaluation of the suggestions (what was helpful, what you changed) in the AI Reflection
* The corrected file(s) committed to your GitHub repo

To receive full credit, you must complete the following:
* Identifying and explaining each real bug
* Correct fixes that produce a working game (wins + draw)
* Proper documentation of Copilot Agent usage and critical review

This exercise is intended to teach debugging, careful code review, and responsible use of AI coding assistants (reviewing and accepting/rejecting suggestions). Keep your commits small and descriptive so the instructor can follow your reasoning.

== Group Project ==

=== Calendar ===

Build a simple calendar that allows users to add and remove events dynamically.

You will use JavaScript to process user interactions at the web browser, without ever refreshing the browser after the initial web page load. You may use a JavaScript library of your choice, so long as that JavaScript library does not defeat the purpose of the assignment. If you have questions about this, ask. In particular, libraries like FullCalendar are unacceptable.

Your application should utilize AJAX to run server-side scripts that query your database to save and retrieve information, including user accounts and events.

We have also written some functions to help you get started: [[JavaScript Calendar Library]]

==== Examples ====

* https://calendar.google.com/
* http://www.zoho.com/calendar/

==== Server Side Language ====

Additionally, you may use a database of your choice. MySQL is probably the logical choice since you have been using it since Module 2, but you are free to explore other databases if you like.
==== Calendar Requirements ====

* Support a month-by-month view of the calendar.
*: Show one month at a time, with buttons to move forward or backward.
*: There should be no limit to how far forward or backward the user can go.
* Users can register and log in to the website.
*: You may leverage your MySQL project code and database from module 3 to get started.
* Unregistered users should see no events on the calendar.
* Registered users can add events.
*: All events should have a date and time, but do not need to have a duration.
*: You do ''not'' need to support recurring events (where you add an event that repeats, for example, every Monday).
* Registered users see only events that they have added.
*: Your AJAX should not ask the server for events from a certain username. Instead, your AJAX should ask the server for events, and the server should respond with the events for only the currently-logged-in user (from the session). Can you think of why?
* Registered users can edit and delete their own events, but not the events of others.
*: Again, the server should edit and delete events based on the username present in the session, not based on a username or event ID provided by the user. (If it deletes only based on an Event ID, an attacker could feed any arbitrary Event ID to your server, even if he/she didn't own that event.)
* All user and event data should be kept in a database.
* At no time should the main page need to be reloaded.
*: User registration, user authentication, event addition, and event deletion should all be handled by JavaScript and AJAX requests to your server.
* Your page needs to work in the versions of Firefox and Chrome installed on the lab computers.

'''Tip:''' Run your database schema by a TA before implementing it.

=== Web Security and Validation ===

Your project needs to demonstrate that thought was put into web security and best practice. For more information, see this week's Web Application Security guide: [[Web Application Security, Part 3]]

In particular:

* '''Your application needs to prevent XSS attacks.''' Be careful when transmitting data over JSON that will be reflected in an event title! (Note: JSON data should be sanitized on the client side, not the server side.)
* '''Perform precautionary measures to prevent session hijacking attacks.'''
*: You should specify your session cookie to be HTTP-Only. However, for the means of this module, you need not test for user agent consistency.

You should continue the practices that you have learned in past weeks:

* Pass tokens in forms to prevent CSRF attacks.
*: '''Hint:''' You will need to send your CSRF tokens in your AJAX requests. Remember that AJAX still submits forms and runs server-side scripts, just like the vanilla forms you've been using in Modules 2 and 3.
* Use prepared queries to prevent SQL Injection attacks.
* If storing passwords in a database, always store them salted and encrypted.
* Your page should validate with no errors or warnings through the W3C validator.

=== AI Security Audit with GitHub Copilot ===

For this module, you will use GitHub Copilot to perform a security audit of your calendar application. This exercise is designed to help you learn how to leverage AI tools for code security analysis while maintaining critical thinking about the results.

* Code Generation: Use GitHub Copilot to help implement core calendar features if needed
* Security Review: Use Copilot's code analysis capabilities to:
** Identify potential security vulnerabilities in your JavaScript and PHP code
** Check for common web security issues (XSS, CSRF, SQL injection, etc.)
**Review authentication and authorization logic
*Vulnerability Assessment: Ask Copilot to analyze specific security aspects:
**Input validation and output escaping
**Session management security
**AJAX request security
**Database query safety

Required Tasks:
#Use GitHub Copilot to generate at least 3 security-focused code reviews for different parts of your application
#Implement fixes for at least 2 identified security issues (real or potential)
#Document the security audit process and findings

* Documentation Requirements
**Examples of security-focused prompts you used with Copilot
**Security issues identified (both real and false positives)
**Changes made based on the security audit
**Your assessment of Copilot's effectiveness as a security review tool

== Grading ==

We will be grading the following aspects of your work. There are 125 points in total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

If you do not include a link to your individual and group portion running on your instance in the respective README.md, you will receive a 0 for the missing portion

_________

# '''JavaScript Calculator (10 Points):'''
#* Calculator successfully adds, subtracts, multiplies, and divides numbers (3 points)
#* The result is automatically computed when a value in either field is changed (3 points)
#* Calculator is written entirely in pure, conventional JavaScript with no external libraries (4 points)*
#*: ''Note: be sure to fully separate content, appearance, and behavior. This means that you should '''not''' use the event attributes on the HTML elements like onclick, onchange, and onkeyup.''
# '''Weather Widget (15 Points):'''
#* Widget performs an AJAX request to fetch the current weather (4 points)
#* The HTML template is filled with the correct information, including an image (4 points)
#* Button to reload the weather widget (2 points)
#* Widget is written entirely in pure, conventional JavaScript with no external libraries (5 points)*
# '''Connect Four Debugging Exercise (15 Points):'''
#* Identify and explain bugs in the provided `connect4.js` (5 points)
#** For each bug, include location (function/lines), description of the symptom, and the root cause.
#* Correct the program so it reliably detects wins and draws and handles invalid input (5 points)
#* Completion of the AI Reflections for the individual portion of the assignment following the AI Best Practices (5 points)
#**Include the prompts used, what Copilot suggested, and what you changed or rejected.
# '''AJAX Calendar (60 Points):'''
#* '''''Calendar View (10 Points):'''''
#** The calendar is displayed as a table grid with days as the columns and weeks as the rows, one month at a time (5 points)
#** The user can view different months as far in the past or future as desired (5 points)
#* '''''User and Event Management (25 Points):'''''
#** Events can be added, modified, and deleted (5 points)
#** Events have a title, date, and time (2 points)
#** Users can log into the site, and they cannot view or manipulate events associated with other users (8 points)
#**: ''Don't fall into the Abuse of Functionality trap! Check user credentials on the server side as well as on the client side.''
#** All actions are performed over AJAX, without ever needing to reload the page (7 points)
#** Refreshing the page does not log a user out (3 points)
#* '''''Best Practices (20 Points):'''''
#** Code is well formatted and easy to read, with proper commenting (2 points)
#** If storing passwords, they are stored salted and hashed (2 points)
#** All AJAX requests that either contain sensitive information or modify something on the server are performed via POST, not GET (3 points)
#** Safe from XSS attacks; that is, all content is escaped on output (3 points)
#** Safe from SQL Injection attacks (2 points)
#** CSRF tokens are passed when adding/editing/deleting events (3 points)
#** Session cookie is HTTP-Only (3 points)
#** Page passes the W3C validator (2 points)
#* '''''Usability (5 Points):'''''
#** Site is intuitive to use and navigate (4 points)
#** Site is visually appealing (1 point)
# '''Creative Portion & AI Security Audit (25 Points)'''
#* '''''AI Security Audit Implementation (15 Points):'''''
#** Used GitHub Copilot for security analysis of at least 3 different code components (4 points)
#** Documented security audit process and findings in README.md (3 points)
#** Completion of the AI Reflections for the group portion of the assignment following the AI Best Practices (5 points)
#** Implemented fixes for identified security issues (3 points)
#** We recommend you to use "Agent" Mode of Copilot to implement this feature
#** Be sure to create a new branch before implement this in case any of your original code being changed.
#* '''Additional Calendars Features (worth 10 points):''' Develop some additional features for the calendar, a few examples are provided below.
#** Users can tag an event with a particular category and enable/disable those tags in the calendar view. (5 points)
#** Users can share their calendar with additional users. (5 points)
#** Users can create group events that display on multiple users calendars (5 points)
#** Feature enhances user experience and calendar functionality
#* '''''Make sure to save a description of your creative portion, AI security audit process, and a link to your server in your README.md file.'''''

''* These points can be earned only if at least 3 other points have been earned in that category. This is to prevent these points from being "free."''

[[Category:Module 4]]
[[Category:Modules]]

Module 2

2026-09-14T17:28:27Z

Todd: /* Simple File Sharing Site */

__NOTOC__
Module 2 introduces you to Linux, a command-line environment, the Apache web server, and PHP. You will create and configure your own cloud instance, install Apache and related software, and then form groups to make a simple file sharing site.

<span style="font-size:1.3em; line-height:1.2em; color:blue;">'''DO NOT WAIT UNTIL THE LAST MINUTE TO START ON THIS (or any) MODULE!''' The most common reason students perform poorly in this class is procrastination. You have been warned.</span>

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

=== Learning Goals ===
* Linux user management
* SSH
* Apache
* PHP fundamentals
* Web security (FIEO)

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

''To jump right into setting up your EC2 Instance, Begin with [[SSH]]''

* [[Linux]]
* [[Bash]]
* [[Amazon Web Services]]
* [[SSH]]
* [[Apache]]
* [[PHP]]
* [[Workflow]]
* [[VS Code]]
* [[Web Application Security, Part 1]]
* [[FAQ - Mod 2]]

== Individual Assignments ==

{{RequiredInstructions|content=

<span style="color:red">There are a lot of wiki pages that you need to read in order to complete the individual portion of Module 2. The wiki pages contain an assortment of required steps, optional steps, and information. To make things easier, we have highlighted the ''required steps'' with a red bar, like you see on the left of this message. Do not skip anything marked with a red bar, or else you will not have a perfectly configured instance.</span>

}}

=== Learn About Linux ===

Linux is an open-source operating system based on UNIX. Linux is highly versatile and is used in a wide range of applications.

If you are not a Linux guru, read the Linux guide to get started: [[Linux]]

=== Windows Users Only: Enable Windows Subsystem for Linux (WSL) or Install Cygwin ===

You will need WSL or Cygwin in order to log into and configure your EC2 instance. Cygwin is already installed on the CEC machines. If you're using Windows 11, you can use WSL, which is an officially-supported way of accessing a Linux terminal on Windows. If not, you'll want to use Git Bash or Cygwin. Instructions for installing either on your personal machine are located in [[Workflow#Cygwin|the Workflow guide]].

Mac OS X users should located the "Terminal" application, which is installed by default; you will need this in the coming steps.

=== Create an AWS EC2 Instance ===

Once you understand [[Linux]], you need to set up your Amazon EC2 Instance. Use the AWS article to guide you through the process: [[Amazon Web Services]]

=== Configure SSH ===

Follow the instructions in [[SSH#SSH Configuration|the SSH guide]] to do the following:

# Create your own SSH key pair
# Log in as the default user to your EC2 instance
# Create a new user
# Give the new user your SSH public key

From now on, when you need to log into your EC2 instance as an administrator, just pop up a terminal and run:

$ ssh <your-instance-username>@<ec2-xx-xx-xx-xx.compute-1.amazonaws.com>

To save from typing this command in every time you want to access your server, you can set an '''alias''' in your terminal.

In the '''Mac''' terminal, vim ~/.zshrc and input the following command:
$ alias aws='ssh <your-instance-username>@<ec2-xx-xx-xx-xx.compute-1.amazonaws.com>'
Now, whenever you type aws in your terminal, it will type your ssh command.

In '''Cygwin''', vim ~/.bash_profile and input the following:
export aws="ssh <your-instance-username>@<ec2-xx-xx-xx-xx.compute-1.amazonaws.com>"
And you run this command by typing '''$aws'''
Also note that you may have to restart your terminal for this to take effect, or put the command in your ~/.bashrc file

=== Install Essential Packages ===

Recall that software installation in Linux instances is usually handled through a package manager, like '''yum'''. For more information, refer to [[Linux#Repository-Based Package Managers|the Linux guide]].

To make sure everything is working properly, '''install your first package(s) according to the ''Essential Packages'' subsection in the Linux guide.'''

=== Set the Timezone ===

'''Set your server to use US Central time (America/Chicago).''' Instructions are in the Linux guide: [[Linux#Synchronizing Date and Time]]

=== Set Up the Apache Web Server ===

You need to '''install the Apache web server on your EC2 instance'''. Refer to [[Apache|the Apache guide]].

In order for your web server to be accessible, you need to '''open up Port 80 on your EC2 instance'''. Instructions are in the AWS guide: [[Amazon Web Services#Enabling Web Access to your EC2 Instance]]

'''Enable the UserDir module in Apache.''' Instructions are in the Apache guide: [[Apache#The UserDir Module]]

=== Install PHP ===

You need to '''install PHP on your EC2 server'''. Instructions are at the top of the PHP guide: [[PHP]]

You need to '''configure PHP to show errors'''. Instructions are immediately below installation in the PHP guide.

=== Learn about the PHP Language ===

Before you can continue, you will need to make yourself acquainted with PHP language components. Read the PHP guide for an overview: [[PHP#PHP Language Components]]

=== Set Up GitHub Copilot ===

You will be using GitHub Copilot in this module to help you generate PHPUnit tests.

# Install the GitHub Copilot extension in VS Code (see the [[AI Tools]] guide for setup).
# Sign in with your GitHub account to enable Copilot.
# Verify that Copilot is active by checking the status icon in the VS Code status bar.

Copilot will suggest code completions as you type. You can use these suggestions to accelerate writing your test cases, but you must still review and adjust its output for correctness. See [[AI Best Practices]].

=== Set Up your Workspace ===

You are now ready to set up the workspace that you will be using for the rest of the semester. Follow the instructions in [[Workflow]] to:

# Make an account on GitHub
# Setup a repo using GitHub Classroom
# Clone your CSE 330 repo from GitHub
# Install a text editor such as '''VSCode''' to write your assignments with
# Either install an SFTP extension in VSCode (recommended) or use SFTP through command line, to transfer files from your local machine to your instance

=== Calculator ===

'''Build a calculator using PHP and an HTML form.'''
The form should include two number inputs and a radio button group for addition, subtraction, multiplication, and division. Submit the form with a GET request, either to the same page or to a separate results page. Be sure to handle edge cases (division by zero, empty fields, non-numeric input, floating point values).

'''GitHub Copilot''' installed
Use Copilot to help you write and refine your calculator logic and to create simple edge-case tests (for example, a small PHP script that calls your calculator with sample inputs).

Finally, include in your README.md:

* A working link to your calculator page on your EC2 instance
* A brief note describing how you used Copilot to write your tests (for example, which suggestions you accepted or modified) as described in [[AI Best Practices]]

== Group Project ==

You will work in pairs (that means you and one other person) on this project.

<span style="font-size:1.3em; line-height:1.2em; color:blue;">In this module, and all future modules, the group portion builds off of material you learn in the individual portion. You should therefore complete the individual portions prior to working on the group portions. (Trust us: it will make your life easier!)</span>

'''Important Reminder:''' frequently commit your work to your repository as a backup!

=== Simple File Sharing Site ===

You will be making a simple file sharing site that supports uploading, viewing, and deleting files associated with various users. Details:

* You should have a file named '''users.txt''' stored in a secure place on your filesystem. It should have at least three usernames, with one username per line.
*: Passwords add an extra layer of complexity (encryption) that we will cover in Module 3. You will not earn credit for implementing passwords as your creative portion for this module.
* Users of the file sharing site should be able to enter their username and then log in.
*: You may implement logins using session variables, or you may implement them using a GET parameter that is passed between pages. You will need to always use sessions starting in Module 3.
* Users should see a list of all files associated with their username after the log in.
* Users should be able to view, upload, and delete files associated with their username.
* The URI should NOT reveal the internal file structure of your web site.
** Example of what not to do: http://www.example.com/download.php?file=/home/paul/file.txt
** Another bad example: http://www.example.com/~user/file.txt
** Good example: http://www.example.com/~user/view.php?user=music&name=file.txt
*: In general, don't reveal any internal information about the site.
*: '''Food for thought:''' Given that Apache processes (with the exception of the main process) do not run as root, but rather as the user apache, how can you allow both your user account and the php scripts to read and write the
*:necessary files?
*:: ''Hint:'' You shouldn't be storing the user-uploaded files in public_html (that is only the place for your own web-page files),
*::''Hint number 2:'' you will need to use chown to change permissions to let user apache have permissions on the user-files (that '''are not''' in the public_html folder). If you don't know what this does or how to do this, look at the [[Apache]] page
* You should customize your file sharing site by implementing an additional feature or two as part of the '''creative portion'''.

You will probably find the PHP guide on this wiki to be helpful: [[PHP#Other PHP Tips]]

=== Web Security and Validation ===

Your project needs to demonstrate that thought was put into web security and best practice. For more information, see this week's Web Application Security guide: [[Web Application Security, Part 1]]

In particular:

* '''Your application needs to follow the conventions of FIEO (Filter Input and Escape Output)'''. Things you should filter include file names, usernames, and so on.
* '''Your project must pass the W3C Validator with no errors or warnings'''. For more information, see the HTML and CSS guide: [[HTML and CSS#Validation]]

== Grading ==

We will be grading the following aspects of your work. There are 105 points total.

'''Assignments (including code) must be committed to GitHub by the end of class on the due date. Commit early and often. Failing to commit by the end of class on the due date will result in a 0.

_____________

# '''Cloud Instance and Web Server (25 Points):'''
#* You can SSH into your instance using your own custom username and SSH key. Put a screenshot in your repository of your terminal SSH-ing into your instance (10 points)
#* Your custom username is able to perform SUDO commands. Put a screenshot in your repository of you successfully executing a command with sudo (5 points)
#* The time zone is correct on your instance. Put a screenshot in your repository of the results of the `date` command (5 points)
#* The UserDir Apache module is working. Place a file in /home/<username>/public_html and link to the file in your README.md (5 points)
# '''PHP Calculator (25 Points):'''
#* The calculator is able to perform all four functions with floating point numbers (2 points each, 8 points in total)
#* Each function is given as a radio button choice (4 points)
#* The calculator page passes the W3C HTML validator (3 points)
#* '''''Make sure you have a README.md file in your individual repo with the link to your calculator on your instance.''''' See the Creative Portion section for more information about .md files.
#* At least three unit tests (written with GitHub Copilot)(5 points).
#** We recommend you to use "Ask" Mode of Copilot to implement this feature
#* Completion of the AI Reflections for the individual portion of the assignment following the [[AI Best Practices]] (5 points)
# '''File Sharing Site (45 Points):'''
#* '''''File Management (25 Points):'''''
#** Users should not be able to see any files until they enter a username and log in (4 points)
#**: ''Remember that users.txt should be stored in a secure location on your filesystem. That is, '''you should not be able to type any URL into your browser and see the raw users.txt file!'''''
#** Users can see a list of all files they have uploaded (4 points)
#** Users can open files they have previously uploaded (5 points)
#**: ''Note: Users should be able to open not only plain text files but also other file formats: images, spreadsheets, etc.''
#** Users can upload files (4 points)
#**: ''Note: Like users.txt, uploaded files should be stored in a secure location on your filesystem. That is, '''do not keep your uploads directory underneath a directory served by Apache!'''''
#** Users can delete files. If a file is "deleted", it should actually be removed from the filesystem (4 points)
#** The directory structure is hidden. Users should not be able to access or view files by manipulating a URL. (2 points)
#** Users can log out (2 points)
#**: ''Note: If using session variables, you must ''actually'' log out the user by destroying their session; i.e., don't just redirect them to the login screen.''
#* '''''Best Practices (15 Points):'''''
#** Code is well formatted and easy to read, with proper commenting (4 points)
#** The site follows the FIEO philosophy (3 points)
#** All pages pass the W3C validator (3 points)
#** Completion of the AI Reflections for the group portion of the assignment following the [[AI Best Practices]] (5 points)
#* '''''Usability (5 Points):'''''
#** Site is intuitive to use and navigate (4 points)
#** Site is visually appealing (1 point)
# '''Creative Portion (10 Points)''' (see below)
#* '''''Make sure you have a README.md file in your group repo with the following:'''''
#** An .md file is a plain text file called a markdown file [https://guides.github.com/features/mastering-markdown/ ] .
#***The contents of your README.md file are shown on your repo, making it easier for us to grade
#*** You may style the page with bolding, hyperlings, images, block quotes and lists
#*** [http://dillinger.io/ This online markdown editor] makes it easy to learn this format
#** The link to your file sharing site. '''''We need this to grade your work.'''''
#** A brief description of what you did for your creative portion
#** Any additional login details needed for the TA

=== Creative Portion ===

This module and all future modules will require that you invest some time into creating additional features for your group project. Plan to invest at the very least 60 minutes of your time into the creative portion. In the above rubric, viewing files is worth five and uploading is worth four. The creative portion is worth 10 points; it should be a very sizable part of your project.

* The creative portion is an opportunity for you to learn the material of your own interest.
* You will not earn credit for a creative-portion feature that simply rehashes something you've already done in a previous module.

If you need ideas for a creative portion, or if you want to know whether or not your creative portion idea is "hard enough", ask a TA.

[[Category:Module 2]]
[[Category:Modules]]

SSH

2026-09-02T18:44:20Z

Todd: /* SSH Configuration */

Secure SHell, or '''SSH''', is the leading interface for connecting as an administrator from your local computer to something on the cloud. You will be using exclusively SSH to execute commands and upload files to your cloud instance. If you use a Git hosting service like BitBucket or Github, you will need SSH in order to save your changes there as well.

SSH access requires that the ''sshd'' daemon is running on the remote machine. By default, SSH is preinstalled on your EC2 instance. If you are not using an EC2 instance, simply install '''ssh''' from yum or apt on the remote machine.

== SSH Keys ==

SSH can work using password-based authentication, but it is more common nowadays, and also more secure, to use ''public and private keys'', also known as a ''key pair''.

Here's how it works. You have a private copy of your key, called your '''private key'''. Servers to which you want to connect have an analog to your private key called your '''public key'''. When you attempt to connect to a server using your private key, the server checks to see if any of its public keys "fits" your private key, and if it finds a match, it lets you in.

You can think of the ''private key'' as the "key" and the ''public key'' as the "lock".

== SSH Configuration ==

This section discusses how to set up your computer and your remote instance for SSH. You need to do this only once.

{{RequiredInstructions|content=

=== Creating an SSH Key Pair ===

You should create your own SSH Key Pair. You will keep the private key on your own computer, and you will upload the public key to all places to which you need to connect.

To generate a key pair, open a terminal ([[Workflow#Installing_a_Terminal_Emulator|on Windows, we recommend using Git Bash]] and run the following command:

<source lang="bash"># Run on Local Machine in Terminal or Cygwin
$ ssh-keygen -t rsa -b 4096</source>

'''Important:''' Don't name the file unless you are using a CEC machine. If you are using a CEC machine, name the file ''/cygdrive/h/.ssh/id_rsa''

For the purposes of this course, you do not need to enter a passphrase, although you would probably want one in real life.

Your keys should have been created in ~/.ssh. Check to make sure they exist using the ''ls'' command:

<source lang="bash">
$ ls ~/.ssh
id_rsa id_rsa.pub
</source>

''id_rsa'' is your private key, and ''id_rsa.pub'' is the corresponding public key. Let's look at the public signature of your key pair:

<source lang="bash">
$ cat ~/.ssh/id_rsa.pub
ssh-rsa AAAA3Bblahblahblahblah yourname@somedomain
</source>



=== Amazon EC2 SSH Configuration ===

When you first created your EC2 instance, you downloaded a *.pem file. This is the ''private key'' for the default user ('''ec2-user''' on AMI). We need use this key to connect to your instance using the default user, at which point we will create a new custom user. We will give that new user the public key that you created in the previous step. You will then be able to log into your custom user using your personal key pair, so you won't need the default user again (although you should keep the *.pem file around just in case).

==== Logging In as the Default User ====

To connect to the default user on your Amazon EC2 instance, run this command in your terminal:

<source lang="bash">
# Run on Local Machine
$ ssh -i </path/to/default-privatekey.pem> ec2-user@<ec2-xx-xx-xx-xx.compute-1.amazonaws.com>
</source>

'''Important:''' As soon as you are able to successfully log in, commands you type into your prompt will be executed on the remote instance, ''not'' your local machine.

If you get this scary-looking warning:

<source lang="text">
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: UNPROTECTED PRIVATE KEY FILE! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
</source>

…then you need to correctly set the permissions on your *.pem file. You should know how to do this from the Linux guide, but in case you didn't catch that detail, run:

<source lang="bash">
# Run on Local Machine

# Cygwin Only:

$ chgrp Users </path/to/default-privatekey.pem>

# For Everyone:
$ chmod 600 </path/to/default-privatekey.pem>
</source>

'''Food for Thought:''' Why you wouldn't want other people viewing your private key file?

==== Creating a New User with SSH Permissions ====

First, you need to create your new user with sudo and SSH permissions. Again, the instructions for this are in the Linux guide, but to keep everything in one place, the commands are:

<source lang="bash">
# Run these on your instance, not on your local machine!

# Don't forget to customize `<My Full Name>` and `<usernameHere>`:
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
$ sudo passwd <usernameHere>

# You need to add your username to the sudoers list. Refer to the Linux guide for details.
# Look around line 101.
$ sudo visudo

# Restart the SSH server:
$ sudo service sshd restart
</source>

Okay, cool: we have created our custom username on our remote instance. Now, we need to enable this account to accept our SSH key when authenticating. To do this, we need to add our public key to a file named '''authorized_keys''', which is stored in your remote username's SSH configuration directory.

To create the directory and edit the file, run on your instance:

<source lang="bash">
# Switch to our own user to ensure that permissions are set correctly:
$ su <username here>

# Change the working directory to our user's home directory:
$ cd

# Make the nonexistent SSH configuration directory and set its permissions:
$ mkdir .ssh
$ chmod 700 .ssh

# Create the `authorized_keys` file and set the permissions
$ touch .ssh/authorized_keys
$ chmod 600 .ssh/authorized_keys

# Edit the `authorized_keys` file
$ nano .ssh/authorized_keys
</source>

For more detail on editing files on the command line, see [[Linux#File Editors|the Linux guide]].

Inside of the `authorized_keys` file, paste in your public key. Your public key is the content of `~/.ssh/id_rsa.pub` '''on your local machine''' (it starts with "ssh-rsa"). There are a few ways to get it onto your clipboard:

# '''OS X Only:''' Open a new Terminal and run: <source lang="bash">cat ~/.ssh/id_rsa.pub | pbcopy</source> This immediately copies the contents of your public key to your clipboard.
# '''Windows Only:''' Navigate to id_rsa.pub manually, open it in your favorite text editor (like Notepad++), select all, and copy. The location of id_rsa.pub might be: ''C:\cygwin\home\username\.ssh\id_rsa.pub''
# '''*NIX Only:''' Open a new Terminal and copy the output of the following command: <source lang="bash">cat ~/.ssh/id_rsa.pub</source> Note that this won't work as advertised in Cygwin because Cygwin adds extra line breaks when you try to copy out of it.

When finished, save and close `authorized_keys`.

'''Food for Thought:''' How would you enable your remote user to authenticate over SSH using the same default key instead of the one you created using ''ssh-keygen''?

==== Logging In as your New User ====

Let's test whether we can log into our instance using our own username and our own key pair. Open up a new Terminal or Cygwin window '''on your local machine''' (not from ec2) and run:

<source lang="bash">
$ ssh <username here>@<ec2-xx-xx-xx-xx.amazonaws.com>
</source>

This is how you will be SSHing into your instances for the remainder of the semester.

}}

=== Troubleshooting ===

Almost everyone receives the following error at some point in their career: <code>Permission denied (publickey)</code>.

Here are some possible causes for the error.

==== The Authorized Keys File ====

Make sure that your remote ''authorized_keys'' file contains ''exactly'' your public signature from ''id_rsa.pub''.

===== Pasting into Vi =====

If you used vi to edit your file and you forgot to enter "insert" mode before pasting in your key, it is possible that you lost the first "s" in "ssh-rsa".

Check the contents of authorized_keys via <code>cat ~/.ssh/authorized_keys</code> on your server. If the output starts with "sh-rsa" instead of "ssh-rsa", edit the authorized_keys file and add the second '''s'''.

===== Unintentional Line Breaks =====

If you got your key via a <code>cat ~/.ssh/id_rsa.pub</code> and then copied it from the terminal, it's possible that you unintentionally introduced line breaks. Ensure that the key is represented by only one line of text.

==== Permissions ====

They need to be correct on both the client side and on the server side.

* Local ''.ssh'' = 700
* Local ''id_rsa'' = 600
* Remote ''.ssh'' = 700
* Remote ''authorized_keys'' = 600

If you are in Cygwin and the permissions don't seem to change, you might need to add the troubled file to a usergroup, like this:

<source lang="bash">
$ chgrp Users .ssh/id_rsa
</source>


=== More SSH Server Configurations ===

Up to this point, we have been using all of the default SSH configurations. Like most things in Linux, SSH can be customized.

For the purposes of CSE 330, the additional configurations in this short section are optional; this serves only as a reference.

==== Disabling Root Access ====

It is almost always a good idea to disable root access over ssh. This could be done by editing ''/etc/ssh/sshd_config'' and setting

<source lang="text">PermitRootLogin no</source>

You will need to restart the SSH server for changes to take effect:

<source lang="bash">
$ sudo service sshd restart
</source>

==== Enabling Password-Based Authentication ====

Up to this point, we have been using key pairs for SSH. A public/private key pair is generally considered to be more secure, but it requires that you always have access to your private key file when you want to log into your remote machine.

By default, EC2 instances allow only public/private key pair authentication. You can enable password-based authentication by setting the PaswordAuthentication option in ''/etc/ssh/sshd_config'' to '''yes''':

<source lang="text">PasswordAuthentication yes</source>

There may be a line with this option that you can un-comment. For me, it is line 25. You will need to restart the server for changes to take effect.

If possible, however, you should restrict yourself to using private and public keys.

== Using SSH ==

Once you have completed the [[#SSH Configuration]] section above, all you need to do in order to SSH into your instance is to open a terminal and run:

<source lang="bash">
$ ssh <username here>@<ec2-xx-xx-xx-xx.compute-1.amazonaws.com>
</source>

=== PuTTY ===

'''This short section about PuTTY serves only as a reference.'''

If you have Cygwin available, you should use it to SSH into your instance. However, if you are using a different computer, you might not have Cygwin at your fingertips. In this case, a lighter-weight SSH client called '''PuTTY''' is available for Windows.

You can download PuTTY from: http://www.chiark.greenend.org.uk/~sgtatham/putty/

Amazon provides [http://docs.amazonwebservices.com/AWSEC2/latest/GettingStartedGuide/ConnectToInstanceLinux.html#connect-from-windows-machine a great tutorial on how to connect to a virtual machine from Windows].

PuTTY is fairly simple and straight forward with one caveat: Amazon's ''*.pem'' files are SSH private key files, and they need to be converted to PuTTY's own '''.ppk''' format. To do this, use the ''puttygen.exe'' utility available from the same page as PuTTY. Select "Import" under the conversions menu, load the amazon ''*.pem'' key file, and press the "Save Private Key" button.

Copy and paste works similarly to the X Window System in Unix. You use the left mouse button to select text in the PuTTY window. The act of selection automatically copies the text to the clipboard: there is no need to press Ctrl-Ins or Ctrl-C or anything else. In fact, pressing Ctrl-C will send a Ctrl-C character to the other end of your connection (just like it does the rest of the time), which may have unpleasant effects. The only thing you need to do, to copy text to the clipboard, is to select it.

To paste the clipboard contents into a PuTTY window, by default you click the right mouse button. If you have a three-button mouse and are used to X applications, you can configure pasting to be done by the middle button instead, but this is not the default because most Windows users don't have a middle button at all.

Here is a good PuTTY tutorial that you might find useful to get started: http://kb.mediatemple.net/questions/1595/Using+SSH+in+Putty+%28Windows%29

== SSHFS and SFTP ==

In addition to just SSH, your SSH server also supports '''SSHFS''', which enables you to mount your remote instance as a disk on your local computer, and '''SFTP''', which is a file transfer protocol that enables you to upload files directly to your instance.

=== SSHFS ===

SSHFS is a filesystem client which allows secure mounting of remote file systems. While there are other ways to mount remote file systems, SSHFS has the advantage of being able to mount a file system located on any host that has an SSH daemon running without any host side installation or configuration. This means that you can easily access and edit your files using all of your local applications including IDEs.

As you may have inferred from the name, the underlying implementation utilizes SSH File Transfer Protocol in combination with FUSE, a package now included in the kernel that allows unprivileged users to easily create their own file systems in userspace (see the wikipedia entry for more information [http://en.wikipedia.org/wiki/Filesystem_in_Userspace]).

To mount a share using password based authentication, the command is:

<source lang="bash">
$ sshfs <user>@<domain>:</path/to/remote/directory> </path/to/local/mountpoint>
</source>

For example, to mount the directory /home/joe/myfiles in the user ''joe'''s home directory for a machine with the domain schmoesfiles.org using SSHFS you would enter the command

<source lang="bash">
$ sshfs joe@www.schmoesfiles.org:myfiles
</source>

Note that if you are using public key authentication, the command to mount the remote filesystem may need to be slightly different:

<source lang="bash">
$ sshfs -o IdentityFile=</path/to/private/key> <user>@<domain>:</path/to/remote/directory> </path/to/local/mountpoint>
</source>

To unmount the filesystem, you can use the following command:

<source lang="bash">
$ fusermount -u </path/to/local/mountpoint>
</source>

=== SFTP ===

Any server running an SSH server is also compatible with '''SFTP''' or Secure File Transfer Protocol. (Compare to FTP, or File Transfer Protocol.) SFTP is a convenient way to edit files on your computer and then upload them to your server in just a few clicks.

[[Category:Module 2]]

Workflow

2026-08-20T14:03:37Z

Todd: /* Installing a Terminal Emulator */

The few minutes it takes to optimize your workflow will be the best few minutes you will spend in CSE 330 and your career. It is remarkable how many hours you can save just by using the best interface for text editing and deployment.

== Overview ==

There are going to be several aspects to our workflow in CSE 3300, and we will be switching between multiple different programs. Here is how they all fit together.

=== Running Commands ===

''Mac OS X:'' You will be running commands on your local machine using '''Terminal''', which you can find in your Applications -> Utilities folder. You will be connecting to your server via SSH.

''Windows:'' You will be running commands on your local machine using '''Git Bash''', which you will install in the next section. You will be connecting to your server via SSH.

=== Version Control ===

You will be using '''Git''' as your version control system. Git enables you to keep track of changes to your source code. If you're using VS Code, the Git integration makes is very user friendly.

=== Text Editing ===

Although we highly recommend '''VS Code''', you may use '''Sublime Text''', '''Komodo Edit''', '''Notepad++''' (for Windows), and '''TextWrangler''' (for Mac). You can also use an IDE, like '''PHPStorm''', if you prefer.

=== File Transfer ===

In order to deploy your projects to your EC2 instance, you need some sort of method to transfer files from your local machine to your instance using SFTP. One option is using '''FileZilla''', an FTP client, to transport files from your local computer to your server.

=== Flowchart ===

If you are more visual, this flowchart might help:

[[File:CSE-330-Workflow.png]]

The flowchart illustrates 3 methods to copy files to your cloud instance: via your text editor, via an external SFTP client, and by cloning your remote Git repository. We will be primarily using '''Option 2''' in CSE 330 this semester.

In the flowchart, your ''Git Client'' is SourceTree and your ''Text Editor'' is Komodo. The ''SFTP Client'' could be FileZilla.

== Installing a Terminal Emulator ==
{{RequiredInstructions|content=

Windows is based on a fundamentally different architecture than Linux, meaning that, if you want to run Linux programs on Windows, you'll have to enable or install a special terminal emulator for it. Mac users do not need to install a terminal emulator since MacOs itself is a derivative of Unix, which is an ancestor of Linux. The Terminal utility is all you need.

=== Git Bash ===

Git Bash is a software application for Windows that gives you a Bash shell terminal and the Git command-line tool. It lets Windows users run Linux-style commands and manage code using Git. You can download it from [https://git-scm.com/install/windows Git for Windows].

}}

== Github ==

{{RequiredInstructions|content=

'''Github''' is a service that enables you to store your code for free in the cloud.

=== Creating a Github Account ===

Go to [https://github.org/ Github.org] to create an account.

'''Important:''' Use your @wustl.edu e-mail address to create your account. This will put your account on the "educational plan", which removes some limitations of the free account.

=== Adding Your Key to Github ===
'''Not uploading your key is perfectly fine, and in many cases easier. Here are the instructions though, if you'd like'''

# First make sure that you've finished the [[SSH]] guide configuration instructions.
#: We will use the same key for connecting to your remote server as for connecting to Github. (This is completely valid practice.)
# Go to the "SSH keys" section of the settings panel (Manage Account -> SSH Keys)
# Add a new key.
#* I recommend naming it after the computer you're using; if you're in the CEC, for example, you could name it "Warehouse Cygwin".
#* The contents of your key is the contents of your ''id_rsa.pub''. It looks like <code>ssh-rsa AAAAB3blahblahblahblah yourname@somedomain</code>. It is exactly the same thing that you had to paste into the ''authorized_keys'' file on your EC2 instance.

You will now be able to push code to your Github repository using your personal SSH key.

}}

== FileZilla ==

You can use SFTP from the command line, or you can use any GUI file transfer client. All FTP clients I have seen also support SFTP. One popular FTP client is [http://www.filezilla-project.org/ Filezilla].

# Download and install FileZilla from http://filezilla-project.org/download.php?type=client
#: If you are using a lab computer, you can save it to your H drive.
# When you launch FileZilla, go to Edit→Settings or FileZilla→Preferences, and go to the SFTP options (under Connection). Click "Add keyfile…".
#* Choose your ''id_rsa'' file. '''OS X Tip:''' Press Shift+Command+Period to reveal hidden files in the file chooser window.
#* FileZilla will want to make a *.ppk file. A good place to save it would be the .ssh directory as ''id_rsa.ppk''.
#: When finished, press '''OK''' (not the red ×) to save your changes.
# Back on the main FileZilla screen, there are four fields: Host, Username, Password, and Port. Fill them in as follows:
#* '''Hostname:''' sftp://<ec2-xxx-xx-xx-xxx.compute-1.amazonaws.com/>
#* '''Username:''' The username you created on your server.
#* '''Password:''' Since you are using a key, you may leave this blank.
#*: If you changed your SSH settings to allow password-based authentication, then you could put your password in here.
#* '''Port:''' 22
# Then click Quickconnect. If everything is configured correctly, FileZilla should log into your server.

[[File:FileZilla.png]]

On the left and right of the FileZilla window, you can drag files between your computer and your server. Thus, you can edit a file in a text editor like Notepad++ on your decktop, and then upload it to your server by simply dragging it from the left pane to the right pane in FileZilla.

Workflow

2026-08-20T14:03:30Z

Todd: /* Installing a Terminal Emulator */

Workflow

2026-08-20T14:00:47Z

Todd: /* Running Commands */

The few minutes it takes to optimize your workflow will be the best few minutes you will spend in CSE 330 and your career. It is remarkable how many hours you can save just by using the best interface for text editing and deployment.

== Overview ==

There are going to be several aspects to our workflow in CSE 3300, and we will be switching between multiple different programs. Here is how they all fit together.

=== Running Commands ===

''Mac OS X:'' You will be running commands on your local machine using '''Terminal''', which you can find in your Applications -> Utilities folder. You will be connecting to your server via SSH.

''Windows:'' You will be running commands on your local machine using '''Git Bash''', which you will install in the next section. You will be connecting to your server via SSH.

=== Version Control ===

You will be using '''Git''' as your version control system. Git enables you to keep track of changes to your source code. If you're using VS Code, the Git integration makes is very user friendly.

=== Text Editing ===

Although we highly recommend '''VS Code''', you may use '''Sublime Text''', '''Komodo Edit''', '''Notepad++''' (for Windows), and '''TextWrangler''' (for Mac). You can also use an IDE, like '''PHPStorm''', if you prefer.

=== File Transfer ===

In order to deploy your projects to your EC2 instance, you need some sort of method to transfer files from your local machine to your instance using SFTP. One option is using '''FileZilla''', an FTP client, to transport files from your local computer to your server.

=== Flowchart ===

If you are more visual, this flowchart might help:

[[File:CSE-330-Workflow.png]]

The flowchart illustrates 3 methods to copy files to your cloud instance: via your text editor, via an external SFTP client, and by cloning your remote Git repository. We will be primarily using '''Option 2''' in CSE 330 this semester.

In the flowchart, your ''Git Client'' is SourceTree and your ''Text Editor'' is Komodo. The ''SFTP Client'' could be FileZilla.

== Installing a Terminal Emulator ==
{{RequiredInstructions|content=

Windows is based on a fundamentally different architecture than Linux, meaning that, if you want to run Linux programs on Windows, you'll have to enable or install a special terminal emulator for it. Mac users do not need to install a terminal emulator since MacOs itself is a derivative of Unix, which is an ancestor of Linux. The Terminal utility is all you need.

=== Windows Subsystem for Linux ===

Starting in Windows 10, Windows has the ability to emulate Linux, meaning that you can run Linux commands on Windows, without having to install Cygwin. To enable WSL, follow [https://msdn.microsoft.com/en-us/commandline/wsl/install_guide these instructions]. Once those instructions are complete, you can open a shell by clicking on the Start menu, typing "Bash", then clicking on the entry labeled "Bash on Ubuntu on Windows".

=== Cygwin ===

'''Cygwin''' is a Linux Terminal emulator for Windows.

==== Installation ====

The CEC lab machines already have Cygwin installed. Follow these instructions to get Cygwin up and running on your personal PC.

# Run ''setup.exe'' from http://www.cygwin.com/
# Keep the Cygwin directory as the default, ''C:\cygwin''. Choose a place like ''C:\cygwin\downloads'' to download the installation files. Choose any download site, although probably one with a .com suffix is best when you're in the US.
# In the "Select Packages" screen, select the following packages:
#* Net -> openssh
#* Net -> openssl
#* Python -> python3 (you will need this for Module 4)
#* Devel -> git (version control system)
#* One or more of the following:
#** Editors -> vim
#** Editors -> emacs
#** Editors -> nano
# Allow the installation to complete.

Throughout the rest of this course, when we say to "open a terminal", if you are on Windows, we mean to "open WSL/Cygwin".

}}

== Github ==

{{RequiredInstructions|content=

'''Github''' is a service that enables you to store your code for free in the cloud.

=== Creating a Github Account ===

Go to [https://github.org/ Github.org] to create an account.

'''Important:''' Use your @wustl.edu e-mail address to create your account. This will put your account on the "educational plan", which removes some limitations of the free account.

=== Adding Your Key to Github ===
'''Not uploading your key is perfectly fine, and in many cases easier. Here are the instructions though, if you'd like'''

# First make sure that you've finished the [[SSH]] guide configuration instructions.
#: We will use the same key for connecting to your remote server as for connecting to Github. (This is completely valid practice.)
# Go to the "SSH keys" section of the settings panel (Manage Account -> SSH Keys)
# Add a new key.
#* I recommend naming it after the computer you're using; if you're in the CEC, for example, you could name it "Warehouse Cygwin".
#* The contents of your key is the contents of your ''id_rsa.pub''. It looks like <code>ssh-rsa AAAAB3blahblahblahblah yourname@somedomain</code>. It is exactly the same thing that you had to paste into the ''authorized_keys'' file on your EC2 instance.

You will now be able to push code to your Github repository using your personal SSH key.

}}

== FileZilla ==

You can use SFTP from the command line, or you can use any GUI file transfer client. All FTP clients I have seen also support SFTP. One popular FTP client is [http://www.filezilla-project.org/ Filezilla].

# Download and install FileZilla from http://filezilla-project.org/download.php?type=client
#: If you are using a lab computer, you can save it to your H drive.
# When you launch FileZilla, go to Edit→Settings or FileZilla→Preferences, and go to the SFTP options (under Connection). Click "Add keyfile…".
#* Choose your ''id_rsa'' file. '''OS X Tip:''' Press Shift+Command+Period to reveal hidden files in the file chooser window.
#* FileZilla will want to make a *.ppk file. A good place to save it would be the .ssh directory as ''id_rsa.ppk''.
#: When finished, press '''OK''' (not the red ×) to save your changes.
# Back on the main FileZilla screen, there are four fields: Host, Username, Password, and Port. Fill them in as follows:
#* '''Hostname:''' sftp://<ec2-xxx-xx-xx-xxx.compute-1.amazonaws.com/>
#* '''Username:''' The username you created on your server.
#* '''Password:''' Since you are using a key, you may leave this blank.
#*: If you changed your SSH settings to allow password-based authentication, then you could put your password in here.
#* '''Port:''' 22
# Then click Quickconnect. If everything is configured correctly, FileZilla should log into your server.

[[File:FileZilla.png]]

On the left and right of the FileZilla window, you can drag files between your computer and your server. Thus, you can edit a file in a text editor like Notepad++ on your decktop, and then upload it to your server by simply dragging it from the left pane to the right pane in FileZilla.

SSH

2026-08-20T13:59:37Z

Todd: /* SSH Configuration */

Secure SHell, or '''SSH''', is the leading interface for connecting as an administrator from your local computer to something on the cloud. You will be using exclusively SSH to execute commands and upload files to your cloud instance. If you use a Git hosting service like BitBucket or Github, you will need SSH in order to save your changes there as well.

SSH access requires that the ''sshd'' daemon is running on the remote machine. By default, SSH is preinstalled on your EC2 instance. If you are not using an EC2 instance, simply install '''ssh''' from yum or apt on the remote machine.

== SSH Keys ==

SSH can work using password-based authentication, but it is more common nowadays, and also more secure, to use ''public and private keys'', also known as a ''key pair''.

Here's how it works. You have a private copy of your key, called your '''private key'''. Servers to which you want to connect have an analog to your private key called your '''public key'''. When you attempt to connect to a server using your private key, the server checks to see if any of its public keys "fits" your private key, and if it finds a match, it lets you in.

You can think of the ''private key'' as the "key" and the ''public key'' as the "lock".

== SSH Configuration ==

This section discusses how to set up your computer and your remote instance for SSH. You need to do this only once.

{{RequiredInstructions|content=

=== Creating an SSH Key Pair ===

You should create your own SSH Key Pair. You will keep the private key on your own computer, and you will upload the public key to all places to which you need to connect.

To generate a key pair, open a terminal ([[Workflow#Installing_a_Terminal_Emulator|on Windows, you'll need to have enabled WSL or installed Cygwin]] and run the following command:

<source lang="bash"># Run on Local Machine in Terminal or Cygwin
$ ssh-keygen -t rsa -b 4096</source>

'''Important:''' Don't name the file unless you are using a CEC machine. If you are using a CEC machine, name the file ''/cygdrive/h/.ssh/id_rsa''

For the purposes of this course, you do not need to enter a passphrase, although you would probably want one in real life.

Your keys should have been created in ~/.ssh. Check to make sure they exist using the ''ls'' command:

<source lang="bash">
$ ls ~/.ssh
id_rsa id_rsa.pub
</source>

''id_rsa'' is your private key, and ''id_rsa.pub'' is the corresponding public key. Let's look at the public signature of your key pair:

<source lang="bash">
$ cat ~/.ssh/id_rsa.pub
ssh-rsa AAAA3Bblahblahblahblah yourname@somedomain
</source>



=== Amazon EC2 SSH Configuration ===

When you first created your EC2 instance, you downloaded a *.pem file. This is the ''private key'' for the default user ('''ec2-user''' on AMI). We need use this key to connect to your instance using the default user, at which point we will create a new custom user. We will give that new user the public key that you created in the previous step. You will then be able to log into your custom user using your personal key pair, so you won't need the default user again (although you should keep the *.pem file around just in case).

==== Logging In as the Default User ====

To connect to the default user on your Amazon EC2 instance, run this command in your terminal:

<source lang="bash">
# Run on Local Machine
$ ssh -i </path/to/default-privatekey.pem> ec2-user@<ec2-xx-xx-xx-xx.compute-1.amazonaws.com>
</source>

'''Important:''' As soon as you are able to successfully log in, commands you type into your prompt will be executed on the remote instance, ''not'' your local machine.

If you get this scary-looking warning:

<source lang="text">
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: UNPROTECTED PRIVATE KEY FILE! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
</source>

…then you need to correctly set the permissions on your *.pem file. You should know how to do this from the Linux guide, but in case you didn't catch that detail, run:

<source lang="bash">
# Run on Local Machine

# Cygwin Only:

$ chgrp Users </path/to/default-privatekey.pem>

# For Everyone:
$ chmod 600 </path/to/default-privatekey.pem>
</source>

'''Food for Thought:''' Why you wouldn't want other people viewing your private key file?

==== Creating a New User with SSH Permissions ====

First, you need to create your new user with sudo and SSH permissions. Again, the instructions for this are in the Linux guide, but to keep everything in one place, the commands are:

<source lang="bash">
# Run these on your instance, not on your local machine!

# Don't forget to customize `<My Full Name>` and `<usernameHere>`:
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
$ sudo passwd <usernameHere>

# You need to add your username to the sudoers list. Refer to the Linux guide for details.
# Look around line 101.
$ sudo visudo

# Restart the SSH server:
$ sudo service sshd restart
</source>

Okay, cool: we have created our custom username on our remote instance. Now, we need to enable this account to accept our SSH key when authenticating. To do this, we need to add our public key to a file named '''authorized_keys''', which is stored in your remote username's SSH configuration directory.

To create the directory and edit the file, run on your instance:

<source lang="bash">
# Switch to our own user to ensure that permissions are set correctly:
$ su <username here>

# Change the working directory to our user's home directory:
$ cd

# Make the nonexistent SSH configuration directory and set its permissions:
$ mkdir .ssh
$ chmod 700 .ssh

# Create the `authorized_keys` file and set the permissions
$ touch .ssh/authorized_keys
$ chmod 600 .ssh/authorized_keys

# Edit the `authorized_keys` file
$ nano .ssh/authorized_keys
</source>

For more detail on editing files on the command line, see [[Linux#File Editors|the Linux guide]].

Inside of the `authorized_keys` file, paste in your public key. Your public key is the content of `~/.ssh/id_rsa.pub` '''on your local machine''' (it starts with "ssh-rsa"). There are a few ways to get it onto your clipboard:

# '''OS X Only:''' Open a new Terminal and run: <source lang="bash">cat ~/.ssh/id_rsa.pub | pbcopy</source> This immediately copies the contents of your public key to your clipboard.
# '''Windows Only:''' Navigate to id_rsa.pub manually, open it in your favorite text editor (like Notepad++), select all, and copy. The location of id_rsa.pub might be: ''C:\cygwin\home\username\.ssh\id_rsa.pub''
# '''*NIX Only:''' Open a new Terminal and copy the output of the following command: <source lang="bash">cat ~/.ssh/id_rsa.pub</source> Note that this won't work as advertised in Cygwin because Cygwin adds extra line breaks when you try to copy out of it.

When finished, save and close `authorized_keys`.

'''Food for Thought:''' How would you enable your remote user to authenticate over SSH using the same default key instead of the one you created using ''ssh-keygen''?

==== Logging In as your New User ====

Let's test whether we can log into our instance using our own username and our own key pair. Open up a new Terminal or Cygwin window '''on your local machine''' (not from ec2) and run:

<source lang="bash">
$ ssh <username here>@<ec2-xx-xx-xx-xx.amazonaws.com>
</source>

This is how you will be SSHing into your instances for the remainder of the semester.

}}

=== Troubleshooting ===

Almost everyone receives the following error at some point in their career: <code>Permission denied (publickey)</code>.

Here are some possible causes for the error.

==== The Authorized Keys File ====

Make sure that your remote ''authorized_keys'' file contains ''exactly'' your public signature from ''id_rsa.pub''.

===== Pasting into Vi =====

If you used vi to edit your file and you forgot to enter "insert" mode before pasting in your key, it is possible that you lost the first "s" in "ssh-rsa".

Check the contents of authorized_keys via <code>cat ~/.ssh/authorized_keys</code> on your server. If the output starts with "sh-rsa" instead of "ssh-rsa", edit the authorized_keys file and add the second '''s'''.

===== Unintentional Line Breaks =====

If you got your key via a <code>cat ~/.ssh/id_rsa.pub</code> and then copied it from the terminal, it's possible that you unintentionally introduced line breaks. Ensure that the key is represented by only one line of text.

==== Permissions ====

They need to be correct on both the client side and on the server side.

* Local ''.ssh'' = 700
* Local ''id_rsa'' = 600
* Remote ''.ssh'' = 700
* Remote ''authorized_keys'' = 600

If you are in Cygwin and the permissions don't seem to change, you might need to add the troubled file to a usergroup, like this:

<source lang="bash">
$ chgrp Users .ssh/id_rsa
</source>


=== More SSH Server Configurations ===

Up to this point, we have been using all of the default SSH configurations. Like most things in Linux, SSH can be customized.

For the purposes of CSE 330, the additional configurations in this short section are optional; this serves only as a reference.

==== Disabling Root Access ====

It is almost always a good idea to disable root access over ssh. This could be done by editing ''/etc/ssh/sshd_config'' and setting

<source lang="text">PermitRootLogin no</source>

You will need to restart the SSH server for changes to take effect:

<source lang="bash">
$ sudo service sshd restart
</source>

==== Enabling Password-Based Authentication ====

Up to this point, we have been using key pairs for SSH. A public/private key pair is generally considered to be more secure, but it requires that you always have access to your private key file when you want to log into your remote machine.

By default, EC2 instances allow only public/private key pair authentication. You can enable password-based authentication by setting the PaswordAuthentication option in ''/etc/ssh/sshd_config'' to '''yes''':

<source lang="text">PasswordAuthentication yes</source>

There may be a line with this option that you can un-comment. For me, it is line 25. You will need to restart the server for changes to take effect.

If possible, however, you should restrict yourself to using private and public keys.

== Using SSH ==

Once you have completed the [[#SSH Configuration]] section above, all you need to do in order to SSH into your instance is to open a terminal and run:

<source lang="bash">
$ ssh <username here>@<ec2-xx-xx-xx-xx.compute-1.amazonaws.com>
</source>

=== PuTTY ===

'''This short section about PuTTY serves only as a reference.'''

If you have Cygwin available, you should use it to SSH into your instance. However, if you are using a different computer, you might not have Cygwin at your fingertips. In this case, a lighter-weight SSH client called '''PuTTY''' is available for Windows.

You can download PuTTY from: http://www.chiark.greenend.org.uk/~sgtatham/putty/

Amazon provides [http://docs.amazonwebservices.com/AWSEC2/latest/GettingStartedGuide/ConnectToInstanceLinux.html#connect-from-windows-machine a great tutorial on how to connect to a virtual machine from Windows].

PuTTY is fairly simple and straight forward with one caveat: Amazon's ''*.pem'' files are SSH private key files, and they need to be converted to PuTTY's own '''.ppk''' format. To do this, use the ''puttygen.exe'' utility available from the same page as PuTTY. Select "Import" under the conversions menu, load the amazon ''*.pem'' key file, and press the "Save Private Key" button.

Copy and paste works similarly to the X Window System in Unix. You use the left mouse button to select text in the PuTTY window. The act of selection automatically copies the text to the clipboard: there is no need to press Ctrl-Ins or Ctrl-C or anything else. In fact, pressing Ctrl-C will send a Ctrl-C character to the other end of your connection (just like it does the rest of the time), which may have unpleasant effects. The only thing you need to do, to copy text to the clipboard, is to select it.

To paste the clipboard contents into a PuTTY window, by default you click the right mouse button. If you have a three-button mouse and are used to X applications, you can configure pasting to be done by the middle button instead, but this is not the default because most Windows users don't have a middle button at all.

Here is a good PuTTY tutorial that you might find useful to get started: http://kb.mediatemple.net/questions/1595/Using+SSH+in+Putty+%28Windows%29

== SSHFS and SFTP ==

In addition to just SSH, your SSH server also supports '''SSHFS''', which enables you to mount your remote instance as a disk on your local computer, and '''SFTP''', which is a file transfer protocol that enables you to upload files directly to your instance.

=== SSHFS ===

SSHFS is a filesystem client which allows secure mounting of remote file systems. While there are other ways to mount remote file systems, SSHFS has the advantage of being able to mount a file system located on any host that has an SSH daemon running without any host side installation or configuration. This means that you can easily access and edit your files using all of your local applications including IDEs.

As you may have inferred from the name, the underlying implementation utilizes SSH File Transfer Protocol in combination with FUSE, a package now included in the kernel that allows unprivileged users to easily create their own file systems in userspace (see the wikipedia entry for more information [http://en.wikipedia.org/wiki/Filesystem_in_Userspace]).

To mount a share using password based authentication, the command is:

<source lang="bash">
$ sshfs <user>@<domain>:</path/to/remote/directory> </path/to/local/mountpoint>
</source>

For example, to mount the directory /home/joe/myfiles in the user ''joe'''s home directory for a machine with the domain schmoesfiles.org using SSHFS you would enter the command

<source lang="bash">
$ sshfs joe@www.schmoesfiles.org:myfiles
</source>

Note that if you are using public key authentication, the command to mount the remote filesystem may need to be slightly different:

<source lang="bash">
$ sshfs -o IdentityFile=</path/to/private/key> <user>@<domain>:</path/to/remote/directory> </path/to/local/mountpoint>
</source>

To unmount the filesystem, you can use the following command:

<source lang="bash">
$ fusermount -u </path/to/local/mountpoint>
</source>

=== SFTP ===

Any server running an SSH server is also compatible with '''SFTP''' or Secure File Transfer Protocol. (Compare to FTP, or File Transfer Protocol.) SFTP is a convenient way to edit files on your computer and then upload them to your server in just a few clicks.

[[Category:Module 2]]

AJAX and JSON

2026-08-12T14:18:58Z

Todd: /* Javascript Fetch API */

Asynchronous Javascript And XML, or '''''AJAX''''', is a group of related web development techniques, standards, and technologies used on the client (web browser) side of the standard web server-client communication model.

Here's the general concept: JavaScript is used to send requests to the web server in the background and retrieve data, without the need to refresh the page. The result: dynamic, fast, user-friendly web pages.

The requests are performed ''asynchronously'': this means that the end user can continue interacting with your web page while the server data is being loaded.

The key idea is that a large fraction of the work happens at the web browser, and larger requests happen behind the scenes, keeping waiting times for data to come back over the network to a minimum. AJAX is generally also associated with higher-level APIs and libraries that aid in producing cleaner user interfaces for web applications.

== The XMLHttpRequest Object ==

The JavaScript specification defines the '''XMLHttpRequest''' object (sometimes abbreviated as '''XHR'''), which is used to exchange data with the web servers without needing to reload the entire web page in the browser.

'''Note:''' For security reasons, you cannot perform AJAX requests to other domains, unless that domain has a special security policy set up to enable such requests.
=== Javascript Fetch API ===

While creating an xhr object works, it's messy and hard to cleanly organize JavaScript's asynchronous nature.

Javascript has a [https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch Fetch API] that you should be using. The Fetch API uses a concept in JavaScript known as a [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise Promise] to represent the completion or failure of an asynchronous operation.

=== Sending Data ===

==== GET Data ====

To send GET data, create a fetch object with method "GET"

<source lang="javascript">
fetch('/path/to/php/file', {
method: "GET"
})
</source>

You can build your url to include GET variables if you want to send data.
ex: '/path/to/php/file?x='hi'

==== POST Data ====

To send POST data, create a fetch object with method "POST". You need to create an object of the data you want to send.

<source lang="javascript">
const data = { x: 'hi', y: 'hello' };
fetch('/path/to/php/file', {
method: "POST",
body: JSON.stringify(data)
})
</source>

=== Listening for a Response ===

When expecting a response from your php script, javascript's fetch api has a clean promise-based method of handling this.

<source lang="javascript">
const pathToPhpFile = 'test.php';
const data = { x: 'hi', y: 'hello' };
fetch(pathToPhpFile, {
method: "POST",
body: JSON.stringify(data)
})
.then(res => res.json())
.then(response => console.log('Success:', JSON.stringify(response)))
.catch(error => console.error('Error:',error))
</source>

You'll notice unfamiliar syntax here with the .then() methods attached.
These are attaching event listeners to the end of your fetch request, and will trigger a function when your php script returns a response.

You should '''always''' have a catch block at the end, in case an error occurs in your response. In the near future, Javascript will ignore any requests that do not include a .catch() block.

==== Browser Support ====

Many examples that you find when Googling for "AJAX" use the '''onreadystatechange''' property of the XMLHttpRequest instance to react on the completion of the request, rather than using an event listener. This approach works, and it is required for comprehensive browser support, but it is no longer recommended for future use in modern web applications. The implementation of XMLHttpRequest documented here (so-called "XHR level 2") works in the following browsers:
* Firefox
* Safari
* Chrome
* Opera

=== Response Formats ===

More often than not, a plaintext response form the server is not very helpful: you want to transmit more information than simply a single string of text. There are two good options to get more information from a single AJAX request: '''XML''' (the original format, thus the ''X'' in ''AJAX'') and '''JSON'''.

==== XML ====

Your server can respond with an XML document (whence, ''XMLHttpRequest''). An '''XML document''' uses syntax that is extremely close to HTML For example:

<source lang="xml">
<?xml version="1.0" standalone="yes" ?>
<note>
<date year="2023" month="02" day="14" />
<to>Sally</to>
<message>Happy Valentine's Day!</message>
<from>Your Secret Admirer</from>
</note>
</source>

Like HTML, XML has a DOM that can be traversed in JavaScript.

If you make an AJAX request to a script generating an XML document, the root XML node is accessible in the '''responseXML''' property.

<source lang="javascript">
function ajaxCallback(event){
var xmlDocument = event.target.responseXML;

alert(xmlDocument.getElementsByTagName("to")[0].textContent); // Sally (in the case of the example XML above)
}
</source>

==== JSON ====

JavaScript Object Notation, or '''JSON''', is a rising standard interface format because of its lightweight syntax that makes it especially useful for AJAX requests.

The JSON syntax closely follows the syntax for [[JavaScript#Object Literals|object literals]]. For example:

<source lang="javascript">
{
"apple": {
"color": "red",
"flavor": "sweet"
},
"lemon": {
"color": "yellow",
"flavor": "sour"
}
}
</source>

Usually when JSON is transferred over the internet, it is condensed down to one line, like this:

<source lang="javascript">
{"apple":{"color":"red","flavor":"sweet"},"lemon":{"color":"yellow","flavor":"sour"}}
</source>

In JavaScript, you can convert a JSON string to an object using '''JSON.parse()'''. For example:

<source lang="javascript">
var jsonData = JSON.parse('{"apple":{"color":"red","flavor":"sweet"},"lemon":{"color":"yellow","flavor":"sour"}}');

alert(jsonData.apple.color); // red
</source>

Here's how to use it in conjunction with your AJAX response callback:

<source lang="javascript">
function ajaxCallback(event){
var jsonData = JSON.parse(event.target.responseText);

alert(jsonData.lemon.flavor); // sour (in the case of the example JSON above)
}
</source>

Here is a graphic to illustrate the JSON process.

[[File:JSON-Flowchart.png‎]]

== Examples ==

=== Logging In a User ===

Suppose you had the following PHP script:
Please note the difference in accessing POST data.

<source lang="php">
<?php
// login_ajax.php

header("Content-Type: application/json"); // Since we are sending a JSON response here (not an HTML document), set the MIME Type to application/json

//Because you are posting the data via fetch(), php has to retrieve it elsewhere.
$json_str = file_get_contents('php://input');
//This will store the data into an associative array
$json_obj = json_decode($json_str, true);

//Variables can be accessed as such:
$username = $json_obj['username'];
$password = $json_obj['password'];
//This is equivalent to what you previously did with $_POST['username'] and $_POST['password']

// Check to see if the username and password are valid. (You learned how to do this in Module 3.)

if( /* valid username and password */ ){
session_start();
$_SESSION['username'] = $username;
$_SESSION['token'] = bin2hex(openssl_random_pseudo_bytes(32));

echo json_encode(array(
"success" => true
));
exit;
}else{
echo json_encode(array(
"success" => false,
"message" => "Incorrect Username or Password"
));
exit;
}
?>
</source>

'''Note:''' This example uses PHP's very handy '''json_encode()''' function to translate an associative array into a JSON object. This means that you can access in JavaScript the same structure that you made in PHP!

And suppose you had the following HTML content:

<source lang="html4strict">
<input type="text" id="username" placeholder="Username" />
<input type="password" id="password" placeholder="Password" />
<button id="login_btn">Log In</button>

<script type="text/javascript" src="ajax.js"></script> 
</source>

You could use the following JavaScript code to prepare, send, and receive a request from the server to see if the user is logged in, without ever having to refresh the page.

<source lang="javascript">
// ajax.js

function loginAjax(event) {
const username = document.getElementById("username").value; // Get the username from the form
const password = document.getElementById("password").value; // Get the password from the form

// Make a URL-encoded string for passing POST data:
const data = { 'username': username, 'password': password };

fetch("login_ajax.php", {
method: 'POST',
body: JSON.stringify(data),
headers: { 'content-type': 'application/json' }
})
.then(response => response.json())
.then(data => console.log(data.success ? "You've been logged in!" : `You were not logged in ${data.message}`))
.catch(err => console.error(err));
}

document.getElementById("login_btn").addEventListener("click", loginAjax, false); // Bind the AJAX call to button click
</source>

'''Note:''' The above example uses an '''anonymous function''' (a function without a name that is declared in an attribute) as the callback. If you are using a certain callback function only once in your program, this is a perfectly valid approach to reduce the amount of code you need to write.

=== Loading Data from an XML File for Display in HTML ===

Suppose you have a file '''note.xml''' that contains the following information:

<source lang="xml">
<?xml version="1.0" standalone="yes" ?>
<note>
<date year="2023" month="02" day="14" />
<to>Sally</to>
<message>Happy Valentine's Day!</message>
<from>Your Secret Admirer</from>
</note>
</source>

Further, suppose you had an HTML element with ID '''note''':

<source lang="html4strict">
<div id="note"></div>
</source>

You could load this XML file and then display it inside of your HTML document like this:

<source lang="javascript">
function getNoteAjax(event){
// The XMLHttpRequest is simple this time:
var xmlHttp = new XMLHttpRequest();
xmlHttp.open("GET", "note.xml", true);
xmlHttp.addEventListener("load", getNoteCallback, false);
xmlHttp.send(null);
}

function getNoteCallback(event){
var htmlParent = document.getElementById("note"); // Get the HTML element into which we want to write the note
var xmlDocument = event.target.responseXML; // Get the XML root node from the response

// Find the <date/> element from the XML response. We expect only 1 such element, so we can call
// xmlDocument.getElementsByTagName() and then get the first (and only) element in the array all in
// one step. This is called chaining.
var xmlDateElement = xmlDocument.getElementsByTagName("date")[0];

// Put together a YYYY-MM-DD type date into a string based on the attributes of the <date/> element.
var dateString = xmlDateElement.getAttribute("year") + "-" + xmlDateElement.getAttribute("month")
+ "-" + xmlDateElement.getAttribute("day");

// Get the content of the <to>, <message>, and <from> tags. Again, you can use a chain to do this in one line for each.
var to = xmlDocument.getElementsByTagName("to")[0].textContent;
var message = xmlDocument.getElementsByTagName("message")[0].textContent;
var from = xmlDocument.getElementsByTagName("from")[0].textContent;

// Make a <strong> tag, append the date string as its content, and then append it to the HTML element.
var htmlDateObj = document.createElement("strong");
htmlDateObj.appendChild(document.createTextNode(dateString));
htmlParent.appendChild(htmlDateObj);

// Make a <p> tag to contain the note.
var htmlParagraphObj = document.createElement("p");
htmlParagraphObj.appendChild(document.createTextNode("Dear "+to+",")); // First append the greeting
htmlParagraphObj.appendChild(document.createElement("br")); // Append a couple line feeds
htmlParagraphObj.appendChild(document.createElement("br"));
htmlParagraphObj.appendChild(document.createTextNode(message)); // Write the message itself
htmlParagraphObj.appendChild(document.createElement("br")); // Append a couple more line feeds
htmlParagraphObj.appendChild(document.createElement("br"));
htmlParagraphObj.appendChild(document.createTextNode("Love, "+from)); // Finally, append the salutation
htmlParent.appendChild(htmlParagraphObj); // Append the newly engineered <p> to the HTML element.
}

document.addEventListener("DOMContentLoaded", getNoteAjax, false); // Bind the AJAX call to page load
</source>

This example uses a lot of techniques documented in the [[JavaScript#Document Object Model]] section above. The resulting DOM will be something like this:

<source lang="html4strict">
<div id="note">
<strong>2023-02-14</strong>
<p>Dear Sally,<br /><br />Happy Valentine's Day!<br /><br />Love, Your Secret Admirer</p>
</div>
</source>

== Debugging AJAX and JSON ==

It is helpful when building your application to look at the AJAX requests and responses as they happen in real time. Fortunately, there are many tools to help.

In your favorite web inspector (Chrome Dev Tools, Mozilla Dev Tools, Firebug, Dragonfly, and so on), go to the "Network" tab. This is where you can see all assets loaded by the application: images, stylesheets, and, most importantly for us, AJAX files. Some inspectors let you filter requests by type; for example, the Chrome inspector lets you click "XHR" to only show XMLHttpRequest (AJAX) requests.

You can also view the JSON sent by your server. Double-clicking the entries in the web inspector opens the source URL in a new tab.

If you find minified JSON hard to read, we recommend that you install the JSONView browser extension or one of its close relatives:
* [https://addons.mozilla.org/en-us/firefox/addon/jsonview/ Firefox]
* [https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en Chrome]
* [https://addons.opera.com/en/extensions/details/jsonviewer/ Opera]
* [https://github.com/rfletcher/safari-json-formatter Safari]

[[Category:Module 6]]

Module 6

2026-07-25T18:54:54Z

Todd: /* Dockerfile */

__NOTOC__
In Module 6, you will learn the fundamentals of Python, a widely used scripting language, and Regular Expressions, which provide powerful tools for text processing. You will also explore the Model Context Protocol (MCP), a framework that allows software tools to communicate with large language models (LLMs).

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 6]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user-controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
** <code>get_player_stats</code>: Retrieve and show batting averages for a player.
** <code>get_team_roster</code>: List all players from a given season.
** <code>get_top_players</code>: Sort and show the top hitters.
** <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''MCP Toolkit''' → '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
** <code>get_player_stats</code>: Show batting averages for one player
** <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
** <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
** <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import logging
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Configure logging to stderr
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
stream=sys.stderr,
)
logger = logging.getLogger("CardinalsMCP-server")

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

You can find an explanation of the hello function in the [[MCP_Fundamentals#Example MCP Tool: hello|MCP Fundamentals]]

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run the hello tool in the chat of Claude Desktop:

<pre>"Use CardinalsMCP to say hello"</pre>

If everything is working correctly, you should see a "Hello CSE 3300 Student" response.

After you have implemented the MCP tools, you can run commands like this:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>

==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

Module 5

2026-07-07T13:31:29Z

Todd: /* Submission Instructions */

__NOTOC__

Module 5 builds upon the JavaScript skills you learned in Module 4 and introduces server-side JavaScript using Node.js, along with real-time communication using Socket.IO.

== Reading ==

The following articles on the class wiki contain information that will help you complete the assignments:

* [[Node.JS]]
* [[Socket.IO]]
* [[FAQ - Mod 5]]

== Individual Assignments ==

=== Install Node.js ===

Install Node.js using the instructions in the [[Node.JS]] guide (use the current LTS version via nvm).

=== Static File Server in Node.js ===

The individual portion is intentionally short so you have sufficient time for the group project.

Follow these steps carefully.

# Copy the static file server example from the [[Node.JS]] page into a file named <code>app.js</code>. Save it on your EC2 instance in a directory that is NOT served by Apache.
# Ensure that you understand what the static file server script is doing.
# Create a directory parallel to <code>app.js</code> named <code>static</code>.
# Confirm that your server’s <code>STATIC_DIR</code> variable matches this directory name.
# Create the following files inside the <code>static</code> directory:
#* <code>hello.txt</code> — a text file containing: <b>Hello World</b>
#* <code>brookings.jpg</code> — download from: http://classes.engineering.wustl.edu/cse330/content/brookings.jpg
#* <code>college.html</code> — an HTML page based on the [[HTML and CSS#Quick and Easy Page Layout|Quick and Easy HTML Layout]] that includes an <code><img></code> referencing <code>brookings.jpg</code>
#* <code>phpinfo.php</code> — a PHP file containing:
#: <source lang="php"><?php phpinfo(); ?></source>
# Start your Node.js server and load all four files in your browser.

Questions to consider:

* Which files work and which do not?
* Why does <code>phpinfo.php</code> behave differently when served by Node instead of Apache?

== Group Project: Multi-Room Chat Server ==

In the group portion of Module 5, you will build a multi-room chat system using Node.js and Socket.IO.

The system must include:

* A main lobby where users select a nickname
* Ability to create chat rooms
* Ability to join chat rooms
* A list of available rooms
* A list of users currently in the room
* The entire application displayed on a single webpage

The single-room example is provided here:

* [[Socket.IO]]

== AI Agent Extension ==

You will enhance your chat server with an AI assistant.

Users can message the AI by typing:

<pre>/agent What is the capital of France?</pre>

The server detects messages that begin with <code>/agent</code>, sends the prompt to an AI model, and broadcasts the response as <b>Agent</b> in the same room.

You may use:

* Ollama (recommended — runs locally and free)
* OpenAI
* Gemini
* HuggingFace
* Any approved model

If using an API, store your key in a file named <code>.env</code> at the root of your project:

<source lang="bash">
OPENAI_API_KEY=your_key_here
</source>

Load it securely in your server:

<source lang="javascript">
import 'dotenv/config';
</source>

Refer to your chosen model’s documentation for setup details.

== Grading ==

We will be grading the following aspects of your work. There are 100 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

'''Additionally, for this module, the TA should be able to simply download your repo and start up your file server, without having to copy files or create additional subdirectories. This applies to both the individual and the creative portion'''

_________

# '''Individual Portion (30 Points):'''
#* Node.JS is installed on your EC2 instance (5 points)
#*: ''Take a screenshot of your browser visiting your EC2 instance serving up the college.html web page on port 3456, make sure the URL is visible in the screenshot.''
#* The ''hello.txt'', ''brookings.jpg'', and ''college.html'' files all load successfully (4 points each)
#* Visiting a file that does not exist inside the ''static'' directory results in a 404 (4 points)
#* Discuss in the README.md why ''phpinfo.php'' behaves the way it does when loaded through Node.JS (4 points)
#* Make sure all of your individual portion files are pushed to Github (include your node.js files, hello.txt, brookings.jpg, college.html, and phpinfo.php)
#* Completion of the AI Reflections for the individual portion of the assignment following the [[AI Best Practices]] (5 points)
# '''Multi-room Chat Server (70 Points):'''
#* '''''Administration of user created chat rooms (25 Points):'''''
#** Users can create chat rooms with an arbitrary room name(5 points)
#** Users can join an arbitrary chat room (5 points)
#** The chat room displays all users currently in the room (5 points)
#** A private room can be created that is password protected (5 points)
#** Creators of chat rooms can temporarily kick others out of the room (3 points)
#** Creators of chat rooms can permanently ban users from joining that particular room (2 points)
#* '''''Messaging (5 Points):'''''
#** A user's message shows their username and is sent to everyone in the room (1 point)
#** Users can send private messages to another user in the same room (4 points)
#* '''''Best Practices (5 Points):'''''
#** Code is well formatted and easy to read, with proper commenting (2 points)
#** Code passes HTML validation (2 points)
#** node_modules folder is ignored by version control (1 points)
#* '''''Usability (5 Points):'''''
#** Communicating with others and joining rooms is easy and intuitive (4 points)
#** Site is visually appealing (1 point)
#* '''AI Agent and Reflection (20 Points)'''
#** Implement an AI assistant accessible via the command \agent ... that replies in the current room (10 points)
#** Handles basic errors gracefully and does not crash the server (5 point)
#** Completion of the AI Reflections for the group portion of the assignment following the [[AI Best Practices]] (5 points)
#* '''Creative Portion (10 Points)'''


== Submission Instructions ==

To ensure your project can be graded quickly and reliably, follow these submission requirements carefully.

All students must submit a working GitHub repository. In addition, your project must be verifiable by the TA using one of the two methods below.

=== Required for ALL Submissions ===

Your GitHub repository must include:

* All source code for both the individual and group portions
* A complete <code>package.json</code> file
* A <code>README.md</code> containing:
** How to run your server
** Which AI model you used (Ollama, OpenAI, Gemini, etc.)
** Any special setup instructions
* A <code>.gitignore</code> file that excludes:
** <code>node_modules/</code>
** <code>.env</code>

'''Do NOT commit your API keys.'''

If your project uses environment variables, include a file named:

<source lang="bash">
.env.example
</source>

Example:

<source lang="bash">
OPENAI_API_KEY=
</source>

Your server must not crash if the API key is missing. It should fail gracefully.

=== Option A - Running on EC2 ===

Deploy your chat server on your EC2 instance and keep it running using [[#Running Tmux|tmux]].

Your README must include:

* Public EC2 URL
* Port number (e.g., 3456)
* Any login instructions (if applicable)

The TA will:

* Visit your running server
* Test chat functionality
* Test multi-room behavior
* Test the <code>/agent</code> AI command

This is the fastest and preferred grading method.

=== Option B — Local Execution + Demo Video ===

If your server is NOT running on EC2, you must provide a short demonstration video.

The video must show:

* Starting the server
* Two browser windows connected
* Chat working between users
* The <code>/agent</code> command working

Video length: approximately 1–2 minutes.

The TA may still run your code locally if needed.

=== Server Requirements ===

Your submission must:

* Start successfully with:

<source lang="bash">
npm install
node chat-server.js
</source>

(or equivalent script)

* Not require manual file copying or directory creation
* Not require editing source code to run
* Handle missing AI keys gracefully
* Not crash during normal use

=== Common Causes of Lost Points ===

* Missing README instructions
* API key committed to GitHub
* Server crashes when AI key missing
* Broken EC2 deployment (port closed)
* Cannot run after <code>npm install</code>
* <code>node_modules</code> committed to repo
* Hardcoded absolute file paths
* Missing AI demonstration

Following these instructions ensures your project can be graded quickly and fairly.

=== Running Tmux ===

To keep your Node.js apps running after you disconnect from your EC2 instance, you can use a tool called tmux. Normally, when you SSH into a server and start a program, it stops running as soon as you close the terminal. tmux lets your programs continue running in the background even after you disconnect.

First, install tmux on your EC2 instance by running:
sudo yum install tmux

To start using tmux, create a session by typing:
tmux

This opens a new terminal session managed by tmux. You can now start your Node.js server inside this session (for example, node server.js).

If you want to disconnect from the server but keep your program running, detach from tmux by pressing:
Control + b, then press d

Your Node.js app will continue running even after you disconnect from SSH.

Later, when you SSH back into your EC2 instance, you can return to the same tmux session by running:
tmux attach

[[Category:Module 5]]
[[Category:Modules]]

Module 5

2026-07-07T13:26:31Z

Todd: /* Submission Instructions */

__NOTOC__

Module 5 builds upon the JavaScript skills you learned in Module 4 and introduces server-side JavaScript using Node.js, along with real-time communication using Socket.IO.

== Reading ==

The following articles on the class wiki contain information that will help you complete the assignments:

* [[Node.JS]]
* [[Socket.IO]]
* [[FAQ - Mod 5]]

== Individual Assignments ==

=== Install Node.js ===

Install Node.js using the instructions in the [[Node.JS]] guide (use the current LTS version via nvm).

=== Static File Server in Node.js ===

The individual portion is intentionally short so you have sufficient time for the group project.

Follow these steps carefully.

# Copy the static file server example from the [[Node.JS]] page into a file named <code>app.js</code>. Save it on your EC2 instance in a directory that is NOT served by Apache.
# Ensure that you understand what the static file server script is doing.
# Create a directory parallel to <code>app.js</code> named <code>static</code>.
# Confirm that your server’s <code>STATIC_DIR</code> variable matches this directory name.
# Create the following files inside the <code>static</code> directory:
#* <code>hello.txt</code> — a text file containing: <b>Hello World</b>
#* <code>brookings.jpg</code> — download from: http://classes.engineering.wustl.edu/cse330/content/brookings.jpg
#* <code>college.html</code> — an HTML page based on the [[HTML and CSS#Quick and Easy Page Layout|Quick and Easy HTML Layout]] that includes an <code><img></code> referencing <code>brookings.jpg</code>
#* <code>phpinfo.php</code> — a PHP file containing:
#: <source lang="php"><?php phpinfo(); ?></source>
# Start your Node.js server and load all four files in your browser.

Questions to consider:

* Which files work and which do not?
* Why does <code>phpinfo.php</code> behave differently when served by Node instead of Apache?

== Group Project: Multi-Room Chat Server ==

In the group portion of Module 5, you will build a multi-room chat system using Node.js and Socket.IO.

The system must include:

* A main lobby where users select a nickname
* Ability to create chat rooms
* Ability to join chat rooms
* A list of available rooms
* A list of users currently in the room
* The entire application displayed on a single webpage

The single-room example is provided here:

* [[Socket.IO]]

== AI Agent Extension ==

You will enhance your chat server with an AI assistant.

Users can message the AI by typing:

<pre>/agent What is the capital of France?</pre>

The server detects messages that begin with <code>/agent</code>, sends the prompt to an AI model, and broadcasts the response as <b>Agent</b> in the same room.

You may use:

* Ollama (recommended — runs locally and free)
* OpenAI
* Gemini
* HuggingFace
* Any approved model

If using an API, store your key in a file named <code>.env</code> at the root of your project:

<source lang="bash">
OPENAI_API_KEY=your_key_here
</source>

Load it securely in your server:

<source lang="javascript">
import 'dotenv/config';
</source>

Refer to your chosen model’s documentation for setup details.

== Grading ==

We will be grading the following aspects of your work. There are 100 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

'''Additionally, for this module, the TA should be able to simply download your repo and start up your file server, without having to copy files or create additional subdirectories. This applies to both the individual and the creative portion'''

_________

# '''Individual Portion (30 Points):'''
#* Node.JS is installed on your EC2 instance (5 points)
#*: ''Take a screenshot of your browser visiting your EC2 instance serving up the college.html web page on port 3456, make sure the URL is visible in the screenshot.''
#* The ''hello.txt'', ''brookings.jpg'', and ''college.html'' files all load successfully (4 points each)
#* Visiting a file that does not exist inside the ''static'' directory results in a 404 (4 points)
#* Discuss in the README.md why ''phpinfo.php'' behaves the way it does when loaded through Node.JS (4 points)
#* Make sure all of your individual portion files are pushed to Github (include your node.js files, hello.txt, brookings.jpg, college.html, and phpinfo.php)
#* Completion of the AI Reflections for the individual portion of the assignment following the [[AI Best Practices]] (5 points)
# '''Multi-room Chat Server (70 Points):'''
#* '''''Administration of user created chat rooms (25 Points):'''''
#** Users can create chat rooms with an arbitrary room name(5 points)
#** Users can join an arbitrary chat room (5 points)
#** The chat room displays all users currently in the room (5 points)
#** A private room can be created that is password protected (5 points)
#** Creators of chat rooms can temporarily kick others out of the room (3 points)
#** Creators of chat rooms can permanently ban users from joining that particular room (2 points)
#* '''''Messaging (5 Points):'''''
#** A user's message shows their username and is sent to everyone in the room (1 point)
#** Users can send private messages to another user in the same room (4 points)
#* '''''Best Practices (5 Points):'''''
#** Code is well formatted and easy to read, with proper commenting (2 points)
#** Code passes HTML validation (2 points)
#** node_modules folder is ignored by version control (1 points)
#* '''''Usability (5 Points):'''''
#** Communicating with others and joining rooms is easy and intuitive (4 points)
#** Site is visually appealing (1 point)
#* '''AI Agent and Reflection (20 Points)'''
#** Implement an AI assistant accessible via the command \agent ... that replies in the current room (10 points)
#** Handles basic errors gracefully and does not crash the server (5 point)
#** Completion of the AI Reflections for the group portion of the assignment following the [[AI Best Practices]] (5 points)
#* '''Creative Portion (10 Points)'''


== Submission Instructions ==

To ensure your project can be graded quickly and reliably, follow these submission requirements carefully.

All students must submit a working GitHub repository. In addition, your project must be verifiable by the TA using one of the two methods below.

=== Required for ALL Submissions ===

Your GitHub repository must include:

* All source code for both the individual and group portions
* A complete <code>package.json</code> file
* A <code>README.md</code> containing:
** How to run your server
** Which AI model you used (Ollama, OpenAI, Gemini, etc.)
** Any special setup instructions
* A <code>.gitignore</code> file that excludes:
** <code>node_modules/</code>
** <code>.env</code>

'''Do NOT commit your API keys.'''

If your project uses environment variables, include a file named:

<source lang="bash">
.env.example
</source>

Example:

<source lang="bash">
OPENAI_API_KEY=
</source>

Your server must not crash if the API key is missing. It should fail gracefully.

=== Option A - Running on EC2 ===

Deploy your chat server on your EC2 instance and keep it running using tmux.

Your README must include:

* Public EC2 URL
* Port number (e.g., 3456)
* Any login instructions (if applicable)

The TA will:

* Visit your running server
* Test chat functionality
* Test multi-room behavior
* Test the <code>/agent</code> AI command

This is the fastest and preferred grading method.

=== Option B — Local Execution + Demo Video ===

If your server is NOT running on EC2, you must provide a short demonstration video.

The video must show:

* Starting the server
* Two browser windows connected
* Chat working between users
* The <code>/agent</code> command working

Video length: approximately 1–2 minutes.

The TA may still run your code locally if needed.

=== Server Requirements ===

Your submission must:

* Start successfully with:

<source lang="bash">
npm install
node chat-server.js
</source>

(or equivalent script)

* Not require manual file copying or directory creation
* Not require editing source code to run
* Handle missing AI keys gracefully
* Not crash during normal use

=== Common Causes of Lost Points ===

* Missing README instructions
* API key committed to GitHub
* Server crashes when AI key missing
* Broken EC2 deployment (port closed)
* Cannot run after <code>npm install</code>
* <code>node_modules</code> committed to repo
* Hardcoded absolute file paths
* Missing AI demonstration

Following these instructions ensures your project can be graded quickly and fairly.

=== Running Tmux ===

To keep your Node.js apps running after you disconnect from your EC2 instance, you can use a tool called tmux. Normally, when you SSH into a server and start a program, it stops running as soon as you close the terminal. tmux lets your programs continue running in the background even after you disconnect.

First, install tmux on your EC2 instance by running:
sudo yum install tmux

To start using tmux, create a session by typing:
tmux

This opens a new terminal session managed by tmux. You can now start your Node.js server inside this session (for example, node server.js).

If you want to disconnect from the server but keep your program running, detach from tmux by pressing:
Control + b, then press d

Your Node.js app will continue running even after you disconnect from SSH.

Later, when you SSH back into your EC2 instance, you can return to the same tmux session by running:
tmux attach

[[Category:Module 5]]
[[Category:Modules]]

Module 5

2026-07-07T13:25:34Z

Todd: /* Option A - Running on EC2 */

__NOTOC__

Module 5 builds upon the JavaScript skills you learned in Module 4 and introduces server-side JavaScript using Node.js, along with real-time communication using Socket.IO.

== Reading ==

The following articles on the class wiki contain information that will help you complete the assignments:

* [[Node.JS]]
* [[Socket.IO]]
* [[FAQ - Mod 5]]

== Individual Assignments ==

=== Install Node.js ===

Install Node.js using the instructions in the [[Node.JS]] guide (use the current LTS version via nvm).

=== Static File Server in Node.js ===

The individual portion is intentionally short so you have sufficient time for the group project.

Follow these steps carefully.

# Copy the static file server example from the [[Node.JS]] page into a file named <code>app.js</code>. Save it on your EC2 instance in a directory that is NOT served by Apache.
# Ensure that you understand what the static file server script is doing.
# Create a directory parallel to <code>app.js</code> named <code>static</code>.
# Confirm that your server’s <code>STATIC_DIR</code> variable matches this directory name.
# Create the following files inside the <code>static</code> directory:
#* <code>hello.txt</code> — a text file containing: <b>Hello World</b>
#* <code>brookings.jpg</code> — download from: http://classes.engineering.wustl.edu/cse330/content/brookings.jpg
#* <code>college.html</code> — an HTML page based on the [[HTML and CSS#Quick and Easy Page Layout|Quick and Easy HTML Layout]] that includes an <code><img></code> referencing <code>brookings.jpg</code>
#* <code>phpinfo.php</code> — a PHP file containing:
#: <source lang="php"><?php phpinfo(); ?></source>
# Start your Node.js server and load all four files in your browser.

Questions to consider:

* Which files work and which do not?
* Why does <code>phpinfo.php</code> behave differently when served by Node instead of Apache?

== Group Project: Multi-Room Chat Server ==

In the group portion of Module 5, you will build a multi-room chat system using Node.js and Socket.IO.

The system must include:

* A main lobby where users select a nickname
* Ability to create chat rooms
* Ability to join chat rooms
* A list of available rooms
* A list of users currently in the room
* The entire application displayed on a single webpage

The single-room example is provided here:

* [[Socket.IO]]

== AI Agent Extension ==

You will enhance your chat server with an AI assistant.

Users can message the AI by typing:

<pre>/agent What is the capital of France?</pre>

The server detects messages that begin with <code>/agent</code>, sends the prompt to an AI model, and broadcasts the response as <b>Agent</b> in the same room.

You may use:

* Ollama (recommended — runs locally and free)
* OpenAI
* Gemini
* HuggingFace
* Any approved model

If using an API, store your key in a file named <code>.env</code> at the root of your project:

<source lang="bash">
OPENAI_API_KEY=your_key_here
</source>

Load it securely in your server:

<source lang="javascript">
import 'dotenv/config';
</source>

Refer to your chosen model’s documentation for setup details.

== Grading ==

We will be grading the following aspects of your work. There are 100 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

'''Additionally, for this module, the TA should be able to simply download your repo and start up your file server, without having to copy files or create additional subdirectories. This applies to both the individual and the creative portion'''

_________

# '''Individual Portion (30 Points):'''
#* Node.JS is installed on your EC2 instance (5 points)
#*: ''Take a screenshot of your browser visiting your EC2 instance serving up the college.html web page on port 3456, make sure the URL is visible in the screenshot.''
#* The ''hello.txt'', ''brookings.jpg'', and ''college.html'' files all load successfully (4 points each)
#* Visiting a file that does not exist inside the ''static'' directory results in a 404 (4 points)
#* Discuss in the README.md why ''phpinfo.php'' behaves the way it does when loaded through Node.JS (4 points)
#* Make sure all of your individual portion files are pushed to Github (include your node.js files, hello.txt, brookings.jpg, college.html, and phpinfo.php)
#* Completion of the AI Reflections for the individual portion of the assignment following the [[AI Best Practices]] (5 points)
# '''Multi-room Chat Server (70 Points):'''
#* '''''Administration of user created chat rooms (25 Points):'''''
#** Users can create chat rooms with an arbitrary room name(5 points)
#** Users can join an arbitrary chat room (5 points)
#** The chat room displays all users currently in the room (5 points)
#** A private room can be created that is password protected (5 points)
#** Creators of chat rooms can temporarily kick others out of the room (3 points)
#** Creators of chat rooms can permanently ban users from joining that particular room (2 points)
#* '''''Messaging (5 Points):'''''
#** A user's message shows their username and is sent to everyone in the room (1 point)
#** Users can send private messages to another user in the same room (4 points)
#* '''''Best Practices (5 Points):'''''
#** Code is well formatted and easy to read, with proper commenting (2 points)
#** Code passes HTML validation (2 points)
#** node_modules folder is ignored by version control (1 points)
#* '''''Usability (5 Points):'''''
#** Communicating with others and joining rooms is easy and intuitive (4 points)
#** Site is visually appealing (1 point)
#* '''AI Agent and Reflection (20 Points)'''
#** Implement an AI assistant accessible via the command \agent ... that replies in the current room (10 points)
#** Handles basic errors gracefully and does not crash the server (5 point)
#** Completion of the AI Reflections for the group portion of the assignment following the [[AI Best Practices]] (5 points)
#* '''Creative Portion (10 Points)'''


== Submission Instructions ==

To ensure your project can be graded quickly and reliably, follow these submission requirements carefully.

All students must submit a working GitHub repository. In addition, your project must be verifiable by the TA using one of the two methods below.

=== Required for ALL Submissions ===

Your GitHub repository must include:

* All source code for both the individual and group portions
* A complete <code>package.json</code> file
* A <code>README.md</code> containing:
** How to run your server
** Which AI model you used (Ollama, OpenAI, Gemini, etc.)
** Any special setup instructions
* A <code>.gitignore</code> file that excludes:
** <code>node_modules/</code>
** <code>.env</code>

'''Do NOT commit your API keys.'''

If your project uses environment variables, include a file named:

<source lang="bash">
.env.example
</source>

Example:

<source lang="bash">
OPENAI_API_KEY=
</source>

Your server must not crash if the API key is missing. It should fail gracefully.

=== Option A - Running on EC2 ===

Deploy your chat server on your EC2 instance and keep it running using tmux.

Your README must include:

* Public EC2 URL
* Port number (e.g., 3456)
* Any login instructions (if applicable)

The TA will:

* Visit your running server
* Test chat functionality
* Test multi-room behavior
* Test the <code>/agent</code> AI command

This is the fastest and preferred grading method.

=== Option B — Local Execution + Demo Video ===

If your server is NOT running on EC2, you must provide a short demonstration video.

The video must show:

* Starting the server
* Two browser windows connected
* Chat working between users
* The <code>/agent</code> command working

Video length: approximately 1–2 minutes.

The TA may still run your code locally if needed.

=== Server Requirements ===

Your submission must:

* Start successfully with:

<source lang="bash">
npm install
node chat-server.js
</source>

(or equivalent script)

* Not require manual file copying or directory creation
* Not require editing source code to run
* Handle missing AI keys gracefully
* Not crash during normal use

=== Common Causes of Lost Points ===

* Missing README instructions
* API key committed to GitHub
* Server crashes when AI key missing
* Broken EC2 deployment (port closed)
* Cannot run after <code>npm install</code>
* <code>node_modules</code> committed to repo
* Hardcoded absolute file paths
* Missing AI demonstration

Following these instructions ensures your project can be graded quickly and fairly.

[[Category:Module 5]]
[[Category:Modules]]

AJAX and JSON

2026-07-06T18:26:48Z

Todd: /* Javascript Fetch API */

Asynchronous Javascript And XML, or '''''AJAX''''', is a group of related web development techniques, standards, and technologies used on the client (web browser) side of the standard web server-client communication model.

Here's the general concept: JavaScript is used to send requests to the web server in the background and retrieve data, without the need to refresh the page. The result: dynamic, fast, user-friendly web pages.

The requests are performed ''asynchronously'': this means that the end user can continue interacting with your web page while the server data is being loaded.

The key idea is that a large fraction of the work happens at the web browser, and larger requests happen behind the scenes, keeping waiting times for data to come back over the network to a minimum. AJAX is generally also associated with higher-level APIs and libraries that aid in producing cleaner user interfaces for web applications.

== The XMLHttpRequest Object ==

The JavaScript specification defines the '''XMLHttpRequest''' object (sometimes abbreviated as '''XHR'''), which is used to exchange data with the web servers without needing to reload the entire web page in the browser.

'''Note:''' For security reasons, you cannot perform AJAX requests to other domains, unless that domain has a special security policy set up to enable such requests.
=== Javascript Fetch API ===

While creating an xhr object works, it's messy and hard to cleanly organize JavaScript's asynchronous nature.

Javascript has a [https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch Fetch API] that you should be using. The Fetch API uses a concept in JavaScript known as a [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise Promise] to represent the completion or failure of an asynchronous operation.

An interesting discussion of XMLHttpRequest vs Fetch can be found [https://web.archive.org/web/20220421025435/https://blog.openreplay.com/ajax-battle-xmlhttprequest-vs-the-fetch-api here].

=== Sending Data ===

==== GET Data ====

To send GET data, create a fetch object with method "GET"

<source lang="javascript">
fetch('/path/to/php/file', {
method: "GET"
})
</source>

You can build your url to include GET variables if you want to send data.
ex: '/path/to/php/file?x='hi'

==== POST Data ====

To send POST data, create a fetch object with method "POST". You need to create an object of the data you want to send.

<source lang="javascript">
const data = { x: 'hi', y: 'hello' };
fetch('/path/to/php/file', {
method: "POST",
body: JSON.stringify(data)
})
</source>

=== Listening for a Response ===

When expecting a response from your php script, javascript's fetch api has a clean promise-based method of handling this.

<source lang="javascript">
const pathToPhpFile = 'test.php';
const data = { x: 'hi', y: 'hello' };
fetch(pathToPhpFile, {
method: "POST",
body: JSON.stringify(data)
})
.then(res => res.json())
.then(response => console.log('Success:', JSON.stringify(response)))
.catch(error => console.error('Error:',error))
</source>

You'll notice unfamiliar syntax here with the .then() methods attached.
These are attaching event listeners to the end of your fetch request, and will trigger a function when your php script returns a response.

You should '''always''' have a catch block at the end, in case an error occurs in your response. In the near future, Javascript will ignore any requests that do not include a .catch() block.

==== Browser Support ====

Many examples that you find when Googling for "AJAX" use the '''onreadystatechange''' property of the XMLHttpRequest instance to react on the completion of the request, rather than using an event listener. This approach works, and it is required for comprehensive browser support, but it is no longer recommended for future use in modern web applications. The implementation of XMLHttpRequest documented here (so-called "XHR level 2") works in the following browsers:
* Firefox
* Safari
* Chrome
* Opera

=== Response Formats ===

More often than not, a plaintext response form the server is not very helpful: you want to transmit more information than simply a single string of text. There are two good options to get more information from a single AJAX request: '''XML''' (the original format, thus the ''X'' in ''AJAX'') and '''JSON'''.

==== XML ====

Your server can respond with an XML document (whence, ''XMLHttpRequest''). An '''XML document''' uses syntax that is extremely close to HTML For example:

<source lang="xml">
<?xml version="1.0" standalone="yes" ?>
<note>
<date year="2023" month="02" day="14" />
<to>Sally</to>
<message>Happy Valentine's Day!</message>
<from>Your Secret Admirer</from>
</note>
</source>

Like HTML, XML has a DOM that can be traversed in JavaScript.

If you make an AJAX request to a script generating an XML document, the root XML node is accessible in the '''responseXML''' property.

<source lang="javascript">
function ajaxCallback(event){
var xmlDocument = event.target.responseXML;

alert(xmlDocument.getElementsByTagName("to")[0].textContent); // Sally (in the case of the example XML above)
}
</source>

==== JSON ====

JavaScript Object Notation, or '''JSON''', is a rising standard interface format because of its lightweight syntax that makes it especially useful for AJAX requests.

The JSON syntax closely follows the syntax for [[JavaScript#Object Literals|object literals]]. For example:

<source lang="javascript">
{
"apple": {
"color": "red",
"flavor": "sweet"
},
"lemon": {
"color": "yellow",
"flavor": "sour"
}
}
</source>

Usually when JSON is transferred over the internet, it is condensed down to one line, like this:

<source lang="javascript">
{"apple":{"color":"red","flavor":"sweet"},"lemon":{"color":"yellow","flavor":"sour"}}
</source>

In JavaScript, you can convert a JSON string to an object using '''JSON.parse()'''. For example:

<source lang="javascript">
var jsonData = JSON.parse('{"apple":{"color":"red","flavor":"sweet"},"lemon":{"color":"yellow","flavor":"sour"}}');

alert(jsonData.apple.color); // red
</source>

Here's how to use it in conjunction with your AJAX response callback:

<source lang="javascript">
function ajaxCallback(event){
var jsonData = JSON.parse(event.target.responseText);

alert(jsonData.lemon.flavor); // sour (in the case of the example JSON above)
}
</source>

Here is a graphic to illustrate the JSON process.

[[File:JSON-Flowchart.png‎]]

== Examples ==

=== Logging In a User ===

Suppose you had the following PHP script:
Please note the difference in accessing POST data.

<source lang="php">
<?php
// login_ajax.php

header("Content-Type: application/json"); // Since we are sending a JSON response here (not an HTML document), set the MIME Type to application/json

//Because you are posting the data via fetch(), php has to retrieve it elsewhere.
$json_str = file_get_contents('php://input');
//This will store the data into an associative array
$json_obj = json_decode($json_str, true);

//Variables can be accessed as such:
$username = $json_obj['username'];
$password = $json_obj['password'];
//This is equivalent to what you previously did with $_POST['username'] and $_POST['password']

// Check to see if the username and password are valid. (You learned how to do this in Module 3.)

if( /* valid username and password */ ){
session_start();
$_SESSION['username'] = $username;
$_SESSION['token'] = bin2hex(openssl_random_pseudo_bytes(32));

echo json_encode(array(
"success" => true
));
exit;
}else{
echo json_encode(array(
"success" => false,
"message" => "Incorrect Username or Password"
));
exit;
}
?>
</source>

'''Note:''' This example uses PHP's very handy '''json_encode()''' function to translate an associative array into a JSON object. This means that you can access in JavaScript the same structure that you made in PHP!

And suppose you had the following HTML content:

<source lang="html4strict">
<input type="text" id="username" placeholder="Username" />
<input type="password" id="password" placeholder="Password" />
<button id="login_btn">Log In</button>

<script type="text/javascript" src="ajax.js"></script> 
</source>

You could use the following JavaScript code to prepare, send, and receive a request from the server to see if the user is logged in, without ever having to refresh the page.

<source lang="javascript">
// ajax.js

function loginAjax(event) {
const username = document.getElementById("username").value; // Get the username from the form
const password = document.getElementById("password").value; // Get the password from the form

// Make a URL-encoded string for passing POST data:
const data = { 'username': username, 'password': password };

fetch("login_ajax.php", {
method: 'POST',
body: JSON.stringify(data),
headers: { 'content-type': 'application/json' }
})
.then(response => response.json())
.then(data => console.log(data.success ? "You've been logged in!" : `You were not logged in ${data.message}`))
.catch(err => console.error(err));
}

document.getElementById("login_btn").addEventListener("click", loginAjax, false); // Bind the AJAX call to button click
</source>

'''Note:''' The above example uses an '''anonymous function''' (a function without a name that is declared in an attribute) as the callback. If you are using a certain callback function only once in your program, this is a perfectly valid approach to reduce the amount of code you need to write.

=== Loading Data from an XML File for Display in HTML ===

Suppose you have a file '''note.xml''' that contains the following information:

<source lang="xml">
<?xml version="1.0" standalone="yes" ?>
<note>
<date year="2023" month="02" day="14" />
<to>Sally</to>
<message>Happy Valentine's Day!</message>
<from>Your Secret Admirer</from>
</note>
</source>

Further, suppose you had an HTML element with ID '''note''':

<source lang="html4strict">
<div id="note"></div>
</source>

You could load this XML file and then display it inside of your HTML document like this:

<source lang="javascript">
function getNoteAjax(event){
// The XMLHttpRequest is simple this time:
var xmlHttp = new XMLHttpRequest();
xmlHttp.open("GET", "note.xml", true);
xmlHttp.addEventListener("load", getNoteCallback, false);
xmlHttp.send(null);
}

function getNoteCallback(event){
var htmlParent = document.getElementById("note"); // Get the HTML element into which we want to write the note
var xmlDocument = event.target.responseXML; // Get the XML root node from the response

// Find the <date/> element from the XML response. We expect only 1 such element, so we can call
// xmlDocument.getElementsByTagName() and then get the first (and only) element in the array all in
// one step. This is called chaining.
var xmlDateElement = xmlDocument.getElementsByTagName("date")[0];

// Put together a YYYY-MM-DD type date into a string based on the attributes of the <date/> element.
var dateString = xmlDateElement.getAttribute("year") + "-" + xmlDateElement.getAttribute("month")
+ "-" + xmlDateElement.getAttribute("day");

// Get the content of the <to>, <message>, and <from> tags. Again, you can use a chain to do this in one line for each.
var to = xmlDocument.getElementsByTagName("to")[0].textContent;
var message = xmlDocument.getElementsByTagName("message")[0].textContent;
var from = xmlDocument.getElementsByTagName("from")[0].textContent;

// Make a <strong> tag, append the date string as its content, and then append it to the HTML element.
var htmlDateObj = document.createElement("strong");
htmlDateObj.appendChild(document.createTextNode(dateString));
htmlParent.appendChild(htmlDateObj);

// Make a <p> tag to contain the note.
var htmlParagraphObj = document.createElement("p");
htmlParagraphObj.appendChild(document.createTextNode("Dear "+to+",")); // First append the greeting
htmlParagraphObj.appendChild(document.createElement("br")); // Append a couple line feeds
htmlParagraphObj.appendChild(document.createElement("br"));
htmlParagraphObj.appendChild(document.createTextNode(message)); // Write the message itself
htmlParagraphObj.appendChild(document.createElement("br")); // Append a couple more line feeds
htmlParagraphObj.appendChild(document.createElement("br"));
htmlParagraphObj.appendChild(document.createTextNode("Love, "+from)); // Finally, append the salutation
htmlParent.appendChild(htmlParagraphObj); // Append the newly engineered <p> to the HTML element.
}

document.addEventListener("DOMContentLoaded", getNoteAjax, false); // Bind the AJAX call to page load
</source>

This example uses a lot of techniques documented in the [[JavaScript#Document Object Model]] section above. The resulting DOM will be something like this:

<source lang="html4strict">
<div id="note">
<strong>2023-02-14</strong>
<p>Dear Sally,<br /><br />Happy Valentine's Day!<br /><br />Love, Your Secret Admirer</p>
</div>
</source>

== Debugging AJAX and JSON ==

It is helpful when building your application to look at the AJAX requests and responses as they happen in real time. Fortunately, there are many tools to help.

In your favorite web inspector (Chrome Dev Tools, Mozilla Dev Tools, Firebug, Dragonfly, and so on), go to the "Network" tab. This is where you can see all assets loaded by the application: images, stylesheets, and, most importantly for us, AJAX files. Some inspectors let you filter requests by type; for example, the Chrome inspector lets you click "XHR" to only show XMLHttpRequest (AJAX) requests.

You can also view the JSON sent by your server. Double-clicking the entries in the web inspector opens the source URL in a new tab.

If you find minified JSON hard to read, we recommend that you install the JSONView browser extension or one of its close relatives:
* [https://addons.mozilla.org/en-us/firefox/addon/jsonview/ Firefox]
* [https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en Chrome]
* [https://addons.opera.com/en/extensions/details/jsonviewer/ Opera]
* [https://github.com/rfletcher/safari-json-formatter Safari]

[[Category:Module 6]]

Module 4

2026-06-29T23:13:39Z

Todd: /* Connect Four Debugging Exercise */

__NOTOC__

In Module 4, you will learn JavaScript, the dominant client-side web language. JavaScript is the second programming language you will learn in CSE 3300.

This article contains your assignments for Module 4.

'''Warning:'''

''This module takes students a while. It is strongly recommended that you start early and ask questions as they come up.''

=== Learning Goals ===
* JavaScript
* DOM Events
* AJAX
* JSON

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[JavaScript]]
* [[AJAX and JSON]]
* [[jQuery]]
* [[Web Application Security, Part 3]]
* [[FAQ - Mod 4]]
* [[FAQ - Mod 5]]

== Individual Assignments ==

'''''IMPORTANT:'' The individual assignments must be completed ''without'' using a JavaScript library like jQuery.''' However, you may use jQuery for the group portion.

=== JavaScript Calculator ===

In Module 2, you made a calculator using PHP. Now you will be making one using JavaScript.

* The web page should have two input fields and a radio button group for the operation, with the 4 basic math operations represented (add, subtract, multiply, divide).
* JavaScript should monitor all three fields and display the current result whenever the user changes any value in any field, without refreshing the page.
*: '''Tip 1:''' Consider using either the ''change'' or the ''keyup'' event on the text fields, and either the ''change'' or the ''click'' event on the radio buttons.
*: '''Tip 2:''' Re-read [[JavaScript|the JavaScript guide]] if you need help figuring our how to bind callback functions to events, or how to determine which radio button is currently selected. (There are examples for both of these!)
* The calculator should be completely self-contained; i.e., you should not be making any requests to any other server-side or client-side scripts or web pages after the initial page load.

'''Tip:''' You can embed JavaScript code into an HTML document like this:

<source lang="html4strict">
<script>
// your code here
</script>
</source>

'''Tip:''' If your code isn't working the way you expect, use a JavaScript error console. In Chrome, for example, press Ctrl-Shift-I (or Cmd-Option-I) to open the WebKit inspector.

'''Important:''' It is best practice to fully separate the content, appearance, and behavior. In previous modules, you may have lost points for using HTML tags that change the appearance of things <nowiki>(like <center> and <font>).</nowiki> In this module, make sure that you define your event listeners in JavaScript as in <code>document.getElementById("xyz").addEventListener(...)</code> and '''''not''''' in the HTML like <code><button onclick="badExample();">Bad Example</button></code>.

=== Weather Widget ===

In this section, you will make a web page that displays the weather forecast using AJAX requests to a weather server.

# Make an empty HTML document; name it '''weather.html'''
#: Refer to the [[HTML and CSS]] guide for the skeleton of an HTML document
# Define a function in JavaScript; call it '''fetchWeather()'''. You may write your JavaScript in an embedded script in your HTML document.
# Inside your '''fetchWeather()''' function, make an AJAX request to the weather server.
#: We have a server that outputs the current weather in JSON format. The format is documented in the [[#JSON Structure]] section below.

#: '''URL:''' https://classes.engineering.wustl.edu/cse330/content/weather_json.php
#* '''IMPORTANT:''' Under normal circumstances, AJAX requests ''cannot'' be performed cross-domain for security reasons. We have set the <code>Access-Control-Allow-Origin</code> header on our server to allow requests from your EC2 instances, or from localhost. '''You will therefore need to upload your code to your EC2, or access it via localhost, in order for the AJAX requests to work.''' This means that you cannot, for example, complete this part of the individual portion in JSFiddle.
# In your callback, process the JSON and use JavaScript to manipulate the HTML DOM to display the following information on your page:
#* Location
#** City, in a <nowiki><strong></nowiki> tag
#** State, not in any tag
#* Humidity
#* Current Temperature
#* Image for Tomorrow's Forecast (see [[#Weather Condition Images]] below for more information)
#* Image for the Day After Tomorrow's Forecast
# Finally, bind '''fetchWeather()''' to the DOMContentLoaded event so that your weather widget is automatically initialized when the page is loaded:
#: <source lang="javascript">document.addEventListener("DOMContentLoaded", fetchWeather, false);</source>
# In addition, add a button that runs your ''fetchWeather'' function when clicked. This should update your widget with the current weather conditions.

Use the following HTML:

<source lang="html4strict">
<div class="weather" id="weatherWidget">
<div class="weather-loc"></div>
<div class="weather-humidity"></div>
<div class="weather-temp"></div>
<img class="weather-tomorrow" />
<img class="weather-dayaftertomorrow" />
</div>
</source>

Include the CSS file from here: https://classes.engineering.wustl.edu/cse330/content/weather.css

When everything is working, the weather widget should look something like this:

[[File:WeatherWidget.png]]

'''Important:''' The widget in this section needs to work in only Firefox and Chrome. It does '''''not''''' need to work Internet Explorer.

==== Tips ====

===== JSON Structure =====

The JSON from our server looks like this:

<source lang="javascript">
{
"updated": "Thu, 11 Oct 2025 5:54 pm CDT",
"location": {
"city": "St. Louis",
"state": "MO"
},
"wind": {
"chill": "62",
"direction": "150",
"speed": "3 mph"
},
"atmosphere": {
"humidity": "50",
"visibility": "10",
"pressure": "30.12 in"
},
"current": {
"code": "28",
"text": "Mostly Cloudy",
"temp": "62°F",
"date": "Thu, 11 Oct 2025 5:54 pm CDT"
},
"tomorrow": {
"code": "29",
"text": "Clouds Early/Clearing Late",
"low": "45°F",
"high": "61°F"
},
"dayafter": {
"code": "30",
"text": "Partly Cloudy",
"low": "53°F",
"high": "65°F"
},
"credit": "http://us.rd.yahoo.com/dailynews/rss/weather/St._Louis__MO/*http://weather.yahoo.com/forecast/USMO0170_f.html"
}
</source>

===== Weather Condition Images =====

Each day's forecast has a code. There are images associated with these codes.

One place to get the images is from here: <nowiki>http://us.yimg.com/i/us/nws/weather/gr/</nowiki>'''##'''<nowiki>ds.png</nowiki>

Replace the '''##''' with the forecast code. For example, for code 32, the URL would be: http://us.yimg.com/i/us/nws/weather/gr/32ds.png

=== Connect Four Debugging Exercise ===

As a short debugging exercise for Module 4, you will be given a broken Connect Four implementation (located in the repository and named `connect4`). You may also download the files [https://research.engineering.wustl.edu/~todd/cse3300-wiki/connect4/ here].

The goals of this assignment are to complete the following:

* Run the provided program and observe failures or incorrect behavior.
* Produce a list of all bugs you find. For each bug include:
** The file and function (or approximate line) where it appears
** A short description of why it is a bug and what symptom it causes (crash, wrong output, missing feature)
** A suggested fix (one or two sentences)
* Use GitHub Copilot in "Agent" mode to assist you in writing and testing fixes. When you use Copilot Agent, document the prompts you issued, any code the agent generated, and what changes you applied or rejected after code review.
* Produce a corrected version of the program that can demonstrate the following:
** A horizontal, vertical, or diagonal win is detected correctly
** A draw (full-board) is detected correctly

A video of the working Connect Four app can be found
[https://wustl.box.com/s/4u4h0rx9z7umrunmgdv0fq73rhhz8p99 here]

Documentation to include in your repository:
* The bug list (as described above) is inserted as a comment at the top of the connect4.js file
* The Copilot Agent prompts you used and a short evaluation of the suggestions (what was helpful, what you changed) in the AI Reflection
* The corrected file(s) committed to your GitHub repo

To receive full credit, you must complete the following:
* Identifying and explaining each real bug
* Correct fixes that produce a working game (wins + draw)
* Proper documentation of Copilot Agent usage and critical review

This exercise is intended to teach debugging, careful code review, and responsible use of AI coding assistants (reviewing and accepting/rejecting suggestions). Keep your commits small and descriptive so the instructor can follow your reasoning.

== Group Project ==

=== Calendar ===

Build a simple calendar that allows users to add and remove events dynamically.

You will use JavaScript to process user interactions at the web browser, without ever refreshing the browser after the initial web page load. You may use a JavaScript library of your choice, so long as that JavaScript library does not defeat the purpose of the assignment. If you have questions about this, ask. In particular, libraries like FullCalendar are unacceptable.

Your application should utilize AJAX to run server-side scripts that query your database to save and retrieve information, including user accounts and events.

We have also written some functions to help you get started: [[JavaScript Calendar Library]]

==== Examples ====

* https://calendar.google.com/
* http://www.zoho.com/calendar/

==== Server Side Language ====

Additionally, you may use a database of your choice. MySQL is probably the logical choice since you have been using it since Module 2, but you are free to explore other databases if you like.
==== Calendar Requirements ====

* Support a month-by-month view of the calendar.
*: Show one month at a time, with buttons to move forward or backward.
*: There should be no limit to how far forward or backward the user can go.
* Users can register and log in to the website.
*: You may leverage your MySQL project code and database from module 3 to get started.
* Unregistered users should see no events on the calendar.
* Registered users can add events.
*: All events should have a date and time, but do not need to have a duration.
*: You do ''not'' need to support recurring events (where you add an event that repeats, for example, every Monday).
* Registered users see only events that they have added.
*: Your AJAX should not ask the server for events from a certain username. Instead, your AJAX should ask the server for events, and the server should respond with the events for only the currently-logged-in user (from the session). Can you think of why?
* Registered users can edit and delete their own events, but not the events of others.
*: Again, the server should edit and delete events based on the username present in the session, not based on a username or event ID provided by the user. (If it deletes only based on an Event ID, an attacker could feed any arbitrary Event ID to your server, even if he/she didn't own that event.)
* All user and event data should be kept in a database.
* At no time should the main page need to be reloaded.
*: User registration, user authentication, event addition, and event deletion should all be handled by JavaScript and AJAX requests to your server.
* Your page needs to work in the versions of Firefox and Chrome installed on the lab computers.

'''Tip:''' Run your database schema by a TA before implementing it.

=== Web Security and Validation ===

Your project needs to demonstrate that thought was put into web security and best practice. For more information, see this week's Web Application Security guide: [[Web Application Security, Part 3]]

In particular:

* '''Your application needs to prevent XSS attacks.''' Be careful when transmitting data over JSON that will be reflected in an event title! (Note: JSON data should be sanitized on the client side, not the server side.)
* '''Perform precautionary measures to prevent session hijacking attacks.'''
*: You should specify your session cookie to be HTTP-Only. However, for the means of this module, you need not test for user agent consistency.

You should continue the practices that you have learned in past weeks:

* Pass tokens in forms to prevent CSRF attacks.
*: '''Hint:''' You will need to send your CSRF tokens in your AJAX requests. Remember that AJAX still submits forms and runs server-side scripts, just like the vanilla forms you've been using in Modules 2 and 3.
* Use prepared queries to prevent SQL Injection attacks.
* If storing passwords in a database, always store them salted and encrypted.
* Your page should validate with no errors or warnings through the W3C validator.

=== AI Security Audit with GitHub Copilot ===

For this module, you will use GitHub Copilot to perform a security audit of your calendar application. This exercise is designed to help you learn how to leverage AI tools for code security analysis while maintaining critical thinking about the results.

* Code Generation: Use GitHub Copilot to help implement core calendar features if needed
* Security Review: Use Copilot's code analysis capabilities to:
** Identify potential security vulnerabilities in your JavaScript and PHP code
** Check for common web security issues (XSS, CSRF, SQL injection, etc.)
**Review authentication and authorization logic
*Vulnerability Assessment: Ask Copilot to analyze specific security aspects:
**Input validation and output escaping
**Session management security
**AJAX request security
**Database query safety

Required Tasks:
#Use GitHub Copilot to generate at least 3 security-focused code reviews for different parts of your application
#Implement fixes for at least 2 identified security issues (real or potential)
#Document the security audit process and findings

* Documentation Requirements
**Examples of security-focused prompts you used with Copilot
**Security issues identified (both real and false positives)
**Changes made based on the security audit
**Your assessment of Copilot's effectiveness as a security review tool

== Grading ==

We will be grading the following aspects of your work. There are 125 points in total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

If you do not include a link to your individual and group portion running on your instance in the respective README.md, you will receive a 0 for the missing portion

_________

# '''JavaScript Calculator (10 Points):'''
#* Calculator successfully adds, subtracts, multiplies, and divides numbers (3 points)
#* The result is automatically computed when a value in either field is changed (3 points)
#* Calculator is written entirely in pure, conventional JavaScript with no external libraries (4 points)*
#*: ''Note: be sure to fully separate content, appearance, and behavior. This means that you should '''not''' use the event attributes on the HTML elements like onclick, onchange, and onkeyup.''
# '''Weather Widget (15 Points):'''
#* Widget performs an AJAX request to fetch the current weather (4 points)
#* The HTML template is filled with the correct information, including an image (4 points)
#* Button to reload the weather widget (2 points)
#* Widget is written entirely in pure, conventional JavaScript with no external libraries (5 points)*
# '''Connect Four Debugging Exercise (15 Points):'''
#* Identify and explain bugs in the provided `connect4.js` (5 points)
#** For each bug, include location (function/lines), description of the symptom, and the root cause.
#* Correct the program so it reliably detects wins and draws and handles invalid input (5 points)
#* Completion of the AI Reflections for the individual portion of the assignment following the AI Best Practices (5 points)
#**Include the prompts used, what Copilot suggested, and what you changed or rejected.
# '''AJAX Calendar (60 Points):'''
#* '''''Calendar View (10 Points):'''''
#** The calendar is displayed as a table grid with days as the columns and weeks as the rows, one month at a time (5 points)
#** The user can view different months as far in the past or future as desired (5 points)
#* '''''User and Event Management (25 Points):'''''
#** Events can be added, modified, and deleted (5 points)
#** Events have a title, date, and time (2 points)
#** Users can log into the site, and they cannot view or manipulate events associated with other users (8 points)
#**: ''Don't fall into the Abuse of Functionality trap! Check user credentials on the server side as well as on the client side.''
#** All actions are performed over AJAX, without ever needing to reload the page (7 points)
#** Refreshing the page does not log a user out (3 points)
#* '''''Best Practices (20 Points):'''''
#** Code is well formatted and easy to read, with proper commenting (2 points)
#** If storing passwords, they are stored salted and hashed (2 points)
#** All AJAX requests that either contain sensitive information or modify something on the server are performed via POST, not GET (3 points)
#** Safe from XSS attacks; that is, all content is escaped on output (3 points)
#** Safe from SQL Injection attacks (2 points)
#** CSRF tokens are passed when adding/editing/deleting events (3 points)
#** Session cookie is HTTP-Only (3 points)
#** Page passes the W3C validator (2 points)
#* '''''Usability (5 Points):'''''
#** Site is intuitive to use and navigate (4 points)
#** Site is visually appealing (1 point)
# '''Creative Portion & AI Security Audit (25 Points)'''
#* '''''AI Security Audit Implementation (15 Points):'''''
#** Used GitHub Copilot for security analysis of at least 3 different code components (4 points)
#** Documented security audit process and findings in README.md (3 points)
#** Completion of the AI Reflections for the group portion of the assignment following the AI Best Practices (5 points)
#** Implemented fixes for identified security issues (3 points)
#** We recommend you to use "Agent" Mode of Copilot to implement this feature
#** Be sure to create a new branch before implement this in case any of your original code being changed.
#* '''Additional Calendars Features (worth 10 points):''' Develop some additional features for the calendar, a few examples are provided below.
#** Users can tag an event with a particular category and enable/disable those tags in the calendar view. (5 points)
#** Users can share their calendar with additional users. (5 points)
#** Users can create group events that display on multiple users calendars (5 points)
#** Feature enhances user experience and calendar functionality
#* '''''Make sure to save a description of your creative portion, AI security audit process, and a link to your server in your README.md file.'''''

''* These points can be earned only if at least 3 other points have been earned in that category. This is to prevent these points from being "free."''

[[Category:Module 4]]
[[Category:Modules]]

Module 4

2026-06-29T20:20:32Z

Todd: /* Weather Widget */

__NOTOC__

In Module 4, you will learn JavaScript, the dominant client-side web language. JavaScript is the second programming language you will learn in CSE 3300.

This article contains your assignments for Module 4.

'''Warning:'''

''This module takes students a while. It is strongly recommended that you start early and ask questions as they come up.''

=== Learning Goals ===
* JavaScript
* DOM Events
* AJAX
* JSON

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[JavaScript]]
* [[AJAX and JSON]]
* [[jQuery]]
* [[Web Application Security, Part 3]]
* [[FAQ - Mod 4]]
* [[FAQ - Mod 5]]

== Individual Assignments ==

'''''IMPORTANT:'' The individual assignments must be completed ''without'' using a JavaScript library like jQuery.''' However, you may use jQuery for the group portion.

=== JavaScript Calculator ===

In Module 2, you made a calculator using PHP. Now you will be making one using JavaScript.

* The web page should have two input fields and a radio button group for the operation, with the 4 basic math operations represented (add, subtract, multiply, divide).
* JavaScript should monitor all three fields and display the current result whenever the user changes any value in any field, without refreshing the page.
*: '''Tip 1:''' Consider using either the ''change'' or the ''keyup'' event on the text fields, and either the ''change'' or the ''click'' event on the radio buttons.
*: '''Tip 2:''' Re-read [[JavaScript|the JavaScript guide]] if you need help figuring our how to bind callback functions to events, or how to determine which radio button is currently selected. (There are examples for both of these!)
* The calculator should be completely self-contained; i.e., you should not be making any requests to any other server-side or client-side scripts or web pages after the initial page load.

'''Tip:''' You can embed JavaScript code into an HTML document like this:

<source lang="html4strict">
<script>
// your code here
</script>
</source>

'''Tip:''' If your code isn't working the way you expect, use a JavaScript error console. In Chrome, for example, press Ctrl-Shift-I (or Cmd-Option-I) to open the WebKit inspector.

'''Important:''' It is best practice to fully separate the content, appearance, and behavior. In previous modules, you may have lost points for using HTML tags that change the appearance of things <nowiki>(like <center> and <font>).</nowiki> In this module, make sure that you define your event listeners in JavaScript as in <code>document.getElementById("xyz").addEventListener(...)</code> and '''''not''''' in the HTML like <code><button onclick="badExample();">Bad Example</button></code>.

=== Weather Widget ===

In this section, you will make a web page that displays the weather forecast using AJAX requests to a weather server.

# Make an empty HTML document; name it '''weather.html'''
#: Refer to the [[HTML and CSS]] guide for the skeleton of an HTML document
# Define a function in JavaScript; call it '''fetchWeather()'''. You may write your JavaScript in an embedded script in your HTML document.
# Inside your '''fetchWeather()''' function, make an AJAX request to the weather server.
#: We have a server that outputs the current weather in JSON format. The format is documented in the [[#JSON Structure]] section below.

#: '''URL:''' https://classes.engineering.wustl.edu/cse330/content/weather_json.php
#* '''IMPORTANT:''' Under normal circumstances, AJAX requests ''cannot'' be performed cross-domain for security reasons. We have set the <code>Access-Control-Allow-Origin</code> header on our server to allow requests from your EC2 instances, or from localhost. '''You will therefore need to upload your code to your EC2, or access it via localhost, in order for the AJAX requests to work.''' This means that you cannot, for example, complete this part of the individual portion in JSFiddle.
# In your callback, process the JSON and use JavaScript to manipulate the HTML DOM to display the following information on your page:
#* Location
#** City, in a <nowiki><strong></nowiki> tag
#** State, not in any tag
#* Humidity
#* Current Temperature
#* Image for Tomorrow's Forecast (see [[#Weather Condition Images]] below for more information)
#* Image for the Day After Tomorrow's Forecast
# Finally, bind '''fetchWeather()''' to the DOMContentLoaded event so that your weather widget is automatically initialized when the page is loaded:
#: <source lang="javascript">document.addEventListener("DOMContentLoaded", fetchWeather, false);</source>
# In addition, add a button that runs your ''fetchWeather'' function when clicked. This should update your widget with the current weather conditions.

Use the following HTML:

<source lang="html4strict">
<div class="weather" id="weatherWidget">
<div class="weather-loc"></div>
<div class="weather-humidity"></div>
<div class="weather-temp"></div>
<img class="weather-tomorrow" />
<img class="weather-dayaftertomorrow" />
</div>
</source>

Include the CSS file from here: https://classes.engineering.wustl.edu/cse330/content/weather.css

When everything is working, the weather widget should look something like this:

[[File:WeatherWidget.png]]

'''Important:''' The widget in this section needs to work in only Firefox and Chrome. It does '''''not''''' need to work Internet Explorer.

==== Tips ====

===== JSON Structure =====

The JSON from our server looks like this:

<source lang="javascript">
{
"updated": "Thu, 11 Oct 2025 5:54 pm CDT",
"location": {
"city": "St. Louis",
"state": "MO"
},
"wind": {
"chill": "62",
"direction": "150",
"speed": "3 mph"
},
"atmosphere": {
"humidity": "50",
"visibility": "10",
"pressure": "30.12 in"
},
"current": {
"code": "28",
"text": "Mostly Cloudy",
"temp": "62°F",
"date": "Thu, 11 Oct 2025 5:54 pm CDT"
},
"tomorrow": {
"code": "29",
"text": "Clouds Early/Clearing Late",
"low": "45°F",
"high": "61°F"
},
"dayafter": {
"code": "30",
"text": "Partly Cloudy",
"low": "53°F",
"high": "65°F"
},
"credit": "http://us.rd.yahoo.com/dailynews/rss/weather/St._Louis__MO/*http://weather.yahoo.com/forecast/USMO0170_f.html"
}
</source>

===== Weather Condition Images =====

Each day's forecast has a code. There are images associated with these codes.

One place to get the images is from here: <nowiki>http://us.yimg.com/i/us/nws/weather/gr/</nowiki>'''##'''<nowiki>ds.png</nowiki>

Replace the '''##''' with the forecast code. For example, for code 32, the URL would be: http://us.yimg.com/i/us/nws/weather/gr/32ds.png

=== Connect Four Debugging Exercise ===

As a short debugging exercise for Module 4, you will be given a broken Connect Four implementation (located in the repository and named `connect4`). You may also download the files [https://research.engineering.wustl.edu/~todd/cse3300-wiki/connect4/ here].

The goals of this assignment are to complete the following:

* Run the provided program and observe failures or incorrect behavior.
* Produce a list of all bugs you find. For each bug include:
** The file and function (or approximate line) where it appears
** A short description of why it is a bug and what symptom it causes (crash, wrong output, missing feature)
** A suggested fix (one or two sentences)
* Use GitHub Copilot in "Agent" mode to assist you in writing and testing fixes. When you use Copilot Agent, document the prompts you issued, any code the agent generated, and what changes you applied or rejected after code review.
* Produce a corrected version of the program that can demonstrate the following:
** A horizontal, vertical, or diagonal win is detected correctly
** A draw (full-board) is detected correctly

A video of the working Connect Four app can be found [https://wustl.box.com/s/jjafn5x0ffcjki8irfni1ko1e4jickqh here]

Documentation to include in your repository:
* The bug list (as described above) is inserted as a comment at the top of the connect4.js file
* The Copilot Agent prompts you used and a short evaluation of the suggestions (what was helpful, what you changed) in the AI Reflection
* The corrected file(s) committed to your GitHub repo

To receive full credit, you must complete the following:
* Identifying and explaining each real bug
* Correct fixes that produce a working game (wins + draw)
* Proper documentation of Copilot Agent usage and critical review

This exercise is intended to teach debugging, careful code review, and responsible use of AI coding assistants (reviewing and accepting/rejecting suggestions). Keep your commits small and descriptive so the instructor can follow your reasoning.

== Group Project ==

=== Calendar ===

Build a simple calendar that allows users to add and remove events dynamically.

You will use JavaScript to process user interactions at the web browser, without ever refreshing the browser after the initial web page load. You may use a JavaScript library of your choice, so long as that JavaScript library does not defeat the purpose of the assignment. If you have questions about this, ask. In particular, libraries like FullCalendar are unacceptable.

Your application should utilize AJAX to run server-side scripts that query your database to save and retrieve information, including user accounts and events.

We have also written some functions to help you get started: [[JavaScript Calendar Library]]

==== Examples ====

* https://calendar.google.com/
* http://www.zoho.com/calendar/

==== Server Side Language ====

Additionally, you may use a database of your choice. MySQL is probably the logical choice since you have been using it since Module 2, but you are free to explore other databases if you like.
==== Calendar Requirements ====

* Support a month-by-month view of the calendar.
*: Show one month at a time, with buttons to move forward or backward.
*: There should be no limit to how far forward or backward the user can go.
* Users can register and log in to the website.
*: You may leverage your MySQL project code and database from module 3 to get started.
* Unregistered users should see no events on the calendar.
* Registered users can add events.
*: All events should have a date and time, but do not need to have a duration.
*: You do ''not'' need to support recurring events (where you add an event that repeats, for example, every Monday).
* Registered users see only events that they have added.
*: Your AJAX should not ask the server for events from a certain username. Instead, your AJAX should ask the server for events, and the server should respond with the events for only the currently-logged-in user (from the session). Can you think of why?
* Registered users can edit and delete their own events, but not the events of others.
*: Again, the server should edit and delete events based on the username present in the session, not based on a username or event ID provided by the user. (If it deletes only based on an Event ID, an attacker could feed any arbitrary Event ID to your server, even if he/she didn't own that event.)
* All user and event data should be kept in a database.
* At no time should the main page need to be reloaded.
*: User registration, user authentication, event addition, and event deletion should all be handled by JavaScript and AJAX requests to your server.
* Your page needs to work in the versions of Firefox and Chrome installed on the lab computers.

'''Tip:''' Run your database schema by a TA before implementing it.

=== Web Security and Validation ===

Your project needs to demonstrate that thought was put into web security and best practice. For more information, see this week's Web Application Security guide: [[Web Application Security, Part 3]]

In particular:

* '''Your application needs to prevent XSS attacks.''' Be careful when transmitting data over JSON that will be reflected in an event title! (Note: JSON data should be sanitized on the client side, not the server side.)
* '''Perform precautionary measures to prevent session hijacking attacks.'''
*: You should specify your session cookie to be HTTP-Only. However, for the means of this module, you need not test for user agent consistency.

You should continue the practices that you have learned in past weeks:

* Pass tokens in forms to prevent CSRF attacks.
*: '''Hint:''' You will need to send your CSRF tokens in your AJAX requests. Remember that AJAX still submits forms and runs server-side scripts, just like the vanilla forms you've been using in Modules 2 and 3.
* Use prepared queries to prevent SQL Injection attacks.
* If storing passwords in a database, always store them salted and encrypted.
* Your page should validate with no errors or warnings through the W3C validator.

=== AI Security Audit with GitHub Copilot ===

For this module, you will use GitHub Copilot to perform a security audit of your calendar application. This exercise is designed to help you learn how to leverage AI tools for code security analysis while maintaining critical thinking about the results.

* Code Generation: Use GitHub Copilot to help implement core calendar features if needed
* Security Review: Use Copilot's code analysis capabilities to:
** Identify potential security vulnerabilities in your JavaScript and PHP code
** Check for common web security issues (XSS, CSRF, SQL injection, etc.)
**Review authentication and authorization logic
*Vulnerability Assessment: Ask Copilot to analyze specific security aspects:
**Input validation and output escaping
**Session management security
**AJAX request security
**Database query safety

Required Tasks:
#Use GitHub Copilot to generate at least 3 security-focused code reviews for different parts of your application
#Implement fixes for at least 2 identified security issues (real or potential)
#Document the security audit process and findings

* Documentation Requirements
**Examples of security-focused prompts you used with Copilot
**Security issues identified (both real and false positives)
**Changes made based on the security audit
**Your assessment of Copilot's effectiveness as a security review tool

== Grading ==

We will be grading the following aspects of your work. There are 125 points in total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

If you do not include a link to your individual and group portion running on your instance in the respective README.md, you will receive a 0 for the missing portion

_________

# '''JavaScript Calculator (10 Points):'''
#* Calculator successfully adds, subtracts, multiplies, and divides numbers (3 points)
#* The result is automatically computed when a value in either field is changed (3 points)
#* Calculator is written entirely in pure, conventional JavaScript with no external libraries (4 points)*
#*: ''Note: be sure to fully separate content, appearance, and behavior. This means that you should '''not''' use the event attributes on the HTML elements like onclick, onchange, and onkeyup.''
# '''Weather Widget (15 Points):'''
#* Widget performs an AJAX request to fetch the current weather (4 points)
#* The HTML template is filled with the correct information, including an image (4 points)
#* Button to reload the weather widget (2 points)
#* Widget is written entirely in pure, conventional JavaScript with no external libraries (5 points)*
# '''Connect Four Debugging Exercise (15 Points):'''
#* Identify and explain bugs in the provided `connect4.js` (5 points)
#** For each bug, include location (function/lines), description of the symptom, and the root cause.
#* Correct the program so it reliably detects wins and draws and handles invalid input (5 points)
#* Completion of the AI Reflections for the individual portion of the assignment following the AI Best Practices (5 points)
#**Include the prompts used, what Copilot suggested, and what you changed or rejected.
# '''AJAX Calendar (60 Points):'''
#* '''''Calendar View (10 Points):'''''
#** The calendar is displayed as a table grid with days as the columns and weeks as the rows, one month at a time (5 points)
#** The user can view different months as far in the past or future as desired (5 points)
#* '''''User and Event Management (25 Points):'''''
#** Events can be added, modified, and deleted (5 points)
#** Events have a title, date, and time (2 points)
#** Users can log into the site, and they cannot view or manipulate events associated with other users (8 points)
#**: ''Don't fall into the Abuse of Functionality trap! Check user credentials on the server side as well as on the client side.''
#** All actions are performed over AJAX, without ever needing to reload the page (7 points)
#** Refreshing the page does not log a user out (3 points)
#* '''''Best Practices (20 Points):'''''
#** Code is well formatted and easy to read, with proper commenting (2 points)
#** If storing passwords, they are stored salted and hashed (2 points)
#** All AJAX requests that either contain sensitive information or modify something on the server are performed via POST, not GET (3 points)
#** Safe from XSS attacks; that is, all content is escaped on output (3 points)
#** Safe from SQL Injection attacks (2 points)
#** CSRF tokens are passed when adding/editing/deleting events (3 points)
#** Session cookie is HTTP-Only (3 points)
#** Page passes the W3C validator (2 points)
#* '''''Usability (5 Points):'''''
#** Site is intuitive to use and navigate (4 points)
#** Site is visually appealing (1 point)
# '''Creative Portion & AI Security Audit (25 Points)'''
#* '''''AI Security Audit Implementation (15 Points):'''''
#** Used GitHub Copilot for security analysis of at least 3 different code components (4 points)
#** Documented security audit process and findings in README.md (3 points)
#** Completion of the AI Reflections for the group portion of the assignment following the AI Best Practices (5 points)
#** Implemented fixes for identified security issues (3 points)
#** We recommend you to use "Agent" Mode of Copilot to implement this feature
#** Be sure to create a new branch before implement this in case any of your original code being changed.
#* '''Additional Calendars Features (worth 10 points):''' Develop some additional features for the calendar, a few examples are provided below.
#** Users can tag an event with a particular category and enable/disable those tags in the calendar view. (5 points)
#** Users can share their calendar with additional users. (5 points)
#** Users can create group events that display on multiple users calendars (5 points)
#** Feature enhances user experience and calendar functionality
#* '''''Make sure to save a description of your creative portion, AI security audit process, and a link to your server in your README.md file.'''''

''* These points can be earned only if at least 3 other points have been earned in that category. This is to prevent these points from being "free."''

[[Category:Module 4]]
[[Category:Modules]]

Module 4

2026-06-29T15:09:22Z

Todd: /* Weather Widget */

__NOTOC__

In Module 4, you will learn JavaScript, the dominant client-side web language. JavaScript is the second programming language you will learn in CSE 3300.

This article contains your assignments for Module 4.

'''Warning:'''

''This module takes students a while. It is strongly recommended that you start early and ask questions as they come up.''

=== Learning Goals ===
* JavaScript
* DOM Events
* AJAX
* JSON

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[JavaScript]]
* [[AJAX and JSON]]
* [[jQuery]]
* [[Web Application Security, Part 3]]
* [[FAQ - Mod 4]]
* [[FAQ - Mod 5]]

== Individual Assignments ==

'''''IMPORTANT:'' The individual assignments must be completed ''without'' using a JavaScript library like jQuery.''' However, you may use jQuery for the group portion.

=== JavaScript Calculator ===

In Module 2, you made a calculator using PHP. Now you will be making one using JavaScript.

* The web page should have two input fields and a radio button group for the operation, with the 4 basic math operations represented (add, subtract, multiply, divide).
* JavaScript should monitor all three fields and display the current result whenever the user changes any value in any field, without refreshing the page.
*: '''Tip 1:''' Consider using either the ''change'' or the ''keyup'' event on the text fields, and either the ''change'' or the ''click'' event on the radio buttons.
*: '''Tip 2:''' Re-read [[JavaScript|the JavaScript guide]] if you need help figuring our how to bind callback functions to events, or how to determine which radio button is currently selected. (There are examples for both of these!)
* The calculator should be completely self-contained; i.e., you should not be making any requests to any other server-side or client-side scripts or web pages after the initial page load.

'''Tip:''' You can embed JavaScript code into an HTML document like this:

<source lang="html4strict">
<script>
// your code here
</script>
</source>

'''Tip:''' If your code isn't working the way you expect, use a JavaScript error console. In Chrome, for example, press Ctrl-Shift-I (or Cmd-Option-I) to open the WebKit inspector.

'''Important:''' It is best practice to fully separate the content, appearance, and behavior. In previous modules, you may have lost points for using HTML tags that change the appearance of things <nowiki>(like <center> and <font>).</nowiki> In this module, make sure that you define your event listeners in JavaScript as in <code>document.getElementById("xyz").addEventListener(...)</code> and '''''not''''' in the HTML like <code><button onclick="badExample();">Bad Example</button></code>.

=== Weather Widget ===

In this section, you will make a web page that displays the weather forecast using AJAX requests to a weather server.

# Make an empty HTML document; name it '''weather.html'''
#: Refer to the [[HTML and CSS]] guide for the skeleton of an HTML document
# Define a function in JavaScript; call it '''fetchWeather()'''. You may write your JavaScript in an embedded script in your HTML document.
# Inside your '''fetchWeather()''' function, make an AJAX request to the weather server.
#: We have a server that outputs the current weather in JSON format. The format is documented in the [[#JSON Structure]] section below.
#: '''URL:''' http://ec2-100-52-167-82.compute-1.amazonaws.com/weather_json.php
#* '''IMPORTANT:''' Under normal circumstances, AJAX requests ''cannot'' be performed cross-domain for security reasons. We have set the <code>Access-Control-Allow-Origin</code> header on our server to allow requests from your EC2 instances, or from localhost. '''You will therefore need to upload your code to your EC2, or access it via localhost, in order for the AJAX requests to work.''' This means that you cannot, for example, complete this part of the individual portion in JSFiddle.
# In your callback, process the JSON and use JavaScript to manipulate the HTML DOM to display the following information on your page:
#* Location
#** City, in a <nowiki><strong></nowiki> tag
#** State, not in any tag
#* Humidity
#* Current Temperature
#* Image for Tomorrow's Forecast (see [[#Weather Condition Images]] below for more information)
#* Image for the Day After Tomorrow's Forecast
# Finally, bind '''fetchWeather()''' to the DOMContentLoaded event so that your weather widget is automatically initialized when the page is loaded:
#: <source lang="javascript">document.addEventListener("DOMContentLoaded", fetchWeather, false);</source>
# In addition, add a button that runs your ''fetchWeather'' function when clicked. This should update your widget with the current weather conditions.

Use the following HTML:

<source lang="html4strict">
<div class="weather" id="weatherWidget">
<div class="weather-loc"></div>
<div class="weather-humidity"></div>
<div class="weather-temp"></div>
<img class="weather-tomorrow" />
<img class="weather-dayaftertomorrow" />
</div>
</source>

Include the CSS file from here: https://classes.engineering.wustl.edu/cse330/content/weather.css

When everything is working, the weather widget should look something like this:

[[File:WeatherWidget.png]]

'''Important:''' The widget in this section needs to work in only Firefox and Chrome. It does '''''not''''' need to work Internet Explorer.

==== Tips ====

===== JSON Structure =====

The JSON from our server looks like this:

<source lang="javascript">
{
"updated": "Thu, 11 Oct 2025 5:54 pm CDT",
"location": {
"city": "St. Louis",
"state": "MO"
},
"wind": {
"chill": "62",
"direction": "150",
"speed": "3 mph"
},
"atmosphere": {
"humidity": "50",
"visibility": "10",
"pressure": "30.12 in"
},
"current": {
"code": "28",
"text": "Mostly Cloudy",
"temp": "62°F",
"date": "Thu, 11 Oct 2025 5:54 pm CDT"
},
"tomorrow": {
"code": "29",
"text": "Clouds Early/Clearing Late",
"low": "45°F",
"high": "61°F"
},
"dayafter": {
"code": "30",
"text": "Partly Cloudy",
"low": "53°F",
"high": "65°F"
},
"credit": "http://us.rd.yahoo.com/dailynews/rss/weather/St._Louis__MO/*http://weather.yahoo.com/forecast/USMO0170_f.html"
}
</source>

===== Weather Condition Images =====

Each day's forecast has a code. There are images associated with these codes.

One place to get the images is from here: <nowiki>http://us.yimg.com/i/us/nws/weather/gr/</nowiki>'''##'''<nowiki>ds.png</nowiki>

Replace the '''##''' with the forecast code. For example, for code 32, the URL would be: http://us.yimg.com/i/us/nws/weather/gr/32ds.png

=== Connect Four Debugging Exercise ===

As a short debugging exercise for Module 4, you will be given a broken Connect Four implementation (located in the repository and named `connect4`). You may also download the files [https://research.engineering.wustl.edu/~todd/cse3300-wiki/connect4/ here].

The goals of this assignment are to complete the following:

* Run the provided program and observe failures or incorrect behavior.
* Produce a list of all bugs you find. For each bug include:
** The file and function (or approximate line) where it appears
** A short description of why it is a bug and what symptom it causes (crash, wrong output, missing feature)
** A suggested fix (one or two sentences)
* Use GitHub Copilot in "Agent" mode to assist you in writing and testing fixes. When you use Copilot Agent, document the prompts you issued, any code the agent generated, and what changes you applied or rejected after code review.
* Produce a corrected version of the program that can demonstrate the following:
** A horizontal, vertical, or diagonal win is detected correctly
** A draw (full-board) is detected correctly

A video of the working Connect Four app can be found [https://wustl.box.com/s/jjafn5x0ffcjki8irfni1ko1e4jickqh here]

Documentation to include in your repository:
* The bug list (as described above) is inserted as a comment at the top of the connect4.js file
* The Copilot Agent prompts you used and a short evaluation of the suggestions (what was helpful, what you changed) in the AI Reflection
* The corrected file(s) committed to your GitHub repo

To receive full credit, you must complete the following:
* Identifying and explaining each real bug
* Correct fixes that produce a working game (wins + draw)
* Proper documentation of Copilot Agent usage and critical review

This exercise is intended to teach debugging, careful code review, and responsible use of AI coding assistants (reviewing and accepting/rejecting suggestions). Keep your commits small and descriptive so the instructor can follow your reasoning.

== Group Project ==

=== Calendar ===

Build a simple calendar that allows users to add and remove events dynamically.

You will use JavaScript to process user interactions at the web browser, without ever refreshing the browser after the initial web page load. You may use a JavaScript library of your choice, so long as that JavaScript library does not defeat the purpose of the assignment. If you have questions about this, ask. In particular, libraries like FullCalendar are unacceptable.

Your application should utilize AJAX to run server-side scripts that query your database to save and retrieve information, including user accounts and events.

We have also written some functions to help you get started: [[JavaScript Calendar Library]]

==== Examples ====

* https://calendar.google.com/
* http://www.zoho.com/calendar/

==== Server Side Language ====

Additionally, you may use a database of your choice. MySQL is probably the logical choice since you have been using it since Module 2, but you are free to explore other databases if you like.
==== Calendar Requirements ====

* Support a month-by-month view of the calendar.
*: Show one month at a time, with buttons to move forward or backward.
*: There should be no limit to how far forward or backward the user can go.
* Users can register and log in to the website.
*: You may leverage your MySQL project code and database from module 3 to get started.
* Unregistered users should see no events on the calendar.
* Registered users can add events.
*: All events should have a date and time, but do not need to have a duration.
*: You do ''not'' need to support recurring events (where you add an event that repeats, for example, every Monday).
* Registered users see only events that they have added.
*: Your AJAX should not ask the server for events from a certain username. Instead, your AJAX should ask the server for events, and the server should respond with the events for only the currently-logged-in user (from the session). Can you think of why?
* Registered users can edit and delete their own events, but not the events of others.
*: Again, the server should edit and delete events based on the username present in the session, not based on a username or event ID provided by the user. (If it deletes only based on an Event ID, an attacker could feed any arbitrary Event ID to your server, even if he/she didn't own that event.)
* All user and event data should be kept in a database.
* At no time should the main page need to be reloaded.
*: User registration, user authentication, event addition, and event deletion should all be handled by JavaScript and AJAX requests to your server.
* Your page needs to work in the versions of Firefox and Chrome installed on the lab computers.

'''Tip:''' Run your database schema by a TA before implementing it.

=== Web Security and Validation ===

Your project needs to demonstrate that thought was put into web security and best practice. For more information, see this week's Web Application Security guide: [[Web Application Security, Part 3]]

In particular:

* '''Your application needs to prevent XSS attacks.''' Be careful when transmitting data over JSON that will be reflected in an event title! (Note: JSON data should be sanitized on the client side, not the server side.)
* '''Perform precautionary measures to prevent session hijacking attacks.'''
*: You should specify your session cookie to be HTTP-Only. However, for the means of this module, you need not test for user agent consistency.

You should continue the practices that you have learned in past weeks:

* Pass tokens in forms to prevent CSRF attacks.
*: '''Hint:''' You will need to send your CSRF tokens in your AJAX requests. Remember that AJAX still submits forms and runs server-side scripts, just like the vanilla forms you've been using in Modules 2 and 3.
* Use prepared queries to prevent SQL Injection attacks.
* If storing passwords in a database, always store them salted and encrypted.
* Your page should validate with no errors or warnings through the W3C validator.

=== AI Security Audit with GitHub Copilot ===

For this module, you will use GitHub Copilot to perform a security audit of your calendar application. This exercise is designed to help you learn how to leverage AI tools for code security analysis while maintaining critical thinking about the results.

* Code Generation: Use GitHub Copilot to help implement core calendar features if needed
* Security Review: Use Copilot's code analysis capabilities to:
** Identify potential security vulnerabilities in your JavaScript and PHP code
** Check for common web security issues (XSS, CSRF, SQL injection, etc.)
**Review authentication and authorization logic
*Vulnerability Assessment: Ask Copilot to analyze specific security aspects:
**Input validation and output escaping
**Session management security
**AJAX request security
**Database query safety

Required Tasks:
#Use GitHub Copilot to generate at least 3 security-focused code reviews for different parts of your application
#Implement fixes for at least 2 identified security issues (real or potential)
#Document the security audit process and findings

* Documentation Requirements
**Examples of security-focused prompts you used with Copilot
**Security issues identified (both real and false positives)
**Changes made based on the security audit
**Your assessment of Copilot's effectiveness as a security review tool

== Grading ==

We will be grading the following aspects of your work. There are 125 points in total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

If you do not include a link to your individual and group portion running on your instance in the respective README.md, you will receive a 0 for the missing portion

_________

# '''JavaScript Calculator (10 Points):'''
#* Calculator successfully adds, subtracts, multiplies, and divides numbers (3 points)
#* The result is automatically computed when a value in either field is changed (3 points)
#* Calculator is written entirely in pure, conventional JavaScript with no external libraries (4 points)*
#*: ''Note: be sure to fully separate content, appearance, and behavior. This means that you should '''not''' use the event attributes on the HTML elements like onclick, onchange, and onkeyup.''
# '''Weather Widget (15 Points):'''
#* Widget performs an AJAX request to fetch the current weather (4 points)
#* The HTML template is filled with the correct information, including an image (4 points)
#* Button to reload the weather widget (2 points)
#* Widget is written entirely in pure, conventional JavaScript with no external libraries (5 points)*
# '''Connect Four Debugging Exercise (15 Points):'''
#* Identify and explain bugs in the provided `connect4.js` (5 points)
#** For each bug, include location (function/lines), description of the symptom, and the root cause.
#* Correct the program so it reliably detects wins and draws and handles invalid input (5 points)
#* Completion of the AI Reflections for the individual portion of the assignment following the AI Best Practices (5 points)
#**Include the prompts used, what Copilot suggested, and what you changed or rejected.
# '''AJAX Calendar (60 Points):'''
#* '''''Calendar View (10 Points):'''''
#** The calendar is displayed as a table grid with days as the columns and weeks as the rows, one month at a time (5 points)
#** The user can view different months as far in the past or future as desired (5 points)
#* '''''User and Event Management (25 Points):'''''
#** Events can be added, modified, and deleted (5 points)
#** Events have a title, date, and time (2 points)
#** Users can log into the site, and they cannot view or manipulate events associated with other users (8 points)
#**: ''Don't fall into the Abuse of Functionality trap! Check user credentials on the server side as well as on the client side.''
#** All actions are performed over AJAX, without ever needing to reload the page (7 points)
#** Refreshing the page does not log a user out (3 points)
#* '''''Best Practices (20 Points):'''''
#** Code is well formatted and easy to read, with proper commenting (2 points)
#** If storing passwords, they are stored salted and hashed (2 points)
#** All AJAX requests that either contain sensitive information or modify something on the server are performed via POST, not GET (3 points)
#** Safe from XSS attacks; that is, all content is escaped on output (3 points)
#** Safe from SQL Injection attacks (2 points)
#** CSRF tokens are passed when adding/editing/deleting events (3 points)
#** Session cookie is HTTP-Only (3 points)
#** Page passes the W3C validator (2 points)
#* '''''Usability (5 Points):'''''
#** Site is intuitive to use and navigate (4 points)
#** Site is visually appealing (1 point)
# '''Creative Portion & AI Security Audit (25 Points)'''
#* '''''AI Security Audit Implementation (15 Points):'''''
#** Used GitHub Copilot for security analysis of at least 3 different code components (4 points)
#** Documented security audit process and findings in README.md (3 points)
#** Completion of the AI Reflections for the group portion of the assignment following the AI Best Practices (5 points)
#** Implemented fixes for identified security issues (3 points)
#** We recommend you to use "Agent" Mode of Copilot to implement this feature
#** Be sure to create a new branch before implement this in case any of your original code being changed.
#* '''Additional Calendars Features (worth 10 points):''' Develop some additional features for the calendar, a few examples are provided below.
#** Users can tag an event with a particular category and enable/disable those tags in the calendar view. (5 points)
#** Users can share their calendar with additional users. (5 points)
#** Users can create group events that display on multiple users calendars (5 points)
#** Feature enhances user experience and calendar functionality
#* '''''Make sure to save a description of your creative portion, AI security audit process, and a link to your server in your README.md file.'''''

''* These points can be earned only if at least 3 other points have been earned in that category. This is to prevent these points from being "free."''

[[Category:Module 4]]
[[Category:Modules]]

Module 1

2026-06-23T13:07:28Z

Todd: /* Make a Portal to a DuckDuckGo Search */

__NOTOC__
Module 1 introduces the fundamentals of HTML and CSS. You will first make a static document using HTML and CSS, and then you will make a portal to a DuckDuckGo search. This module is worth 80 points.

=== Learning Goals ===

* HTML
* CSS
* Git
* VS Code
* HTML Forms

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignment.

* [[Git]]
* [[HTML and CSS]]
* [[HTML Forms]]
* [[VS Code]]
* [[FAQ - Mod 1]]

== Assignments ==

=== Write a Birthday Card ===

'''Write a birthday card to a friend or family member using HTML and CSS.''' Use HTML to define the content of the card (like the headings and the paragraphs), and use CSS to define the appearance. Some ideas:

* Make the background-color of the page baby blue and use purple ink to write a card to a little boy
* Make the text big and include pictures of hearts
* Use a font with text shadows (more advanced)

Use this opportunity to experiment with the plethora of CSS properties. Remember that you're in a computer science class (not an art class), so we don't care if your card looks ugly. The main thing is that you learn HTML and CSS and use them appropriately.

==== AI-Powered Animation Requirement ====

For this assignment, you are required to use an AI tool (e.g., ChatGPT, GitHub Copilot) to generate one creative CSS animation for your birthday card. This component is worth 10 points of the overall grade, split as follows:

* '''Implementation (5 points):''' Integrate the AI-generated CSS animation into your birthday card so that it runs correctly.
* '''Documentation (5 points):''' In your project's README file, document the AI tool you used, the prompt you gave, and how you applied the generated code.

Example prompts you could use include:
* Generate CSS code to make a heart icon pulse using keyframes.
* How can I create a bouncing animation for text with CSS?
* Provide code for a smooth color-changing background animation.

You must implement the AI-generated code, ensure it works, and document its use in your project's README.

==== How to Edit Your File ====

Throughout this course we '''highly''' recommend using VS Code https://code.visualstudio.com/download, and have included tips for each module specific to VS Code.
Visit the wiki page [[VS Code]] and check out the Module 1 section

'''Important Note:''' Writing your web page in a word processor like Microsoft Word or even WordPad or TextEdit will ''not'' work. You need a plain text editor.

==== How to View Your HTML Document ====

Once you have ''birthday.html'', you can open it using your favorite web browser (like Firefox). For the purposes of this exercise, it suffices to right-click the file and tell it to "open with" Firefox. When the file opens, it should be under the file:/// protocol.

In Module 2, we will install a web server that serves up pages on the http:// and https:// protocols.

==== Validation ====

'''Your birthday card and search portal pages must pass the W3C Validators for both HTML and CSS with no errors or warnings.''' You can upload your HTML to [https://validator.w3.org/ the HTML validator] and your CSS to [https://jigsaw.w3.org/css-validator/ the CSS validator].

For more information on validation, see the HTML and CSS guide: [[HTML and CSS#Validation]]

=== Make a Portal to a DuckDuckGo Search ===

'''Write an HTML document containing a form that searches DuckDuckGo's web site.''' You should be able to type in a search term and have your form load the DuckDuckGo search page. In this HTML document you must also include this course's regrade policy to ensure that you have read it and understand it. [https://www.arl.wustl.edu/~todd/cse3300/regrade.html Regrade Policy]

# Visit [https://www.duckduckgo.com/ www.duckduckgo.com]. Search for something easy to spot in the URL, like "QUERY".
# Look at the URL of the search page. What is the query variable?
# Make an HTML document containing a text field and a submit button. Typing a search query into the text field and pressing the submit button should load the DuckDuckGo search page.

- Additionally, we want you to copy/paste this course's regrade policy somewhere into this html document to ensure your familiarity.

=== Git Tutorial ===

Complete all of the levels of the Main and Remote sections of [https://learngitbranching.js.org/ this Git tutorial]. After you finish the tutorial, take two screenshots showing the completion of all of the levels of the Main and Remote sections. Place these two screenshots in your repo.

== Grading ==

We will be grading the following aspects of your work. There are 80 points total.

'''Assignments (including code) must be committed to GitHub by the end of class on the due date. Commit early and often. Failing to commit by the end of class on the due date will result in a 0.

# '''Birthday Card (35 Points):'''
#* Correct usage of HTML and CSS in your birthday card (10 points).
#*: ''Make sure that you use HTML for "content" and CSS for "appearance." Don't write inline styles: use a separate stylesheet and link your HTML file to it.''
#* Experimenting with at least 5 different CSS properties in your birthday card (10 points).
#* Implementation of an AI-generated CSS animation (5 points).
#* Birthday card and search portal pages pass the W3C validation for HTML 5 and CSS. (10 points).
# '''Search Portal (10 Points):'''
#* DuckDuckGo search portal is functional (9 points).
#* Your search portal page includes the text of this course's regrade policy (1 point).
# '''Account Creation and Version Control (10 Points):'''
#* GitHub account created (2 Points)
#* Module 1 repo created using the link provided on Piazza (2 Points)
#* Account created on Amazon Web Services and an image file containing a screenshot of your account page pushed to GitHub. (4 Points)
#* Files pushed to repo on GitHub using Git (2 Points)
# '''Git Tutorial (20 Points):'''
#* Two screenshots showing the completion of all of the levels of the Main and Remote sections placed in your individual assignment repository.
# '''AI Reflection (5 Points):'''
#* Document use of AI for this assignment in the AI Reflections as described in [[AI Best Practices]] (5 Points)

[[Category:Module 1]]
[[Category:Modules]]

Module 1

2026-06-08T19:59:39Z

Todd: /* Make a Portal to a DuckDuckGo Search */

__NOTOC__
Module 1 introduces the fundamentals of HTML and CSS. You will first make a static document using HTML and CSS, and then you will make a portal to a DuckDuckGo search. This module is worth 80 points.

=== Learning Goals ===

* HTML
* CSS
* Git
* VS Code
* HTML Forms

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignment.

* [[Git]]
* [[HTML and CSS]]
* [[HTML Forms]]
* [[VS Code]]
* [[FAQ - Mod 1]]

== Assignments ==

=== Write a Birthday Card ===

'''Write a birthday card to a friend or family member using HTML and CSS.''' Use HTML to define the content of the card (like the headings and the paragraphs), and use CSS to define the appearance. Some ideas:

* Make the background-color of the page baby blue and use purple ink to write a card to a little boy
* Make the text big and include pictures of hearts
* Use a font with text shadows (more advanced)

Use this opportunity to experiment with the plethora of CSS properties. Remember that you're in a computer science class (not an art class), so we don't care if your card looks ugly. The main thing is that you learn HTML and CSS and use them appropriately.

==== AI-Powered Animation Requirement ====

For this assignment, you are required to use an AI tool (e.g., ChatGPT, GitHub Copilot) to generate one creative CSS animation for your birthday card. This component is worth 10 points of the overall grade, split as follows:

* '''Implementation (5 points):''' Integrate the AI-generated CSS animation into your birthday card so that it runs correctly.
* '''Documentation (5 points):''' In your project's README file, document the AI tool you used, the prompt you gave, and how you applied the generated code.

Example prompts you could use include:
* Generate CSS code to make a heart icon pulse using keyframes.
* How can I create a bouncing animation for text with CSS?
* Provide code for a smooth color-changing background animation.

You must implement the AI-generated code, ensure it works, and document its use in your project's README.

==== How to Edit Your File ====

Throughout this course we '''highly''' recommend using VS Code https://code.visualstudio.com/download, and have included tips for each module specific to VS Code.
Visit the wiki page [[VS Code]] and check out the Module 1 section

'''Important Note:''' Writing your web page in a word processor like Microsoft Word or even WordPad or TextEdit will ''not'' work. You need a plain text editor.

==== How to View Your HTML Document ====

Once you have ''birthday.html'', you can open it using your favorite web browser (like Firefox). For the purposes of this exercise, it suffices to right-click the file and tell it to "open with" Firefox. When the file opens, it should be under the file:/// protocol.

In Module 2, we will install a web server that serves up pages on the http:// and https:// protocols.

==== Validation ====

'''Your birthday card and search portal pages must pass the W3C Validators for both HTML and CSS with no errors or warnings.''' You can upload your HTML to [https://validator.w3.org/ the HTML validator] and your CSS to [https://jigsaw.w3.org/css-validator/ the CSS validator].

For more information on validation, see the HTML and CSS guide: [[HTML and CSS#Validation]]

=== Make a Portal to a DuckDuckGo Search ===

'''Write an HTML document containing a form that searches DuckDuckGo's web site.''' You should be able to type in a search term and have your form load the DuckDuckGo search page. In this HTML document you must also include this course's regrade policy to ensure that you have read it and understand it. [https://www.arl.wustl.edu/~todd/cse3300/info.html Regrade Policy]

# Visit [https://www.duckduckgo.com/ www.duckduckgo.com]. Search for something easy to spot in the URL, like "QUERY".
# Look at the URL of the search page. What is the query variable?
# Make an HTML document containing a text field and a submit button. Typing a search query into the text field and pressing the submit button should load the DuckDuckGo search page.

- Additionally, we want you to copy/paste this course's regrade policy somewhere into this html document to ensure your familiarity.

=== Git Tutorial ===

Complete all of the levels of the Main and Remote sections of [https://learngitbranching.js.org/ this Git tutorial]. After you finish the tutorial, take two screenshots showing the completion of all of the levels of the Main and Remote sections. Place these two screenshots in your repo.

== Grading ==

We will be grading the following aspects of your work. There are 80 points total.

'''Assignments (including code) must be committed to GitHub by the end of class on the due date. Commit early and often. Failing to commit by the end of class on the due date will result in a 0.

# '''Birthday Card (35 Points):'''
#* Correct usage of HTML and CSS in your birthday card (10 points).
#*: ''Make sure that you use HTML for "content" and CSS for "appearance." Don't write inline styles: use a separate stylesheet and link your HTML file to it.''
#* Experimenting with at least 5 different CSS properties in your birthday card (10 points).
#* Implementation of an AI-generated CSS animation (5 points).
#* Birthday card and search portal pages pass the W3C validation for HTML 5 and CSS. (10 points).
# '''Search Portal (10 Points):'''
#* DuckDuckGo search portal is functional (9 points).
#* Your search portal page includes the text of this course's regrade policy (1 point).
# '''Account Creation and Version Control (10 Points):'''
#* GitHub account created (2 Points)
#* Module 1 repo created using the link provided on Piazza (2 Points)
#* Account created on Amazon Web Services and an image file containing a screenshot of your account page pushed to GitHub. (4 Points)
#* Files pushed to repo on GitHub using Git (2 Points)
# '''Git Tutorial (20 Points):'''
#* Two screenshots showing the completion of all of the levels of the Main and Remote sections placed in your individual assignment repository.
# '''AI Reflection (5 Points):'''
#* Document use of AI for this assignment in the AI Reflections as described in [[AI Best Practices]] (5 Points)

[[Category:Module 1]]
[[Category:Modules]]

Tools for Performance Evaluation in Linux

2026-04-22T17:43:17Z

Todd: /* Additional Performance Evaluation Resources */

Learning how to evaluate the performance of your system is critical to scaling up your web services to a large number of users. This article will discuss a few tools that will help you with evaluating the performance of your Linux server and web applications.

== Linux Command Line Tools ==
The Linux command line offers an excellent set of tools to help you monitor the performance of your server. When evaluating the performance of your web application you need to understand the impact your application has on the server you've deployed it on. It is important to understand where a potential bottleneck exists for your application.

There are many different factors that influence an applications performance. A good place to start is to investigate the CPU utilization and IO (disk and network) of your server. Below are a few examples of tools to start to dissect performance issues in Linux.

=== top ===
The Linux command ''top'' provides real-time view of the running system. The command is helpful for displaying high utilizing resources.
To run the command simply type the name:

<source lang="bash">
$ top
</source>

The output of the screen will look something like this:
<pre>

top - 18:38:09 up 2:13, 3 users, load average: 0.57, 0.13, 0.04
Tasks: 83 total, 2 running, 81 sleeping, 0 stopped, 0 zombie
Cpu(s): 49.7%us, 39.3%sy, 0.0%ni, 0.0%id, 0.0%wa, 0.0%hi, 11.0%si, 0.0%st
Mem: 1019452k total, 186040k used, 833412k free, 12000k buffers
Swap: 0k total, 0k used, 0k free, 99032k cached

PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
3854 ec2-user 20 0 88776 8012 4956 R 21.0 0.8 0:03.69 ab
3871 apache 20 0 334m 10m 6252 S 14.3 1.1 0:00.55 httpd
3868 apache 20 0 334m 10m 6252 S 14.0 1.1 0:00.55 httpd
3869 apache 20 0 334m 10m 6252 S 14.0 1.1 0:00.55 httpd
3870 apache 20 0 334m 10m 6252 S 14.0 1.1 0:00.55 httpd
3873 apache 20 0 334m 10m 6252 S 5.7 1.1 0:00.17 httpd
3874 apache 20 0 334m 10m 6252 S 0.7 1.1 0:00.02 httpd
3875 apache 20 0 334m 10m 6252 S 0.7 1.1 0:00.02 httpd
1 root 20 0 19612 2416 2092 S 0.0 0.2 0:00.78 init
2 root 20 0 0 0 0 S 0.0 0.0 0:00.00 kthreadd
3 root 20 0 0 0 0 S 0.0 0.0 0:00.03 ksoftirqd/0
5 root 0 -20 0 0 0 S 0.0 0.0 0:00.00 kworker/0:0H
6 root 20 0 0 0 0 S 0.0 0.0 0:00.00 kworker/u30:0
7 root 20 0 0 0 0 S 0.0 0.0 0:00.07 rcu_sched
8 root 20 0 0 0 0 S 0.0 0.0 0:00.00 rcu_bh
9 root RT 0 0 0 0 S 0.0 0.0 0:00.00 migration/0
10 root 0 -20 0 0 0 S 0.0 0.0 0:00.00 khelper

</pre>

Explanation of Columns:
* PID – process ID
* USER – username for the owner of each process
* PR – process priority (RT means a Real Time priority class – used for system processes)
* NI – priority set by nice utility
* VIRT – the amount of virtual memory used by a process: code, data and shared libraries plus pages that have been swapped out
* RES – the resident part of a process – how much of it resides in the physical memory (non-swapped memory)
* SHR – shows you the size of potentially shared memory segments for a process
* S – the current state of each process
* %CPU – percentage of the time shares CPU spends running a particular process
* %MEM – percentage of the physical memory of your system which is used by each process
* %TIME+ – total time CPUs spent running each process
* COMMAND – a command used to initiate each process.

This ''top'' interactive mode allows you to control the output of top and even send signals to kill a process.

From this example, we can see that the process 'ab' (which is the Apache benchmark tool) is utilizing 21% of the CPU and 0.8% of the memory.
=== vmstat ===

''vmstat'' (virtual memory statistics) is a monitoring utility, which also provides information about block IO and CPU activity in addition to memory.

vmstat provides a number of values and is typically called with one or two parameters. For example:

<source lang="bash">
$ vmstat 1 5
</source>

The first argument specifies a sampling period of 1 second, the second argument instructs vmstat to stop after 5 measurements.

The first line of the report below will contain the average values since the last reboot. The additional lines provide information based on the sampling period.

<pre>
[ec2-user@ip-172-30-0-240 ~]$ vmstat 1 5
procs -----------memory---------- ---swap-- -----io---- --system-- -----cpu-----
r b swpd free buff cache si so bi bo in cs us sy id wa st
1 0 0 1869728 11612 112776 0 0 16 2 8 19 0 0 99 0 0
0 0 0 1869756 11612 112776 0 0 0 0 13 22 1 0 99 0 0
0 0 0 1869752 11612 112776 0 0 0 0 9 11 0 0 100 0 0
0 0 0 1869748 11612 112776 0 0 0 0 12 18 0 0 100 0 0
1 0 0 1869748 11612 112776 0 0 0 0 9 8 0 0 100 0 0
[ec2-user@ip-172-30-0-240 ~]$

</pre>

Explanation of Individual Values:
(Source <code>man vmstat</code>)
* Procs
** r: The number of processes waiting for run time.
** b: The number of processes in uninterruptible sleep.
* Memory
** swpd: the amount of virtual memory used.
** free: the amount of idle memory.
** buff: the amount of memory used as buffers.
** cache: the amount of memory used as cache.
** inact: the amount of inactive memory. (-a option)
** active: the amount of active memory. (-a option)
* Swap
** si: Amount of memory swapped in from disk (/s).
** so: Amount of memory swapped to disk (/s).
* IO
** bi: Blocks received from a block device (blocks/s).
** bo: Blocks sent to a block device (blocks/s).
* System
** in: The number of interrupts per second, including the clock.
** cs: The number of context switches per second.
* CPU
** These are percentages of total CPU time.
** us: Time spent running non-kernel code. (user time, including nice time)
** sy: Time spent running kernel code. (system time)
** id: Time spent idle. Prior to Linux 2.5.41, this includes IO-wait time.
** wa: Time spent waiting for IO. Prior to Linux 2.5.41, included in idle.
** st: Time stolen from a virtual machine.

A detailed discussion of using vmstat to diagnose Linux performance can be found here [https://www.thomas-krenn.com/en/wiki/Linux_Performance_Measurements_using_vmstat Linux].

=== Additional System Tools ===
A comprehensive list of tools can be found here [http://www.brendangregg.com/linuxperf.html]. Depending on what aspect of the Linux OS you want to explore, an appropriate tool exists.

== Application Benchmarks ==

Below is a list of common application benchmark tools.

=== Apache Benchmark Tool ===

The Apache Benchmark ab [https://httpd.apache.org/docs/2.2/programs/ab.html] provides a convenient way to stress test your web server. The tool is included with the default installation of Apache.

An example of using ab to send 1000 requests, 10 at a time to the URL http://example.com/ is shown below:
<source lang="bash">
$ ab -c 10 –n 1000 http://example.com/
</source>

The output of the tool will look similar to this:

<pre>

Document Path: /
Document Length: 25951 bytes

Concurrency Level: 10
Time taken for tests: 11.072 seconds
Complete requests: 1000
Failed requests: 0
Write errors: 0
Total transferred: 26253056 bytes
HTML transferred: 25995542 bytes
Requests per second: 90.32 [#/sec] (mean)
Time per request: 110.722 [ms] (mean)
Time per request: 11.072 [ms] (mean, across all concurrent requests)
Transfer rate: 2315.51 [Kbytes/sec] received

Connection Times (ms)
min mean[+/-sd] median max
Connect: 32 33 0.4 33 39
Processing: 67 77 22.5 68 141
Waiting: 34 35 0.9 35 44
Total: 100 110 22.4 101 174

</pre>

From the tests, we see that Apache is able to serve 90 requests per second to the machine running the ab tool. We also have statistics on the min, mean, median, and max time to send a request.

In order to effectively measure the performance of your server we should execute the ab tool from a separate machine. The ab tool can utilize a decent amount of CPU, which may interfere with the performance of your web server.

==== Using ab in AWS ====
When using ab in AWS with multiple instances, we should take advantage of Amazon's Virtual Private Cloud (VPC) [https://aws.amazon.com/vpc/getting-started/ VPC]. You actually have a VPC setup by default and to communicate with other instances, you simply use the private IP address assigned to it. Each instance by default will have a public IP address (which you ssh into) and the private IP address that is only accessible from inside the VPC. When load testing your server on AWS you should always communicate with the private IP address of your server, to avoid contention from other networks.

=== Additional Application Testing Tools ===
*Web Server Tests
**Siege [https://www.joedog.org/siege-home/]
**JMeter [http://jmeter.apache.org/]
**weighttp [http://redmine.lighttpd.net/projects/weighttp/wiki]
**httperf [http://sourceforge.net/projects/httperf/]
** Bees with Machine Guns [http://blog.bluemalkin.net/load-testing-on-ec2-using-bees-with-machine-guns/]

*Database
**MySQL Benchmark Tools [https://dev.mysql.com/downloads/benchmarks.html]
**MongoDB Benchmark [https://github.com/mongodb/mongo-perf] [https://docs.mongodb.org/manual/reference/program/mongoperf/]

*JavaScript
**Visualizing Client-Side JavaScript Performance [https://developers.google.com/web/tools/chrome-devtools/profile/rendering-tools/js-execution] [https://developer.mozilla.org/en-US/docs/Tools/Performance/Call_Tree] [http://www.smashingmagazine.com/2012/06/javascript-profiling-chrome-developer-tools/]
** Node.js Profiling [https://nodejs.org/en/docs/guides/simple-profiling/]

== Additional Performance Evaluation Resources ==

[http://alvinalexander.com/linux/unix-linux-top-command-cpu-memory Linux Top Command]

[https://www.thomas-krenn.com/en/wiki/Linux_Performance_Measurements_using_vmstat Linux Performance Measurements using vmstat]

[https://www.datadoghq.com/blog/understanding-aws-stolen-cpu-and-how-it-affects-your-apps/ CPU Steal Time]

[https://aws.amazon.com/blogs/aws/choosing-the-right-ec2-instance-type-for-your-application/ Choosing the Right EC2 Instance Type]

[https://developers.google.com/speed/pagespeed/insights/ Google PageSpeed Insights]

Tools for Performance Evaluation in Linux

2026-04-22T17:29:55Z

Todd: /* Additional Performance Evaluation Resources */

Learning how to evaluate the performance of your system is critical to scaling up your web services to a large number of users. This article will discuss a few tools that will help you with evaluating the performance of your Linux server and web applications.

== Linux Command Line Tools ==
The Linux command line offers an excellent set of tools to help you monitor the performance of your server. When evaluating the performance of your web application you need to understand the impact your application has on the server you've deployed it on. It is important to understand where a potential bottleneck exists for your application.

There are many different factors that influence an applications performance. A good place to start is to investigate the CPU utilization and IO (disk and network) of your server. Below are a few examples of tools to start to dissect performance issues in Linux.

=== top ===
The Linux command ''top'' provides real-time view of the running system. The command is helpful for displaying high utilizing resources.
To run the command simply type the name:

<source lang="bash">
$ top
</source>

The output of the screen will look something like this:
<pre>

top - 18:38:09 up 2:13, 3 users, load average: 0.57, 0.13, 0.04
Tasks: 83 total, 2 running, 81 sleeping, 0 stopped, 0 zombie
Cpu(s): 49.7%us, 39.3%sy, 0.0%ni, 0.0%id, 0.0%wa, 0.0%hi, 11.0%si, 0.0%st
Mem: 1019452k total, 186040k used, 833412k free, 12000k buffers
Swap: 0k total, 0k used, 0k free, 99032k cached

PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
3854 ec2-user 20 0 88776 8012 4956 R 21.0 0.8 0:03.69 ab
3871 apache 20 0 334m 10m 6252 S 14.3 1.1 0:00.55 httpd
3868 apache 20 0 334m 10m 6252 S 14.0 1.1 0:00.55 httpd
3869 apache 20 0 334m 10m 6252 S 14.0 1.1 0:00.55 httpd
3870 apache 20 0 334m 10m 6252 S 14.0 1.1 0:00.55 httpd
3873 apache 20 0 334m 10m 6252 S 5.7 1.1 0:00.17 httpd
3874 apache 20 0 334m 10m 6252 S 0.7 1.1 0:00.02 httpd
3875 apache 20 0 334m 10m 6252 S 0.7 1.1 0:00.02 httpd
1 root 20 0 19612 2416 2092 S 0.0 0.2 0:00.78 init
2 root 20 0 0 0 0 S 0.0 0.0 0:00.00 kthreadd
3 root 20 0 0 0 0 S 0.0 0.0 0:00.03 ksoftirqd/0
5 root 0 -20 0 0 0 S 0.0 0.0 0:00.00 kworker/0:0H
6 root 20 0 0 0 0 S 0.0 0.0 0:00.00 kworker/u30:0
7 root 20 0 0 0 0 S 0.0 0.0 0:00.07 rcu_sched
8 root 20 0 0 0 0 S 0.0 0.0 0:00.00 rcu_bh
9 root RT 0 0 0 0 S 0.0 0.0 0:00.00 migration/0
10 root 0 -20 0 0 0 S 0.0 0.0 0:00.00 khelper

</pre>

Explanation of Columns:
* PID – process ID
* USER – username for the owner of each process
* PR – process priority (RT means a Real Time priority class – used for system processes)
* NI – priority set by nice utility
* VIRT – the amount of virtual memory used by a process: code, data and shared libraries plus pages that have been swapped out
* RES – the resident part of a process – how much of it resides in the physical memory (non-swapped memory)
* SHR – shows you the size of potentially shared memory segments for a process
* S – the current state of each process
* %CPU – percentage of the time shares CPU spends running a particular process
* %MEM – percentage of the physical memory of your system which is used by each process
* %TIME+ – total time CPUs spent running each process
* COMMAND – a command used to initiate each process.

This ''top'' interactive mode allows you to control the output of top and even send signals to kill a process.

From this example, we can see that the process 'ab' (which is the Apache benchmark tool) is utilizing 21% of the CPU and 0.8% of the memory.
=== vmstat ===

''vmstat'' (virtual memory statistics) is a monitoring utility, which also provides information about block IO and CPU activity in addition to memory.

vmstat provides a number of values and is typically called with one or two parameters. For example:

<source lang="bash">
$ vmstat 1 5
</source>

The first argument specifies a sampling period of 1 second, the second argument instructs vmstat to stop after 5 measurements.

The first line of the report below will contain the average values since the last reboot. The additional lines provide information based on the sampling period.

<pre>
[ec2-user@ip-172-30-0-240 ~]$ vmstat 1 5
procs -----------memory---------- ---swap-- -----io---- --system-- -----cpu-----
r b swpd free buff cache si so bi bo in cs us sy id wa st
1 0 0 1869728 11612 112776 0 0 16 2 8 19 0 0 99 0 0
0 0 0 1869756 11612 112776 0 0 0 0 13 22 1 0 99 0 0
0 0 0 1869752 11612 112776 0 0 0 0 9 11 0 0 100 0 0
0 0 0 1869748 11612 112776 0 0 0 0 12 18 0 0 100 0 0
1 0 0 1869748 11612 112776 0 0 0 0 9 8 0 0 100 0 0
[ec2-user@ip-172-30-0-240 ~]$

</pre>

Explanation of Individual Values:
(Source <code>man vmstat</code>)
* Procs
** r: The number of processes waiting for run time.
** b: The number of processes in uninterruptible sleep.
* Memory
** swpd: the amount of virtual memory used.
** free: the amount of idle memory.
** buff: the amount of memory used as buffers.
** cache: the amount of memory used as cache.
** inact: the amount of inactive memory. (-a option)
** active: the amount of active memory. (-a option)
* Swap
** si: Amount of memory swapped in from disk (/s).
** so: Amount of memory swapped to disk (/s).
* IO
** bi: Blocks received from a block device (blocks/s).
** bo: Blocks sent to a block device (blocks/s).
* System
** in: The number of interrupts per second, including the clock.
** cs: The number of context switches per second.
* CPU
** These are percentages of total CPU time.
** us: Time spent running non-kernel code. (user time, including nice time)
** sy: Time spent running kernel code. (system time)
** id: Time spent idle. Prior to Linux 2.5.41, this includes IO-wait time.
** wa: Time spent waiting for IO. Prior to Linux 2.5.41, included in idle.
** st: Time stolen from a virtual machine.

A detailed discussion of using vmstat to diagnose Linux performance can be found here [https://www.thomas-krenn.com/en/wiki/Linux_Performance_Measurements_using_vmstat Linux].

=== Additional System Tools ===
A comprehensive list of tools can be found here [http://www.brendangregg.com/linuxperf.html]. Depending on what aspect of the Linux OS you want to explore, an appropriate tool exists.

== Application Benchmarks ==

Below is a list of common application benchmark tools.

=== Apache Benchmark Tool ===

The Apache Benchmark ab [https://httpd.apache.org/docs/2.2/programs/ab.html] provides a convenient way to stress test your web server. The tool is included with the default installation of Apache.

An example of using ab to send 1000 requests, 10 at a time to the URL http://example.com/ is shown below:
<source lang="bash">
$ ab -c 10 –n 1000 http://example.com/
</source>

The output of the tool will look similar to this:

<pre>

Document Path: /
Document Length: 25951 bytes

Concurrency Level: 10
Time taken for tests: 11.072 seconds
Complete requests: 1000
Failed requests: 0
Write errors: 0
Total transferred: 26253056 bytes
HTML transferred: 25995542 bytes
Requests per second: 90.32 [#/sec] (mean)
Time per request: 110.722 [ms] (mean)
Time per request: 11.072 [ms] (mean, across all concurrent requests)
Transfer rate: 2315.51 [Kbytes/sec] received

Connection Times (ms)
min mean[+/-sd] median max
Connect: 32 33 0.4 33 39
Processing: 67 77 22.5 68 141
Waiting: 34 35 0.9 35 44
Total: 100 110 22.4 101 174

</pre>

From the tests, we see that Apache is able to serve 90 requests per second to the machine running the ab tool. We also have statistics on the min, mean, median, and max time to send a request.

In order to effectively measure the performance of your server we should execute the ab tool from a separate machine. The ab tool can utilize a decent amount of CPU, which may interfere with the performance of your web server.

==== Using ab in AWS ====
When using ab in AWS with multiple instances, we should take advantage of Amazon's Virtual Private Cloud (VPC) [https://aws.amazon.com/vpc/getting-started/ VPC]. You actually have a VPC setup by default and to communicate with other instances, you simply use the private IP address assigned to it. Each instance by default will have a public IP address (which you ssh into) and the private IP address that is only accessible from inside the VPC. When load testing your server on AWS you should always communicate with the private IP address of your server, to avoid contention from other networks.

=== Additional Application Testing Tools ===
*Web Server Tests
**Siege [https://www.joedog.org/siege-home/]
**JMeter [http://jmeter.apache.org/]
**weighttp [http://redmine.lighttpd.net/projects/weighttp/wiki]
**httperf [http://sourceforge.net/projects/httperf/]
** Bees with Machine Guns [http://blog.bluemalkin.net/load-testing-on-ec2-using-bees-with-machine-guns/]

*Database
**MySQL Benchmark Tools [https://dev.mysql.com/downloads/benchmarks.html]
**MongoDB Benchmark [https://github.com/mongodb/mongo-perf] [https://docs.mongodb.org/manual/reference/program/mongoperf/]

*JavaScript
**Visualizing Client-Side JavaScript Performance [https://developers.google.com/web/tools/chrome-devtools/profile/rendering-tools/js-execution] [https://developer.mozilla.org/en-US/docs/Tools/Performance/Call_Tree] [http://www.smashingmagazine.com/2012/06/javascript-profiling-chrome-developer-tools/]
** Node.js Profiling [https://nodejs.org/en/docs/guides/simple-profiling/]

== Additional Performance Evaluation Resources ==

[http://alvinalexander.com/linux/unix-linux-top-command-cpu-memory Linux Top Command]

[https://www.thomas-krenn.com/en/wiki/Linux_Performance_Measurements_using_vmstat Linux Performance Measurements using vmstat]

[https://web.archive.org/web/20180325093837/http://blog.scoutapp.com/articles/2013/07/25/understanding-cpu-steal-time-when-should-you-be-worried CPU Steal Time]

[https://aws.amazon.com/blogs/aws/choosing-the-right-ec2-instance-type-for-your-application/ Choosing the Right EC2 Instance Type]

[https://developers.google.com/speed/pagespeed/insights/ Google PageSpeed Insights]

Tools for Performance Evaluation in Linux

2026-04-22T17:19:51Z

Todd: /* Additional Performance Evaluation Resources */

Learning how to evaluate the performance of your system is critical to scaling up your web services to a large number of users. This article will discuss a few tools that will help you with evaluating the performance of your Linux server and web applications.

== Linux Command Line Tools ==
The Linux command line offers an excellent set of tools to help you monitor the performance of your server. When evaluating the performance of your web application you need to understand the impact your application has on the server you've deployed it on. It is important to understand where a potential bottleneck exists for your application.

There are many different factors that influence an applications performance. A good place to start is to investigate the CPU utilization and IO (disk and network) of your server. Below are a few examples of tools to start to dissect performance issues in Linux.

=== top ===
The Linux command ''top'' provides real-time view of the running system. The command is helpful for displaying high utilizing resources.
To run the command simply type the name:

<source lang="bash">
$ top
</source>

The output of the screen will look something like this:
<pre>

top - 18:38:09 up 2:13, 3 users, load average: 0.57, 0.13, 0.04
Tasks: 83 total, 2 running, 81 sleeping, 0 stopped, 0 zombie
Cpu(s): 49.7%us, 39.3%sy, 0.0%ni, 0.0%id, 0.0%wa, 0.0%hi, 11.0%si, 0.0%st
Mem: 1019452k total, 186040k used, 833412k free, 12000k buffers
Swap: 0k total, 0k used, 0k free, 99032k cached

PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
3854 ec2-user 20 0 88776 8012 4956 R 21.0 0.8 0:03.69 ab
3871 apache 20 0 334m 10m 6252 S 14.3 1.1 0:00.55 httpd
3868 apache 20 0 334m 10m 6252 S 14.0 1.1 0:00.55 httpd
3869 apache 20 0 334m 10m 6252 S 14.0 1.1 0:00.55 httpd
3870 apache 20 0 334m 10m 6252 S 14.0 1.1 0:00.55 httpd
3873 apache 20 0 334m 10m 6252 S 5.7 1.1 0:00.17 httpd
3874 apache 20 0 334m 10m 6252 S 0.7 1.1 0:00.02 httpd
3875 apache 20 0 334m 10m 6252 S 0.7 1.1 0:00.02 httpd
1 root 20 0 19612 2416 2092 S 0.0 0.2 0:00.78 init
2 root 20 0 0 0 0 S 0.0 0.0 0:00.00 kthreadd
3 root 20 0 0 0 0 S 0.0 0.0 0:00.03 ksoftirqd/0
5 root 0 -20 0 0 0 S 0.0 0.0 0:00.00 kworker/0:0H
6 root 20 0 0 0 0 S 0.0 0.0 0:00.00 kworker/u30:0
7 root 20 0 0 0 0 S 0.0 0.0 0:00.07 rcu_sched
8 root 20 0 0 0 0 S 0.0 0.0 0:00.00 rcu_bh
9 root RT 0 0 0 0 S 0.0 0.0 0:00.00 migration/0
10 root 0 -20 0 0 0 S 0.0 0.0 0:00.00 khelper

</pre>

Explanation of Columns:
* PID – process ID
* USER – username for the owner of each process
* PR – process priority (RT means a Real Time priority class – used for system processes)
* NI – priority set by nice utility
* VIRT – the amount of virtual memory used by a process: code, data and shared libraries plus pages that have been swapped out
* RES – the resident part of a process – how much of it resides in the physical memory (non-swapped memory)
* SHR – shows you the size of potentially shared memory segments for a process
* S – the current state of each process
* %CPU – percentage of the time shares CPU spends running a particular process
* %MEM – percentage of the physical memory of your system which is used by each process
* %TIME+ – total time CPUs spent running each process
* COMMAND – a command used to initiate each process.

This ''top'' interactive mode allows you to control the output of top and even send signals to kill a process.

From this example, we can see that the process 'ab' (which is the Apache benchmark tool) is utilizing 21% of the CPU and 0.8% of the memory.
=== vmstat ===

''vmstat'' (virtual memory statistics) is a monitoring utility, which also provides information about block IO and CPU activity in addition to memory.

vmstat provides a number of values and is typically called with one or two parameters. For example:

<source lang="bash">
$ vmstat 1 5
</source>

The first argument specifies a sampling period of 1 second, the second argument instructs vmstat to stop after 5 measurements.

The first line of the report below will contain the average values since the last reboot. The additional lines provide information based on the sampling period.

<pre>
[ec2-user@ip-172-30-0-240 ~]$ vmstat 1 5
procs -----------memory---------- ---swap-- -----io---- --system-- -----cpu-----
r b swpd free buff cache si so bi bo in cs us sy id wa st
1 0 0 1869728 11612 112776 0 0 16 2 8 19 0 0 99 0 0
0 0 0 1869756 11612 112776 0 0 0 0 13 22 1 0 99 0 0
0 0 0 1869752 11612 112776 0 0 0 0 9 11 0 0 100 0 0
0 0 0 1869748 11612 112776 0 0 0 0 12 18 0 0 100 0 0
1 0 0 1869748 11612 112776 0 0 0 0 9 8 0 0 100 0 0
[ec2-user@ip-172-30-0-240 ~]$

</pre>

Explanation of Individual Values:
(Source <code>man vmstat</code>)
* Procs
** r: The number of processes waiting for run time.
** b: The number of processes in uninterruptible sleep.
* Memory
** swpd: the amount of virtual memory used.
** free: the amount of idle memory.
** buff: the amount of memory used as buffers.
** cache: the amount of memory used as cache.
** inact: the amount of inactive memory. (-a option)
** active: the amount of active memory. (-a option)
* Swap
** si: Amount of memory swapped in from disk (/s).
** so: Amount of memory swapped to disk (/s).
* IO
** bi: Blocks received from a block device (blocks/s).
** bo: Blocks sent to a block device (blocks/s).
* System
** in: The number of interrupts per second, including the clock.
** cs: The number of context switches per second.
* CPU
** These are percentages of total CPU time.
** us: Time spent running non-kernel code. (user time, including nice time)
** sy: Time spent running kernel code. (system time)
** id: Time spent idle. Prior to Linux 2.5.41, this includes IO-wait time.
** wa: Time spent waiting for IO. Prior to Linux 2.5.41, included in idle.
** st: Time stolen from a virtual machine.

A detailed discussion of using vmstat to diagnose Linux performance can be found here [https://www.thomas-krenn.com/en/wiki/Linux_Performance_Measurements_using_vmstat Linux].

=== Additional System Tools ===
A comprehensive list of tools can be found here [http://www.brendangregg.com/linuxperf.html]. Depending on what aspect of the Linux OS you want to explore, an appropriate tool exists.

== Application Benchmarks ==

Below is a list of common application benchmark tools.

=== Apache Benchmark Tool ===

The Apache Benchmark ab [https://httpd.apache.org/docs/2.2/programs/ab.html] provides a convenient way to stress test your web server. The tool is included with the default installation of Apache.

An example of using ab to send 1000 requests, 10 at a time to the URL http://example.com/ is shown below:
<source lang="bash">
$ ab -c 10 –n 1000 http://example.com/
</source>

The output of the tool will look similar to this:

<pre>

Document Path: /
Document Length: 25951 bytes

Concurrency Level: 10
Time taken for tests: 11.072 seconds
Complete requests: 1000
Failed requests: 0
Write errors: 0
Total transferred: 26253056 bytes
HTML transferred: 25995542 bytes
Requests per second: 90.32 [#/sec] (mean)
Time per request: 110.722 [ms] (mean)
Time per request: 11.072 [ms] (mean, across all concurrent requests)
Transfer rate: 2315.51 [Kbytes/sec] received

Connection Times (ms)
min mean[+/-sd] median max
Connect: 32 33 0.4 33 39
Processing: 67 77 22.5 68 141
Waiting: 34 35 0.9 35 44
Total: 100 110 22.4 101 174

</pre>

From the tests, we see that Apache is able to serve 90 requests per second to the machine running the ab tool. We also have statistics on the min, mean, median, and max time to send a request.

In order to effectively measure the performance of your server we should execute the ab tool from a separate machine. The ab tool can utilize a decent amount of CPU, which may interfere with the performance of your web server.

==== Using ab in AWS ====
When using ab in AWS with multiple instances, we should take advantage of Amazon's Virtual Private Cloud (VPC) [https://aws.amazon.com/vpc/getting-started/ VPC]. You actually have a VPC setup by default and to communicate with other instances, you simply use the private IP address assigned to it. Each instance by default will have a public IP address (which you ssh into) and the private IP address that is only accessible from inside the VPC. When load testing your server on AWS you should always communicate with the private IP address of your server, to avoid contention from other networks.

=== Additional Application Testing Tools ===
*Web Server Tests
**Siege [https://www.joedog.org/siege-home/]
**JMeter [http://jmeter.apache.org/]
**weighttp [http://redmine.lighttpd.net/projects/weighttp/wiki]
**httperf [http://sourceforge.net/projects/httperf/]
** Bees with Machine Guns [http://blog.bluemalkin.net/load-testing-on-ec2-using-bees-with-machine-guns/]

*Database
**MySQL Benchmark Tools [https://dev.mysql.com/downloads/benchmarks.html]
**MongoDB Benchmark [https://github.com/mongodb/mongo-perf] [https://docs.mongodb.org/manual/reference/program/mongoperf/]

*JavaScript
**Visualizing Client-Side JavaScript Performance [https://developers.google.com/web/tools/chrome-devtools/profile/rendering-tools/js-execution] [https://developer.mozilla.org/en-US/docs/Tools/Performance/Call_Tree] [http://www.smashingmagazine.com/2012/06/javascript-profiling-chrome-developer-tools/]
** Node.js Profiling [https://nodejs.org/en/docs/guides/simple-profiling/]

== Additional Performance Evaluation Resources ==

[http://alvinalexander.com/linux/unix-linux-top-command-cpu-memory Linux Top Command]

[https://www.thomas-krenn.com/en/wiki/Linux_Performance_Measurements_using_vmstat Linux Performance Measurements using vmstat]

[https://web.archive.org/web/20180325093837/http://blog.scoutapp.com/articles/2013/07/25/understanding-cpu-steal-time-when-should-you-be-worried CPU Steal Time]

[https://aws.amazon.com/blogs/aws/choosing-the-right-ec2-instance-type-for-your-application/ Choosing the Right EC2 Instance Type]

[https://developers.google.com/speed/pagespeed/insights/ Google PageSpeed Insights]

Module 7

2026-04-06T15:22:16Z

Todd:

__NOTOC__
The goal of the creative project is for you to learn a new framework or language that you may be interested in. This is a good opportunity to get a head start on learning the frameworks/languages your employer/potential employer uses.

You’re free to choose which frameworks/languages you’ll use, and you’ll earn more points for learning more or harder frameworks, but '''you’re required to learn at least one new framework/technology.'''

'''As an example''':

You cannot use the combination of Plain HTML/JavaScript (frontend), PHP (backend), and MySQL (Database) because we've covered those extensively in class.

You could, however, use React.JS (frontend), PHP, and MySQL, because your React front end would be new.

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignment.

* [[Choosing a Platform]]
* [[Web Frameworks]]

== Creating Your Rubric ==

Before creating a rubric, you should come up with an idea for a site you want to build. From there, check [https://classes.engineering.wustl.edu/cse330/index.php?title=Web_Frameworks here] for guidance on which frameworks/languages to learn for your project and for links on how to get started with each.

As a general structure, your project will consist of:
*Front-end
*Back-end
*Database
*Styling
*Best practices
(Though note that using all may not be necessary for your project! Reallocate as you need)

==== General Rubric Guidelines ====
Your rubric will add up to '''100 points''' (including the 5 points earned for submitting your rubric on time). For each component of your stack, you can allocate the following numbers of points:
*5 points for creating a rubric and uploading it to Github on time (yes, we will be checking your commit timestamps!). Please make sure you check your rubric out with a TA, or else it would not be considered submitted.
*[10 - 40] points: Learning and implementing new framework(s).
*Functionality
**Think about what's happening in your front end, backend, and database that creates functionality. See example rubric.
*5 points: Best Practices
**Code well formatted
**HTML output passes the validator
*[0 - 20] points: Creative Portion
*[0 - 5] points: Styling. "Looks really cool" or "Used Bootstrap" would '''not''' earn any points. Learning and implementing SCSS/SASS, animations, or making your page responsive/mobile-friendly would.

''Note that exceptions can be made to these guidelines, but make sure to get approval from a TA.''

===== Points you can allocate for frameworks =====
Because some stacks have a higher learning curve, more points will be earned for using them. Use the following as a guide:
*React, Vue, Angular, and other frontend frameworks : 10
*Express (Node.js framework), Laravel, Bottle, Flask, other back-end micro frameworks: 10
*Full stack frameworks like Django (python): 20
*Learning a new database system:
**Mongo DB: 10
**Firebase: 5 (lower learning curve)
**Other SQL Databases (Postgres, MariaDB): 5

== Example Rubric ==
Say your project idea is to re-create Bitly (the URL shortener), where shortened URLs expire after 1 week, but users can purchase the shortened URL (using stripe) for it to work forever. You decide you want to use Vue for your frontend, Laravel for your backend, and a MySQL database.
Your rubric could look like the following:
======Rubric turned in on time (5 points)======
Remember to get it checked out by a TA!

======Languages/Frameworks used (20 points)======
*10 - Learned/Used Vue.js frontend
*10 - Learned/Used PHP Laravel backend
*0 - MySQL/MariaDB Database

======Functionality (60 points)======
*5 Users can input a url and receive a shortened url that redirects to it.
*10 Url redirect lasts 1 week before the shortened link doesn't work
*10 Users can register, login, and logout
*10 Logged in users can edit and delete their shortened URLs
*15 Logged in users can purchase a shortened URL via Stripe integration
*10 Database contains Users, Links, and Purchases with the necessary columns and column types to maintain the above functionality
======Best Practices (5 points)======
*3 Code is readable and well formatted
*2 All pages pass the html validator
======Creative Portion (10 points)======

== Grading ==

'''Assignments must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0.'''

___________

Your project will be graded '''in person''' during the last week of classes, using the rubric you create.

___________

[[Category:Module 7]]
[[Category:Modules]]

Module 6

2026-03-30T16:34:58Z

Todd: /* Reading */

__NOTOC__
In Module 6, you will learn the fundamentals of Python, a widely used scripting language, and Regular Expressions, which provide powerful tools for text processing. You will also explore the Model Context Protocol (MCP), a framework that allows software tools to communicate with large language models (LLMs).

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 6]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user-controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
** <code>get_player_stats</code>: Retrieve and show batting averages for a player.
** <code>get_team_roster</code>: List all players from a given season.
** <code>get_top_players</code>: Sort and show the top hitters.
** <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''MCP Toolkit''' → '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
** <code>get_player_stats</code>: Show batting averages for one player
** <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
** <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
** <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import logging
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Configure logging to stderr
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
stream=sys.stderr,
)
logger = logging.getLogger("CardinalsMCP-server")

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

You can find an explanation of the hello function in the [[MCP_Fundamentals#Example MCP Tool: hello|MCP Fundamentals]]

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run the hello tool in the chat of Claude Desktop:

<pre>"Use CardinalsMCP to say hello"</pre>

If everything is working correctly, you should see a "Hello CSE 3300 Student" response.

After you have implemented the MCP tools, you can run commands like this:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>

==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

Module 6

2026-03-21T15:49:03Z

Todd:

__NOTOC__
In Module 6, you will learn the fundamentals of Python, a widely used scripting language, and Regular Expressions, which provide powerful tools for text processing. You will also explore the Model Context Protocol (MCP), a framework that allows software tools to communicate with large language models (LLMs).

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 4]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user-controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
** <code>get_player_stats</code>: Retrieve and show batting averages for a player.
** <code>get_team_roster</code>: List all players from a given season.
** <code>get_top_players</code>: Sort and show the top hitters.
** <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''MCP Toolkit''' → '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
** <code>get_player_stats</code>: Show batting averages for one player
** <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
** <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
** <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import logging
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Configure logging to stderr
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
stream=sys.stderr,
)
logger = logging.getLogger("CardinalsMCP-server")

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

You can find an explanation of the hello function in the [[MCP_Fundamentals#Example MCP Tool: hello|MCP Fundamentals]]

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run the hello tool in the chat of Claude Desktop:

<pre>"Use CardinalsMCP to say hello"</pre>

If everything is working correctly, you should see a "Hello CSE 3300 Student" response.

After you have implemented the MCP tools, you can run commands like this:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>

==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

Module 6

2026-03-19T14:44:14Z

Todd: /* Restart Claude Desktop */

__NOTOC__
<span style="font-size:1.3em; line-height:1.2em; color:red;">
'''This module is under development for Spring 2026. Do not begin this assignment until this notice is removed.''' </span>

In Module 6, you will learn the fundamentals of Python, a widely used scripting language, and Regular Expressions, which provide powerful tools for text processing. You will also explore the Model Context Protocol (MCP), a framework that allows software tools to communicate with large language models (LLMs).

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 4]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user-controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
** <code>get_player_stats</code>: Retrieve and show batting averages for a player.
** <code>get_team_roster</code>: List all players from a given season.
** <code>get_top_players</code>: Sort and show the top hitters.
** <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''MCP Toolkit''' → '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
** <code>get_player_stats</code>: Show batting averages for one player
** <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
** <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
** <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import logging
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Configure logging to stderr
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
stream=sys.stderr,
)
logger = logging.getLogger("CardinalsMCP-server")

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

You can find an explanation of the hello function in the [[MCP_Fundamentals#Example MCP Tool: hello|MCP Fundamentals]]

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run the hello tool in the chat of Claude Desktop:

<pre>"Use CardinalsMCP to say hello"</pre>

If everything is working correctly, you should see a "Hello CSE 3300 Student" response.

After you have implemented the MCP tools, you can run commands like this:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>

==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

Module 6

2026-03-19T14:41:34Z

Todd: /* Restart Claude Desktop */

__NOTOC__
<span style="font-size:1.3em; line-height:1.2em; color:red;">
'''This module is under development for Spring 2026. Do not begin this assignment until this notice is removed.''' </span>

In Module 6, you will learn the fundamentals of Python, a widely used scripting language, and Regular Expressions, which provide powerful tools for text processing. You will also explore the Model Context Protocol (MCP), a framework that allows software tools to communicate with large language models (LLMs).

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 4]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user-controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
** <code>get_player_stats</code>: Retrieve and show batting averages for a player.
** <code>get_team_roster</code>: List all players from a given season.
** <code>get_top_players</code>: Sort and show the top hitters.
** <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''MCP Toolkit''' → '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
** <code>get_player_stats</code>: Show batting averages for one player
** <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
** <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
** <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import logging
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Configure logging to stderr
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
stream=sys.stderr,
)
logger = logging.getLogger("CardinalsMCP-server")

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

You can find an explanation of the hello function in the [[MCP_Fundamentals#Example MCP Tool: hello|MCP Fundamentals]]

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run the hello tool:

<pre>"Use CardinalsMCP to say hello"</pre>

After you have implemented the MCP tools, you can run commands like this:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>

==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

Module 6

2026-03-19T14:31:37Z

Todd: /* Starter Code */

__NOTOC__
<span style="font-size:1.3em; line-height:1.2em; color:red;">
'''This module is under development for Spring 2026. Do not begin this assignment until this notice is removed.''' </span>

In Module 6, you will learn the fundamentals of Python, a widely used scripting language, and Regular Expressions, which provide powerful tools for text processing. You will also explore the Model Context Protocol (MCP), a framework that allows software tools to communicate with large language models (LLMs).

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 4]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user-controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
** <code>get_player_stats</code>: Retrieve and show batting averages for a player.
** <code>get_team_roster</code>: List all players from a given season.
** <code>get_top_players</code>: Sort and show the top hitters.
** <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''MCP Toolkit''' → '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
** <code>get_player_stats</code>: Show batting averages for one player
** <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
** <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
** <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import logging
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Configure logging to stderr
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
stream=sys.stderr,
)
logger = logging.getLogger("CardinalsMCP-server")

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

You can find an explanation of the hello function in the [[MCP_Fundamentals#Example MCP Tool: hello|MCP Fundamentals]]

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run commands like:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>
==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

Module 6

2026-03-19T14:19:22Z

Todd: /* Connect Claude to Docker */

__NOTOC__
<span style="font-size:1.3em; line-height:1.2em; color:red;">
'''This module is under development for Spring 2026. Do not begin this assignment until this notice is removed.''' </span>

In Module 6, you will learn the fundamentals of Python, a widely used scripting language, and Regular Expressions, which provide powerful tools for text processing. You will also explore the Model Context Protocol (MCP), a framework that allows software tools to communicate with large language models (LLMs).

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 4]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user-controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
** <code>get_player_stats</code>: Retrieve and show batting averages for a player.
** <code>get_team_roster</code>: List all players from a given season.
** <code>get_top_players</code>: Sort and show the top hitters.
** <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''MCP Toolkit''' → '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
** <code>get_player_stats</code>: Show batting averages for one player
** <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
** <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
** <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

You can find an explanation of the hello function in the [[MCP_Fundamentals#Example MCP Tool: hello|MCP Fundamentals]]

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run commands like:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>
==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

Module 6

2026-03-19T14:18:59Z

Todd: /* Connect Claude to Docker */

__NOTOC__
<span style="font-size:1.3em; line-height:1.2em; color:red;">
'''This module is under development for Spring 2026. Do not begin this assignment until this notice is removed.''' </span>

In Module 6, you will learn the fundamentals of Python, a widely used scripting language, and Regular Expressions, which provide powerful tools for text processing. You will also explore the Model Context Protocol (MCP), a framework that allows software tools to communicate with large language models (LLMs).

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 4]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user-controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
** <code>get_player_stats</code>: Retrieve and show batting averages for a player.
** <code>get_team_roster</code>: List all players from a given season.
** <code>get_top_players</code>: Sort and show the top hitters.
** <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''MCP Toolkit'''' → '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
** <code>get_player_stats</code>: Show batting averages for one player
** <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
** <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
** <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

You can find an explanation of the hello function in the [[MCP_Fundamentals#Example MCP Tool: hello|MCP Fundamentals]]

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run commands like:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>
==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

Module 6

2026-03-18T15:59:10Z

Todd: /* Starter Code */

__NOTOC__
<span style="font-size:1.3em; line-height:1.2em; color:red;">
'''This module is under development for Spring 2026. Do not begin this assignment until this notice is removed.''' </span>

In Module 6, you will learn the fundamentals of Python, a widely used scripting language, and Regular Expressions, which provide powerful tools for text processing. You will also explore the Model Context Protocol (MCP), a framework that allows software tools to communicate with large language models (LLMs).

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 4]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user-controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
** <code>get_player_stats</code>: Retrieve and show batting averages for a player.
** <code>get_team_roster</code>: List all players from a given season.
** <code>get_top_players</code>: Sort and show the top hitters.
** <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
** <code>get_player_stats</code>: Show batting averages for one player
** <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
** <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
** <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

You can find an explanation of the hello function in the [[MCP_Fundamentals#Example MCP Tool: hello|MCP Fundamentals]]

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run commands like:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>
==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

MCP Fundamentals

2026-03-18T15:55:29Z

Todd:

__NOTOC__

= Model Context Protocol (MCP) =

Large Language Models (LLMs) like Claude, ChatGPT, and other AI assistants are powerful, but they normally operate in isolation.
They cannot directly access your computer, read files, run programs, or query databases.

The '''Model Context Protocol (MCP)''' is a standard that allows language models to safely interact with external tools and data sources.

Instead of executing code directly, the language model communicates with an '''MCP server''', which exposes specific capabilities that the model can use.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol Documentation]

== Mental Model: How MCP Actually Works ==

A helpful way to think about MCP is that the language model is a '''decision maker''' and the MCP server is a '''toolbox'''.

<pre>
User asks question
↓
Claude decides which tool to use
↓
Claude calls the MCP server
↓
Your Python function runs
↓
The result is returned to Claude
↓
Claude explains the result to the user
</pre>

'''Important:''' The language model does not run your code directly.
It decides '''which tool''' should be executed.
The MCP server runs the code and returns the result.

== MCP Architecture ==

The interaction between the user, the language model, and your MCP server looks like this:

<pre>
User Prompt
↓
Language Model (Claude)
↓
MCP Client
↓
MCP Server
↓
Tools / Data Sources
</pre>

The language model analyzes the prompt and determines whether a tool should be used.

If a tool is needed:

1. The model selects a tool
2. The MCP client sends the request
3. The MCP server runs the function
4. The result is returned to the model
5. The model formats the final response

== MCP Building Blocks ==

MCP servers provide three types of capabilities.

=== Tools ===

'''Tools''' are executable functions that perform actions or retrieve data.

Examples include:

* querying a database
* reading files
* performing calculations
* calling APIs
* searching datasets

Example tool:

<pre>
get_weather(city="St. Louis")
</pre>

The MCP server runs the function and returns the result.

=== Resources ===

'''Resources''' are the data sources your MCP tools use.

Examples include:

* files
* documents
* databases
* logs
* datasets

For example, a tool might read a dataset stored in a file.

=== Prompts ===

'''Prompts''' are the instructions given by the user.

Example:

<pre>
Show the top hitters on the 1940 Cardinals.
</pre>

The model interprets the prompt and determines if a tool should be used.

The user never runs the tool directly.

== Example Workflow ==

Suppose the user asks:

<pre>
Show the top hitters on the 1940 Cardinals.
</pre>

The system behaves like this:

1. Claude reads the prompt
2. Claude decides the <code>get_top_players</code> tool is needed
3. Claude calls the MCP server
4. The server runs the Python function
5. The results are returned to Claude

== Why MCP Matters ==

Without MCP, language models can only generate text.

With MCP, models can:

* access real data
* run programs
* query databases
* analyze datasets
* automate workflows

This transforms AI systems from chatbots into '''agents'''.

== MCP in This Course ==

In this module, you will build a simple MCP server using Python.

Your server will expose tools that allow Claude Desktop to analyze historical St. Louis Cardinals batting statistics.

Claude will automatically call your tools when needed.

== Example MCP Tool: hello ==

Below is a simple example of an MCP tool:

<source lang="python">
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"
</source>

This function defines a tool that Claude Desktop can call through the MCP server.

----

== What This Function Does ==

This tool returns a simple greeting message. It is primarily used to verify that:

* your MCP server is running
* Docker is working correctly
* Claude Desktop is connected to your server

If this tool works, your MCP setup is likely correct.

----

== Line-by-Line Explanation ==

=== @mcp.tool() ===

This is a '''decorator''' that registers the function as an MCP tool.

Without this line, Claude will not be able to see or use the function.

----

=== async def hello(...) ===

This defines the function.

* <code>hello</code> is the '''tool name'''
* Claude will refer to this function by this name when calling it

The keyword <code>async</code> indicates that the function runs within the MCP system. You do not need to fully understand asynchronous programming for this assignment.

----

=== name: str = "world" ===

This defines an input parameter:

* <code>name</code> is the parameter name
* <code>str</code> indicates it should be a string
* <code>"world"</code> is the default value

If no value is provided, the function will use "world".

----

=== -> str ===

This is a return type hint.

It indicates that the function returns a string.

Note: Python does not strictly enforce this, but it is important for clarity.

----

=== Docstring ===

<source lang="python">
"""Return a simple greeting to verify the server is working."""
</source>

This is a '''docstring'''.

It serves two purposes:

* explains the function to humans
* helps Claude understand what the tool does and when to use it

----

=== return statement ===

<source lang="python">
return f"Hello CSE 3300 Student, {name}!"
</source>

This returns the output of the tool.

For example:

<pre>
hello("Todd") → Hello CSE 3300 Student, Todd!
</pre>

----

== How Claude Uses This Tool ==

When you type a prompt such as:

<pre>
Use CardinalsMCP to say hello to Todd
</pre>

Claude will:

# recognize that the <code>hello</code> tool is relevant
# call the function with <code>name="Todd"</code>
# receive the returned string
# display the result in the chat

----

== Key Takeaway ==

An MCP tool is just a Python function that:

* is decorated with <code>@mcp.tool()</code>
* has clearly defined inputs (parameters)
* returns a result (usually a string)

Claude reads the function name, parameters, and docstring to decide how to use it.

----

== Try It ==

After your MCP server is running, test this tool in Claude Desktop:

<pre>
Use CardinalsMCP to say hello
</pre>

If it works, your MCP server is correctly configured.

[[Category:Module 6]]
[[Category:Modules]]

Module 5

2026-03-16T16:57:19Z

Todd: /* Option B — Local Execution + Demo Video */

__NOTOC__

Module 5 builds upon the JavaScript skills you learned in Module 4 and introduces server-side JavaScript using Node.js, along with real-time communication using Socket.IO.

== Reading ==

The following articles on the class wiki contain information that will help you complete the assignments:

* [[Node.JS]]
* [[Socket.IO]]
* [[FAQ - Mod 5]]

== Individual Assignments ==

=== Install Node.js ===

Install Node.js using the instructions in the [[Node.JS]] guide (use the current LTS version via nvm).

=== Static File Server in Node.js ===

The individual portion is intentionally short so you have sufficient time for the group project.

Follow these steps carefully.

# Copy the static file server example from the [[Node.JS]] page into a file named <code>app.js</code>. Save it on your EC2 instance in a directory that is NOT served by Apache.
# Ensure that you understand what the static file server script is doing.
# Create a directory parallel to <code>app.js</code> named <code>static</code>.
# Confirm that your server’s <code>STATIC_DIR</code> variable matches this directory name.
# Create the following files inside the <code>static</code> directory:
#* <code>hello.txt</code> — a text file containing: <b>Hello World</b>
#* <code>brookings.jpg</code> — download from: http://classes.engineering.wustl.edu/cse330/content/brookings.jpg
#* <code>college.html</code> — an HTML page based on the [[HTML and CSS#Quick and Easy Page Layout|Quick and Easy HTML Layout]] that includes an <code><img></code> referencing <code>brookings.jpg</code>
#* <code>phpinfo.php</code> — a PHP file containing:
#: <source lang="php"><?php phpinfo(); ?></source>
# Start your Node.js server and load all four files in your browser.

Questions to consider:

* Which files work and which do not?
* Why does <code>phpinfo.php</code> behave differently when served by Node instead of Apache?

== Group Project: Multi-Room Chat Server ==

In the group portion of Module 5, you will build a multi-room chat system using Node.js and Socket.IO.

The system must include:

* A main lobby where users select a nickname
* Ability to create chat rooms
* Ability to join chat rooms
* A list of available rooms
* A list of users currently in the room
* The entire application displayed on a single webpage

The single-room example is provided here:

* [[Socket.IO]]

== AI Agent Extension ==

You will enhance your chat server with an AI assistant.

Users can message the AI by typing:

<pre>/agent What is the capital of France?</pre>

The server detects messages that begin with <code>/agent</code>, sends the prompt to an AI model, and broadcasts the response as <b>Agent</b> in the same room.

You may use:

* Ollama (recommended — runs locally and free)
* OpenAI
* Gemini
* HuggingFace
* Any approved model

If using an API, store your key in a file named <code>.env</code> at the root of your project:

<source lang="bash">
OPENAI_API_KEY=your_key_here
</source>

Load it securely in your server:

<source lang="javascript">
import 'dotenv/config';
</source>

Refer to your chosen model’s documentation for setup details.

== Grading ==

We will be grading the following aspects of your work. There are 100 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

'''Additionally, for this module, the TA should be able to simply download your repo and start up your file server, without having to copy files or create additional subdirectories. This applies to both the individual and the creative portion'''

_________

# '''Individual Portion (30 Points):'''
#* Node.JS is installed on your EC2 instance (5 points)
#*: ''Take a screenshot of your browser visiting your EC2 instance serving up the college.html web page on port 3456, make sure the URL is visible in the screenshot.''
#* The ''hello.txt'', ''brookings.jpg'', and ''college.html'' files all load successfully (4 points each)
#* Visiting a file that does not exist inside the ''static'' directory results in a 404 (4 points)
#* Discuss in the README.md why ''phpinfo.php'' behaves the way it does when loaded through Node.JS (4 points)
#* Make sure all of your individual portion files are pushed to Github (include your node.js files, hello.txt, brookings.jpg, college.html, and phpinfo.php)
#* Completion of the AI Reflections for the individual portion of the assignment following the [[AI Best Practices]] (5 points)
# '''Multi-room Chat Server (70 Points):'''
#* '''''Administration of user created chat rooms (25 Points):'''''
#** Users can create chat rooms with an arbitrary room name(5 points)
#** Users can join an arbitrary chat room (5 points)
#** The chat room displays all users currently in the room (5 points)
#** A private room can be created that is password protected (5 points)
#** Creators of chat rooms can temporarily kick others out of the room (3 points)
#** Creators of chat rooms can permanently ban users from joining that particular room (2 points)
#* '''''Messaging (5 Points):'''''
#** A user's message shows their username and is sent to everyone in the room (1 point)
#** Users can send private messages to another user in the same room (4 points)
#* '''''Best Practices (5 Points):'''''
#** Code is well formatted and easy to read, with proper commenting (2 points)
#** Code passes HTML validation (2 points)
#** node_modules folder is ignored by version control (1 points)
#* '''''Usability (5 Points):'''''
#** Communicating with others and joining rooms is easy and intuitive (4 points)
#** Site is visually appealing (1 point)
#* '''AI Agent and Reflection (20 Points)'''
#** Implement an AI assistant accessible via the command \agent ... that replies in the current room (10 points)
#** Handles basic errors gracefully and does not crash the server (5 point)
#** Completion of the AI Reflections for the group portion of the assignment following the [[AI Best Practices]] (5 points)
#* '''Creative Portion (10 Points)'''


== Submission Instructions ==

To ensure your project can be graded quickly and reliably, follow these submission requirements carefully.

All students must submit a working GitHub repository. In addition, your project must be verifiable by the TA using one of the two methods below.

=== Required for ALL Submissions ===

Your GitHub repository must include:

* All source code for both the individual and group portions
* A complete <code>package.json</code> file
* A <code>README.md</code> containing:
** How to run your server
** Which AI model you used (Ollama, OpenAI, Gemini, etc.)
** Any special setup instructions
* A <code>.gitignore</code> file that excludes:
** <code>node_modules/</code>
** <code>.env</code>

'''Do NOT commit your API keys.'''

If your project uses environment variables, include a file named:

<source lang="bash">
.env.example
</source>

Example:

<source lang="bash">
OPENAI_API_KEY=
</source>

Your server must not crash if the API key is missing. It should fail gracefully.

=== Option A - Running on EC2 ===

Deploy your chat server on your EC2 instance and keep it running.

Your README must include:

* Public EC2 URL
* Port number (e.g., 3456)
* Any login instructions (if applicable)

The TA will:

* Visit your running server
* Test chat functionality
* Test multi-room behavior
* Test the <code>/agent</code> AI command

This is the fastest and preferred grading method.

=== Option B — Local Execution + Demo Video ===

If your server is NOT running on EC2, you must provide a short demonstration video.

The video must show:

* Starting the server
* Two browser windows connected
* Chat working between users
* The <code>/agent</code> command working

Video length: approximately 1–2 minutes.

The TA may still run your code locally if needed.

=== Server Requirements ===

Your submission must:

* Start successfully with:

<source lang="bash">
npm install
node chat-server.js
</source>

(or equivalent script)

* Not require manual file copying or directory creation
* Not require editing source code to run
* Handle missing AI keys gracefully
* Not crash during normal use

=== Common Causes of Lost Points ===

* Missing README instructions
* API key committed to GitHub
* Server crashes when AI key missing
* Broken EC2 deployment (port closed)
* Cannot run after <code>npm install</code>
* <code>node_modules</code> committed to repo
* Hardcoded absolute file paths
* Missing AI demonstration

Following these instructions ensures your project can be graded quickly and fairly.

[[Category:Module 5]]
[[Category:Modules]]

Module 5

2026-03-16T16:57:01Z

Todd: /* Option A - Running on EC2 */

__NOTOC__

Module 5 builds upon the JavaScript skills you learned in Module 4 and introduces server-side JavaScript using Node.js, along with real-time communication using Socket.IO.

== Reading ==

The following articles on the class wiki contain information that will help you complete the assignments:

* [[Node.JS]]
* [[Socket.IO]]
* [[FAQ - Mod 5]]

== Individual Assignments ==

=== Install Node.js ===

Install Node.js using the instructions in the [[Node.JS]] guide (use the current LTS version via nvm).

=== Static File Server in Node.js ===

The individual portion is intentionally short so you have sufficient time for the group project.

Follow these steps carefully.

# Copy the static file server example from the [[Node.JS]] page into a file named <code>app.js</code>. Save it on your EC2 instance in a directory that is NOT served by Apache.
# Ensure that you understand what the static file server script is doing.
# Create a directory parallel to <code>app.js</code> named <code>static</code>.
# Confirm that your server’s <code>STATIC_DIR</code> variable matches this directory name.
# Create the following files inside the <code>static</code> directory:
#* <code>hello.txt</code> — a text file containing: <b>Hello World</b>
#* <code>brookings.jpg</code> — download from: http://classes.engineering.wustl.edu/cse330/content/brookings.jpg
#* <code>college.html</code> — an HTML page based on the [[HTML and CSS#Quick and Easy Page Layout|Quick and Easy HTML Layout]] that includes an <code><img></code> referencing <code>brookings.jpg</code>
#* <code>phpinfo.php</code> — a PHP file containing:
#: <source lang="php"><?php phpinfo(); ?></source>
# Start your Node.js server and load all four files in your browser.

Questions to consider:

* Which files work and which do not?
* Why does <code>phpinfo.php</code> behave differently when served by Node instead of Apache?

== Group Project: Multi-Room Chat Server ==

In the group portion of Module 5, you will build a multi-room chat system using Node.js and Socket.IO.

The system must include:

* A main lobby where users select a nickname
* Ability to create chat rooms
* Ability to join chat rooms
* A list of available rooms
* A list of users currently in the room
* The entire application displayed on a single webpage

The single-room example is provided here:

* [[Socket.IO]]

== AI Agent Extension ==

You will enhance your chat server with an AI assistant.

Users can message the AI by typing:

<pre>/agent What is the capital of France?</pre>

The server detects messages that begin with <code>/agent</code>, sends the prompt to an AI model, and broadcasts the response as <b>Agent</b> in the same room.

You may use:

* Ollama (recommended — runs locally and free)
* OpenAI
* Gemini
* HuggingFace
* Any approved model

If using an API, store your key in a file named <code>.env</code> at the root of your project:

<source lang="bash">
OPENAI_API_KEY=your_key_here
</source>

Load it securely in your server:

<source lang="javascript">
import 'dotenv/config';
</source>

Refer to your chosen model’s documentation for setup details.

== Grading ==

We will be grading the following aspects of your work. There are 100 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

'''Additionally, for this module, the TA should be able to simply download your repo and start up your file server, without having to copy files or create additional subdirectories. This applies to both the individual and the creative portion'''

_________

# '''Individual Portion (30 Points):'''
#* Node.JS is installed on your EC2 instance (5 points)
#*: ''Take a screenshot of your browser visiting your EC2 instance serving up the college.html web page on port 3456, make sure the URL is visible in the screenshot.''
#* The ''hello.txt'', ''brookings.jpg'', and ''college.html'' files all load successfully (4 points each)
#* Visiting a file that does not exist inside the ''static'' directory results in a 404 (4 points)
#* Discuss in the README.md why ''phpinfo.php'' behaves the way it does when loaded through Node.JS (4 points)
#* Make sure all of your individual portion files are pushed to Github (include your node.js files, hello.txt, brookings.jpg, college.html, and phpinfo.php)
#* Completion of the AI Reflections for the individual portion of the assignment following the [[AI Best Practices]] (5 points)
# '''Multi-room Chat Server (70 Points):'''
#* '''''Administration of user created chat rooms (25 Points):'''''
#** Users can create chat rooms with an arbitrary room name(5 points)
#** Users can join an arbitrary chat room (5 points)
#** The chat room displays all users currently in the room (5 points)
#** A private room can be created that is password protected (5 points)
#** Creators of chat rooms can temporarily kick others out of the room (3 points)
#** Creators of chat rooms can permanently ban users from joining that particular room (2 points)
#* '''''Messaging (5 Points):'''''
#** A user's message shows their username and is sent to everyone in the room (1 point)
#** Users can send private messages to another user in the same room (4 points)
#* '''''Best Practices (5 Points):'''''
#** Code is well formatted and easy to read, with proper commenting (2 points)
#** Code passes HTML validation (2 points)
#** node_modules folder is ignored by version control (1 points)
#* '''''Usability (5 Points):'''''
#** Communicating with others and joining rooms is easy and intuitive (4 points)
#** Site is visually appealing (1 point)
#* '''AI Agent and Reflection (20 Points)'''
#** Implement an AI assistant accessible via the command \agent ... that replies in the current room (10 points)
#** Handles basic errors gracefully and does not crash the server (5 point)
#** Completion of the AI Reflections for the group portion of the assignment following the [[AI Best Practices]] (5 points)
#* '''Creative Portion (10 Points)'''


== Submission Instructions ==

To ensure your project can be graded quickly and reliably, follow these submission requirements carefully.

All students must submit a working GitHub repository. In addition, your project must be verifiable by the TA using one of the two methods below.

=== Required for ALL Submissions ===

Your GitHub repository must include:

* All source code for both the individual and group portions
* A complete <code>package.json</code> file
* A <code>README.md</code> containing:
** How to run your server
** Which AI model you used (Ollama, OpenAI, Gemini, etc.)
** Any special setup instructions
* A <code>.gitignore</code> file that excludes:
** <code>node_modules/</code>
** <code>.env</code>

'''Do NOT commit your API keys.'''

If your project uses environment variables, include a file named:

<source lang="bash">
.env.example
</source>

Example:

<source lang="bash">
OPENAI_API_KEY=
</source>

Your server must not crash if the API key is missing. It should fail gracefully.

=== Option A - Running on EC2 ===

Deploy your chat server on your EC2 instance and keep it running.

Your README must include:

* Public EC2 URL
* Port number (e.g., 3456)
* Any login instructions (if applicable)

The TA will:

* Visit your running server
* Test chat functionality
* Test multi-room behavior
* Test the <code>/agent</code> AI command

This is the fastest and preferred grading method.

=== Option B — Local Execution + Demo Video ===

If your server is NOT running on EC2, you must provide a short demonstration video.

The video must show:

* Starting the server
* Two browser windows connected
* Chat working between users
* The <code>\agent</code> command working

Video length: approximately 1–2 minutes.

The TA may still run your code locally if needed.

=== Server Requirements ===

Your submission must:

* Start successfully with:

<source lang="bash">
npm install
node chat-server.js
</source>

(or equivalent script)

* Not require manual file copying or directory creation
* Not require editing source code to run
* Handle missing AI keys gracefully
* Not crash during normal use

=== Common Causes of Lost Points ===

* Missing README instructions
* API key committed to GitHub
* Server crashes when AI key missing
* Broken EC2 deployment (port closed)
* Cannot run after <code>npm install</code>
* <code>node_modules</code> committed to repo
* Hardcoded absolute file paths
* Missing AI demonstration

Following these instructions ensures your project can be graded quickly and fairly.

[[Category:Module 5]]
[[Category:Modules]]

Module6-New2

2026-03-15T23:57:29Z

Todd:

__NOTOC__
In Module 6, you will learn the fundamentals of Python, a popular scripting language, and Regular Expressions, which give you power in text processing. You will also be introduced to the '''Model Context Protocol (MCP)''', a standard for connecting AI assistants like Claude to your own tools and data.

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 6]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

Up to this point in CSE 3300, you have used only one programming language: PHP. In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

You can learn about this in [[MCP Fundamentals]]

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize's batting averages for 1930 and 1940."</pre>

The prompt is user controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
* <code>get_player_stats</code>: Retrieve and show batting averages for a player.
* <code>get_team_roster</code>: List all players from a given season.
* <code>get_top_players</code>: Sort and show the top hitters.
* <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>"Use CardinalsMCP to calculate batting averages."</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>"Use CardinalsMCP to show the top 10 hitters from 1940."</pre>
<pre>"Get batting averages for Johnny Mize in both 1930 and 1940."</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''"Docker MCP Toolkit"'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''Clients → Claude Desktop → Connect'''.
If it says '''"Disconnect"''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
* <code>get_player_stats</code>: Show batting averages for one player
* <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
* <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
* <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import re
import logging
from mcp.server.fastmcp import FastMCP

# Set up logging
logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
logger = logging.getLogger("CardinalsMCP-server")

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run commands like:
<pre>"Use CardinalsMCP to list the top 10 hitters from 1940."</pre>
==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>"Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average."</pre>
<pre>"Show Johnny Mize's batting averages for 1930 and 1940."</pre>
<pre>"Who were the top 5 hitters on the 1930 Cardinals?"</pre>
<pre>"Search for players with 'Martin' in their name."</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 50 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (10 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (<code>cardinals_server.py</code>) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (3 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (2 points)
#*: ''Each example should show the prompt you asked and the MCP's response.''

[[Category:Module 6]]
[[Category:Modules]]

Module 6

2026-03-15T21:43:02Z

Todd: /* cardinals_server.py */

__NOTOC__
<span style="font-size:1.3em; line-height:1.2em; color:red;">
'''This module is under development for Spring 2026. Do not begin this assignment until this notice is removed.''' </span>

In Module 6, you will learn the fundamentals of Python, a widely used scripting language, and Regular Expressions, which provide powerful tools for text processing. You will also explore the Model Context Protocol (MCP), a framework that allows software tools to communicate with large language models (LLMs).

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 4]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user-controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
** <code>get_player_stats</code>: Retrieve and show batting averages for a player.
** <code>get_team_roster</code>: List all players from a given season.
** <code>get_top_players</code>: Sort and show the top hitters.
** <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
** <code>get_player_stats</code>: Show batting averages for one player
** <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
** <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
** <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run commands like:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>
==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

Module 6

2026-03-15T21:42:28Z

Todd: /* Where Prompts, Resources, and Tools Fit in the MCP Server */

__NOTOC__
<span style="font-size:1.3em; line-height:1.2em; color:red;">
'''This module is under development for Spring 2026. Do not begin this assignment until this notice is removed.''' </span>

In Module 6, you will learn the fundamentals of Python, a widely used scripting language, and Regular Expressions, which provide powerful tools for text processing. You will also explore the Model Context Protocol (MCP), a framework that allows software tools to communicate with large language models (LLMs).

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 4]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user-controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
** <code>get_player_stats</code>: Retrieve and show batting averages for a player.
** <code>get_team_roster</code>: List all players from a given season.
** <code>get_top_players</code>: Sort and show the top hitters.
** <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
* <code>get_player_stats</code>: Show batting averages for one player
* <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
* <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
* <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run commands like:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>
==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

Module6-New2

2026-03-15T18:21:19Z

Todd:

__NOTOC__
In Module 6, you will learn the fundamentals of Python, a popular scripting language, and Regular Expressions, which give you power in text processing.

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

Example

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP_Fundamentals|Model Context Protocol (MCP)]]
* [[FAQ - Mod 4]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

Up to this point in CSE 3300, you have used two programming languages: PHP and JavaScript. In Module 6, you will learn a new language: Python.

Before starting this assignment review:

* [[Python]]
* [[Regular Expressions]]

You should use Python version 3 or greater.

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world"
# Match strings containing three or more consecutive vowels
# Match a flight code of format AA####

Save them as:

<code>regex1.txt</code>
<code>regex2.txt</code>
<code>regex3.txt</code>

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league.

In this exercise you will create a Python script that reads box scores from a file and computes the Cardinals' players' batting averages.

==== Input ====

Sample input files may be found here:

http://classes.engineering.wustl.edu/cse330/content/cardinals/

==== Output ====

Each line in the output should have the format:

<pre>
XXX: #.###
</pre>

Players should be sorted by batting average.

=== Baseball Stats MCP Extension ===

This project builds a custom MCP server that lets Claude Desktop explore St. Louis Cardinals batting data.

==== Goal ====

You will build a Python MCP server that:

* reads Cardinals batting averages
* lists team rosters
* returns top hitters
* allows player search
* runs inside Docker
* connects to Claude Desktop

==== Project Structure ====

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

==== Step 1: Prerequisites ====

Install:

* Docker Desktop
* Claude Desktop

==== Step 2: Create the Files ====

===== cardinals_server.py =====

<source lang="python">
import os
import sys
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
players=set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
player_data=[]
for year,year_data in data.items():
for player in year_data:
if player['name'].lower()==player_name.lower():
player_data.append({
'year':year,
'name':player['name'],
'batting_average':player['batting_average']
})
return player_data

# ==== MCP Tools ====

@mcp.tool()
async def hello(name: str = "world") -> str:
return f"Hello CSE 3300 Student, {name}!"

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
# TODO

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
# TODO

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
# TODO

@mcp.tool()
async def search_players(search_term: str = "") -> str:
# TODO

if __name__=="__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

== Grading ==

We will be grading the following aspects of your work. There are 50 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see https://en.wikipedia.org/wiki/Usage_message#Examples''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (10 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (3 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (2 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''

--- NEW -----

==== Verify Your MCP Server Works ====

Before connecting Claude Desktop, verify that your MCP server runs correctly.

Run your container manually:

<source lang="bash">
docker run --rm -it cardinals-mcp-server:latest
</source>

If everything is working correctly, you should see a startup message similar to:

<source lang="text">
Starting Cardinals Historical Data MCP server...
</source>

If the container exits with an error, fix the issue before continuing.

You can stop the container with:

<source lang="bash">
Ctrl+C
</source>

Do not attempt to connect Claude until the container runs successfully.

==== Common Setup Mistakes ====

If Claude cannot see your MCP server, check the following:

'''Docker image was not built'''

You must run:

<source lang="bash">
docker build -t cardinals-mcp-server:latest .
</source>

before attempting to run the container.

'''Container name mismatch'''

The Docker image name in your Claude configuration must match the image name used during the build step.

Example:

<source lang="bash">
docker build -t cardinals-mcp-server:latest .
</source>

must match:

<source lang="json">
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
</source>

'''Claude Desktop was not restarted'''

After editing the MCP configuration file, completely quit and reopen Claude Desktop.

'''The container exits immediately'''

This usually means your Python script crashed. Run the container manually to view the error:

<source lang="bash">
docker run --rm -it cardinals-mcp-server:latest
</source>

==== What Claude Is Actually Doing ====

When you ask Claude a question such as:

<pre>
Use CardinalsMCP to list the top 10 hitters from 1940.
</pre>

the following process occurs:

<pre>
User Prompt
↓
Claude reads the prompt
↓
Claude decides which tool to use
↓
Claude calls the MCP server
↓
Docker launches your container
↓
Your Python tool runs
↓
The results are returned to Claude
</pre>

Claude never directly runs your Python code.

Your MCP server runs the code and sends the results back to Claude.

==== Debugging Your MCP Server ====

If Claude does not return results, try the following:

'''Step 1: Verify the container runs'''

<source lang="bash">
docker run --rm -it cardinals-mcp-server:latest
</source>

'''Step 2: Verify your Python script loads'''

Your container should print a startup message when it launches.

'''Step 3: Verify tools exist'''

Claude should display available tools in the MCP indicator inside the chat interface.

'''Step 4: Check Claude configuration'''

Ensure the file:

<code>claude_desktop_config.json</code>

contains your MCP server configuration.

If necessary, restart Claude Desktop.

[[Category:Module 6]]
[[Category:Modules]]

Module 6

2026-03-15T15:51:04Z

Todd:

__NOTOC__
<span style="font-size:1.3em; line-height:1.2em; color:red;">
'''This module is under development for Spring 2026. Do not begin this assignment until this notice is removed.''' </span>

In Module 6, you will learn the fundamentals of Python, a widely used scripting language, and Regular Expressions, which provide powerful tools for text processing. You will also explore the Model Context Protocol (MCP), a framework that allows software tools to communicate with large language models (LLMs).

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 4]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
* <code>get_player_stats</code>: Retrieve and show batting averages for a player.
* <code>get_team_roster</code>: List all players from a given season.
* <code>get_top_players</code>: Sort and show the top hitters.
* <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
* <code>get_player_stats</code>: Show batting averages for one player
* <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
* <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
* <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run commands like:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>
==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

Module 6

2026-03-15T15:47:03Z

Todd: /* Reading */

__NOTOC__
<span style="font-size:1.3em; line-height:1.2em; color:red;">
'''This module is under development for Spring 2026. Do not begin this assignment until this notice is removed.''' </span>

In Module 6, you will learn the fundamentals of Python, a popular scripting language, and Regular Expressions, which give you power in text processing.

This article contains your assignments for Module 6.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 4]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

In Module 6, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
* <code>get_player_stats</code>: Retrieve and show batting averages for a player.
* <code>get_team_roster</code>: List all players from a given season.
* <code>get_top_players</code>: Sort and show the top hitters.
* <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
* <code>get_player_stats</code>: Show batting averages for one player
* <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
* <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
* <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run commands like:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>
==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 70 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (30 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (14 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (6 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''
#* Completion of the AI Reflections for the assignment following the [[AI Best Practices]] (5 points)

[[Category:Module 6]]
[[Category:Modules]]

Module6-AI

2026-03-15T15:45:45Z

Todd: /* Reading */

__NOTOC__
In Module 4, you will learn the fundamentals of Python, a popular scripting language, and Regular Expressions, which give you power in text processing.

This article contains your assignments for Module 4.

=== Learning Goals ===
* Regular Expressions
* Python
* MCP Fundamentals

== Using the Wiki ==
{{RequiredInstructions|content=
Text enclosed by <syntaxhighlight lang="bash" inline><</syntaxhighlight> and <syntaxhighlight lang="bash" inline>></syntaxhighlight> should be replaced by content unique to you.

'''Example'''

<source lang="bash">
$ sudo useradd -r -m -c "<My Full Name>" <usernameHere>
</source>
becomes
<source lang="bash">
$ sudo useradd -r -m -c "Zach Cohn" zcohn
</source>
}}

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Python]]
* [[Regular Expressions]]
* [[MCP Fundamentals]]
* [[FAQ - Mod 4]]

== Individual Assignments ==

=== Learn Python and Regular Expressions ===

Up to this point in CSE 330, you have used only one programming language: PHP. In Module 4, you will learn a new language: Python. Before starting this assignment, you should look over the [[Python|online textbook article about Python]]. You should be using version 3 (or greater) of Python. Additionally, you may find it helpful to look over the [[Regular Expressions|online textbook article about Regular Expressions]].

=== Write some Regular Expressions ===

Please write regular expressions that do each of the following:

# Match the substring "hello world" in a string.
# Match all character strings in an input string that contain three or more consecutive vowels. The regex should match strings containing three or more consecutive vowels, regardless of whether the letters are uppercase, lowercase, or a mixture of both.
# Match an input string that is '''entirely''' a flight code, of the format AA####, where '''AA''' is a two-letter uppercase airline code, and '''####''' is a three- or four-digit flight number.
Examples:
Note: text in ''[[red]]'' is matched by the regular expression. Please note that each line is a '''separate''' test input string. For Regex 3, '''six''' separate test cases are given.
Regex 1: Programmers will often write ''[[hello world]]'' as their first project with a programming language.
Regex 2: The ''[[gooey]]'' peanut butter and jelly sandwich was a ''[[beauty]]''.
Regex 3: ''[[AA312]]''
''[[AA1298]]''
''[[NW1234]]''
''[[US443]]''
US31344
AA123 extratext

Save your regexes to text files – one each.

=== Baseball Stats Counter ===

The St. Louis Cardinals are the most legendary baseball team in the national league. In this exercise, you will be creating a Python script that reads box scores from a file and computes the Cardinals' players' batting averages in a particular season.

==== Tips and Instructions ====

* You should write a Python script file to solve this problem.
* You should use a regular expression to parse players' names, at-bats, hits, and runs from the input file.
* You may want to create a class to hold and compute information about each player.
* Your file should take one command-line argument: the path to an input file. If no path is given, your program should print a usage message.

==== Input ====

Sample input files may be found here: http://classes.engineering.wustl.edu/cse330/content/cardinals/

The top of the file contains a citation, and what follows is an entire season of Cardinals Baseball box scores. Each game starts with a title; for example:

=== St.Louis Cardinals vs. Chicago Cubs, 1940-04-19 ===

What follows are the performance of each player in that game. The format of each line is as follows:

XXX batted # times with # hits and # runs

where '''XXX''' is the player's name (you may assume that the name is unique), and each '''#''' are integers representing the number of "at bats", the number of "hits", and the number of "runs", respectively.

==== Output ====

Your script needs to output all players' batting average across the season. A player's batting average is that player's total hits divided by that player's total at-bats throughout the entire season. For example, Johnny Hopp was at bat 149 times in 1940, and he had 41 hits, so his batting average was 0.275.

Each line in the output should have the format:

XXX: #.###

where '''XXX''' is the player's name, and '''#.###''' is the player's batting average, '''rounded''' (not truncated) to three decimal places.

The players should be sorted by batting average, with the highest batting average on top. If two players have the exact same batting average (before rounding occurs), the order between those two players is unimportant.

For example, the correct output for the 1940 season is:

<source lang="text">
Pepper Martin: 0.316
Walker Cooper: 0.316
Johnny Mize: 0.314
Ernie Koy: 0.310
Enos Slaughter: 0.306
Joe Medwick: 0.304
Terry Moore: 0.304
Joe Orengo: 0.286
Jimmy Brown: 0.280
Marty Marion: 0.279
Don Gutteridge: 0.276
Johnny Hopp: 0.275
Creepy Crespi: 0.273
Mickey Owen: 0.265
Bill DeLancey: 0.250
Don Padgett: 0.242
Stu Martin: 0.238
Eddie Lake: 0.222
Hal Epps: 0.214
Lon Warneke: 0.209
Harry Walker: 0.185
Max Lanier: 0.179
Bill McGee: 0.178
Carl Doyle: 0.174
Mort Cooper: 0.157
Clyde Shoun: 0.145
Carden Gillenwater: 0.130
Bob Bowman: 0.067
</source>

=== Baseball Stats MCP Extension ===

====Cardinals MCP Server ====

You can learn about this in [[MCP Fundamentals]]

This project builds a '''custom MCP server''' that lets you explore ''St. Louis Cardinals'' batting data from the '''1930''' and '''1940''' seasons using the text files you made in the Baseball Stats Counter section.

The MCP server reads player batting averages from text files, sorts them, and returns the results through '''Claude Desktop'''.

For all of the assignment, feel free to use your favorite AI tool to help.

==== What Is an MCP Server? ====

An '''MCP (Model Context Protocol)''' server is a local tool that '''Claude Desktop''' can talk to directly.
It runs safely inside '''Docker''', allowing Claude to use your Python scripts, such as this Cardinals data processor, through its chat interface.

Learn more:
[https://modelcontextprotocol.io/docs/getting-started/intro Model Context Protocol: Getting Started]

Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable interactions between clients, servers, and language models:

* '''Prompts''': Predefined templates or instructions that guide language model interactions
* '''Resources''': Structured data or content that provides additional context to the model
* '''Tools''': Executable functions that allow models to perform actions or retrieve information

Each primitive can be summarized in the following control hierarchy:

====== Where Prompts, Resources, and Tools Fit in the MCP Server ======

* '''Prompts''': In the context of this project, prompts are what the user will provide to interact with the MCP server. For example, if you want to fetch the top hitters from a particular season, you would issue a prompt like:
<pre>"Show Johnny Mize’s batting averages for 1930 and 1940."</pre>

The prompt is user controlled, and the system will interpret it to execute the appropriate action.

* '''Resources''': These are the data files, such as <code>cardinals-1930.txt</code> and <code>cardinals-1940.txt</code>, that your MCP server uses to provide additional context. These text files are '''resources''' that store structured data (player stats like batting averages) which the server can access to provide meaningful results when the user queries it.

* '''Tools''': The server exposes various '''tools''' that perform specific actions, like:
* <code>get_player_stats</code>: Retrieve and show batting averages for a player.
* <code>get_team_roster</code>: List all players from a given season.
* <code>get_top_players</code>: Sort and show the top hitters.
* <code>search_players</code>: Search for players by name.

Each of these functions is a '''tool''' in the MCP system that the language model can call when responding to prompts from the user.

==== What Is Docker? ====

'''Docker''' lets you run software in isolated, self-contained environments called '''containers'''.
A container is like a tiny computer that holds everything your app needs (code, libraries, and dependencies) so it runs the same way on every machine.

Claude uses Docker to safely run MCP tools '''without touching your main system'''.
When you say:

<pre>“Use CardinalsMCP to calculate batting averages.”</pre>

Claude does not execute code directly. It asks Docker to launch your MCP container, which runs the script in isolation.

==== Goal ====

You will build a '''Python-based MCP server''' that:

* Reads Cardinals player batting averages from '''1930''' and '''1940''' text files
* Lists team rosters and top hitters
* Lets you search players or compare across seasons
* Runs inside Docker and connects to Claude Desktop

After setup, you will be able to say things like:

<pre>“Use CardinalsMCP to show the top 10 hitters from 1940.”</pre>
<pre>“Get batting averages for Johnny Mize in both 1930 and 1940.”</pre>

Claude will automatically run your tool and show the results.

==== Project Structure ====

Your final folder will look like this:

<source lang="text">
cardinals-mcp/
├── Dockerfile
├── cardinals_server.py
├── requirements.txt
└── data/
├── cardinals-1930.txt
└── cardinals-1940.txt
</source>

The <code>/data</code> directory contains the <code>.txt</code> files you created from the Baseball Stats Counter section, listing player names and batting averages.
If you only printed the results, copy and paste them into <code>.txt</code> files.

==== Step 1: Prerequisites ====

You will need:

* [https://www.docker.com/products/docker-desktop/ Docker Desktop]
* [https://claude.ai/download Claude Desktop] (''not the browser version'')

==== Enable MCP in Docker ====

# Open '''Docker Desktop'''.
# Go to '''Settings → Beta Features'''.
# Enable '''“Docker MCP Toolkit”'''.
# Click '''Apply & Restart'''.

===== Connect Claude to Docker =====

In Docker Desktop, go to '''Clients → Claude Desktop → Connect'''.
If it says '''“Disconnect”''', you are good to go.

==== Step 2: Create the Files ====

===== <code>cardinals_server.py</code> =====

This is your main MCP script. It should:

* Load player data from <code>/data/cardinals-1930.txt</code> and <code>/data/cardinals-1940.txt</code>
* Implement at least '''two tools''', such as:
* <code>get_player_stats</code>: Show batting averages for one player
* <code>get_team_roster</code>: List all players for a given season (1930 or 1940)
* <code>get_top_players</code>: Show the top hitters for a given season (by batting average)
* <code>search_players</code>: Find players by partial name and show their batting averages

Each tool should be implemented as an '''asynchronous function''' decorated with <code>@mcp.tool()</code>. For example, the provided <code>get_player_stats</code> function uses the <code>@mcp.tool()</code> decorator to indicate that it is a tool that can be invoked by Claude.

In this script, you need to:

'''Create MCP Tools:'''
* Implement at least two MCP tools (<code>get_player_stats</code>, <code>get_team_roster</code>, <code>get_top_players</code>, <code>search_players</code>).
* Use the <code>@mcp.tool()</code> decorator to register each function as a tool that Claude can use.
* Your functions should:
** Retrieve data from the loaded player stats.
** Perform calculations or sorting (for example, finding the top hitters or listing all players for a season).
** Return well-formatted strings with the results.

===== Starter Code =====

<source lang="python">
import os
import sys
import re
from datetime import datetime
from mcp.server.fastmcp import FastMCP

# Initialize MCP server
mcp = FastMCP("CardinalsMCP")

# Data file paths
DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
CARDINALS_1930_FILE = os.path.join(DATA_DIR, "cardinals-1930.txt")
CARDINALS_1940_FILE = os.path.join(DATA_DIR, "cardinals-1940.txt")

# ==== Helper Functions (You DO NOT need to use these) ====

def load_cardinals_data():
"""Load Cardinals player data from both 1930 and 1940 files."""
data = {"1930": [], "1940": []}

for year, file_path in [("1930", CARDINALS_1930_FILE), ("1940", CARDINALS_1940_FILE)]:
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
data[year] = parse_player_data(content)
except FileNotFoundError:
logger.warning(f"Data file not found: {file_path}")
except Exception as e:
logger.error(f"Error loading {year} data: {e}")

return data

def parse_player_data(content):
"""Parse player data from the simplified Cardinals text files."""
players = []

for line in content.split('\n'):
line = line.strip()
if not line or line.startswith('#'):
continue

# Parse format: "Player Name: 0.XXX"
if ':' in line:
parts = line.split(':')
if len(parts) == 2:
name = parts[0].strip()
try:
batting_avg = float(parts[1].strip())
players.append({
'name': name,
'batting_average': batting_avg
})
except ValueError:
continue

return players

def get_all_players(data):
"""Get all unique players from the data."""
players = set()
for year_data in data.values():
for player in year_data:
players.add(player['name'])
return sorted(list(players))

def get_player_by_name(data, player_name):
"""Get player data for a specific player."""
player_data = []
for year, year_data in data.items():
for player in year_data:
if player['name'].lower() == player_name.lower():
player_data.append({
'year': year,
'name': player['name'],
'batting_average': player['batting_average']
})
return player_data

# ==== MCP Tools ====

# This tool works - use to test your MCP connection.
@mcp.tool()
async def hello(name: str = "world") -> str:
"""Return a simple greeting to verify the server is working."""
return f"Hello CSE 3300 Student, {name}!"

# Only two tools are required here

@mcp.tool()
async def get_player_stats(player: str = "") -> str:
"""Get a player's batting averages for both 1930 and 1940 seasons."""
# TODO: Implement the function to fetch player data using the 'load_cardinals_data'
# and 'get_player_by_name' functions

@mcp.tool()
async def get_team_roster(year: str = "1930") -> str:
"""Get the roster of the Cardinals for the given year, listing player names and batting averages."""
# TODO: Implement the function to fetch and list the team roster for the specified year (1930 or 1940)

@mcp.tool()
async def get_top_players(year: str = "1930", limit: int = 10) -> str:
"""Get the top Cardinals players for a specific year, sorted by batting average."""
# TODO: Implement this function to return the top 'limit' players sorted by their batting averages

@mcp.tool()
async def search_players(search_term: str = "") -> str:
"""Search for Cardinals players by name and show their batting averages."""
# TODO: Implement this function to search for players by name and return their batting averages

# ==== Server Startup ====

if __name__ == "__main__":
logger.info("Starting Cardinals Historical Data MCP server...")
try:
mcp.run(transport="stdio")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
</source>

===== <code>Dockerfile</code> =====

<source lang="dockerfile">
FROM python:3.11-slim

LABEL maintainer="cardinals_server"
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copy dependencies
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY cardinals_server.py /app/cardinals_server.py
COPY data/ /app/data/
COPY *.md /app/

# Create non-root user
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser

CMD ["python", "/app/cardinals_server.py"]
</source>

===== <code>requirements.txt</code> =====

<source lang="text">
mcp
</source>

That is all you need unless you use extra libraries.

==== Step 3: Build and Test the Container ====

Build your Docker image:

<source lang="bash">
$ docker build -t cardinals-mcp-server:latest .
</source>

Run it:

<source lang="bash">
$ docker run --rm -it cardinals-mcp-server
</source>

If it launches correctly, you will see something like:

<source lang="text">
2025-10-19 20:00:00,000 - CardinalsMCP-server - INFO - Starting Cardinals Historical Data MCP server...
</source>

==== Step 4: Connect in Claude Desktop ====

===== Open Claude Desktop Settings =====

On macOS, click '''Claude → Settings…''' from the top menu bar.
(''Do not use the settings inside the Claude chat window; you need the app-level settings.'')

This opens the '''Claude Desktop Settings''' panel, separate from your Claude account settings.

===== Go to Developer Settings =====

In the Settings window, select the '''Developer''' tab in the left sidebar.
This section manages MCP servers and other developer tools.

Click '''Edit Config''' to open the configuration file.
If you do not have one yet, Claude will create it automatically.

'''Configuration file locations:'''

* macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>
* Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>

===== Add the MCP Gateway Configuration =====

Replace (or merge) the contents of the file with the JSON below.
This tells Claude to launch the '''Docker MCP Gateway''', which connects to your custom Cardinals MCP server.

<source lang="json">
{
"mcpServers": {
"cardinals-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"cardinals-mcp-server:latest"
]
}
}
}
</source>

===== Restart Claude Desktop =====

After saving the file:
* Completely quit Claude Desktop (not just close the window).
* Reopen it.

Claude will now start the MCP gateway automatically.

If everything is configured correctly, you will see a small MCP indicator in the lower-right corner of the chat input box. Click it to view all available tools, including your '''Cardinals MCP Server'''.

Once connected, you can run commands like:
<pre>“Use CardinalsMCP to list the top 10 hitters from 1940.”</pre>
==== Step 5: Test It Out ====

Open a new chat in Claude and try:

<pre>“Use CardinalsMCP to list the 1940 Cardinals roster sorted by batting average.”</pre>
<pre>“Show Johnny Mize’s batting averages for 1930 and 1940.”</pre>
<pre>“Who were the top 5 hitters on the 1930 Cardinals?”</pre>
<pre>“Search for players with ‘Martin’ in their name.”</pre>

Claude will call your MCP tool, execute your Python script inside Docker, and display formatted results.

== Grading ==

We will be grading the following aspects of your work. There are 50 points total.

'''Assignments (including code) must be committed to Github by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. '''

Upload your baseball code and a file with your Regular expressions.

# '''Regular Expressions (15 Points):'''
#* '''Your regex files should contain your regex (with no delimiters or flags) and nothing else.'''
#* Regular Expression 1 Correct and saved in a file named <code>regex1.txt</code> (5 points)
#* Regular Expression 2 Correct and saved in a file named <code>regex2.txt</code> (5 points)
#* Regular Expression 3 Correct and saved in a file named <code>regex3.txt</code> (5 points)

# '''Baseball Stats Counter (25 Points):'''
#* Solution is written entirely in Python and saved in a file named <code>baseball.py</code> (5 points)
#*: ''Note: Failing to write your code in Python 3 will result in losing, at a minimum, points for this category.''
#* Correct usage of one or more regular expressions to parse and extract data from each line of the input file (5 points)
#*: ''Note: You should not be using <code>str.split</code> to extract data.''
#* Script prints a usage message if a command line argument is not present (3 points)
#*: ''Note: For an example of a usage message, see [https://en.wikipedia.org/wiki/Usage_message#Examples this link.]''
#* Output is correct for all test cases (12 points)
#*: ''This includes sorting and rounding.''

# '''Baseball Stats MCP Extension (10 Points):'''
#* Docker image builds successfully without errors (5 points)
#*: ''MCP server (`cardinals_server.py`) loads player data and returns correct results.''
#* Includes at least 2 MCP tools (3 points)
#*: ''Each tool must function correctly and return expected output through Claude Desktop.''
#* README includes 3 different example prompts used in Claude (2 points)
#*: ''Each example should show the prompt you asked and the MCP’s response.''

[[Category:Module 6]]
[[Category:Modules]]