README.md
Exposes a trained Deep Q-Network agent for business process resource allocation
MCP4DRL - Model Context Protocol for Deep Reinforcement Learning
MCP server that exposes a trained Deep Q-Network (DQN) agent for business process resource allocation through conversational interfaces. Makes "black box" RL systems transparent via natural language queries.
Features
- Environment State Queries - View simulation state, waiting/active cases, resources
- Q-Value Analysis - Inspect Q-values for all actions
- Action Recommendations - Get agent's top choice with justification
- Explainability - Detailed explanations of why actions are chosen
- Heuristic Comparison - Compare with FIFO, SPT, EDF, LST baselines
- Simulation Control - Step through episodes, reset, run full episodes
Installation
pip install -r requirements.txt
Requirements: Python 3.8+, TensorFlow 2.16+
Quick Start
Test locally
python -m mcp4drl.test_integration
Run MCP server
# Windows
run_server.bat
# Linux/Mac
chmod +x run_server.sh
./run_server.sh
Claude Desktop Integration
Add to claude_desktop_config.json:
{
"mcpServers": {
"mcp4drl": {
"command": "cmd.exe",
"args": ["/c", "C:\\path\\to\\mcp4drl_repo\\run_server.bat"],
"shell": true
}
}
}
Available MCP Tools
| Tool | Description |
|---|---|
get_environment_state |
Current simulation state |
get_eligible_actions |
All possible actions with validity |
get_q_values |
Q-values for all actions |
get_recommended_action |
Agent's best action |
explain_action |
Detailed action explanation |
compare_with_heuristic |
Compare with FIFO/SPT/EDF/LST |
step_simulation |
Execute one step |
reset_simulation |
Reset to initial state |
run_episode |
Run full episode with policy |
Project Structure
mcp4drl_repo/
├── mcp4drl/ # Main Python package
│ ├── core/ # Wrappers (simulator, agent)
│ ├── models/ # Pydantic schemas
│ └── tools/ # MCP tool implementations
├── simprocess/ # Business process simulation engine
├── data/ # Model and event log
└── mcp4drl_server.py # Standalone launcher
Configuration
Environment variables (optional):
MCP4DRL_MODEL_PATH- Path to trained model (.h5)MCP4DRL_EVENT_LOG- Path to XES event logMCP4DRL_TRANSPORT-stdio(default) orsse
Context
Part of doctoral dissertation on intelligent automation of business process management. Demonstrates that RL systems can be made transparent through conversational interfaces.
License
Research prototype.
Tools (9)
get_environment_stateReturns the current simulation state including waiting/active cases and resources.get_eligible_actionsLists all possible actions with their validity status.get_q_valuesRetrieves Q-values for all available actions.get_recommended_actionReturns the agent's best recommended action.explain_actionProvides a detailed explanation of why a specific action is chosen.compare_with_heuristicCompares the agent's performance with FIFO, SPT, EDF, or LST baselines.step_simulationExecutes one step in the simulation.reset_simulationResets the simulation to its initial state.run_episodeRuns a full simulation episode using the trained policy.Environment Variables
MCP4DRL_MODEL_PATHPath to trained model (.h5)MCP4DRL_EVENT_LOGPath to XES event logMCP4DRL_TRANSPORTTransport protocol (stdio or sse)Configuration
claude_desktop_config.json
{"mcpServers": {"mcp4drl": {"command": "cmd.exe", "args": ["/c", "C:\\path\\to\\mcp4drl_repo\\run_server.bat"], "shell": true}}}Try it
→What is the current state of the business process simulation?
→What is the agent's recommended action right now and why?
→Compare the agent's current performance against the FIFO heuristic.
→Run a full simulation episode and summarize the results.
→Show me the Q-values for the available actions in the current state.