Sensei MCP
Enables GitHub-integrated workflows including PR reviews, commit analysis, and issue triage.
Enables CI/CD integration with GitHub Actions workflows for PR reviews and architecture checks.
Enables CI/CD integration with GitLab CI pipelines for multi-stage validation.
Enables pre-commit hooks for consistency, security, and cost analysis.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Sensei MCP Review my pull request for security vulnerabilities"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
π€ 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-mcpManual 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.
Install Cline extension
Open Cline sidebar β MCP Servers icon β Configure MCP Servers
Add:
{
"mcpServers": {
"sensei": {
"command": "uvx",
"args": ["sensei-mcp"]
}
}
}Restart VS Code after saving.
Install Roo Code extension
Configure MCP servers through Roo Code settings
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.
Install an MCP extension from VS Code marketplace
Configure MCP servers in extension settings
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 personasuggest_personas_for_query()- Intelligent persona selection with relevance scoresget_session_context()- Returns session memory (constraints, decisions, patterns) as JSONrecord_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 scenariosIntelligent 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 suggestionsComprehensive 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 collaborationquick: Just Snarky Senior Engineer for fast answerscrisis: 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
.senseifolder 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 recommendation2. 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-engineer3. 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 consistency4. 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 contextv0.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 diffv0.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()andconsult_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 standards14. 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:
Create a
.senseifolder in your project root.Add
rules.mdfor custom project-specific rules.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
Context Inference Engine analyzes:
File patterns (API routes, DB schemas, tests, etc.)
Operation type (CREATE, REFACTOR, DEBUG, etc.)
Keywords (tenant, payment, async, etc.)
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
Session Manager persists decisions:
Stored in
$HOME/.sensei/sessions/<project>.jsonHuman-readable JSON format
Loaded automatically on each tool call
File Pattern Examples
File Type | Triggers | Example Files |
API Files | API contracts, security, multi-tenancy |
|
Database | Data persistence, security, multi-tenancy |
|
Tests | Testing standards, code quality |
|
Infrastructure | Cloud platform, compliance, cost |
|
CI/CD | Delivery, testing, observability |
|
Frontend | Performance, i18n, security (XSS) |
|
Mobile | Cloud, dependencies, compliance |
|
π‘ 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 analysisStarting 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
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
π§ 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
π Links
π Acknowledgments
Built with FastMCP
Powered by Model Context Protocol
Inspired by the need for consistent engineering standards
Made with π₯ by amarodeabreu
Available Tools
25 toolsanalyze_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
Scored across 25 tools
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.
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.
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.
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
Related MCP Connectors
AI personas with a lasting, encrypted memory per project, for Claude Code. Hosted in France.
Agent personas for Claude. 16 tools, 13 personas, 3 workflows. Zero extra API cost. Free.
Multi-brand AI code review for Claude: up to 12 reviewers and a judge, no install.
Claude Code / MCP skills for the dev pipeline: discover, spec, design, build, ship, operate.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceTransforms 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.-
- AlicenseNot gradedqualityAmaintenanceA 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.16Apache 2.0
- FlicenseNot gradedqualityNot gradedmaintenanceAutomatically injects development framework context and workflows into Claude conversations, ensuring Claude follows your established patterns without manual context provision each time. Supports custom frameworks, keyword triggers, and Knowledge Graph integration.-
- AlicenseNot gradedqualityCmaintenanceEnables 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.46MIT