Overview

This MCP (Model Context Protocol) server provides a structured runtime for persona-driven coaching, interview practice, and reflective conversations. It runs as an MCP server that an MCP-capable client (for example, Claude Desktop or another assistant that supports MCP) can call into to load role profiles, start guided session flows, manage timers, and produce session feedback.

The server is intended for developers and power users who want repeatable, customizable conversational scaffolds—mock interviews with realistic interviewers, rehearsal sessions with leadership personas, or adaptive journaling that nudges toward reflection and growth. Sessions are defined by templates and persona files so you can extend and reuse frameworks across different preparation and coaching scenarios.

Features

Persona-driven behavior: load persona documents that change assistant style, expertise, and objectives
Session templates: predefined frameworks with goals, duration, and topic structure
Timer management: start, monitor, and stop timed sessions from the MCP client
Adaptive flow: session logic that advances based on user input and session goals
Post-session evaluation: automated feedback and performance assessment from an evaluator persona
Safe file handling: path validation and error checks to reduce file system risk
Extensible: add new personas and session types via simple YAML/Markdown files

Installation / Configuration

Prerequisites:

Python 3.8+
An MCP-compatible client (e.g., Claude Desktop) to act as the front end

Clone and install:

git clone https://github.com/mattjoyce/mcp-persona-sessions.git
cd mcp-persona-sessions
pip install fastmcp

Create a local config file:

cp config.yaml.example config.yaml
# then edit config.yaml to set paths and defaults

Example config.yaml (essential fields):

persona_path: "roles"
session_types_file: "session_types.yaml"
default_persona_file: "Role-Interviewer-mcp.md"
evaluator_persona_file: "Role-Interview-Evaluator.md"

MCP client configuration (example JSON entry to register the server):

{
  "mcpServers": {
    "persona-sessions": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/mcp-persona-sessions/mcp-persona-sessions.py"],
      "cwd": "/path/to/mcp-persona-sessions"
    }
  }
}

Persona and Session Definitions

Personas are simple Markdown files living in the roles/ directory. They define voice, goals, expertise, and interaction constraints.

Example persona (roles/Role-Interviewer-mcp.md):

# Senior Software Engineering Manager

## Identity and Purpose
A technical hiring manager focusing on architecture and leadership.

## Communication Style
Direct, structured, provides actionable feedback.

## Expertise Areas
Systems design, team leadership, scaling, tradeoffs.

## Goals
Evaluate candidate's problem framing, tradeoff reasoning, and communication.

Session types live in session_types.yaml and map personas to frameworks:

session_types:
  - name: "Mock Interview - Systems Design"
    persona: "Senior Software Engineering Manager"
    persona_file: "Role-Interviewer-mcp.md"
    description: "45-minute systems design interview with follow-up feedback"
    duration: 45
    topics:
      - "Design a URL shortener"
      - "Scale considerations"
    goals:
      - "Assess system decomposition and tradeoff awareness"

Available Tools / Resources

The server exposes a concise set of MCP tool endpoints that clients can call. Typical endpoints:

Tool	Purpose
list_session_frameworks	Return available session templates
list_session_personas	Return persona filenames and metadata
get_persona_details	Fetch full persona Markdown content
assess_session_readiness	Validate inputs and prerequisites
initialize_session	Create session instance and context
start_timer	Start a session timer (optional duration)
check_timer_status	Query remaining/elapsed time
stop_timer	Stop the timer and finalize timestamps
get_session_feedback	Produce evaluator-style feedback on transcript

Use these via your MCP client to orchestrate sessions, attach documents, or pipe transcripts for analysis.

Typical Session Flow

Choose a session template or specify persona and goals.
initialize_session with context (topics, documents, desired duration).
start_timer (optional) to enforce pacing.
Conduct the conversation through your MCP client—assistant behaves as the loaded persona.
stop_timer and call get_session_feedback to receive assessment and improvement suggestions.

Example client prompt to start a session: “Run a mock interview with the ‘Senior Software Engineering Manager’ persona about URL shortener design for 30 minutes. Use attached system spec as context.”

Use Cases (concrete examples)

Job interview prep: candidate runs repeated mock interviews against industry-specific interviewer personas, then requests feedback on structure, clarity, and tradeoffs.
Presentation rehearsal: rehearse a 10-minute product demo with a persona that acts like a skeptical stakeholder; receive critique of messaging and Q&A handling.
Difficult conversation practice: role-play a performance discussion with a persona modeled after a team lead; practice phrasing and receive suggestions.
Guided journaling / reflection: run adaptive daily reflection sessions that surface patterns, gratitude prompts, and action items.
Decision walkthroughs: work through architectural tradeoffs with a persona that prompts for evaluation criteria and risks.

Project Layout (quick)

mcp-persona-sessions.py — main MCP server entry
timer.py — timer and scheduling helpers
config.yaml — runtime configuration
session_types.yaml — session frameworks
roles/ — persona Markdown files
requirements.txt — dependencies

Contributions are straightforward: add a new persona file under roles/, or append a session definition to session_types.yaml. The server reads these at runtime so you can iterate quickly.

Persona Sessions MCP Server for Coaching and Reflection