mcprojsim 0.8.1

Monte Carlo simulation system for software development effort estimation

Monte Carlo Project Simulator (mcprojsim)

Stop guessing deadlines. Start simulating them !

Category	Link
Package
Documentation
License
Release
CI/CD
Code Quality
Repo URL

Overview

mcprojsim is a Monte Carlo simulation tool for projects with emphasis on agile software project estimation. Instead of producing a single deadline, it models uncertainty in task duration, dependencies, risks, and other schedule drivers to produce confidence-based forecast ranges.

It is intended for teams that want answers such as:

• What is the likely completion range for this project?
• What is the $P50$, $P80$, or $P90$ delivery date?
• Which tasks most often drive schedule risk?
• How do risks and uncertainty factors change the forecast?

Key features

• Monte Carlo schedule simulation with configurable iterations and reproducible seeds
• Range-based estimates using explicit low/expected/high values, T-shirt sizes, story points, and multi-category symbolic sizing
• Dependency-only scheduling plus resource- and calendar-constrained scheduling when resources are present
• Risk and uncertainty modeling for both tasks and the overall project
• Analysis outputs including percentiles, delivery dates, critical paths, sensitivity, slack, risk impact, staffing guidance, and target-date probability
• JSON, CSV, and HTML exports, plus optional ASCII table output in the CLI
• Natural-language project generation from plain text with mcprojsim generate
• MCP server support for assistant-driven generation, validation, and simulation workflows
• Sprint planning support with empirical or negative binomial velocity models, sickness modelling, spillover, and historical metrics import

Recommended installation

Most users fall into one of two paths:

• Terminal-first CLI usage: install with pipx.
• MCP-assisted usage: use the released MCP bundle or the optional MCP package install described in docs/user_guide/mcp-server.md.

For direct terminal-only CLI usage, pipx remains the simplest manual install path:

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install mcprojsim

Then verify the installation:

mcprojsim --help
mcprojsim --version

For the fastest first run, start with QUICKSTART.md. For the fuller documentation path after that, use the published User Guide.

[!TIP] There is also a prepared Docker image if you prefer to use an isolated environment to run in. There is also a accompaning script in bin/mcprojsim.sh to run the program in the container in the same way as the Python executable installed via pipx

Minimal example

Create a file named project.yaml:

project:
  name: "My Project"
  description: "Sample project for estimation"
  start_date: "2025-11-01"
  confidence_levels: [50, 80, 90]

tasks:
  - id: "task_001"
    name: "Database schema design"
    estimate:
      low: 3
      expected: 5
      high: 10
      unit: "days"
    dependencies: []
    uncertainty_factors:
      team_experience: "high"
      requirements_maturity: "medium"
      technical_complexity: "low"

Validate the file:

mcprojsim validate project.yaml

Run a simulation:

mcprojsim simulate project.yaml --seed 12345 --table

Typical outputs (see the --help for how to specify output) include:

• *_results.json for full machine-readable output
• *_results.csv for tabular summaries
• *_results.html for a browsable report

Documentation map

Use the entry point that matches your goal:

Documentation Link	Purpose
QUICKSTART.md	Fastest terminal-based first run
User Documentation	The full documentation site
User Guide	The User Guide section
Development Guide	contributor and source-checkout workflows

Additional runnable examples can be seen in the Examples section of the user guide or in the project directory examples/.

Example commands

# Generate a project file from a natural language description
mcprojsim generate examples/nl_example.txt -o my_project.yaml

# Validate an input file
mcprojsim validate examples/sample_project.yaml

# Run a reproducible simulation
mcprojsim simulate examples/sample_project.yaml --seed 42

# Use a custom configuration
mcprojsim simulate examples/sample_project.yaml --config examples/sample_config.yaml --seed 42

# Calculate probability of meeting a target date
mcprojsim simulate examples/sample_project.yaml --target-date 2026-06-01

# Format tabular sections for easier reading
mcprojsim simulate examples/sample_project.yaml --table --seed 42

For full CLI coverage, including constrained scheduling, sprint planning, quiet/minimal modes, staffing, and export options, see docs/user_guide/running_simulations.md.

MCP server integration

mcprojsim can run as a Model Context Protocol (MCP) server, letting AI assistants such as GitHub Copilot, Claude Desktop, or any MCP-compatible client generate project files, validate descriptions, and run simulations conversationally.

Preferred path: install the released MCP bundle artifact from GitHub Releases with your assistant, or follow the manual setup in docs/user_guide/mcp-server.md.

For end-to-end setup, installation tradeoffs, and natural-language input examples, see docs/user_guide/mcp-server.md.

Example prompt to get your assistant to install mcprojsim:

Download and install the latest mcprojsim MCP server from GitHub Releases. Follow the README.md for installation instructions.

See the MCP server detailed documentation for examples of using the server.

For developers

If you want to work from a source checkout, run tests, build docs, or use containers, start with:

• docs/development.md
• scripts/README.md

Use QUICKSTART.md only for the fastest end-user first run. The detailed developer documentation, including Poetry workflow, Make targets, scripts, containers, and release steps, lives in docs/development.md.

The full published documentation is also available at https://johan162.github.io/mcprojsim/.

Contributing

Contributions are welcome.

1. Fork the repository
2. Read the Developer Guide to set up your environment and understand the codebase
3. Create a feature branch
4. Make your changes with tests
5. Use the ./scripts/mkbld.sh script to build and test your changes locally
6. Submit a pull request

Support

• Bug reports: MCProjSim Issues
• Full documentation: MCProjSim Documentation

Citation

If you use this tool in research or project planning, please cite:

@software{mcprojsim,
  title = {Monte Carlo Project Simulator},
  author = {Johan Persson},
  year = {2026},
  url = {https://github.com/johan162/mcprojsim},
  version = {0.8.1}
}

License

MIT License - see LICENSE.

Acknowledgments

Inspired by the work of:

• Steve McConnell - Software Estimation: Demystifying the Black Art
• Frederick Brooks - The Mythical Man-Month
• Douglas Hubbard - How to Measure Anything in Cybersecurity Risk