Skip to main content
Glama
toolprint

superego-mcp

by toolprint
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Superego MCP

Python Version License Code Style Type Checked

Intelligent tool-call review system for AI agents

Overview

Superego MCP Server provides a configurable review system to AI agents to reduce the amount of manual approvals needed as well as provide automated guardrails against dangerous operations. It analyzes incoming tool calls against a set of rules and if no rule is matched it defers to another agent for review or escalation to a human.

Features

  • Rule-based interception: Define flexible rules using YAML configuration with advanced pattern matching (regex, glob, JSONPath)

  • Multiple actions: Allow, block, or require approval (sampling) based on configurable policies

  • Claude Code Hooks Integration: Direct integration with Claude Code for real-time security evaluation

  • Multi-transport Support: STDIO, HTTP, and SSE transports for flexible deployment

  • Hot reload: Configuration changes are applied without restart

  • AI-powered evaluation: Optional AI inference for complex security decisions

  • Performance optimized: Request batching, caching, and connection pooling

  • Comprehensive monitoring: Built-in metrics, health checks, and performance dashboard

  • Structured logging: Comprehensive logging with structured output

  • MCP compatibility: Full Model Context Protocol support with FastMCP framework

Quick Start

Installation

# Install with uv (recommended)
uv pip install superego-mcp

# Or install from source
git clone https://github.com/toolprint/superego-mcp
cd superego-mcp
uv sync

Basic Usage

  1. Run security evaluation (for Claude Code hooks):

    echo '{"tool_name": "bash", "tool_input": {"command": "ls"}}' | superego advise

  2. Start the MCP server:

    # Default STDIO transport
superego mcp

# HTTP transport on custom port
superego mcp -t http -p 9000

# With custom config
superego mcp -c ~/.toolprint/superego/config.yaml

  3. Run interactive demo:

    just demo-fastagent-simple

Claude Code Integration

Superego provides seamless integration with Claude Code through hooks:

Setup Claude Code Hooks

# Add hooks for specific tools (recommended)
superego hooks add --matcher "Bash|Write|Edit|MultiEdit"

# Add universal hook for all tools
superego hooks add --matcher "*"

# Use centralized server mode
superego hooks add --matcher "*" --url http://localhost:8000

For complete hook setup instructions and examples, see: Claude Code Hooks Setup Guide

Quick Hook Configuration

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "superego advise",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Configuration

Server Configuration (config/server.yaml)

# Server settings
host: "localhost"
port: 8000
debug: false
log_level: "INFO"

# Rule engine settings
rules_file: "config/rules.yaml"
hot_reload: true

# Multi-transport configuration
transport:
  stdio:
    enabled: true
  http:
    enabled: true
    host: "0.0.0.0"
    port: 8000
  sse:
    enabled: true
    port: 8002

# AI inference configuration
inference:
  timeout_seconds: 30
  provider_preference:
    - "claude_cli"
    - "mcp_sampling"
  cli_providers:
    - name: "claude_cli"
      enabled: true
      type: "claude"
      command: "claude"
      model: "claude-sonnet-4-20250514"

Security Rules (config/rules.yaml)

rules:
  # Block dangerous commands
  - id: "block_destructive_commands"
    priority: 1
    conditions:
      tool_name:
        type: "regex"
        pattern: "^(rm|delete|remove|destroy).*"
    action: "deny"
    reason: "Destructive command pattern detected"
    
  # Protect system directories
  - id: "protect_system_files"
    priority: 2
    conditions:
      parameters:
        path:
          type: "glob"
          pattern: "/etc/**"
    action: "deny"
    reason: "System directory access denied"
    
  # Require approval for file operations
  - id: "sample_file_operations"
    priority: 10
    conditions:
      AND:
        - tool_name: ["edit", "write", "delete"]
        - parameters:
            path:
              type: "regex"
              pattern: "^(?!/tmp/).*$"
    action: "sample"
    reason: "File operation requires AI evaluation"
    sampling_guidance: "Evaluate if this file operation is safe"

Development

Setup

# Setup development environment
just dev

# Run tests
just test

# Run with coverage
just test-cov

# Lint and format
just lint
just format

# Type check
just typecheck

# Run all quality checks
just check

Project Structure

src/superego_mcp/
├── __init__.py              # Package initialization
├── cli.py                   # Unified CLI interface
├── cli_eval.py              # Evaluation mode implementation  
├── cli_hooks.py             # Claude Code hooks management
├── main.py                  # MCP server entry point
├── main_optimized.py        # Performance-optimized server
├── stdio_main.py            # STDIO transport handler
├── domain/                  # Business logic and models
│   ├── models.py            # Core domain models
│   ├── pattern_engine.py    # Pattern matching engine
│   ├── security_policy.py   # Security evaluation engine
│   ├── services.py          # Domain services
│   ├── repositories.py      # Domain repositories
│   ├── claude_code_models.py # Claude Code hook models
│   └── hook_integration.py  # Hook integration service
├── infrastructure/          # External services and adapters
│   ├── config.py            # Configuration management
│   ├── config_watcher.py    # Hot reload implementation
│   ├── ai_service.py        # AI inference service
│   ├── inference.py         # Extensible inference system
│   ├── circuit_breaker.py   # Circuit breaker pattern
│   ├── metrics.py           # Prometheus metrics
│   ├── performance.py       # Performance optimization
│   └── logging_config.py    # Structured logging setup
└── presentation/            # API and transport layers
    ├── mcp_server.py        # FastMCP server implementation
    ├── http_transport.py    # HTTP/WebSocket transport
    ├── sse_transport.py     # Server-sent events transport
    ├── handlers.py          # Request handlers
    ├── monitoring.py        # Monitoring dashboard
    └── server.py            # Transport server orchestration

Testing

# Run specific test file
just test-file tests/test_security_policy.py

# Run integration tests
uv run pytest tests/test_mcp_server_integration.py -v

# Run performance tests
just test-performance

# Run load tests
just load-test

Performance Optimization

# Run optimized server
just run-optimized

# Run performance demo
just demo-performance

# Benchmark rule evaluation
just benchmark-rules

API Documentation

CLI Commands

  • superego advise - One-off security evaluation for Claude Code hooks

  • superego mcp - Launch the FastMCP server

  • superego hooks - Manage Claude Code hook configurations

Tool Request Format

{
  "tool_name": "string",
  "tool_input": {
    "parameter1": "value1",
    "parameter2": "value2"
  },
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "hook_event_name": "PreToolUse"
}

Security Decision Response

{
  "decision": "allow|deny|sample",
  "confidence": 0.95,
  "reasoning": "Explanation of the decision",
  "risk_factors": ["risk1", "risk2"],
  "matched_rules": ["rule_id1", "rule_id2"]
}

Monitoring

Access the monitoring dashboard at http://localhost:9090/dashboard when running with metrics enabled.

Metrics available:

  • Request volume by tool type

  • Decision distribution (allow/deny/sample)

  • Processing times

  • AI inference latency

  • Error rates

Troubleshooting

Common Issues

  1. Import errors: Ensure proper Python path setup

    export PYTHONPATH=$PYTHONPATH:$(pwd)/src

  2. Hook timeouts: Check Superego service availability

    superego mcp --debug

  3. AI inference failures: Verify API keys are set

    export ANTHROPIC_API_KEY=your-key-here

Debug Mode

Enable debug logging:

superego mcp --debug

Logs Location

  • Server logs: stderr (structured JSON format)

  • Hook operations: /tmp/superego_hook.log

  • Metrics: http://localhost:9090/metrics

Contributing

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'feat: add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

Development Guidelines

  • Follow conventional commits format

  • Ensure all tests pass (just check)

  • Add tests for new features

  • Update documentation as needed

  • Maintain type safety with mypy

License

MIT License - see LICENSE file for details

Container Deployment

Docker Quickstart

  1. Pull the latest image:

docker pull toolprint/superego-mcp:latest

  1. Run with Docker Compose:

# Start in development mode
docker-compose up -d

# Start in production mode
docker-compose -f docker-compose.prod.yml up -d

Container Management

Links

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/toolprint/superego-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server