Skip to main content
Glama

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers