Sensei MCP

🚀 Sensei MCP 🥋

Multi-persona engineering mentor with 64 specialized AI personas orchestrating collaborative guidance

🚀 NEW in v0.9.0: Complete Third-Party MCP Integration Suite - Multi-MCP orchestration with 6 integrated MCP servers (Serena, OpenMemory, GitHub, Context7, Tavily, Playwright), 13 workflow templates, and 10 executable demos! Tactical code execution (Sensei → Serena), cross-project memory (OpenMemory), and GitHub-integrated workflows (PR reviews, commit analysis, issue triage). See Integration Guides for complete workflows.

NEW in v0.8.0: Complete Persona Portfolio (64 Personas) - All personas from claude-skills repository now integrated! Added 17 new personas including complete Design & UX team (6), Strategic Expansion skills (5), Critical Infrastructure gaps (5), and Meta-Navigation personas (2).

🌟 MCP Ecosystem Integration: Sensei MCP is designed to work seamlessly with other MCP servers (Context7, Tavily, Playwright, GitHub, OpenMemory, Sequential Thinking) to create a comprehensive CTO co-pilot. See MCP Integration Architecture for the complete vision.

v0.6.0: Granular Persona Content Access (Option B Architecture) - Fixed orchestrator placeholder bug with new content-provider architecture. MCP now provides persona SKILL.md content for Claude to analyze, instead of trying to perform analysis itself. 4 new granular tools for persona discovery, content access, session context, and consultation recording.

v0.5.0: Enhanced Discovery, CI/CD Integration, Team Collaboration & Database Expertise - Interactive demo mode, GitHub Actions/GitLab CI templates, session merging for teams.

v0.4.0: Analytics & Team Collaboration - Track persona effectiveness, export session summaries as ADRs, and share engineering decisions with your team.

Sensei transforms your engineering standards from passive documentation into an active mentor that injects relevant guidelines before Claude reasons, maintaining session memory of architectural decisions.

🚀 Quick Start

Sensei MCP can be installed in multiple ways, depending on your preferred development environment.

One-Click Install

Cursor

``

CLI Install

Claude Code

claude mcp add sensei -- uvx sensei-mcp

Manual Configuration

{
  "mcpServers": {
    "sensei": {
      "command": "uvx",
      "args": ["sensei-mcp"]
    }
  }
}

{
  "mcpServers": {
    "sensei": {
      "command": "uvx",
      "args": ["sensei-mcp"]
    }
  }
}

{
  "mcpServers": {
    "sensei": {
      "command": "uvx",
      "args": ["sensei-mcp"]
    }
  }
}

{
  "mcpServers": {
    "sensei": {
      "command": "uvx",
      "args": ["sensei-mcp"]
    }
  }
}

{
  "context_servers": {
    "sensei": {
      "command": "uvx",
      "args": ["sensei-mcp"]
    }
  }
}

{
  "mcpServers": {
    "sensei": {
      "command": "uvx",
      "args": ["sensei-mcp"]
    }
  }
}

✨ Features

v0.6.0 - Granular Persona Content Access (Option B Architecture) 🎭

• 🔧 Fixed Critical Bug: Orchestrator was returning placeholder text instead of real analysis
• 🏗️ New Architecture: MCP as content provider (not analysis engine)
  • MCP provides persona SKILL.md content
  • Claude (calling LLM) performs analysis using that content
  • Mirrors .claude/skills/ pattern for consistency
• 🛠️ 4 New Granular Tools:
  • get_persona_content() - Returns full SKILL.md for a specific persona
  • suggest_personas_for_query() - Intelligent persona selection with relevance scores
  • get_session_context() - Returns session memory (constraints, decisions, patterns) as JSON
  • record_consultation() - Records consultations after Claude performs analysis
• 📊 Benefits:
  • No LLM needed in MCP (no API keys, no costs, no latency)
  • Claude does what it's best at (analysis)
  • Predictable, deterministic MCP behavior
  • Extensible (just add SKILL.md files)

v0.5.0 - Enhanced Discovery, CI/CD Integration, Team Collaboration & Database Expertise 🚀

• 🔍 Interactive Persona Discovery - Find the right expert faster:
  • Enhanced list_available_skills() with 3 format modes (standard, detailed, quick)
  • CLI demo mode (sensei-mcp --demo) with 5 real-world scenarios
  • Intelligent context hints when <2 personas selected
  • Technology keyword detection (database, api, security, frontend, mobile, ml)
• 🔧 CI/CD Integration Pack - Integrate Sensei into your development workflow:
  • GitHub Actions workflows for PR reviews and architecture checks
  • Pre-commit hooks (consistency, security, cost analysis)
  • GitLab CI pipeline with 3-stage validation
  • Enhanced analyze_changes() with persona suggestions
  • Comprehensive integration guide (500+ lines)
• 🤝 Session Merge & Team Sync - Collaborate on architectural decisions:
  • Merge multiple developer sessions with conflict resolution
  • 4 merge strategies (latest, oldest, all, manual)
  • Session comparison for side-by-side analysis
  • Attribution tracking for all decisions
• 🗄️ Database Architect Persona - Specialized database expert joins the team:
  • Schema design and normalization expertise
  • Query optimization and indexing strategies
  • Migration planning and scalability patterns
  • Multi-tenancy architecture guidance

v0.4.0 - Analytics & Team Collaboration 📊

• 📊 Session Analytics - Data-driven insights into persona usage and decision patterns:
  • Track which personas are most/least used
  • Context distribution (SECURITY, CRISIS, ARCHITECTURAL, etc.)
  • Decision velocity and consultation patterns
  • Time-based filtering (last 7 days, last 30 days, all time)
  • Export as markdown, JSON, or text
• 📄 Consultation Export - Share individual consultations as professional reports:
  • Markdown format with metadata (ID, timestamp, mode, context)
  • JSON format for CI/CD integration
  • Plain text for communication tools
• 📋 Session Summaries - Export comprehensive ADRs (Architecture Decision Records):
  • Full decision history with rationale
  • Active constraints and agreed patterns
  • Recent consultation history
  • Configurable includes (decisions, consultations, constraints, patterns)
  • Perfect for team onboarding and alignment

v0.3.0 - Multi-Persona Orchestrator 🎭

• 🎭 47 Specialized Personas - Skill Orchestrator coordinates expert perspectives across 12 categories:
  • Core (3): Snarky Senior Engineer, Pragmatic Architect, Legacy Archaeologist
  • Specialized (6): API Platform Engineer, Data Engineer, Database Architect, Frontend UX Specialist, ML Pragmatist, Mobile Platform Engineer
  • Operations (3): Site Reliability Engineer, Incident Commander, Observability Engineer
  • Security (2): Security Sentinel, Compliance Guardian
  • Platform (3): DevEx Champion, Platform Builder, QA Automation Engineer
  • Cost (1): FinOps Optimizer
  • Leadership (4): Empathetic Team Lead, Product Engineering Lead, Executive Liaison, Technical Writer
  • DevRel (4): Developer Advocate, Solutions Architect, Staff IC Advisor, Open Source Strategist
  • Strategic (6): M&A Due Diligence, Vendor Management, Technical Recruiting, Engineering Transformation, AI Ethics Governance, Data Strategy
  • Management (3): Engineering Manager, Director of Engineering, VP Engineering
  • Technical Leadership (2): Chief Architect, Principal Engineer
  • Coordination (3): Technical Program Manager, Technical Product Manager, Engineering Operations
  • Infrastructure (6): Database Reliability Engineer, Release Engineering Lead, Performance Engineer, Cloud Architect, Test Engineering Lead, Customer Success Engineer
  • Meta (1): Skill Orchestrator
• 🧠 Context Detection - Intelligently routes queries to relevant personas (CRISIS, SECURITY, POLITICAL, ARCHITECTURAL, COST, TEAM, TECHNICAL)
• 🤝 Collaborative Synthesis - Multiple perspectives with conflict resolution and consensus building
• 📊 Consultation Tracking - Session memory records which personas were consulted and why
• ⚡ Multiple Modes:
  • orchestrated (default): 2-5 persona collaboration
  • quick: Just Snarky Senior Engineer for fast answers
  • crisis: Emergency team (Incident Commander, SRE, Executive Liaison)
  • standards: Legacy single-voice mode for backwards compatibility

Core Features (v0.2.x)

• 🎯 Context-aware loading - Only 5-15% of rulebook per request (87.5% token savings)
• 🧠 Session memory - Remembers architectural decisions across conversations
• 🤝 Team Sync - Share decisions and rules via .sensei folder in your repo
• 🕵️ Git Awareness - Automatically infer context from staged files
• 📦 50+ file types - Comprehensive tech stack coverage
• 🔍 Smart inference - Automatically determines relevant standards
• 🛡️ Consistent enforcement - No more re-litigating patterns
• 🚀 Zero configuration - Works immediately after install
• 🔒 Privacy-first - Runs locally, no external services

📦 Installation

The installation steps are detailed in the "Quick Start" section above.

💻 Usage Examples

Basic Usage

Sensei provides 20 MCP tools (4 new in v0.6.0, 2 in v0.5.0, 3 in v0.4.0, 3 in v0.3.0) + CLI demo mode. Here are some basic usage examples:

v0.6.0 - Granular Persona Content Tools

1. get_persona_content (NEW)

# Get full Security Sentinel content
content = get_persona_content(
  persona_name="security-sentinel",
  include_metadata=True  # Optional: includes description and expertise
)
# Returns: Complete SKILL.md with principles, personality, expertise, guidelines

# Claude then uses this content as context to analyze your query
# Example workflow:
# 1. Claude suggests personas → ["security-sentinel", "api-platform-engineer"]
# 2. Claude gets content for each → Full SKILL.md files
# 3. Claude analyzes from each perspective using the content
# 4. Claude synthesizes all perspectives into recommendation

2. suggest_personas_for_query (NEW)

# Get persona suggestions for a query
suggestions = suggest_personas_for_query(
  query="How should we handle authentication for our API?",
  max_suggestions=5,  # Maximum number of suggestions (default: 5)
  context_hint="SECURITY"  # Optional: force specific context
)
# Returns JSON:
# {
#   "query": "How should we handle authentication...",
#   "detected_context": "SECURITY",
#   "suggestions": [
#     {
#       "name": "security-sentinel",
#       "display_name": "Security Sentinel",
#       "relevance": 0.95,
#       "rationale": "Expert in authentication, security"
#     },
#     {
#       "name": "api-platform-engineer",
#       "display_name": "API Platform Engineer",
#       "relevance": 0.82,
#       "rationale": "Expert in API design, contracts"
#     }
#   ]
# }

# Auto-detect context from query
suggest_personas_for_query(
  query="Our AWS bill is too high",
  max_suggestions=3
)
# Returns: finops-optimizer, pragmatic-architect, site-reliability-engineer

3. get_session_context (NEW)

# Get full session context
context = get_session_context(
  session_id="saas-backend",
  project_root="/path/to/repo"  # Optional: for project-local sessions
)
# Returns JSON:
# {
#   "session_id": "saas-backend",
#   "active_constraints": ["AWS only", "Python 3.11+", "PostgreSQL"],
#   "patterns_agreed": ["Use FastAPI", "JWT auth"],
#   "recent_decisions": [
#     {
#       "id": "dec-001",
#       "category": "architecture",
#       "description": "Use PostgreSQL for primary data store",
#       "rationale": "Team expertise, ACID guarantees",
#       "timestamp": "2025-01-23T10:30:00"
#     }
#   ]
# }

# Claude includes this context when analyzing to ensure consistency

4. record_consultation (NEW)

# After Claude analyzes using persona content
record_consultation(
  query="Should we migrate to microservices?",
  personas_used=["pragmatic-architect", "site-reliability-engineer", "finops-optimizer"],
  session_id="saas-backend",
  project_root="/path/to/repo",  # Optional
  synthesis="[Claude's complete analysis and recommendation]"  # Optional
)
# Returns: "✅ Consultation recorded: consult_42"

# This consultation is now in session history for:
# - Analytics (get_session_insights)
# - Export (export_session_summary)
# - Future context

Advanced Usage

v0.5.0 - Enhanced Discovery & Team Merge

CLI Demo Mode

# Run the interactive demo
sensei-mcp --demo

# Shows 5 real-world scenarios:
# - Architecture Decision (microservices migration)
# - Production Crisis (database outage)
# - Security Review (authentication audit)
# - Cost Optimization (cloud spending)
# - Code Quality (technical debt)

5. merge_sessions

# Merge two developer sessions
merge_sessions(
  session_ids=["alice-frontend", "bob-backend"],
  target_session_id="sprint-23",
  conflict_strategy="latest",  # "latest", "oldest", "all", "manual"
  session_id="sprint-23",
  project_root="/path/to/repo"
)
# Returns: MergeResult with decisions merged, conflicts detected, attribution tracking

# Manual conflict resolution
merge_sessions(
  session_ids=["alice-session", "bob-session"],
  target_session_id="team-session",
  conflict_strategy="manual"  # Returns conflicts for human resolution
)

6. compare_sessions

compare_sessions(
  session_a_id="alice-session",
  session_b_id="bob-session",
  session_id="default",
  project_root="/path/to/repo"
)
# Returns: Markdown comparison with decisions, constraints, patterns diff

📚 Documentation

Getting Started

• Quick Start Guide - 5-minute fast start
• Usage Guide - Comprehensive usage examples

MCP Ecosystem Integration (NEW)

• MCP Integration Architecture - Complete vision for human-LLM partnership
• MCP Integration Examples - Real-world workflows combining multiple MCP servers
• CI/CD Integration Guide - GitHub Actions, GitLab CI, pre-commit hooks

Technical Documentation

• Architecture Deep Dive - Technical implementation details
• Contributing Guide - How to contribute
• Publishing Guide - PyPI publishing workflow

🔧 Technical Details

How It Works

1. Context Inference Engine analyzes:
   • File patterns (API routes, DB schemas, tests, etc.)
   • Operation type (CREATE, REFACTOR, DEBUG, etc.)
   • Keywords (tenant, payment, async, etc.)
2. Rulebook Loader extracts relevant sections:
   • 57 total sections mapped to 32 file patterns
   • Core sections always loaded (principles, philosophy)
   • Task-specific sections loaded on demand
3. Session Manager persists decisions:
   • Stored in $HOME/.sensei/sessions/<project>.json
   • Human-readable JSON format
   • Loaded automatically on each tool call

File Pattern Examples

📄 License

Apache 2.0 - See LICENSE for details