# Submission Reviewer MCP Server

The Husky Home Finder collects student submissions (apartment reviews, roommate interest, housing survey, and newsletter/waitlist sign ups.) 

Currently, we would need to read each submission manually to catch duplicates, incomplete responses, and other bad submissions. 

This MCP server adds AI review between submission and the database in order to classify the submissions, extract the data, summarize the information, and check for duplicates.

## How Codex and GPT 5.6 were used
Codex was used as the main builder, building the MCP server (the tools, the typescript source (src), and the mock JSON data). I told Codex what I wanted each tool to do and then reviewed it, editing it based on the output. 

GPT 5.6 is called, and powers two of the four tools: classifying submissions and extracting fields from the text reviews. 

The other two tools (dedupe_check and summarize_batch) don't use AI calls, they are rule-based. 


## What it does

The server exposes exactly four tools:

| Tool | Plain-language purpose | What it returns |
| --- | --- | --- |
| `classify_submission` | Helps staff spot incomplete, inconsistent, or potentially duplicate form responses before reviewing them manually. | GPT-5.6 data-quality classifications for redacted records in one form. |
| `extract_fields` | Turns free-text apartment reviews into consistent fields that a future directory or dashboard can use. | GPT-5.6 structured quality, amenity, and concern data from apartment-review text. |
| `dedupe_check` | Finds submissions that may be repeats, so staff do not need to review the same response twice. | Likely duplicate submission IDs using a form-specific matching rule. |
| `summarize_batch` | Gives the team a quick picture of trends, such as budgets, neighborhoods, ratings, or housing concerns. | Privacy-preserving aggregate counts, averages, and common choices for one form. |

The mock data deliberately includes ordinary valid submissions, likely duplicates, incomplete responses, and invalid values so the tools have useful results immediately.

## Project layout

```text
src/
  index.ts            MCP server and tool registration
  call-tool.ts        Small local MCP client for manual testing
  data.ts             Reads mock JSON data (replace this later for a database)
  analysis.ts         Duplicate detection and aggregate summaries
  openai-analysis.ts  Redacted GPT-5.6 classification and field extraction
  types.ts            Form data types
mock-data/            One JSON file for each form type
```

## Setup

You need Node.js 20 or newer.

```bash
npm install
npm run build
```

## Test a tool manually

The `call` command compiles the project, starts the server, calls one tool, prints its JSON result, and stops.

```bash
# Summarize a batch of housing surveys
npm run call -- summarize_batch --form housing_survey

# Find repeated roommate-interest submissions
npm run call -- dedupe_check --form roommate_interest
```

The AI tools require an API key. Copy `.env.example` to `.env`, add `OPENAI_API_KEY`, and use:

```bash
# Classify records for human data-quality review
npm run call:ai -- classify_submission --form roommate_interest

# Extract structured fields from apartment reviews
npm run call:ai -- extract_fields --limit 10

# Analyze one newly pasted apartment review instead of mock data
npm run call:ai -- extract_fields --text "The apartment is close to campus, but our unit had recurring plumbing problems."

# Classify one newly pasted housing-survey response
npm run call:ai -- classify_submission --form housing_survey --text "I live on campus, have a $1400 monthly budget, and want housing near the University District."
```

For pasted text, omit names, email addresses, phone numbers, and other direct identifiers. The server also redacts common email and phone-number patterns before making an AI request.

Form results also include a `formOverview` object so outside users understand what each form category represents:

| Form type | What it covers |
| --- | --- |
| `housing_survey` | Current housing, budget, preferred neighborhoods, and concerns. |
| `apartment_review` | Building quality, rent, room type, rating, and written student experience. |
| `roommate_interest` | Move-in timing, budget, lifestyle preferences, and a short student bio. |
| `newsletter_waitlist` | Interest in Husky Home Finder updates and housing resources. |

## Run as an MCP server

After building, start the standard-input/output server with:

```bash
npm start
```

For an MCP client configuration that uses the AI tools, start it with the environment file loaded:

```bash
npm run build
npm run start:ai
```

MCP uses standard output for protocol messages. The server sends status messages to standard error, so do not add ordinary `console.log` statements to `src/index.ts`.

An MCP client can register the compiled server with:

```json
{
  "command": "node",
  "args": ["/absolute/path/to/submission-reviewer/dist/index.js"]
}
```

## Privacy and MVP notes

This is a learning MVP, not production storage for real student data. The AI tools redact names, email addresses, and phone numbers before sending records to the provider. Classification and duplicate results are review aids, never automatic housing or roommate decisions.

Before collecting real submissions, add authentication and authorization, encrypted database storage and backups, consent and retention rules, rate limiting, audit logs, and a human review process.

## Where to make changes later

- **Add or change a form field:** update `src/types.ts`, its JSON fixture, and summary or extraction logic.
- **Use a database:** replace `loadSubmissions` in `src/data.ts`; the tools can stay the same.
- **Adjust duplicate matching:** edit `dedupeCheck` in `src/analysis.ts`.