InterviewDojo 🥋🎙️

Self-Hosted Model Context Protocol (MCP) Server for Alexa+ Spoken Mock Technical Interviews powered by Amazon Bedrock.

Build, Ship, Shape: Amazon Developer Hackathon (Alexa+ Track + AWS Builder Mini Challenge)

🚀 What it is

InterviewDojo is a production-grade, self-hosted Model Context Protocol (MCP) server (MCP Spec 2025-11-25+, Streamable HTTP / SSE transport) designed to let Alexa+ run spoken mock technical interviews for software engineering candidates.

Instead of asking generic algorithmic questions, InterviewDojo analyzes the candidate's own resume (projects, skills, experience) alongside a target job description. It generates targeted interview questions focusing ~60% on candidate projects, ~40% on skill gap areas, and exactly one STAR-method behavioral question. Answers are scored using Amazon Bar Raiser rubrics via Amazon Bedrock Converse API.

The project includes an Alexa+ Voice Simulator React web app (/web) that interacts directly with the server via the official @modelcontextprotocol/sdk client over HTTP/SSE.

Related MCP server: four-leaf-mcp

📐 Architecture

graph TD
    subgraph Client Layer
        A["Alexa+ Spoken Agent / Simulator Web App"]
    end

    subgraph Transport Layer
        B["MCP Client (@modelcontextprotocol/sdk)"]
        C["Streamable HTTP / SSE Transport (/mcp)"]
    end

    subgraph InterviewDojo MCP Server
        D["Express Server (Node.js + TypeScript)"]
        E["MCP Server Core & Tool Registry"]
        F["parse_resume"]
        G["start_interview"]
        H["next_question"]
        I["score_answer"]
        J["session_report"]
    end

    subgraph AWS & Data Persistence Layer
        K["Amazon Bedrock Converse API (Claude 3.5 Sonnet)"]
        L[("MongoDB / In-Memory Session Store")]
    end

    A <--> B
    B <-->|JSON-RPC over SSE| C
    C <--> D
    D --> E
    E --> F & G & H & I & J
    F & G & I & J <-->|Bedrock SDK| K
    G & H & I & J <-->|Mongoose| L

📦 Registered MCP Tools

All tools validate inputs with zod, return structured content alongside text summaries, and handle errors cleanly:

1. parse_resume { resumeText: string }

   • Extracts candidate skills, project details, work highlights, and education.

2. start_interview { resumeText, jobDescription, role, difficulty, numQuestions }

   • Generates interview plan, question mix, and initializes session.

3. next_question { sessionId }

   • Retrieves next question in sequence.

4. score_answer { sessionId, answer }

   • Evaluates spoken/typed answer using Bedrock Bar Raiser rubric (0-10 scores for correctness, depth, clarity, spoken feedback, follow-up, ideal hint).

5. session_report { sessionId }

   • Generates overall score breakdown, strengths, weak topics, and concrete 3-5 item practice plan.

🛠️ Prerequisites

• Node.js: v20.0.0 or higher

• AWS Bedrock Access: Access to us.anthropic.claude-3-5-sonnet-20241022-v2:0 (or set BEDROCK_MODEL_ID) in AWS_REGION (us-east-1).

• MongoDB (Optional): MONGODB_URI connection string (falls back to in-memory Map store if omitted).

⚙️ Environment Configuration

Copy .env.example to .env inside /server:

cp .env.example server/.env

PORT=3001
NODE_ENV=development
ALLOWED_ORIGIN=http://localhost:5173

# AWS Bedrock Configuration
AWS_REGION=us-east-1
BEDROCK_MODEL_ID=us.anthropic.claude-3-5-sonnet-20241022-v2:0
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key

# Mock LLM Flag (Set to true for test mode without AWS credentials)
MOCK_LLM=false

# MongoDB Connection String (Optional fallback to in-memory)
MONGODB_URI=mongodb://localhost:27017/interviewdojo

🏃 Run Commands

1. Install Dependencies

# Install root, server, and web app packages
npm run install:all # or cd server && npm install && cd ../web && npm install

2. Run Server & Web App Concurrently

npm run dev

• Express MCP Server: http://localhost:3001/mcp

• Health Endpoint: http://localhost:3001/health

• Alexa+ Simulator Web App: http://localhost:5173

3. Run Automated Seed Script (2-Minute Demo Run)

npm run seed

4. Run Vitest Unit & MCP Integration Tests

npm test

🔍 How to Test with MCP Inspector

You can test InterviewDojo with the official Anthropic / Model Context Protocol Inspector tool:

# 1. Start InterviewDojo server
npm run dev:server

# 2. In another terminal, run MCP Inspector pointing to the SSE endpoint
npx @modelcontextprotocol/inspector http://localhost:3001/mcp

Open the Inspector UI in your browser to inspect tools, input schemas, and invoke parse_resume or start_interview interactively.

🎙️ How Alexa+ Connects to /mcp

Alexa+ connects to InterviewDojo over the standard Streamable HTTP transport:

1. Alexa+ establishes an SSE stream by making a GET request to http://<your-server-domain>/mcp.

2. The server responds with an SSE event containing the session endpoint URL (/mcp/messages?sessionId=...).

3. Alexa+ sends JSON-RPC tool invocation requests (tools/call) via POST /mcp/messages?sessionId=....

4. Spoken text responses are returned in structuredContent and spoken aloud by Alexa+.

⚠️ Known Limitations

1. Browser Web Speech API Support: Speech recognition relies on browser support (SpeechRecognition / webkitSpeechRecognition). A typed-answer fallback is provided for browsers without speech recognition support.

2. Audio Streaming: Audio is converted text-to-speech client-side via Web Speech API; native binary PCM streaming over SSE is reserved for future iterations.

📜 Pre-existing vs Built During the Hackathon

Note for Hackathon Judges & Compliance Reviewers:

• Pre-existing Code: None. (Built completely fresh from scratch for this hackathon).

• Built During Hackathon:

  • Entire TypeScript MCP Server with Streamable HTTP transport (/mcp).

  • Amazon Bedrock Converse API integration with JSON validation & retry logic.

  • All 5 MCP tools (parse_resume, start_interview, next_question, score_answer, session_report).

  • MongoDB + in-memory fallback storage layer.

  • React + Vite + Tailwind CSS Alexa+ Voice Simulator web application (/web).

  • Vitest test suite and seed script.

📄 License

MIT License. See LICENSE file for details.