Simulacrum MCP - Motor de Física para Raciocínio de IA
codesmirnov/simulacrum-mcp
Simulação de sistemas complexos com dinâmica, caos e teoria dos jogos
Ver no GitHubToolkit abrangente que transforma sistemas de IA em simuladores sofisticados de realidade. Oferece modelagem matemática avançada, simulação de dinâmica de sistemas, análise de caos, teoria dos jogos e raciocínio bayesiano para permitir que agentes entendam e prevejam fenômenos complexos do mundo real.
Instalação
npx convez-ai codesmirnov/simulacrum-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Modelagem de dinâmica de sistemas complexos com equações diferenciais
- Análise de cenários e comparação de estratégias com métricas sofisticadas
- Raciocínio bayesiano probabilístico em decisões de agentes IA
- Detecção de eventos black swan e sinais de alerta precoce
- Análise de grafos causais com counterfactual reasoning
Veredito

MCP de qualidade técnica sólida (100% cobertura de testes) para agentes IA que precisam ir além de heurísticas simples. Ideal para problemas que exigem modelagem matemática rigorosa, mas requer expertise em sistemas dinâmicos e estatística para aproveitar todo potencial.
README
A tradução para o português deste README ainda está na fila.
Simulacrum MCP
Reality Engine for AI Systems
Simulacrum is a comprehensive toolkit that transforms AI systems into sophisticated reality simulators. By providing advanced mathematical modeling, system dynamics simulation, and chaos analysis, it enables AI to understand and predict complex real-world phenomena through rigorous computational methods.
🌟 Key Features
Core Simulation Tools
- System Dynamics Simulation - Model complex systems with differential equations and feedback loops
- Scenario Comparison - A/B testing for reality with sophisticated similarity metrics
- Feedback Loop Analysis - Identify reinforcing/balancing loops and their systemic impact
- Belief Dynamics - Theory of Mind simulation for social and cognitive modeling
- Game Theory Analysis - Strategic equilibrium analysis and learning dynamics
- Bayesian Reasoning - Replace "I think" with probabilistic evidence-based analysis
- Chaos Detection - Identify black swan events and early warning signals
- Conceptual Vector Analysis - Analyze complex relationships and conflicts in multi-dimensional spaces
Advanced Analysis Tools
- Monte Carlo Simulation - Stochastic modeling with uncertainty quantification and risk analysis
- Mathematical Optimization - Linear/nonlinear programming with constraint support
- Causal Graph Analysis - Counterfactual reasoning with Pearl's do-operator and d-separation
- Network Analysis - Graph theory with centrality measures and community detection
- Sensitivity Analysis - Parameter importance ranking with Sobol indices and Morris screening
Technical Excellence
- 100% Test Coverage - Comprehensive testing with pytest and hypothesis
- MCP Integration - Seamless Cursor AI integration via Model Context Protocol
🚀 Quick Start
Prerequisites
- Python 3.8 or higher
- pip package manager
Installation
-
Clone the repository:
git clone https://github.com/codesmirnov/simulacrum-mcp.git cd simulacrum-mcp -
Install dependencies:
pip install -r requirements.txt -
Install the package:
pip install -e .
Cursor AI Integration
-
Configure MCP in Cursor: Add to your Cursor settings (
.cursorrulesor global settings):{ "mcp": { "servers": { "simulacrum": { "command": "python", "args": ["-m", "simulacrum.server"], "env": {} } } } } -
Verify installation:
simulacrum-server --help
📖 Usage Examples
System Dynamics Simulation
from simulacrum import DynamicsSimulator
# Define a predator-prey model
scenario = {
"name": "Lotka-Volterra Predator-Prey",
"variables": [
{"name": "prey", "initial_value": 10.0, "min_value": 0},
{"name": "predator", "initial_value": 5.0, "min_value": 0}
],
"equations": [
{
"target_variable": "prey",
"expression": "prey * (2.0 - 0.01 * predator)"
},
{
"target_variable": "predator",
"expression": "predator * (-1.0 + 0.01 * prey)"
}
],
"config": {
"time_config": {
"end_time": 50.0,
"time_step": 0.1
}
}
}
simulator = DynamicsSimulator()
result = simulator.simulate_dynamics(scenario)
print(f"Simulation completed: {result['status']}")
Bayesian Belief Update
from simulacrum import ProbabilityAnalyzer
analyzer = ProbabilityAnalyzer()
# Update beliefs with evidence
analysis = {
"analysis_type": "bayesian_update",
"prior": {"rain": 0.3, "no_rain": 0.7},
"likelihood": {
"cloudy": {"rain": 0.8, "no_rain": 0.4}
},
"evidence": [
{"hypothesis": "rain", "observation": "cloudy", "strength": 1.0}
]
}
result = analyzer.analyze_probability(analysis)
print(f"Updated belief in rain: {result['final_posterior']['rain']:.2%}")
Chaos Analysis
from simulacrum import ChaosAnalyzer
analyzer = ChaosAnalyzer()
# Analyze time series for chaotic behavior
time_series_data = {
"time_series": [0.1, 0.15, 0.08, 0.12, 0.18, 0.14, 0.09, 0.16, ...]
}
result = analyzer.analyze_chaos(time_series_data)
print(f"System state: {result['overall_assessment']['system_state']}")
print(f"Risk level: {result['overall_assessment']['risk_level']}")
Conceptual Vector Analysis
from simulacrum import VectorAnalyzer
analyzer = VectorAnalyzer()
# Analyze strategic alignment between different entities
vectors = [
{
"name": "Innovation_Focus",
"components": {"growth": 0.8, "stability": -0.2, "innovation": 0.9}
},
{
"name": "Market_Reality",
"components": {"growth": 0.3, "stability": 0.7, "innovation": 0.1}
}
]
strengths = [
{"name": "Innovation_Focus", "value": 1.5},
{"name": "Market_Reality", "value": 1.0}
]
result = analyzer.multidimensional_vector_analysis(vectors, strengths)
print(f"Total system magnitude: {result['total_magnitude']:.4f}")
print(f"Top dimensions: {', '.join([d['dimension'] for d in result['top_dimensions']])}")
Monte Carlo Simulation
from simulacrum import MonteCarloSimulator
simulator = MonteCarloSimulator()
# Model with uncertainty
def profit_model(price, cost, demand):
return (price - cost) * demand
simulation = {
"model": profit_model,
"parameter_distributions": {
"price": {"type": "normal", "params": {"mean": 100, "std": 10}},
"cost": {"type": "uniform", "params": {"low": 60, "high": 80}},
"demand": {"type": "triangular", "params": {"low": 50, "mode": 100, "high": 200}}
},
"n_iterations": 5000,
"confidence_levels": [0.95, 0.99]
}
result = simulator.simulate_monte_carlo(simulation)
print(f"Expected profit: ${result['statistics']['output']['mean']:.0f}")
print(f"95% VaR: ${result['statistics']['output']['risk_metrics']['var_95']:.0f}")
Causal Analysis
from simulacrum import CausalAnalyzer
analyzer = CausalAnalyzer()
# Define causal graph
causal_graph = {
"nodes": ["Smoking", "Cancer", "Age"],
"edges": [("Smoking", "Cancer"), ("Age", "Cancer"), ("Age", "Smoking")],
"queries": [{
"type": "causal_effect",
"cause": "Smoking",
"effect": "Cancer"
}]
}
result = analyzer.analyze_causal_graph(causal_graph)
effect = result["queries"][0]
print(f"Causal effect identifiable: {effect['identifiable']}")
🧪 Testing
Run the comprehensive test suite:
# Install test dependencies
pip install -e ".[dev]"
# Run all tests with coverage
pytest --cov=simulacrum --cov-report=html
# Run specific test categories
pytest tests/test_dynamics.py
pytest tests/test_probability.py
pytest tests/test_chaos.py
pytest tests/test_vector_analysis.py
🏗️ Architecture
Core Principles
- Single Responsibility - Each class has one clear purpose
- Open/Closed - Extensible without modifying existing code
- Liskov Substitution - Subtypes are substitutable for base types
- Interface Segregation - Clients depend only on methods they use
- Dependency Inversion - Depend on abstractions, not concretions
Package Structure
simulacrum/
├── core/ # Core engine and interfaces
├── tools/ # Analysis tools and simulators
├── validation/ # Data validation and type safety
└── server.py # MCP server implementation
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
Code of Conduct
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Security
For security-related issues, please see our Security Policy.
Development Setup
# Clone and setup
git clone https://github.com/codesmirnov/simulacrum-mcp.git
cd simulacrum-mcp
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run linting
black simulacrum/
isort simulacrum/
mypy simulacrum/
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Built for the AI safety and alignment research community
- Inspired by system dynamics, chaos theory, and Bayesian epistemology
- Designed for practical deployment in AI assistant systems
📞 Contact
codesmirnov
- GitHub: @codesmirnov
- Email: hello@codesmirnov.ru
Transforming AI from pattern recognition to reality simulation.