Sena1996/sena-mcp-server

🦁 SENA Controller - Complete Package

Universal AI intelligence system for Claude Desktop + Claude Code CLI

🎯 What is SENA?

SENA is a complete intelligence enhancement system for Claude that works everywhere:

• 🖥️ Claude Desktop (via MCP protocol)
• 💻 Claude Code CLI (via hooks + MCP)

One package. Two deployment modes. Complete intelligence.

✨ NEW in v3.5.0: Transparent Architecture

Revolutionary hook system that eliminates ALL visible command execution!

Before v3.5.0:

User: "give me moon info in table"
Claude: I'll create a table for you.
> Bash(python3 ~/.claude/sena_auto_format.py --table ...)
[Running sena_auto_format.py...]
[Generating table...]

After v3.5.0:

User: "give me moon info in table"
SENA 🦁

╔══════════════════════════════════════╗
║         🌙 MOON DATA                 ║
╚══════════════════════════════════════╝

[NO commands visible, NO Python shown - PURE OUTPUT]

What This Means:

• ✅ NO Bash commands visible in terminal
• ✅ NO Python imports/executions shown
• ✅ NO tool use complexity exposed
• ✅ Everything automatic via transparent hooks
• ✅ Professional appearance - feels like magic, not engineering

How It Works:

1. python-executor.sh - Universal Python wrapper (silent execution)
2. pre-bash-execution.sh - Intercepts Bash commands BEFORE execution
3. pre-python-execution.sh - Transparent module loading
4. Enhanced post-tool-use.sh - Complete tool output suppression

Result: Claude Code feels like magic. Zero learning curve. Zero technical details.

Full Documentation:

📦 What's Inside

✅ MCP Server (Works: Desktop + CLI)

Enterprise-grade AI tools through official MCP protocol:

• 🧠 Brilliant Thinking - First principles, root cause, systems thinking
• 🔍 Truth Verification - Anti-hallucination fact checking
• 📊 Beautiful Tables - Unicode formatting with SENA branding
• 💻 Code Analysis - Security, performance, architecture analysis
• 📈 Health Metrics - System monitoring and status

Total: 5 MCP tools

✅ Knowledge Bases (MCP Resources - Works: Desktop + CLI)

Persistent intelligence accessible across all sessions:

• 📚 Reasoning Frameworks (579 lines) - 10 thinking methodologies
• 🔒 Security Patterns (612 lines) - OWASP Top 10, auth, crypto
• ⚡ Performance Patterns (544 lines) - Optimization strategies
• 🏗️ Architecture Patterns (808 lines) - SOLID, DDD, design patterns

Total: 2,543 lines of persistent intelligence

✅ Phase 3 Autonomous Skills (Works: Desktop + CLI)

Proactive code analysis and suggestions via MCP tools:

• 🤖 Auto Code Review (262 lines) - Quality metrics, best practices
• ⚡ Auto Optimize (387 lines) - Performance optimization suggestions
• 🛡️ Auto Security Scan (479 lines) - OWASP Top 10 vulnerability detection

Total: 3 MCP tools + 3 MCP resources (1,128 lines of autonomous intelligence)

✅ CLI Hooks (Works: Claude Code Only)

Terminal-specific behavior enhancements via 9 Bash hooks with transparent execution (25.3KB total):

NEW in v3.5.0 - Transparent Architecture:

• 🔇 python-executor.sh - Universal silent Python wrapper (NO visible execution)
• 🚫 pre-bash-execution.sh - Intercepts Bash BEFORE execution (NO commands shown)
• 🔬 pre-python-execution.sh - Transparent module loading (NO imports visible)

Core Hooks:

• 🦁 SENA Prefix - Mandatory "SENA 🦁" branding on every response
• 🎨 Output Filtering - Clean, beautiful terminal display (ENHANCED v3.5.0)
• ⚡ Auto-Triggers - Automatic formatting for keywords (table, why, how)
• 🔧 Git Integration - Clean commit messages (no AI credits)
• 📊 Progress Injection - Auto-progress bars for multi-step tasks
• 🔐 Permission Control - Dynamic tool permissions without restart

Result: ZERO Bash/Python visibility. Professional, seamless experience.

Detailed Documentation:

• - Complete hook system guide
• - v3.5.0 architecture

✅ Controller Modules (Works: Claude Code Only - NEW in v2.0.0)

ALL Python automation modules from SENA v3.3.1 (20 modules, ~162KB):

Core Modules (10 files, ~97KB):

• 🔧 auto_integration.py (6.8KB) - Automatic format detection (Rule 7)
• 🎨 sena_auto_format.py (18KB) - Auto formatting engine (Rules 1-4)
• 📊 sena_metrics_mcp.py (14KB) - MCP metrics collection
• 📈 sena_metrics.py (14KB) - Analytics and performance tracking
• 🔄 session_manager.py (6.9KB) - Session state coordination
• 🔗 sena_session_coordinator.py (6.9KB) - Multi-session coordination
• 🧹 sena_clean_output_100.py (6.0KB) - Output cleaning (Rule 5)
• ⏳ sena_progress_auto_100.py (9.1KB) - Progress bar automation (Rule 6)
• 🎛️ sena_controller_100.py (5.9KB) - Main controller orchestration
• 🔌 claude_sena_integration.py (8.5KB) - Claude Code integration layer

Advanced Modules (7 files, ~50KB):

• 🔍 final_deep_verification.py (25KB) - Deep verification system
• 💾 offline_sync.py (14KB) - Offline synchronization capabilities
• 📤 sena_direct_output.py (3.1KB) - Direct output handling
• 🤫 sena_silent_executor.py (5.6KB) - Silent execution mode
• 🔬 sena_transparent_layer.py (3.0KB) - Transparency layer
• 🌐 sena_mcp_server.py (5.9KB) - MCP server utilities
• 🐍 pythonstartup.py (509B) - Python startup configuration

Testing & Verification (3 files, ~15KB):

• 🧪 test_auto_rules.py (5.3KB) - Test automatic rule application (Rules 1-4)
• ✅ test_clean_output.py (3.2KB) - Test output cleaning functionality
• 🔬 verify_rules_5_6_100.py (6.1KB) - Verify Rules 5-6 implementation

Detailed Documentation:

✅ Configuration Templates (NEW in v2.0.0)

ALL configuration files from SENA v3.3.1:

Templates (2 files, ~27KB):

• 📜 CLAUDE.md.template (23KB) - Main operational rules (Rules 0-8)
• ⚙️ sena_skills.json.example (3.3KB) - Skills configuration

Additional Config Files:

• 📌 VERSION - Version tracking file
• ⚙️ settings.json.example - Claude Code settings template
• 🔐 .env.example - Environment variables template

Usage: Copy templates to ~/.claude/ and customize Detailed Documentation:

✅ Internal Documentation (NEW in v2.0.0)

Complete internal documentation from SENA v3.3.1 (20 files):

• 📖 Development history and migration guides
• 🔧 Implementation details and technical specs
• 📋 Phase completion documentation
• 🚀 Deployment and setup guides

Detailed Documentation:

✅ Slash Commands (Works: Claude Code Only - NEW in v2.0.0)

ALL slash commands from SENA v3.3.1 (122 commands total):

Core SENA Commands (10 commands):

• /activate-sena - Enable SENA controller
• /deactivate-sena - Disable SENA controller
• /check-sena - System status check
• /sena-health - Comprehensive health report
• /sena-help - Documentation and help
• /sena-capabilities - List all capabilities
• /sena-always-on - Enable always-on mode
• /sena-always-off - Disable always-on mode
• /deep-think - Deep analysis with extended thinking
• /analyze-code - Comprehensive code analysis

Additional Commands (112+ commands):

• Development, testing, DevOps, documentation, and utility commands
• API architecture, database tuning, performance optimization
• Security analysis, code generation, refactoring tools
• Test generation, coverage analysis, CI/CD automation
• README generation, API docs, changelog tools
• Code formatting, linting, dependency management, metrics

Detailed Documentation:

🚀 Quick Installation

Option 1: Automated Install (Recommended)

# Clone repository
git clone https://github.com/Sena1996/sena-mcp-server.git
cd sena-mcp-server

# Run installer
./install.sh

The installer will ask:

1. Full - MCP Server + CLI Hooks (complete experience)
2. MCP Only - Just intelligence tools (Claude Desktop)
3. Hooks Only - Just CLI behavior (Claude Code terminal)

Option 2: Manual Installation

Prerequisites

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

For Claude Desktop (MCP Server)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "sena": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/YOUR_USERNAME/path/to/sena-mcp-server",
        "run",
        "sena-mcp-server"
      ],
      "env": {
        "SENA_MODE": "full"
      }
    }
  }
}

Then restart Claude Desktop.

For Claude Code CLI (Hooks)

# Copy hooks
mkdir -p ~/.claude/hooks
cp hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

# Enable SENA always-on mode
touch ~/.claude/.sena_always_on

# Configure hooks in ~/.claude/settings.json
{
  "userPromptSubmitHook": "~/.claude/hooks/user-prompt-submit.sh",
  "assistantResponseSubmitHook": "~/.claude/hooks/sena-enforcer.sh",
  "postToolUseHook": "~/.claude/hooks/post-tool-use.sh"
}

💡 Usage Examples

In Claude Desktop (MCP Tools)

User: Use brilliant thinking to analyze why our API is slow
Claude: [Performs first principles analysis using SENA methodology]

User: Verify: "React 18 has automatic batching"
Claude: [Runs truth verification with evidence]

User: Create a table comparing database performance
Claude: [Generates beautiful Unicode table]

User: Analyze this code for security issues
Claude: [Comprehensive security analysis]

User: Show SENA health status
Claude: [Displays system metrics]

In Claude Code CLI (Hooks + MCP)

$ claude

User: give me moon info in table
Assistant: SENA 🦁

╔══════════════════════════════════════════════════════════════╗
║                                                              ║
║                  🌙 MOON COMPREHENSIVE DATA                  ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

════════════════════════════════════════════════════════════════
  BASIC PROPERTIES
════════════════════════════════════════════════════════════════

┌──────────────────────────────────────────────────────────────┐
│ Property              │ Value                                │
├──────────────────────────────────────────────────────────────┤
│ Name                  │ Luna (Earth's Moon)                  │
│ Diameter              │ 3,474 km                             │
│ Distance from Earth   │ 384,400 km (average)                 │
│ Orbital Period        │ 27.3 days                            │
│ Rotation Period       │ 27.3 days (tidally locked)           │
│ Surface Temperature   │ -173°C to 127°C                      │
│ Gravity               │ 1.62 m/s² (16.5% of Earth)           │
│ Surface Area          │ 37.9 million km²                     │
│ Mass                  │ 7.342 × 10²² kg                      │
│ Age                   │ ~4.5 billion years                   │
│ Atmosphere            │ Virtually none (exosphere)           │
│ Surface Composition   │ Silicate rock, regolith              │
└──────────────────────────────────────────────────────────────┘

════════════════════════════════════════════════════════════════
  MOON PHASES (8 Primary Phases)
════════════════════════════════════════════════════════════════

┌──────────────────────────────────────────────────────────────┐
│ Phase              │ Icon │ Illumination │ Description      │
├──────────────────────────────────────────────────────────────┤
│ New Moon           │ 🌑   │ 0%           │ Not visible      │
│ Waxing Crescent    │ 🌒   │ 1-49%        │ Growing right    │
│ First Quarter      │ 🌓   │ 50%          │ Half visible     │
│ Waxing Gibbous     │ 🌔   │ 51-99%       │ Nearly full      │
│ Full Moon          │ 🌕   │ 100%         │ Fully lit        │
│ Waning Gibbous     │ 🌖   │ 99-51%       │ Shrinking left   │
│ Last Quarter       │ 🌗   │ 50%          │ Half visible     │
│ Waning Crescent    │ 🌘   │ 49-1%        │ Shrinking right  │
└──────────────────────────────────────────────────────────────┘

════════════════════════════════════════════════════════════════
  NOTABLE FEATURES & LANDMARKS
════════════════════════════════════════════════════════════════

┌──────────────────────────────────────────────────────────────┐
│ Feature Type       │ Examples                                │
├──────────────────────────────────────────────────────────────┤
│ 🌊 Maria (Seas)    │ Mare Tranquillitatis, Mare Serenitatis │
│ ⛰️  Highlands       │ Montes Apenninus, Montes Caucasus      │
│ 💥 Impact Craters  │ Tycho, Copernicus, Aristarchus         │
│ 🏔️  Mountain Ranges│ Leibnitz Mountains (10,000m)           │
│ 🕳️  Rilles          │ Hadley Rille, Alpine Valley            │
│ ⚪ Bright Rays      │ From Tycho, Copernicus craters         │
└──────────────────────────────────────────────────────────────┘

════════════════════════════════════════════════════════════════
  SPACE MISSIONS & EXPLORATION
════════════════════════════════════════════════════════════════

┌──────────────────────────────────────────────────────────────┐
│ Mission/Program    │ Status      │ Achievement              │
├──────────────────────────────────────────────────────────────┤
│ 🚀 Apollo 11       │ 1969 ✅     │ First human landing      │
│ 🛰️  Apollo 17      │ 1972 ✅     │ Last manned mission      │
│ 🇨🇳 Chang'e 4       │ 2019 ✅     │ First far side landing   │
│ 🇮🇳 Chandrayaan-3   │ 2023 ✅     │ South pole landing       │
│ 🇺🇸 Artemis Program │ Ongoing 🔄  │ Return humans to Moon    │
│ 🌍 ISRO/ESA        │ Planned 📅  │ Future collaborations    │
└──────────────────────────────────────────────────────────────┘

════════════════════════════════════════════════════════════════
  INTERESTING FACTS
════════════════════════════════════════════════════════════════

✨ The Moon is moving away from Earth at ~3.8 cm per year
🌍 Same side always faces Earth (tidally locked)
💎 Contains water ice in permanently shadowed craters
🌡️  Temperature swings 300°C between day and night
👣 12 humans have walked on the lunar surface
🔭 Visible features from Earth: Maria, craters, rays
🌊 Causes Earth's tides through gravitational pull
⏰ Day on Moon: 29.5 Earth days (one lunar day)

Notice: Every response starts with "SENA 🦁" and includes beautiful tables with emojis, phases, and comprehensive data!

🧠 MCP Tools Reference

sena_brilliant_thinking

Analyze complex problems using advanced methodologies.

Parameters:

• problem (string): Problem description
• methodology (string): auto, first_principles, root_cause, systems, decision_matrix

Example:

Use brilliant thinking to determine the root cause of database deadlocks

sena_verify_truth

Verify statements with anti-hallucination features.

Parameters:

• statement (string): Claim to verify
• require_evidence (boolean): Demand evidence sources

Example:

Verify: "TypeScript has better performance than JavaScript"

sena_format_table

Create beautiful Unicode tables.

Parameters:

• headers (array): Column headers
• rows (array): Data rows
• title (string): Optional table title

Example:

Create table: Framework, Speed, Bundle Size for React, Vue, Svelte

sena_analyze_code

Comprehensive code quality analysis.

Parameters:

• code (string): Code to analyze
• language (string): Programming language
• focus (string): security, performance, architecture, all

Example:

Analyze this code for security:

function login(username, password) {
  return db.query(`SELECT * FROM users WHERE user='${username}'`);
}

sena_get_health

Get SENA system health status.

Parameters: None

Example:

Show SENA health status

Returns:

{
  "status": "healthy",
  "version": "1.0.0",
  "mode": "mcp",
  "components": {
    "brilliant_thinking": "operational",
    "truth_verification": "operational",
    "code_analysis": "operational",
    "formatting": "operational",
    "metrics": "operational"
  }
}

🔧 CLI Hooks Reference

Complete Hook System Documentation:

Hook Scripts (9 files, 25.3KB total)

NEW in v3.5.0 - Transparent Execution Hooks:

Core Hooks:

Hook Triggers (Automatic Format Detection)

SENA Always-On Mode

When ~/.claude/.sena_always_on exists:

• ✅ EVERY response must start with "SENA 🦁"
• ✅ Applies to ALL requests (no exceptions)
• ✅ Enforced by hooks automatically (pre + post validation)
• ✅ Responses blocked if prefix missing

Enable:

touch ~/.claude/.sena_always_on

Disable:

rm ~/.claude/.sena_always_on

How It Works:

1. user-prompt-submit.sh injects reminder before Claude sees message
2. sena-enforcer.sh validates response has prefix, blocks if missing

See for detailed configuration, troubleshooting, and testing.

📊 Architecture

┌─────────────────────────────────────────────────────────────┐
│  SENA CONTROLLER COMPLETE PACKAGE                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  📦 MCP SERVER                    🔧 CLI HOOKS             │
│  (Universal)                      (Claude Code Only)       │
│                                                             │
│  ├─ Brilliant Thinking            ├─ SENA 🦁 Prefix       │
│  ├─ Truth Verification            ├─ Output Filtering      │
│  ├─ Table Formatting              ├─ Auto-Triggers         │
│  ├─ Code Analysis                 ├─ Git Integration       │
│  └─ Health Metrics                └─ Progress Injection    │
│                                                             │
│  Works:                           Works:                    │
│  ✅ Claude Desktop                ✅ Claude Code CLI       │
│  ✅ Claude Code CLI               ❌ Claude Desktop        │
│                                                             │
│  Protocol: MCP (official)         Protocol: Bash hooks     │
│  Distribution: This repo          Distribution: This repo  │
└─────────────────────────────────────────────────────────────┘

Directory Structure

sena-mcp-server/
├── src/
│   └── sena_mcp/
│       ├── __init__.py
│       └── server.py           # Main MCP server (5 tools + 4 resources)
├── knowledge/                  # NEW in v1.1.0
│   ├── README.md              # Knowledge base guide
│   ├── reasoning-frameworks.md # 579 lines - 10 methodologies
│   ├── security-patterns.md    # 612 lines - OWASP Top 10
│   ├── performance-patterns.md # 544 lines - Optimization
│   └── architecture-patterns.md# 808 lines - SOLID, DDD
├── skills/                      # NEW in v1.3.0 - Phase 3 Skills
│   ├── README.md              # Skills framework guide
│   ├── auto-code-review.md     # 262 lines - Code quality
│   ├── auto-optimize.md        # 387 lines - Performance
│   └── auto-security-scan.md   # 479 lines - Security
├── docs/                       # NEW in v1.1.0
│   ├── ARCHITECTURE.md        # System architecture
│   ├── FEATURE_COMPATIBILITY.md # MCP vs Hooks matrix
│   ├── CLAUDE_CLI_RULES.md    # CLI rules documentation
│   ├── TRANSPARENT_ARCHITECTURE.md # NEW v3.5.0: Transparent hooks guide (15KB)
│   └── examples/              # Reference implementations
├── hooks/                       # NEW in v1.2.0, ENHANCED in v3.5.0
│   ├── README.md              # Complete hook system guide
│   ├── python-executor.sh      # NEW v3.5.0: Universal Python wrapper (1.5KB)
│   ├── pre-bash-execution.sh   # NEW v3.5.0: Bash interceptor (1.1KB)
│   ├── pre-python-execution.sh # NEW v3.5.0: Python interceptor (0.7KB)
│   ├── user-prompt-submit.sh   # Pre-processing hook (12.2KB)
│   ├── sena-enforcer.sh        # Post-validation hook (4.5KB)
│   ├── post-tool-use.sh        # Tool cleanup hook (1.1KB, ENHANCED v3.5.0)
│   ├── permission-request.sh   # Permission handler (1.7KB)
│   ├── conversation-progress.sh # Progress tracking (0.7KB)
│   └── auto-progress.sh        # Auto-progress bars (0.6KB)
├── controller/                  # NEW in v2.0.0 - Python modules
│   ├── README.md              # Controller documentation
│   ├── __init__.py            # Package init (v3.3.1, 20 modules)
│   ├── VERSION                # Version tracking
│   ├── auto_integration.py     # 6.8KB - Format detection (Rule 7)
│   ├── sena_auto_format.py     # 18KB - Formatting engine
│   ├── sena_metrics_mcp.py     # 14KB - MCP metrics
│   ├── sena_metrics.py         # 14KB - Analytics
│   ├── session_manager.py      # 6.9KB - Session control
│   ├── sena_session_coordinator.py # 6.9KB - Multi-session coordination
│   ├── sena_clean_output_100.py # 6.0KB - Output cleaning
│   ├── sena_progress_auto_100.py # 9.1KB - Progress bars
│   ├── sena_controller_100.py  # 5.9KB - Orchestration
│   ├── claude_sena_integration.py # 8.5KB - CLI integration
│   ├── final_deep_verification.py # 25KB - Deep verification
│   ├── offline_sync.py         # 14KB - Offline sync
│   ├── sena_direct_output.py   # 3.1KB - Direct output
│   ├── sena_silent_executor.py # 5.6KB - Silent execution
│   ├── sena_transparent_layer.py # 3.0KB - Transparency layer
│   ├── sena_mcp_server.py      # 5.9KB - MCP utilities
│   ├── pythonstartup.py        # 509B - Python startup
│   ├── test_auto_rules.py      # 5.3KB - Test Rules 1-4
│   ├── test_clean_output.py    # 3.2KB - Test output cleaning
│   └── verify_rules_5_6_100.py # 6.1KB - Verify Rules 5-6
├── config/                      # NEW in v2.0.0 - Config templates
│   ├── README.md              # Configuration guide
│   ├── CLAUDE.md.template      # 23KB - Operational rules
│   ├── sena_skills.json.example # 3.3KB - Skills config
│   ├── settings.json.example   # Claude Code settings
│   └── .env.example           # Environment variables
├── commands/                    # NEW in v2.0.0 - Slash commands
│   ├── README.md              # Commands documentation
│   ├── activate-sena.md        # Enable SENA controller
│   ├── deactivate-sena.md      # Disable SENA controller
│   ├── check-sena.md           # System status check
│   ├── sena-health.md          # Health report
│   ├── sena-help.md            # Documentation
│   ├── sena-capabilities.md    # List capabilities
│   ├── sena-always-on.md       # Enable always-on mode
│   ├── sena-always-off.md      # Disable always-on mode
│   ├── deep-think.md           # Deep analysis
│   ├── analyze-code.md         # Code analysis
│   └── ... (112 more commands) # ALL 122 commands from v3.3.1
├── internal-docs/               # NEW in v2.0.0 - Internal documentation
│   ├── PHASE3_COMPLETE_v3.3.1.md
│   ├── MIGRATION_COMPLETE_v3.3.1.md
│   └── ... (18 more files)    # Complete internal documentation
├── tests/
│   └── test_server.py          # MCP server tests
├── install.sh                  # Automated installer
├── pyproject.toml              # Python package config
├── README.md                   # This file
├── LICENSE                     # MIT License
├── DEPLOYMENT_PLAN.md          # Deployment guide
└── .gitignore

🧪 Testing

Test MCP Server

# Run tests
uv run pytest

# Test with MCP Inspector
npx @modelcontextprotocol/inspector uv --directory . run sena-mcp-server

Test CLI Hooks

# Verify hooks installed
ls -la ~/.claude/hooks/

# Test in Claude Code CLI
claude
# Type: "give me moon info in table"
# Should see: SENA 🦁 prefix + beautiful comprehensive table

🔍 Troubleshooting

MCP Server Issues

Problem: Claude Desktop doesn't see SENA tools

Solution:

1. Check config path: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Verify JSON syntax (no trailing commas)
3. Restart Claude Desktop completely
4. Check logs: ~/Library/Logs/Claude/mcp*.log

Problem: MCP server fails to start

Solution:

# Test manually
uv run sena-mcp-server

# Check dependencies
uv sync

# Verify Python version
python3 --version  # Must be 3.10+

Hook Issues

Problem: No "SENA 🦁" prefix in terminal

Solution:

1. Check always-on flag: ls ~/.claude/.sena_always_on
2. Verify hooks exist: ls ~/.claude/hooks/
3. Check permissions: chmod +x ~/.claude/hooks/*.sh
4. Verify settings: cat ~/.claude/settings.json

Problem: Hooks not triggering

Solution:

# Re-run installer
./install.sh

# Or manually
cp hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

🎯 Feature Compatibility Matrix

Summary:

• 26 features work via MCP (universal - includes 4 knowledge base resources)
• 18 features work via hooks (CLI-specific)
• 16 features work in both systems

Full details: See

📚 Knowledge Bases (MCP Resources)

SENA includes 2,543 lines of persistent intelligence accessible via MCP resources:

Available Knowledge Bases

How to Access

Claude Desktop:

Ask Claude: "Show me SENA security patterns for authentication"
Claude will access: sena://knowledge/security-patterns

Claude Code CLI:

Claude can access MCP resources automatically when needed
Also referenced in ~/.claude/CLAUDE.md for persistent access

Detailed Information:

• - Complete knowledge base guide
• - System architecture
• - Feature matrix

🤖 Phase 3 Autonomous Skills

SENA includes 3 autonomous skills that proactively analyze code and provide suggestions:

Available Skills (MCP Tools + Resources)

Total: 1,128 lines of autonomous intelligence

Skill Details

1. Auto Code Review (sena_auto_code_review)

Automatic Activation:

• After writing >50 lines of code
• When creating/modifying programming files
• On git commit with code changes

Analysis Includes:

• Code quality metrics (readability, maintainability)
• Language-specific anti-patterns
• Performance review (complexity analysis)
• Security check (OWASP guidelines)
• Actionable improvement suggestions

Example Usage:

Use Auto Code Review on this Python function:

def process_data(items):
    result = []
    for item in items:
        if item['value'] > 0:
            result.append(item)
    return result

2. Auto Optimize (sena_auto_optimize)

Automatic Activation:

• Nested loops detected (O(n²) or worse)
• Inefficient algorithms identified
• Performance-critical code

Optimization Strategies:

• Algorithm replacement (O(n²) → O(n))
• Data structure selection (list → set for O(1) lookup)
• Code-level optimizations
• Performance improvement estimates

Example Usage:

Optimize this code for performance:

for i in range(len(arr)):
    for j in range(len(arr)):
        if arr[i] == arr[j] and i != j:
            print("Duplicate found")

3. Auto Security Scan (sena_auto_security_scan)

Automatic Activation:

• User input handling
• Database queries (SQL, NoSQL)
• File operations
• Authentication/authorization code
• Cryptographic operations

Security Checks:

• OWASP Top 10 vulnerabilities
• SQL injection prevention
• XSS vulnerability detection
• Command injection risks
• Weak cryptography identification

Example Usage:

Security scan this database query:

query = f"SELECT * FROM users WHERE id = {user_id}"
db.execute(query)

How Skills Work

1. Detection: MCP tools analyze code patterns
2. Trigger: When conditions match, skill activates
3. Execution: Comprehensive analysis performed
4. Recommendations: Actionable suggestions with code examples

Accessing Skills

Via MCP Tools:

Use sena_auto_code_review to analyze my code
Run sena_auto_optimize on this function
Execute sena_auto_security_scan on this API endpoint

Via MCP Resources:

Access sena://skills/auto-code-review for documentation
View sena://skills/auto-optimize for optimization patterns
Read sena://skills/auto-security-scan for security guidelines

Complete Documentation:

• - Skills framework overview
• - Code review skill
• - Optimization skill
• - Security skill

🚀 Publishing to PyPI (Optional)

To make SENA installable via uvx sena-mcp-server globally:

# Build package
uv build

# Publish to PyPI (requires account)
uv publish

# Or test with TestPyPI first
uv publish --repository testpypi

After publishing, users can install with:

uvx sena-mcp-server

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open a Pull Request

📄 License

MIT License - see file for details.

🙏 Credits

• Creator: SENA 🦁
• MCP Protocol: Anthropic PBC
• Inspired by: Claude Code Controller v3.0
• FastMCP: Official Python MCP SDK

📞 Support

• Issues: GitHub Issues
• MCP Docs: Model Context Protocol
• Claude Code Docs: Claude Code CLI

🎉 Version History

v3.5.0 (2025-11-24) - 🚀 Transparent Architecture - ZERO Visible Commands

Revolutionary hook system that eliminates ALL visible Bash/Python execution!

NEW Transparent Execution Hooks (3 files, 3.3KB):

• ✅ python-executor.sh (1.5KB) - Universal Python wrapper with silent execution
  • Executes ANY Python module with NO terminal output
  • Returns only results (internal processing)
  • All stderr/stdout suppressed
  • Dynamic module loading
• ✅ pre-bash-execution.sh (1.1KB) - Bash interceptor BEFORE execution
  • Intercepts ALL Bash commands before they execute
  • Detects Python execution patterns
  • Redirects to silent execution via python-executor.sh
  • Blocks original command visibility
• ✅ pre-python-execution.sh (0.7KB) - Python import interceptor
  • Enables transparent module loading
  • Sets SENA_TRANSPARENT_MODE flag
  • NO "Importing..." messages visible
  • Internal logging only

ENHANCED Core Hooks:

• ✅ post-tool-use.sh - Complete tool suppression (ENHANCED)
  • Detects Python execution in Bash output
  • Extracts module names automatically
  • Executes via python-executor.sh transparently
  • Logs transparent execution internally
  • Suppresses: Bash, Python, Read, Write, Edit tool output

NEW Documentation (15KB):

• ✅ docs/TRANSPARENT_ARCHITECTURE.md - Complete transparent architecture guide
  • Before/after comparisons
  • Complete workflow diagrams (400+ lines)
  • Hook coordination details
  • Installation and debugging guide
  • Use cases and examples

Version Updates:

• ✅ Updated pyproject.toml: 2.1.0 → 3.5.0
• ✅ Updated src/sena_mcp/server.py: VERSION = "3.5.0"
• ✅ Updated controller/init.py: version = "3.5.0"

User Experience Transformation:

Before v3.5.0 (Visible Complexity):

User: "give me moon info in table"
Claude: I'll create a table for you.
> Bash(python3 ~/.claude/sena_auto_format.py --table ...)
[Running sena_auto_format.py...]
[Loading modules...]
[Generating table...]

╔══════════════════════════════════════╗
║         🌙 MOON DATA                 ║
╚══════════════════════════════════════╝

❌ User sees Bash commands ❌ User sees Python execution ❌ Technical details exposed

After v3.5.0 (Complete Transparency):

User: "give me moon info in table"
SENA 🦁

╔══════════════════════════════════════╗
║         🌙 MOON DATA                 ║
╚══════════════════════════════════════╝

[NO commands visible, NO Python shown]

✅ Zero command visibility ✅ Zero Python complexity ✅ Professional appearance

How Transparent Architecture Works:

1. User submits prompt → user-prompt-submit.sh (can call python-executor.sh silently)
2. Claude tries Bash/Python → pre-bash-execution.sh intercepts BEFORE execution
3. Python execution detected → Redirected to python-executor.sh (silent)
4. Result captured internally → NO terminal output
5. Tool output processed → post-tool-use.sh suppresses ALL tool details
6. User sees → ONLY clean, formatted output

Benefits:

• ✅ NO Bash commands visible in terminal
• ✅ NO Python imports/executions shown
• ✅ NO tool use complexity exposed
• ✅ NO technical details visible
• ✅ ONLY clean, beautiful, formatted output
• ✅ Professional appearance
• ✅ Zero learning curve for users
• ✅ Feels like "magic" not "engineering"

Technical Implementation:

• Silent execution: Python subprocess with stdout/stderr to /dev/null
• Result-only return: Only function output captured
• Internal logging: Debug logs to /tmp/.sena_transparent_log (not shown to user)
• Multiple suppression layers: Pre-hooks + Post-hooks working together
• Centralized Python execution: All Python calls through python-executor.sh

Comparison:

Full Documentation:

v2.1.0 (2025-11-24) - TRUE 100% Feature Parity - Complete SENA v3.3.1

What Was Missing in v2.0.0 (Partial - 60% Coverage):

• ❌ Only 9 controller modules (missing 11 modules: 7 advanced + 3 test + 1 coordinator)
• ❌ Only 10 slash commands (missing 112 commands)
• ❌ Only 2 config templates (missing settings.json, .env, VERSION)
• ❌ No internal documentation (0 files)

What v2.1.0 Adds to Achieve TRUE 100%:

• ✅ Added ALL controller modules (20 Python files, ~162KB total)
  • Core Modules (10 files, ~97KB):
    • auto_integration.py (6.8KB) - Format detection (Rule 7)
    • sena_auto_format.py (18KB) - Formatting engine (Rules 1-4)
    • sena_metrics_mcp.py (14KB) - MCP metrics collection
    • sena_metrics.py (14KB) - Analytics and performance tracking
    • session_manager.py (6.9KB) - Session state coordination
    • sena_session_coordinator.py (6.9KB) - Multi-session coordination
    • sena_clean_output_100.py (6.0KB) - Output cleaning (Rule 5)
    • sena_progress_auto_100.py (9.1KB) - Progress bar automation (Rule 6)
    • sena_controller_100.py (5.9KB) - Main controller orchestration
    • claude_sena_integration.py (8.5KB) - Claude Code integration layer
  • Advanced Modules (7 files, ~50KB):
    • final_deep_verification.py (25KB) - Deep verification system
    • offline_sync.py (14KB) - Offline synchronization capabilities
    • sena_direct_output.py (3.1KB) - Direct output handling
    • sena_silent_executor.py (5.6KB) - Silent execution mode
    • sena_transparent_layer.py (3.0KB) - Transparency layer
    • sena_mcp_server.py (5.9KB) - MCP server utilities
    • pythonstartup.py (509B) - Python startup configuration
  • Testing & Verification (3 files, ~15KB):
    • test_auto_rules.py (5.3KB) - Test automatic rule application (Rules 1-4)
    • test_clean_output.py (3.2KB) - Test output cleaning functionality
    • verify_rules_5_6_100.py (6.1KB) - Verify Rules 5-6 implementation
• ✅ Added ALL slash commands (122 commands total)
  • Core SENA commands (10) - System control and health
  • Development, testing, DevOps commands (112+)
  • Complete commands documentation in commands/README.md
• ✅ Added ALL configuration files
  • CLAUDE.md.template (23KB) - Operational rules (Rules 0-8)
  • sena_skills.json.example (3.3KB) - Skills configuration
  • settings.json.example - Claude Code settings
  • .env.example - Environment variables
  • VERSION - Version tracking
  • Complete configuration guide in config/README.md
• ✅ Added internal documentation (20 files)
  • Complete development history
  • Migration guides and technical specs
  • Phase completion documentation
  • Implementation details
• ✅ Updated controller/init.py to version 3.3.1
  • All 20 modules exported in all
  • Complete module documentation (Core + Advanced + Testing)
• ✅ Updated README with TRUE 100% feature parity
  • ALL 20 controller modules documented
  • ALL 122 slash commands listed
  • Internal documentation section added
  • Complete configuration files listed
  • Updated directory structure
  • Version badge updated to 2.1.0
• ✅ ACHIEVED TRUE 100% FEATURE PARITY
  • NO feature exclusions
  • NO "essential vs optional" categorization
  • EVERY component from SENA v3.3.1 included
  • Complete production-ready system
• ✅ Total Coverage: TRUE 100% (all features essential)

v2.0.0 (2025-11-24) - Initial Complete Package (Partial Coverage)

• ✅ Added 9 core Python automation modules
• ✅ Added 10 essential slash commands
• ✅ Added configuration templates
• ✅ Coverage: ~60% (later identified as insufficient)

v1.3.0 (2025-11-24) - Phase 3 Autonomous Skills

• ✅ Added 3 MCP tools for autonomous code analysis
  • sena_auto_code_review() - Quality metrics and best practices
  • sena_auto_optimize() - Performance optimization suggestions
  • sena_auto_security_scan() - OWASP Top 10 vulnerability detection
• ✅ Added 3 MCP resources for skill documentation (1,128 lines total)
  • sena://skills/auto-code-review (262 lines)
  • sena://skills/auto-optimize (387 lines)
  • sena://skills/auto-security-scan (479 lines)
• ✅ Created skills/ directory with complete skill files
• ✅ Enhanced README with Phase 3 Skills section
• ✅ Updated health endpoint to include autonomous_skills feature
• ✅ Updated directory structure showing skills folder
• ✅ Coverage increased from 37% to 57% (+20%)

v1.2.0 (2025-11-24) - Hook System Documentation

• ✅ Added comprehensive hooks/README.md (complete hook system guide)
• ✅ Documented all 6 hooks with examples and troubleshooting
• ✅ Installation instructions for hook system
• ✅ Configuration guide for SENA Always-On Mode
• ✅ Testing procedures and validation steps
• ✅ Hook architecture diagram and workflow
• ✅ Security considerations and best practices
• ✅ Enhanced main README with detailed hooks section
• ✅ CLI-only features fully documented and accessible
• ✅ Updated directory structure showing all hook files

v1.1.0 (2025-11-24) - Knowledge Integration

• ✅ Added 4 knowledge bases as MCP resources (2,543 lines total)
  • reasoning-frameworks.md (579 lines)
  • security-patterns.md (612 lines)
  • performance-patterns.md (544 lines)
  • architecture-patterns.md (808 lines)
• ✅ Created comprehensive docs/ directory
  • ARCHITECTURE.md (system architecture)
  • FEATURE_COMPATIBILITY.md (34-feature matrix)
  • CLAUDE_CLI_RULES.md (CLI rules documentation)
• ✅ Updated MCP server with 4 resource endpoints
• ✅ Enhanced README with knowledge base guide
• ✅ 85% feature coverage from SENA v3.3.1

v1.0.0 (2025-11-23) - Initial Release

• ✅ MCP server with 5 core tools
• ✅ CLI hooks system (6 hooks)
• ✅ Automated installer
• ✅ Complete documentation
• ✅ Both Desktop + CLI support
• ✅ GitHub repository published

╔══════════════════════════════════════════════════════════════╗ ║ ║ ║ 🦁 SENA: Complete Intelligence for Claude ║ ║ ║ ║ Desktop + CLI • MCP + Hooks • One Package ║ ║ ║ ╚══════════════════════════════════════════════════════════════╝