Skip to main content
Glama

Sensei MCP πŸ₯‹

PyPI

Python

License

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.

🀝 Human-LLM Partnership (The Killer Insight)

Human provides: Domain expertise, judgment, context, business constraints, strategic direction

LLM provides: Synthesis across 64 expert personas, pattern matching against 32,000 lines of wisdom, consistency checking, real-time intelligence

Together: CTO-level decisions at code-writing speed with multi-perspective analysis and no weak links


πŸš€ Quick Install

One-Click Install

Cursor

<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">

CLI Install

Claude Code

claude mcp add sensei -- uvx sensei-mcp

Manual Configuration

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

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

Restart Claude Desktop after saving.

Add to your Windsurf MCP config:

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

Restart Windsurf after saving.

  1. Install Cline extension

  2. Open Cline sidebar β†’ MCP Servers icon β†’ Configure MCP Servers

  3. Add:

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

Restart VS Code after saving.

  1. Install Roo Code extension

  2. Configure MCP servers through Roo Code settings

  3. Add:

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

Restart VS Code after saving.

Note: Requires Zed Preview version

Add to Zed's context servers config:

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

Restart Zed after saving.

  1. Install an MCP extension from VS Code marketplace

  2. Configure MCP servers in extension settings

  3. Add:

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

Restart VS Code after saving.


Related MCP server: Mimir

🎯 What is Sensei?

The Problem: Output styles and custom instructions are cosmeticβ€”applied AFTER Claude has already reasoned.

The Solution: Sensei injects engineering standards BEFORE reasoning based on:

  • 50+ file types (Python, JS/TS, Go, Java, Kotlin, Swift, Rust, GraphQL, Docker, k8s, etc.)

  • Operation context (CREATE, REFACTOR, DEBUG, SECURITY, etc.)

  • Keywords (multi-tenant, payment, async, etc.)

  • Session memory of architectural decisions

Result: Standards actually influence behavior, not just formatting.

Why This Matters

Output Styles (Cosmetic):

User: "Write an API endpoint"
Claude: [reasons about design]
Claude: [writes code]
Output Style: [formats the response]  ← Too late!

Sensei MCP (Active):

User: "Write an API endpoint"
Sensei: [injects API contracts, security, multi-tenancy standards]
Claude: [reasons WITH standards in context]
Claude: [writes code that follows standards]

⚑ Key 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


πŸ“š Supported File Types

Programming Languages (20+)

Python, JavaScript, TypeScript, Go, Java, Kotlin, Swift, Ruby, Rust, PHP, C#, Scala, C/C++, Dart, Elixir, Clojure, Elm, Julia, R

Frontend & Web

React (JSX/TSX), Vue, Svelte, Astro, HTML, CSS, SCSS, SASS, LESS

Infrastructure & DevOps

Terraform, Docker, Kubernetes, nginx, Apache, Shell scripts (bash/zsh), Makefiles, HCL

Data & APIs

SQL, Prisma, GraphQL, Protobuf, Avro, CSV, XML, Jupyter notebooks

Config & Tools

YAML, JSON, TOML, ESLint, Prettier, Jest, Playwright, Cypress, Webpack, Vite, tsconfig.json

CI/CD

GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines

Mobile

Android (AndroidManifest.xml, build.gradle), iOS (Info.plist, Podfile)

Package Managers

package.json, Gemfile, Cargo.toml, go.mod, requirements.txt, Pipfile

Monitoring

Prometheus, Grafana, Datadog, New Relic, Sentry


πŸ› οΈ Usage

πŸ“– NEW: Complete Usage Guide with Real-World Examples

See detailed use cases including API design review, production crisis response, cost optimization, code review, and session-aware architecture decisions.

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:

NEW v0.6.0 - Granular Persona Content Tools

1. get_persona_content (NEW)

Get full SKILL.md content for a specific persona. Claude uses this content to analyze queries from that persona's perspective.

# 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)

Intelligent persona selection based on query analysis with relevance scores and rationale.

# 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 session memory (constraints, decisions, patterns) as JSON for context-aware analysis.

# 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)

Record consultations in session history after Claude performs analysis.

# 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

v0.5.0 - Enhanced Discovery & Team Merge

CLI Demo Mode

Interactive walkthrough of Sensei's multi-persona capabilities.

# 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 multiple developer sessions with intelligent conflict resolution.

# 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 two sessions side-by-side before merging.

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

v0.4.0 Tools - Analytics & Collaboration

7. get_session_insights

Get data-driven insights into persona usage, consultation patterns, and decision velocity.

# Get insights for last 7 days
get_session_insights(
  session_id="saas-backend",
  time_range="last_7_days",  # "last_7_days", "last_30_days", "all_time"
  format="markdown",  # "markdown", "json", "text"
  min_consultations=2  # Only include personas with 2+ consultations
)
# Returns: Most/least used personas, context distribution, decision metrics

# Get JSON for CI/CD integration
get_session_insights(
  session_id="saas-backend",
  format="json"
)

8. export_consultation

Export a single consultation as a shareable report.

# Export as markdown with full metadata
export_consultation(
  consultation_id="c-2025-01-22-001",
  session_id="saas-backend",
  format="markdown",  # "markdown", "json", "text"
  include_metadata=True
)
# Returns: Professional report with query, personas consulted, synthesis, linked decision

# Export as JSON for API integration
export_consultation(
  consultation_id="c-2025-01-22-001",
  format="json"
)

9. export_session_summary

Export comprehensive ADRs and session summaries for team sharing.

# Full session export with all sections
export_session_summary(
  session_id="saas-backend",
  format="markdown",  # "markdown", "json", "text"
  include=["decisions", "consultations", "constraints", "patterns"],
  max_consultations=10
)
# Returns: ADRs, consultation history, constraints, patterns in markdown

# Export only decisions as JSON
export_session_summary(
  session_id="saas-backend",
  format="json",
  include=["decisions"]
)

v0.3.0 Tools - Multi-Persona Orchestrator

Note: get_engineering_guidance() and consult_skill() will be deprecated in v0.7.0. Use the new v0.6.0 granular tools instead (get_persona_content, suggest_personas_for_query, get_session_context, record_consultation).

10. get_engineering_guidance

Get collaborative multi-persona guidance on any engineering question.

# Example: Architecture decision
get_engineering_guidance(
  query="Should we use microservices or a monolith for our SaaS app?",
  mode="orchestrated",  # default: auto-selects 2-5 relevant personas
  session_id="saas-backend",
  output_format="standard"
)
# Returns: Synthesis from Pragmatic Architect, Snarky Senior Engineer,
#          Product Engineering Lead with consensus and tensions

# Quick mode - fast answer from just Snarky
get_engineering_guidance(
  query="How do I fix this API bug?",
  mode="quick"  # Only Snarky Senior Engineer responds
)

# Crisis mode - emergency team
get_engineering_guidance(
  query="Production database is down!",
  mode="crisis"  # Incident Commander, SRE, Executive Liaison
)

# Request specific personas
get_engineering_guidance(
  query="How do we reduce our AWS bill?",
  specific_personas=["finops-optimizer", "pragmatic-architect"]
)

11. consult_skill

Consult a single persona directly for targeted expertise.

consult_skill(
  skill_name="security-sentinel",
  query="Review this authentication implementation for vulnerabilities",
  session_id="saas-backend"
)

12. list_available_skills

Discover all 64 available personas organized by category.

# List all personas (standard format)
list_available_skills()

# Detailed format with examples and metadata
list_available_skills(format="detailed")

# Quick format (names only)
list_available_skills(format="quick")

# List by category
list_available_skills(category="operations")  # SRE, Incident Commander, etc.
list_available_skills(category="specialized")  # Security, FinOps, Database Architect, etc.

Core Tools (v0.2.x) - Still Supported

13. get_engineering_context (Legacy)

Smart context injection - loads relevant standards based on files and operation.

Note: In v0.3.0, this is now called via get_engineering_guidance(..., mode="standards") for backwards compatibility.

# Example: Working on payment API
get_engineering_context(
  operation="CREATE",
  file_paths=["api/payments.py"],
  description="Building Stripe payment endpoint",
  session_id="saas-backend"
)
# Returns: API contracts, security, multi-tenancy, idempotency standards

14. record_decision

Save architectural decisions to prevent re-litigation.

record_decision(
  category="architecture",
  description="Use PostgreSQL for primary data store",
  rationale="Team expertise, ACID guarantees, proven at scale",
  session_id="saas-backend"
)

15. validate_against_standards

Pre-implementation validation check.

validate_against_standards(
  design_description="REST API with JWT auth",
  focus_areas=["security", "multi-tenant"],
  session_id="saas-backend"
)

16. get_session_summary

Review all decisions and constraints for current project.

get_session_summary(session_id="saas-backend")

17. list_sessions

Manage multiple projects with separate session states.

list_sessions()

18. query_specific_standard

Direct access to specific rulebook sections.

query_specific_standard(
  section_name="multi_tenancy",
  session_id="saas-backend"
)

19. check_consistency

Validate proposed changes against past decisions.

check_consistency(
  proposed_change="Switch from Postgres to MongoDB",
  session_id="saas-backend"
)

20. analyze_changes

Automatically infer context from staged git changes (enhanced in v0.5.0 with persona suggestions).

analyze_changes(project_root="/path/to/repo")
# Returns: File changes, diff stats, and suggested personas based on file patterns

🀝 Team Sync & Project Isolation

Sensei supports sharing decisions and rules with your team:

  1. Create a .sensei folder in your project root.

  2. Add rules.md for custom project-specific rules.

  3. Run tools with project_root: Decisions will be saved to .sensei/decisions.md.

This allows you to commit your engineering memory to Git!


πŸ—οΈ 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

File Type

Triggers

Example Files

API Files

API contracts, security, multi-tenancy

api/billing.py, routes/users.ts

Database

Data persistence, security, multi-tenancy

migrations/001.sql, schema.prisma

Tests

Testing standards, code quality

test_api.py, api.spec.ts

Infrastructure

Cloud platform, compliance, cost

main.tf, docker-compose.yml, k8s/*.yaml

CI/CD

Delivery, testing, observability

.github/workflows/*.yml, Jenkinsfile

Frontend

Performance, i18n, security (XSS)

App.tsx, index.html, styles.css

Mobile

Cloud, dependencies, compliance

AndroidManifest.xml, Podfile


πŸ’‘ Example Workflows

Architecture Decision (v0.3.0 Multi-Persona)

# 1. Get multi-persona guidance on architecture
result = get_engineering_guidance(
  query="Should we migrate from a monolith to microservices? We have 5 engineers and 10K users.",
  mode="orchestrated",  # Auto-selects relevant personas
  session_id="saas-backend"
)
# Personas consulted: Pragmatic Architect, Snarky Senior Engineer, Product Engineering Lead
# Synthesis includes: Consensus points, tensions/trade-offs, recommendation

# 2. Consult specific expert for follow-up
consult_skill(
  skill_name="finops-optimizer",
  query="What's the cost impact of microservices vs monolith?",
  session_id="saas-backend"
)

# 3. Record the decision
record_decision(
  category="architecture",
  description="Stay monolith for now, plan modular architecture",
  rationale="Team size and user scale don't justify microservices complexity yet",
  session_id="saas-backend"
)

Production Incident (Crisis Mode)

# Crisis mode activates emergency response team
get_engineering_guidance(
  query="Production database has 10K connections and is timing out!",
  mode="crisis",  # Incident Commander, SRE, Executive Liaison
  session_id="saas-backend"
)
# Returns: Immediate triage steps, communication plan, root cause analysis

Starting a New Feature (v0.2.x Legacy Mode)

# 1. Get context for the feature (legacy standards mode)
get_engineering_context(
  operation="CREATE",
  file_paths=["api/webhooks.py"],
  description="Stripe webhook handler for subscription events",
  session_id="saas-backend"
)

# 2. Record key decisions
record_decision(
  category="architecture",
  description="Use idempotent webhook processing with deduplication",
  rationale="Webhooks can be retried, need to handle duplicates safely",
  session_id="saas-backend"
)

# 3. Validate before implementation
validate_against_standards(
  design_description="POST /webhooks/stripe with signature verification",
  focus_areas=["security", "api"],
  session_id="saas-backend"
)

Code Review

# Load relevant standards for review
get_engineering_context(
  operation="REVIEW",
  file_paths=["api/users.py", "db/queries.sql"],
  description="User management PR - check multi-tenancy",
  session_id="saas-backend"
)

# Check consistency with past decisions
check_consistency(
  proposed_change="Add user_id index without tenant_id",
  session_id="saas-backend"
)

Debugging Production Issue

# Get observability and debugging context
get_engineering_context(
  operation="DEBUG",
  file_paths=["services/payment_processor.py"],
  description="Investigating payment timeout issues",
  session_id="saas-backend"
)

# Query specific standards
query_specific_standard(
  section_name="observability",
  session_id="saas-backend"
)

πŸ“– Documentation

Getting Started

MCP Ecosystem Integration (NEW)

Technical Documentation


πŸ”§ Development

Local Setup

git clone https://github.com/amarodeabreu/sensei-mcp.git
cd sensei-mcp
pip install -e .

Run Tests

pytest tests/

Code Formatting

black src/ tests/
isort src/ tests/

🀝 Contributing

Contributions welcome! See CONTRIBUTING.md for:

  • Development setup

  • Running tests

  • Code style guidelines

  • PR submission process


πŸ“Š Comparison: Before & After

Before Sensei

❌ Output styles applied after reasoning ❌ Repeating same context every conversation ❌ Re-litigating architectural decisions ❌ Forgetting past constraints ❌ Loading entire rulebook (40% of tokens)

After Sensei

βœ… Standards influence reasoning before code is written βœ… Context-aware loading (5-15% of rulebook) βœ… Session memory persists decisions βœ… Consistent enforcement across conversations βœ… Multi-project support with isolation


πŸ† ROI Calculation

Team of 5 engineers:

  • 10 mins/day saved per engineer avoiding re-explanation

  • 5 architectural re-litigations prevented/week

  • 30 mins/incident saved with better observability

Annual Savings: ~500 hours of engineering time


πŸ“„ License

Apache 2.0 - See LICENSE for details



πŸ™ Acknowledgments


Made with πŸ₯‹ by amarodeabreu

Available Tools

25 tools
analyze_changesB

Analyze staged git changes to identify relevant engineering contexts (v0.5.0 enhanced).

Args: project_root: Absolute path to the project root include_diff_stats: Include line change statistics (additions/deletions) suggest_personas: Suggest relevant personas based on change context

Returns: Summary of changed files, contexts, and recommended personas for review

Inputs: project_root (required), suggest_personas, include_diff_stats. Returns: result

check_consistencyB

Check if a proposed change is consistent with session decisions and constraints.

Inputs: proposed_change (required), session_id, project_root. Returns: result

compare_sessionsA

Compare two sessions and return differences (v0.5.0).

Useful for understanding what decisions and patterns differ between two developer sessions or team branches before merging.

Args: session_a_id: First session ID session_b_id: Second session ID project_root: Optional project root for local sessions

Returns: Formatted comparison showing unique and shared items

Examples: # Compare two developer sessions compare_sessions( session_a_id="alice-session", session_b_id="bob-session" )

# Compare feature branches
compare_sessions(
    session_a_id="feature-auth",
    session_b_id="feature-payments"
)

Inputs: session_a_id (required), session_b_id (required), project_root. Returns: result

consult_skillA

Consult a single skill persona directly.

⚠️ DEPRECATION NOTICE (v0.6.0): This tool will be deprecated in v0.7.0. Please use get_persona_content() instead:

  • get_persona_content(persona_name=skill_name) - Get full SKILL.md content Then Claude performs the analysis using that content as context.

Use this when you want guidance from a specific expert without orchestration.

Args: skill_name: Persona name (e.g., "snarky-senior-engineer", "security-sentinel") query: Your question session_id: Session identifier project_root: Absolute path to project root

Returns: The persona's perspective

Available Personas: Core: snarky-senior-engineer, pragmatic-architect, legacy-archaeologist Specialized: api-platform-engineer, data-engineer, frontend-ux-specialist, ml-pragmatist, mobile-platform-engineer Operations: site-reliability-engineer, incident-commander, observability-engineer Security: security-sentinel, compliance-guardian Platform: devex-champion, platform-builder, qa-automation-engineer Cost: finops-optimizer Leadership: empathetic-team-lead, product-engineering-lead, executive-liaison, technical-writer Meta: skill-orchestrator

Inputs: query (required), skill_name (required), session_id, project_root. Returns: result

export_consultationA

Export a single consultation as shareable report.

Perfect for sharing specific decision-making discussions with your team, documenting why you chose a particular approach, or creating ADRs.

Args: consultation_id: Consultation ID (e.g., "consult_1") session_id: Session identifier project_root: Absolute path to project root format: Output format ("markdown", "json", "text")

Returns: Formatted consultation report

Examples: # Export as markdown export_consultation( consultation_id="consult_5", session_id="my-project" )

# Export as JSON for CI/CD
export_consultation(
    consultation_id="consult_5",
    format="json"
)

Inputs: consultation_id (required), format, session_id, project_root. Returns: result

export_session_summaryA

Export comprehensive session summary for team sharing.

Generates Architecture Decision Records (ADRs), consultation history, and active constraints/patterns. Perfect for:

  • Onboarding new team members

  • Documenting architectural decisions

  • Sharing team knowledge

  • Creating weekly/monthly reports

Args: session_id: Session identifier project_root: Absolute path to project root format: Output format ("markdown", "json", "text") include: Components to include (default: all) - "decisions": Architecture decisions - "consultations": Consultation history - "constraints": Active constraints - "patterns": Agreed patterns max_consultations: Max recent consultations to include (default: 10)

Returns: Comprehensive session summary report

Examples: # Full summary export_session_summary(session_id="my-project")

# Just decisions and constraints
export_session_summary(
    session_id="my-project",
    include=["decisions", "constraints"]
)

# JSON export for processing
export_session_summary(
    session_id="my-project",
    format="json"
)

Inputs: format, include, session_id, project_root, +1 more. Returns: result

get_engineering_contextA

Get relevant Sensei engineering context for the current task.

Args: operation: What you're doing (e.g., "reviewing API endpoints") file_paths: List of file paths involved description: Additional context about the task session_id: Session identifier project_root: Absolute path to the project root (for local rules/sessions)

Returns: Markdown-formatted engineering standards relevant to this task

Inputs: operation, file_paths, session_id, description, +1 more. Returns: result

get_engineering_guidanceA

Get engineering guidance via multi-persona orchestration (DEFAULT in v0.3.0).

⚠️ DEPRECATION NOTICE (v0.6.0): This tool will be deprecated in v0.7.0. Please use the new granular tools instead:

  • suggest_personas_for_query() - Get persona suggestions

  • get_persona_content() - Get persona SKILL.md content

  • get_session_context() - Get session memory

  • record_consultation() - Record consultation after analysis

The new architecture provides content for Claude to analyze, rather than trying to perform analysis within the MCP server.

This is the NEW primary tool for getting engineering guidance. The Skill Orchestrator coordinates 21 specialized personas to provide holistic, multi-perspective analysis of your engineering questions.

Args: query: Your question or scenario mode: Analysis mode: - "orchestrated" (DEFAULT): Multi-persona analysis with intelligent selection - "quick": Single persona (Snarky Senior Engineer) for fast answers - "crisis": Emergency team (Incident Commander, SRE, Executive) - "standards": Legacy mode (engineering standards only, no personas) session_id: Session identifier project_root: Absolute path to project root (for local rules/sessions) specific_personas: Override auto-selection (e.g., ["security-sentinel", "pragmatic-architect"]) output_format: Response format ("brief", "standard", "executive")

Returns: Orchestrated multi-perspective guidance with synthesis and recommendations

Examples: # Auto-orchestrated (DEFAULT) get_engineering_guidance( query="Should we migrate to microservices?", session_id="saas-backend" )

# Crisis mode
get_engineering_guidance(
    query="Production database is down",
    mode="crisis"
)

# Specific personas
get_engineering_guidance(
    query="Review this payment API design",
    specific_personas=["security-sentinel", "api-platform-engineer"]
)

Inputs: query (required), mode, session_id, project_root, +2 more. Returns: result

get_mcp_workflow_templateA

Get a pre-built multi-MCP workflow template.

Returns step-by-step workflow definitions for common scenarios, with optional parameter substitution for customization.

Args: template_name: Workflow template name Available templates: - "auth-security-review": Comprehensive auth security review - "performance-debug": Performance debugging workflow - "cost-optimization": Cloud cost analysis - "tech-due-diligence": Technology evaluation - "incident-postmortem": Incident analysis - "accessibility-audit": WCAG compliance check - "api-design-review": API design review

parameters: Optional dict of parameters to substitute
    Example: {
        "user_query": "Review FastAPI auth",
        "app_url": "https://app.example.com",
        "framework": "FastAPI"
    }

Returns: JSON with workflow steps, required MCPs, personas, and estimates

Example: # Get auth security review workflow get_mcp_workflow_template( template_name="auth-security-review", parameters={ "user_query": "Review authentication implementation", "app_url": "https://app.example.com/login", "framework": "FastAPI" } )

Inputs: template_name (required), parameters. Returns: result

get_persona_contentA

Get full skill content for a specific persona.

This returns the complete SKILL.md content that defines the persona's expertise, principles, personality, and guidelines. The calling LLM should use this content to analyze queries from that persona's perspective.

MCP Design Philosophy: This tool returns CONTENT for the LLM to use, not pre-generated analysis. The calling LLM (Claude) receives the persona content and performs the analysis itself.

Args: persona_name: Name of persona (e.g., "security-sentinel", "pragmatic-architect") include_metadata: Include metadata header (name, description, expertise)

Returns: Full persona skill content (markdown format)

Example: # Get Security Sentinel's content content = get_persona_content("security-sentinel")

# Claude then uses this content to analyze from that perspective

Inputs: persona_name (required), include_metadata. Returns: result

get_session_contextA

Get session context (constraints, decisions, patterns) for context-aware analysis.

Returns session memory that can be included when asking personas to analyze queries. This ensures consistency with previous decisions and agreed patterns.

MCP Design Philosophy: This tool returns session memory as data. The LLM includes this context when analyzing queries to ensure consistency with previous decisions.

Args: session_id: Session identifier project_root: Optional project root for local sessions

Returns: JSON with session constraints, patterns, and recent decisions

Example: # Get session context context = get_session_context(session_id="my-project")

# LLM includes this when asking persona to analyze:
# "Given these constraints: ..., analyze this query"

Inputs: session_id, project_root. Returns: result

get_session_insightsA

Get comprehensive analytics and insights for a session.

Provides data-driven insights into persona usage patterns, consultation frequency, decision-making trends, and session health metrics.

Args: session_id: Session identifier project_root: Absolute path to project root (for local sessions) time_range: Analysis window: - "all_time" (default): All consultations - "last_7_days": Last 7 days - "last_30_days": Last 30 days format: Output format ("markdown", "json", "text")

Returns: Formatted analytics report with: - Persona usage statistics (most/least used) - Context distribution (CRISIS, SECURITY, etc.) - Mode usage (orchestrated, quick, crisis, standards) - Decision metrics and velocity - Session health indicators

Examples: # Get all-time insights get_session_insights(session_id="my-project")

# Last 30 days in JSON
get_session_insights(
    session_id="my-project",
    time_range="last_30_days",
    format="json"
)

Inputs: format, session_id, time_range, project_root. Returns: result

get_session_summaryC

Get a summary of the current session's decisions and context.

Args: session_id: Session identifier project_root: Absolute path to the project root

Returns: Summary of session state

Inputs: session_id, project_root. Returns: result

list_available_skillsA

List all available skill personas with flexible detail levels.

Args: category: Optional filter (core, specialized, operations, security, platform, cost, leadership, meta) format: Output format: - "standard" (default): Name, description, and expertise areas - "detailed": Adds example queries, use cases, and related personas - "quick": One-line quick tips for each persona

Returns: Formatted list of available personas

Examples: # Standard list list_available_skills()

# Detailed format with examples
list_available_skills(format="detailed")

# Quick reference
list_available_skills(format="quick")

# Specific category
list_available_skills(category="operations", format="detailed")

Inputs: format, category. Returns: result

list_demosA

List all available demonstration workflows.

Returns a summary of executable demos that showcase multi-MCP orchestration capabilities.

Returns: JSON array of available demos with descriptions and example parameters

Example: # List all demos list_demos()

# Returns: 4 demos (auth-review, performance-debug, cost-analysis, api-review)

Inputs: no named parameters. Returns: result

list_mcp_workflow_templatesA

List all available multi-MCP workflow templates.

Returns a summary of pre-built workflows with their descriptions, required MCPs, cost estimates, and time estimates.

Returns: JSON array of available workflow templates

Example: # List all templates list_mcp_workflow_templates()

# Returns: 7 templates (auth-security-review, performance-debug, etc.)

Inputs: no named parameters. Returns: result

list_sessionsA

List all available sessions in the global directory. (Note: Does not list local project sessions)

Inputs: no named parameters. Returns: result

merge_sessionsA

Merge multiple sessions into a single target session (v0.5.0).

Enables teams to combine session insights from multiple developers, resolving conflicts and tracking attribution.

Args: session_ids: List of session IDs to merge (e.g., ["dev1-session", "dev2-session"]) target_session_id: ID for the merged session (e.g., "team-session") conflict_strategy: How to resolve conflicts: - "latest" (default): Use most recent timestamp - "oldest": Use oldest timestamp - "all": Keep all variants (creates numbered versions) - "manual": Return conflicts for manual resolution project_root: Optional project root for local sessions

Returns: Formatted merge result with statistics and conflicts

Examples: # Merge two developer sessions merge_sessions( session_ids=["alice-frontend", "bob-backend"], target_session_id="sprint-23", conflict_strategy="latest" )

# Merge with manual conflict resolution
merge_sessions(
    session_ids=["team-a", "team-b"],
    target_session_id="combined",
    conflict_strategy="manual"
)

# Keep all decision variants
merge_sessions(
    session_ids=["experiment-1", "experiment-2"],
    target_session_id="final",
    conflict_strategy="all"
)

Inputs: session_ids (required), target_session_id (required), project_root, conflict_strategy. Returns: result

query_specific_standardA

Query a specific section of the rulebook directly by name.

Inputs: section_name (required), session_id, project_root. Returns: result

record_consultationA

Record a consultation in session history.

After Claude analyzes a query using persona content, record the consultation for session analytics and history.

Args: query: The original query personas_used: List of persona names that were consulted session_id: Session identifier project_root: Optional project root synthesis: Optional synthesis/recommendation from Claude

Returns: Confirmation with consultation ID

Example: # After Claude analyzes using persona content: record_consultation( query="Should we migrate to microservices?", personas_used=["pragmatic-architect", "site-reliability-engineer"], synthesis="[Claude's full analysis and recommendation]" )

Inputs: query (required), personas_used (required), synthesis, session_id, +1 more. Returns: result

record_decisionA

Record an architectural or technical decision for this session.

Args: category: Type of decision ("architecture", "pattern", "constraint", "standard") description: Brief description of the decision rationale: Why this decision was made session_id: Session identifier constraint: Optional constraint to add to active constraints pattern: Optional pattern to add to agreed patterns project_root: Absolute path to the project root

Returns: Confirmation message with decision ID

Inputs: category (required), rationale (required), description (required), pattern, +3 more. Returns: result

run_demoA

Execute a demonstration workflow that showcases multi-MCP orchestration.

Runs a self-contained demo that combines Sensei + external MCPs (Context7, Tavily, Playwright) in realistic workflows. Perfect for:

  • Testing multi-MCP coordination

  • Generating example documentation

  • Demonstrating Sensei capabilities

  • Training and onboarding

Args: demo_type: Type of demo to run Available demos: - "auth-review": Authentication security review (Sensei + Context7 + Tavily + Playwright) - "performance-debug": Performance debugging (Sensei + Playwright + Context7) - "cost-analysis": Cloud cost optimization (Sensei + Tavily) - "api-review": API design review (Sensei + Context7 + Tavily)

custom_params: Optional custom parameters to override defaults
    Example for auth-review: {
        "user_query": "Review FastAPI authentication",
        "app_url": "https://myapp.com/login",
        "framework": "FastAPI"
    }

output_format: Output format ("markdown", "json", "text")

Returns: Comprehensive demo execution report showing: - Workflow steps and MCP coordination - Example findings from multi-MCP synthesis - Expected output structure - How to run the demo yourself

Examples: # Run auth security review demo with defaults run_demo(demo_type="auth-review")

# Run with custom parameters
run_demo(
    demo_type="auth-review",
    custom_params={
        "user_query": "Review OAuth implementation",
        "framework": "Django"
    }
)

# Get JSON output
run_demo(demo_type="performance-debug", output_format="json")

Inputs: demo_type (required), custom_params, output_format. Returns: result

suggest_mcps_for_queryA

Suggest which MCP servers to use for a given query.

Analyzes the query and recommends which MCP servers (Context7, Tavily, Playwright, etc.) would be most helpful, along with pre-built workflow templates if available.

Args: query: The user's query context: Detected query context (default: "GENERAL") Options: SECURITY, COST, CRISIS, ARCHITECTURAL, TECHNICAL, etc. user_mcps: Optional list of MCPs to filter suggestions (e.g., ["context7", "tavily"])

Returns: JSON with suggested MCPs, rationale, matching workflows, and cost/time estimates

Example: # Get MCP suggestions suggest_mcps_for_query( query="Review authentication for security issues", context="SECURITY" )

# Returns: sensei + context7 (OWASP docs) + tavily (CVEs) + playwright (live inspection)

Inputs: query (required), context, user_mcps. Returns: result

suggest_personas_for_queryA

Suggest relevant personas for a given query using intelligent selection.

Uses keyword matching, context detection, and relevance scoring to recommend which personas would be most helpful for the query.

MCP Design Philosophy: This tool helps the LLM discover which personas to consult, but doesn't perform analysis itself. The LLM uses the suggestions to call get_persona_content() for each recommended persona.

Args: query: The user's question or scenario max_suggestions: Maximum number of personas to suggest (default: 5) context_hint: Optional context hint to improve suggestions (e.g., "crisis", "security", "architectural")

Returns: JSON list of suggested personas with relevance scores and rationale

Example: # Get suggestions for a query suggestions = suggest_personas_for_query( query="How should we handle user authentication?", max_suggestions=3 )

# Returns JSON with suggested personas and why they're relevant
# LLM then calls get_persona_content() for each suggestion

Inputs: query (required), context_hint, max_suggestions. Returns: result

validate_against_standardsB

Validate code or design against Sensei engineering standards.

Args: code_snippet: Code to validate (optional) design_description: Design/architecture to validate (optional) focus_areas: Specific areas to check session_id: Session identifier project_root: Absolute path to the project root

Returns: Structured validation report

Inputs: session_id, focus_areas, code_snippet, project_root, +1 more. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 25 tools

    Disambiguation2/5

    Multiple tools overlap in purpose, particularly the deprecated get_engineering_guidance vs the new granular tools (suggest_personas_for_query, get_persona_content, record_consultation), making it unclear which path to use. Similarly, get_session_summary and export_session_summary both return session summaries, and get_session_context overlaps with session summary functions, creating ambiguity for agents.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case (e.g., get_engineering_guidance, record_decision, list_available_skills). The verbs are clear and varied appropriately, making the naming predictable and easy to learn.

    Tool Count3/5

    With 25 tools, this server is at the high end of acceptable scope. While most tools serve a distinct resource, several are redundant or could be consolidated (e.g., list_mcp_workflow_templates and list_demos, or get_session_summary and export_session_summary). The count feels heavy, especially given the transitional deprecations.

    Completeness4/5

    The toolset covers the core domain of engineering guidance, sessions, personas, standards, and MCP workflows comprehensively. However, there are minor gaps such as no delete/update operations for sessions or consultations, and the deprecated tools add confusion rather than a true missing capability. Overall, the surface is nearly complete for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Transforms Claude into a production-grade pair programmer by orchestrating best-in-class APIs (Morph, Chroma, DSPy) for iterative code evolution to 95%+ quality, semantic codebase search, package discovery across 3,000+ libraries, and pattern learning.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      A self-evolving engineering playbook system that provides AI assistants with structured access to development methodologies, workflows, and best practices. Enables generation of work plans, progress tracking, and continuous process improvement through AI-proposed playbook updates.
      16
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude to consult over 17 AI platforms and 800,000+ models to provide alternative perspectives, code reviews, and diverse feedback. It features a unique personality system and supports multi-AI group discussions and debates directly within the chat interface.
      46
      MIT