https://github.com/toolprint/superego-mcp
https://github.com/toolprint/superego-mcp
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/toolprint/superego-mcp
- Owner: toolprint
- License: other
- Created: 2025-08-11T07:39:47.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-25T21:58:23.000Z (9 months ago)
- Last Synced: 2025-09-29T18:45:43.673Z (8 months ago)
- Language: Python
- Size: 2.08 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Superego MCP
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/astral-sh/ruff)
[](http://mypy-lang.org/)
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
```bash
# 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)**:
```bash
echo '{"tool_name": "bash", "tool_input": {"command": "ls"}}' | superego advise
```
2. **Start the MCP server**:
```bash
# 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**:
```bash
just demo-fastagent-simple
```
## Claude Code Integration
Superego provides seamless integration with Claude Code through hooks:
### Setup Claude Code Hooks
```bash
# 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](docs/claude-code-hooks-setup.md)**
### Quick Hook Configuration
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "superego advise",
"timeout": 5000
}
]
}
]
}
}
```
## Configuration
### Server Configuration (`config/server.yaml`)
```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`)
```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
```bash
# 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
```bash
# 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
```bash
# 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
```json
{
"tool_name": "string",
"tool_input": {
"parameter1": "value1",
"parameter2": "value2"
},
"session_id": "string",
"transcript_path": "string",
"cwd": "string",
"hook_event_name": "PreToolUse"
}
```
### Security Decision Response
```json
{
"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
```bash
export PYTHONPATH=$PYTHONPATH:$(pwd)/src
```
2. **Hook timeouts**: Check Superego service availability
```bash
superego mcp --debug
```
3. **AI inference failures**: Verify API keys are set
```bash
export ANTHROPIC_API_KEY=your-key-here
```
### Debug Mode
Enable debug logging:
```bash
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](LICENSE) file for details
## Container Deployment
### Docker Quickstart
1. Pull the latest image:
```bash
docker pull toolprint/superego-mcp:latest
```
2. Run with Docker Compose:
```bash
# Start in development mode
docker-compose up -d
# Start in production mode
docker-compose -f docker-compose.prod.yml up -d
```
### Container Management
- Comprehensive container usage guide: [Container Usage Docs](/docs/container-usage.md)
- Deployment guide: [Deployment Guide](/docs/deployment-guide.md)
- Troubleshooting: [Troubleshooting Guide](/docs/troubleshooting.md)
## Links
- [Repository](https://github.com/toolprint/superego-mcp)
- [Issues](https://github.com/toolprint/superego-mcp/issues)
- [PyPI Package](https://pypi.org/project/superego-mcp/)
- [Documentation](/docs)
- [Container Documentation](/docs/container-usage.md)