{"id":31810876,"url":"https://github.com/toolprint/superego-mcp","last_synced_at":"2025-10-11T06:17:29.421Z","repository":{"id":310916046,"uuid":"1035857264","full_name":"toolprint/superego-mcp","owner":"toolprint","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-25T21:58:23.000Z","size":2184,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-29T18:45:43.673Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toolprint.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-11T07:39:47.000Z","updated_at":"2025-08-25T21:57:26.000Z","dependencies_parsed_at":"2025-08-21T02:45:32.485Z","dependency_job_id":null,"html_url":"https://github.com/toolprint/superego-mcp","commit_stats":null,"previous_names":["toolprint/superego-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/toolprint/superego-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fsuperego-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fsuperego-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fsuperego-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fsuperego-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toolprint","download_url":"https://codeload.github.com/toolprint/superego-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fsuperego-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006450,"owners_count":26084107,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-11T06:17:25.974Z","updated_at":"2025-10-11T06:17:29.413Z","avatar_url":"https://github.com/toolprint.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Superego MCP\n\n[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Code Style](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![Type Checked](https://img.shields.io/badge/type_checked-mypy-blue)](http://mypy-lang.org/)\n\nIntelligent tool-call review system for AI agents\n\n## Overview\n\nSuperego 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.\n\n## Features\n\n- **Rule-based interception**: Define flexible rules using YAML configuration with advanced pattern matching (regex, glob, JSONPath)\n- **Multiple actions**: Allow, block, or require approval (sampling) based on configurable policies\n- **Claude Code Hooks Integration**: Direct integration with Claude Code for real-time security evaluation\n- **Multi-transport Support**: STDIO, HTTP, and SSE transports for flexible deployment\n- **Hot reload**: Configuration changes are applied without restart\n- **AI-powered evaluation**: Optional AI inference for complex security decisions\n- **Performance optimized**: Request batching, caching, and connection pooling\n- **Comprehensive monitoring**: Built-in metrics, health checks, and performance dashboard\n- **Structured logging**: Comprehensive logging with structured output\n- **MCP compatibility**: Full Model Context Protocol support with FastMCP framework\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install with uv (recommended)\nuv pip install superego-mcp\n\n# Or install from source\ngit clone https://github.com/toolprint/superego-mcp\ncd superego-mcp\nuv sync\n```\n\n### Basic Usage\n\n1. **Run security evaluation (for Claude Code hooks)**:\n   ```bash\n   echo '{\"tool_name\": \"bash\", \"tool_input\": {\"command\": \"ls\"}}' | superego advise\n   ```\n\n2. **Start the MCP server**:\n   ```bash\n   # Default STDIO transport\n   superego mcp\n   \n   # HTTP transport on custom port\n   superego mcp -t http -p 9000\n   \n   # With custom config\n   superego mcp -c ~/.toolprint/superego/config.yaml\n   ```\n\n3. **Run interactive demo**:\n   ```bash\n   just demo-fastagent-simple\n   ```\n\n## Claude Code Integration\n\nSuperego provides seamless integration with Claude Code through hooks:\n\n### Setup Claude Code Hooks\n\n```bash\n# Add hooks for specific tools (recommended)\nsuperego hooks add --matcher \"Bash|Write|Edit|MultiEdit\"\n\n# Add universal hook for all tools\nsuperego hooks add --matcher \"*\"\n\n# Use centralized server mode\nsuperego hooks add --matcher \"*\" --url http://localhost:8000\n```\n\n**For complete hook setup instructions and examples, see: [Claude Code Hooks Setup Guide](docs/claude-code-hooks-setup.md)**\n\n### Quick Hook Configuration\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"*\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"superego advise\",\n            \"timeout\": 5000\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n## Configuration\n\n### Server Configuration (`config/server.yaml`)\n\n```yaml\n# Server settings\nhost: \"localhost\"\nport: 8000\ndebug: false\nlog_level: \"INFO\"\n\n# Rule engine settings\nrules_file: \"config/rules.yaml\"\nhot_reload: true\n\n# Multi-transport configuration\ntransport:\n  stdio:\n    enabled: true\n  http:\n    enabled: true\n    host: \"0.0.0.0\"\n    port: 8000\n  sse:\n    enabled: true\n    port: 8002\n\n# AI inference configuration\ninference:\n  timeout_seconds: 30\n  provider_preference:\n    - \"claude_cli\"\n    - \"mcp_sampling\"\n  cli_providers:\n    - name: \"claude_cli\"\n      enabled: true\n      type: \"claude\"\n      command: \"claude\"\n      model: \"claude-sonnet-4-20250514\"\n```\n\n### Security Rules (`config/rules.yaml`)\n\n```yaml\nrules:\n  # Block dangerous commands\n  - id: \"block_destructive_commands\"\n    priority: 1\n    conditions:\n      tool_name:\n        type: \"regex\"\n        pattern: \"^(rm|delete|remove|destroy).*\"\n    action: \"deny\"\n    reason: \"Destructive command pattern detected\"\n    \n  # Protect system directories\n  - id: \"protect_system_files\"\n    priority: 2\n    conditions:\n      parameters:\n        path:\n          type: \"glob\"\n          pattern: \"/etc/**\"\n    action: \"deny\"\n    reason: \"System directory access denied\"\n    \n  # Require approval for file operations\n  - id: \"sample_file_operations\"\n    priority: 10\n    conditions:\n      AND:\n        - tool_name: [\"edit\", \"write\", \"delete\"]\n        - parameters:\n            path:\n              type: \"regex\"\n              pattern: \"^(?!/tmp/).*$\"\n    action: \"sample\"\n    reason: \"File operation requires AI evaluation\"\n    sampling_guidance: \"Evaluate if this file operation is safe\"\n```\n\n## Development\n\n### Setup\n```bash\n# Setup development environment\njust dev\n\n# Run tests\njust test\n\n# Run with coverage\njust test-cov\n\n# Lint and format\njust lint\njust format\n\n# Type check\njust typecheck\n\n# Run all quality checks\njust check\n```\n\n### Project Structure\n```\nsrc/superego_mcp/\n├── __init__.py              # Package initialization\n├── cli.py                   # Unified CLI interface\n├── cli_eval.py              # Evaluation mode implementation  \n├── cli_hooks.py             # Claude Code hooks management\n├── main.py                  # MCP server entry point\n├── main_optimized.py        # Performance-optimized server\n├── stdio_main.py            # STDIO transport handler\n├── domain/                  # Business logic and models\n│   ├── models.py            # Core domain models\n│   ├── pattern_engine.py    # Pattern matching engine\n│   ├── security_policy.py   # Security evaluation engine\n│   ├── services.py          # Domain services\n│   ├── repositories.py      # Domain repositories\n│   ├── claude_code_models.py # Claude Code hook models\n│   └── hook_integration.py  # Hook integration service\n├── infrastructure/          # External services and adapters\n│   ├── config.py            # Configuration management\n│   ├── config_watcher.py    # Hot reload implementation\n│   ├── ai_service.py        # AI inference service\n│   ├── inference.py         # Extensible inference system\n│   ├── circuit_breaker.py   # Circuit breaker pattern\n│   ├── metrics.py           # Prometheus metrics\n│   ├── performance.py       # Performance optimization\n│   └── logging_config.py    # Structured logging setup\n└── presentation/            # API and transport layers\n    ├── mcp_server.py        # FastMCP server implementation\n    ├── http_transport.py    # HTTP/WebSocket transport\n    ├── sse_transport.py     # Server-sent events transport\n    ├── handlers.py          # Request handlers\n    ├── monitoring.py        # Monitoring dashboard\n    └── server.py            # Transport server orchestration\n```\n\n### Testing\n\n```bash\n# Run specific test file\njust test-file tests/test_security_policy.py\n\n# Run integration tests\nuv run pytest tests/test_mcp_server_integration.py -v\n\n# Run performance tests\njust test-performance\n\n# Run load tests\njust load-test\n```\n\n### Performance Optimization\n\n```bash\n# Run optimized server\njust run-optimized\n\n# Run performance demo\njust demo-performance\n\n# Benchmark rule evaluation\njust benchmark-rules\n```\n\n## API Documentation\n\n### CLI Commands\n\n- `superego advise` - One-off security evaluation for Claude Code hooks\n- `superego mcp` - Launch the FastMCP server\n- `superego hooks` - Manage Claude Code hook configurations\n\n### Tool Request Format\n\n```json\n{\n  \"tool_name\": \"string\",\n  \"tool_input\": {\n    \"parameter1\": \"value1\",\n    \"parameter2\": \"value2\"\n  },\n  \"session_id\": \"string\",\n  \"transcript_path\": \"string\",\n  \"cwd\": \"string\",\n  \"hook_event_name\": \"PreToolUse\"\n}\n```\n\n### Security Decision Response\n\n```json\n{\n  \"decision\": \"allow|deny|sample\",\n  \"confidence\": 0.95,\n  \"reasoning\": \"Explanation of the decision\",\n  \"risk_factors\": [\"risk1\", \"risk2\"],\n  \"matched_rules\": [\"rule_id1\", \"rule_id2\"]\n}\n```\n\n## Monitoring\n\nAccess the monitoring dashboard at `http://localhost:9090/dashboard` when running with metrics enabled.\n\nMetrics available:\n- Request volume by tool type\n- Decision distribution (allow/deny/sample)\n- Processing times\n- AI inference latency\n- Error rates\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Import errors**: Ensure proper Python path setup\n   ```bash\n   export PYTHONPATH=$PYTHONPATH:$(pwd)/src\n   ```\n\n2. **Hook timeouts**: Check Superego service availability\n   ```bash\n   superego mcp --debug\n   ```\n\n3. **AI inference failures**: Verify API keys are set\n   ```bash\n   export ANTHROPIC_API_KEY=your-key-here\n   ```\n\n### Debug Mode\n\nEnable debug logging:\n```bash\nsuperego mcp --debug\n```\n\n### Logs Location\n\n- Server logs: `stderr` (structured JSON format)\n- Hook operations: `/tmp/superego_hook.log`\n- Metrics: `http://localhost:9090/metrics`\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'feat: add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n\n- Follow conventional commits format\n- Ensure all tests pass (`just check`)\n- Add tests for new features\n- Update documentation as needed\n- Maintain type safety with mypy\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n## Container Deployment\n\n### Docker Quickstart\n\n1. Pull the latest image:\n```bash\ndocker pull toolprint/superego-mcp:latest\n```\n\n2. Run with Docker Compose:\n```bash\n# Start in development mode\ndocker-compose up -d\n\n# Start in production mode\ndocker-compose -f docker-compose.prod.yml up -d\n```\n\n### Container Management\n- Comprehensive container usage guide: [Container Usage Docs](/docs/container-usage.md)\n- Deployment guide: [Deployment Guide](/docs/deployment-guide.md)\n- Troubleshooting: [Troubleshooting Guide](/docs/troubleshooting.md)\n\n## Links\n\n- [Repository](https://github.com/toolprint/superego-mcp)\n- [Issues](https://github.com/toolprint/superego-mcp/issues)\n- [PyPI Package](https://pypi.org/project/superego-mcp/)\n- [Documentation](/docs)\n- [Container Documentation](/docs/container-usage.md)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolprint%2Fsuperego-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoolprint%2Fsuperego-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolprint%2Fsuperego-mcp/lists"}