MCS-MCP: Monte-Carlo Simulation for Model Context Protocol

MCS-MCP is a Model Context Protocol (MCP) server that connects AI assistants like Claude to your Jira project history, enabling natural-language delivery analytics and probabilistic forecasting. Ask questions like "When will we finish these 20 items?", "Is our process getting more predictable?", or "Where are items getting stuck?" — and get answers grounded in your team's actual historical performance, not estimates or gut feel.

---

🚀 Key Capabilities

• Interactive Chart Rendering: Every analytical tool can render an interactive chart — served directly from the MCP server over localhost HTTP. Charts are self-contained React/Recharts pages requiring no external dependencies. On by default (MCS_CHARTS_BUFFER_SIZE=20, set to 0 to disable); each tool response includes a chart_url ready to open in any browser.
• Monte-Carlo Forecasting: Run 10,000+ simulations to answer "When will it be done?" (Duration) or "How much can we do?" (Scope). Uses your team's actual historical throughput, not estimates.
• Forecast Backtesting: Empirically validate how accurate the forecasts would have been by replaying them against your own historical data (Walk-Forward Analysis).
• Predictability Guardrails: Detect "Special Cause" variation using XmR Control Charts — assesses process stability for Cycle Time, WIP populations, and Delivery Cadence.
• SLE Adherence Trending: Trend weekly Service Level Expectation attainment and breach severity (max cycle time + P95 of breach excess). Defaults to the rolling-window P85 SLE; pass an explicit sle_duration_days to lock a stable Vacanti-style baseline.
• Workflow Semantic Discovery: Automatically infer the purpose of each workflow status (active work, waiting queues, entry funnel, terminal exit) to identify true bottlenecks rather than administrative overhead.
• Process Yield & Abandonment: Quantify waste by identifying exactly where work is discarded — broken down by work type and workflow stage.
• High-Fidelity Aging Analysis: Identify "neglected" inventory by comparing current WIP age against historical norms at the individual status level.
• Stratified Analytics: Work item type stratification is pervasive across the suite. Separate Bugs from Stories in simulations, throughput, cycle time, and stability to surface capacity conflicts (the "Bug-Tax").
• Sample Path Analysis (Residence Time): Compute the finite Little's Law identity L(T) = Λ(T) · w(T) to unify cycle time, WIP age, and flow debt into a single coherent view. Includes w'(T) (departure-denominated residence time) and Θ(T) (departure rate) to detect flow imbalance. The coherence gap between residence time and sojourn time reveals the "end effect" of active items on the system.
• Strategic Evolution Tracking: Longitudinal audits using Three-Way Control Charts (weekly/monthly) detect systemic improvements or process drift over time.
• Historical Time-Travel: Set a specific past date as the analytical reference point to recreate the state of your process at that moment. Useful for retrospectives, post-mortems, or before/after comparisons following a process change.
• Session Analysis Window: One [start, end] range scopes every diagnostic. Set it once with set_analysis_window (e.g. {end_date, duration_days} or two explicit dates), and every subsequent analysis — throughput, cycle time, flow debt, WIP, yield, residence time, etc. — uses the same window. Shifting "one month back" is a single call, not ten. Forecasting tools keep their own engine-driven sample windows; their accuracy isn't tied to the diagnostic lens.
• Guided Analytical Roadmaps: The server proactively suggests the right sequence of diagnostic steps for a given goal (forecasting, bottleneck analysis, capacity planning), preventing AI agents from guessing at the right path.

---

🧱 Limitations and Assumptions

• The Server doesn't use Jira's workflow related REST APIs. It infers the workflow from actual issue transitions, which is very reliable if - and that is the assumption - all work item types on a board share the same workflow, or - to be more precise - share the same statuses in the same order. If that assumtion doesn't hold, workflow discovery will yield unpredictable results and analytics/diagnostic and forecasting functions might get confused. I don't know whether I will ever tackle such cases, because analyzing a flow across different workflows seems nonsensical to me (I'm open to be proven wrong).
• For the same reason, the Server currently works on Boards and doesn't allow you to pass JQL to it. A simple workaround is obvious: Create a board using your query as the Board-JQL. Just be mindful of what you're doing.

---

🛡️ Data Security & GRC Principles

Work-Management Systems like Atlassian Jira often contain sensitive project and personal data. MCS-MCP is built with a Security-by-Design approach, operating on two fundamental governing principles:

1. The "Need-to-Know" Principle (Data Minimization)

To protect intellectual property and privacy, the server strictly minimizes the data it ingests and persists.

• What we ingest & persist: Analytical metadata only — Issue Keys, Issue Types, Status Transitions, Timestamps, and Resolution names. This is the minimum set required for high-fidelity flow analysis.
• What we DROP: While the Jira API might return comprehensive issue objects, the system is designed to immediately drop sensitive content such as Titles, Descriptions, Acceptance Criteria, or Assignees.

This ensures that even if the server's cache were compromised, it contains no human-readable content that could leak project secrets or PII. Furthermore, because this data is never processed by the analytical engine or stored in memory, it is impossible for sensitive content to leak to the AI Agent during interaction.

2. The Transparency Principle (Auditability)

We believe in "No Black Boxes." The server operates primarily from its local caches after the initial ingestion.

• Human-Readable Caches: All persisted data (Event Logs, Workflow Mappings) is stored in standard, human-readable formats (JSON and JSON-Lines) in the data directory.
• Verifiable Logic: You can scan or monitor these files at any time to verify that no sensitive data has leaked into the server's long-term memory.

---

🛠️ How it Works (high-level)

1. Ingestion: The server fetches Jira items from a Board within a Project and reconstructs a complete, event-sourced history from their transition logs.

2. Workflow Mapping: Every Jira workflow is unique. Before analysis can begin, the server needs to understand the purpose of each status. It proposes a mapping to a four-tier meta-workflow:

   • Demand: The entry funnel — ideas and backlog items not yet committed to.
   • Upstream: Analysis and refinement — work that has been picked up but not yet committed to delivery.
   • Downstream: Active execution — coding, testing, review. This is the "commitment zone."
   • Finished: Terminal states — done, cancelled, discarded.

   This mapping, along with what "done" means (delivered vs. abandoned) and where the Commitment Point is (the status where work is officially started — this defines Cycle Time and WIP), is proposed automatically and confirmed by you. It is cached so you only need to do this once per board.

3. Set the Analysis Window: Diagnostics need a time range — the slice of history they look at. There is one window per session that every diagnostic shares: throughput, cycle time, flow debt, WIP stability, yield, residence time, status persistence, process stability, work item age (snapshot at the End), and process evolution (long-term anchor at the End). The window defaults to a rolling 26 weeks ending today; the AI calls set_analysis_window to change it ({end_date, duration_days} or two explicit dates), and "move one month back" is one call, not ten. Forecasting (forecast_monte_carlo, forecast_backtest) is intentionally exempt — their sample windows are picked by the simulation engine for forecast accuracy, independent of the diagnostic lens.

4. Diagnostics & Forecasting: With the data, a clear understanding of what each status means, and a chosen window, you can ask the AI a wide range of questions about your delivery system's health, predictability, and future throughput.

---

🏃 Getting Started

Prerequisites

• Access to Atlassian Jira (Data Center or Cloud)
• A MCP-capable AI Agent to chat with (Claude Desktop is mine)
• Recent Version of Go if you want to build yourself — not needed if you download a release

Installation

1. Build from sources (see Building from Sources) or download a release.
2. Copy mcs-mcp.exe (or mcs-mcp) to a location of your choice (for builders, look into dist/).
3. Run it once. It creates a commented .env in its data folder — by default the standard per-user location for your platform (%AppData%\mcs-mcp on Windows, ~/Library/Application Support/mcs-mcp on macOS, ~/.config/mcs-mcp on Linux), see Where Settings Come From — pre-filled with every setting and its default. Edit that file: at a minimum you need to provide information about your Jira instance and how to authenticate (see Authentication). Your edits are never overwritten.
4. To keep the data somewhere else, start it with --data-path /path/to/writable/dir (or set the DATA_PATH environment variable) and it will keep its data — including the .env — there instead.
5. Configure an AI Agent to use it as an MCP tool (see Agent Configuration). Typically, you need to restart the Agent for the changes to take effect.
6. Chat:
   • Tell the AI Agent which Project and which Board you want to look at.
   • Tell the Agent to discover the workflow. Carefully review whether the proposal matches your actual process. You should confirm the Tiers (Demand, Upstream, Downstream, Finished), which resolutions or terminal statuses mean delivered vs. abandoned (this determines what counts as throughput), and what your Commitment Point is (the status where work officially starts — this defines Cycle Time and WIP) and of course the order of workflow statuses. These choices are cached, so you only need to confirm them once (unlesss you empty the cache folder).
   • Ask the Agent for the diagnostic roadmap to get a goal-oriented sequence of tools (e.g., "I want to forecast 15 items" or "I want to understand what's slowing us down").
   • Optionally, ask the Agent to set an evaluation date if you want to analyze the system as it existed at a point in the past (e.g., for a retrospective or post-mortem).

Authentication

The server supports 3 ways of Authentication. Set these in your .env file or through your agent's env block.

JIRA_TOKEN_TYPE is inferred and normally does not need to be set: if JIRA_USER_EMAIL is present the server uses api (Jira Cloud, Basic auth), otherwise pat (Data Center, Bearer). Set it explicitly only to override that. On startup the server logs which mode it chose (mode=basic|bearer|cookie|none) — check that line first if authentication fails.

Variables that don't apply can be left empty or commented out; empty values are treated as unset.

Option A: Personal Access Token (PAT) for Jira Datacenter

JIRA_TOKEN=your-personal-access-token

Option B: API Token for Jira Cloud

JIRA_TOKEN=your-api-token
JIRA_USER_EMAIL=your-jira-account-email

Option C: Session Cookies - Fallback

If neither is available, provide session cookies extracted from an active browser session:

JIRA_SESSION_ID=jira-session-ID
JIRA_XSRF_TOKEN=XSRF-token
JIRA_REMEMBERME_COOKIE=Jira-RememberMe-cookie
JIRA_GCILB=optional-google-cloud-load-balancer-cookie-GCILB
JIRA_GCLB=optional-google-cloud-load-balancer-cookie-GCLB

Cookies are only consulted when no token is set. If both are configured the token wins, and the server says so in the log.

Note that Cookies a) might expire from time to time and b) Atlassian may take measures to prevent the use of session cookies this way.

Building from Sources

Download Sources or clone the repository.

On Windows (PowerShell):

.\build.ps1 build

On Unix/Linux/MacOS (Make):

Untested, but should work.

make build

The resulting binary will be located in the dist/ folder along with an exemplary .env file. That example is generated from internal/config/template.go — edit the registry there, not conf/.env-example, which a test keeps in sync.

Agent Configuration

To use as a server for an AI Agent (like Claude or Gemini), point your MCP client configuration to the compiled binary:

{
	"mcpServers": {
		"mcs-mcp": {
			"command": "/path/to/mcs-mcp/mcs-mcp.exe",
			"args": []
		}
	}
}

By default the server keeps cache, logs and .env in the per-user location for your platform (see Where Settings Come From). To put them somewhere else, pass --data-path:

{
	"mcpServers": {
		"mcs-mcp": {
			"command": "/path/to/mcs-mcp/mcs-mcp.exe",
			"args": ["--data-path", "/path/to/writable/folder"],
			"env": {
				"JIRA_URL": "https://your-domain.atlassian.net",
				"JIRA_TOKEN": "your-token",
				"JIRA_USER_EMAIL": "your-jira-account-email"
			}
		}
	}
}

Anything in the env block outranks the .env file (see Where Settings Come From), so you can set credentials here and leave the rest of the settings to the file.

Where Settings Come From

Settings are resolved in this order, highest priority first:

1. Process environment — what your MCP client passes in its env block
2. .env in the data folder — the file created on first run; this is the one to edit
3. .env next to the binary — supported for backward compatibility
4. .env in the working directory — for development
5. Built-in defaults — shown in the generated .env

At startup the server logs one line per setting recording where its value came from — flag, env, dotenv, default or inferred — so a value that isn't what you expected can be traced without guesswork. Secrets are logged as present/absent only, never as a value.

The data folder itself is the exception. It has to be known before any .env can be found, so it is read only from the --data-path flag or the DATA_PATH environment variable — in that order, then falling back to the standard per-user location for your platform (%AppData%\mcs-mcp, ~/Library/Application Support/mcs-mcp, ~/.config/mcs-mcp), the binary directory, the system temp folder, and finally the working directory.

Setting DATA_PATH inside a .env file has no effect; the server warns when it finds one.

Upgrading from 0.21 or earlier? The default data folder moved. Earlier versions kept cache, logs and .env next to the binary; the default is now the per-user location listed above. If you never set --data-path or DATA_PATH, the server starts with an empty cache and re-ingests from Jira. Nothing is deleted — point --data-path at the old folder, or move its contents to the new one, to keep your history.

If you set DATA_PATH inside your .env, move it to --data-path or a real environment variable; it has never taken effect there. The server detects this case and says so explicitly in the log.

Optional Settings

These optional variables can be set in the .env file:

Variable	Default	Description
JIRA_TOKEN_TYPE	(inferred)	api or pat. Inferred from JIRA_USER_EMAIL when unset.
JIRA_DEPLOYMENT	(detected)	cloud or datacenter. Detected from the server; set only if that fails.
VERBOSE	false	Write detailed debug information to the log file.
COMMITMENT_POINT_BACKFLOW_RESET_CLOCK	true	Reset Cycle Time and WIP Age clock on backflow past commitment point.
JIRA_REQUEST_DELAY_SECONDS	10	Enforced delay (in seconds) between requests to the Jira REST API.
MCS_CHARTS_BUFFER_SIZE	20	Chart rendering buffer (0=off, 1-100=on). Starts HTTP server on localhost.
MCS_ENGINE	crude	Simulation engine: crude, bbak (regime-aware), or auto (backtest-driven).
MCS_ENGINE_CRUDE	50	Weight for the crude engine (0=disabled). Breaks ties in auto mode.
MCS_ENGINE_BBAK	50	Weight for the bbak engine (0=disabled). Breaks ties in auto mode.
INGESTION_UPDATED_LOOKBACK	24	Months back for the updated >= predicate of the initial Jira hydration JQL.
INGESTION_CREATED_LOOKBACK	36	Months back for the created >= predicate. Captures long-lived items not touched recently.
INGESTION_MAX_ITEMS	5000	Page-cap on initial hydration. Forward catch-up (import_history_update) is uncapped.

DATA_PATH is not listed here because it has no effect when set in .env — use --data-path or the environment variable.

Command-Line Flags

Flag	Description
--data-path	Base directory for cache, logs and .env. Overrides DATA_PATH.

---

📊 Chart Rendering

MCS-MCP renders interactive charts server-side. When MCS_CHARTS_BUFFER_SIZE is set to a value between 1 and 100, the server starts an HTTP listener on a random localhost port (3000-4000).

Changed in this release: charts are now on by default (MCS_CHARTS_BUFFER_SIZE=20). Previously the built-in default was 0 and charts were only enabled because the shipped .env-example set 20. If you never set this variable and do not want a local listener, set MCS_CHARTS_BUFFER_SIZE=0 explicitly. Each analytical tool response includes a chart_url in the context field. Opening that URL in a browser renders a self-contained React/Recharts chart with the tool's data.

The server buffers the most recent N tool results (MRU). Older entries are evicted when the buffer is full. Charts are rendered on demand when the URL is accessed.

Opening Chart URLs from an AI Agent

The server exposes an open_in_browser tool that AI agents can call to open a chart_url directly in your system's default browser — no browser extension or manual copy-paste required. After running any analytical tool, the agent can immediately follow up with open_in_browser to display the chart.

If for any reason the agent doesn't call open_in_browser, you can always copy the chart_url from the tool response and paste it into any browser manually. The chart is fully self-contained and requires no active server connection beyond the initial load.

Note for users of previous versions: The old Skills-based chart rendering (docs/skills/, inject.py) has been removed. Charts are now rendered entirely server-side. If you have the mcs-mcp.skill file installed in Claude Desktop, you should uninstall or disable it to avoid conflicts.

---

👉 Usage Tips

• Ask the Agent for the diagnostic roadmap at the start of a session. It returns a goal-oriented sequence of tools so you always have a clear path of analysis rather than guessing what to run next.
• After a significant process change (team restructure, workflow overhaul), tell the Agent to re-run workflow discovery with a force-refresh to re-evaluate the semantic mapping against current patterns.
• The server caches all event history locally. After the initial ingestion, most queries run entirely offline — no Jira connection needed.

---

🧪 Simulation Engines

Forecasts run on a selectable simulation engine, set via MCS_ENGINE:

Value	Behaviour
crude (default)	Baseline Monte Carlo over the empirical throughput histogram.
bbak	Regime-aware sampling — weights recent process regimes more heavily.
auto	Backtests both against your history and uses whichever scored more accurately.

New forecasting approaches ship as additional engine values and are opt-in until they prove out, so the default behaviour never changes underneath you. The earlier gate-based system (MCS_ALLOW_EXPERIMENTAL plus a set_experimental tool) has been removed — if you used it, MCS_ENGINE=bbak is the replacement.

See Architecture: Multi-Engine Framework sections 4.6–4.8 for how selection and backtesting work.

---

🎲 Offline Testing & Simulation (mockgen)

If you do not have a live Jira connection (or simply want to test the server's analytical capabilities without using sensitive corporate data), MCS-MCP includes a built-in mock data generator called mockgen.

This tool produces a standardized, simulated dataset that you can analyze using MCSTEST as project key and board name. The MCP-Server then operates based on the files MCSTEST_0.jsonl and MCSTEST_0_workflow.json which are expected to be in the cache/ directory.

For comprehensive details on how to use mockgen, configure data distributions (mild, chaotic, drifted), and rebuild the cached simulation, please check the Mock Data Generator Guide.

---

⚠️ Probabilistic Nature & Disclaimer

MCS-MCP is a statistical tool. It generates probabilistic forecasts based on historical performance, not guarantees.

• No Direct Answer: A forecast saying "85% confidence by Oct 12" means there is a 15% chance it will take longer.
• Garbage In, Garbage Out: Results are strictly dependent on the quality and consistency of your Jira data.
• No Liability: This tool is provided "AS IS". The authors and contributors are not responsible for any project delays, financial losses, or business decisions made based on its output.

---

📖 Guided Interaction

MCS-MCP is designed to be used by AI Agents as a "Technical Co-Pilot". For detailed guidance on specific workflows, refer to:

• Project Charter: Conceptual foundations and architectural principles.
• Interaction Use Cases: Detailed scenarios for PMs and AI Agents (When, Scope, Bottlenecks, Backtesting, etc.).
• Architecture Deep-Dive: Internal mechanics, tool directory, analytical pipeline, and data flow. The primary reference for AI Agents interacting with this server.
• Mock Data Generator: Instructions for using mockgen and manipulating the MCSTEST synthetic sandbox.

---

Developing & Contributing

To be honest, I havent thought that through.

If you want to contribute, get in touch. I welcome any feedback, because tools like this get better by being exposed to many different projects. If any diagnosis or forecast feels off, let me know.

If you want to develop, make sure your Coding Agent reads .agent/rules/preferences.md - especially since this points to further relevant files.

---

⚖️ Conceptual Integrity

This project adheres to the core principles of Cohesion, Coherence, and Consistency. Every tool and analytical model is designed to provide a unified, reliable view of delivery performance without administrative noise.

---

Acknowledgements

• Redidence Time is based on the work of Krishna Kumar and our implementation is heavily based on and validated against his reference implementation in the Sample Path Analysis Toolkit.

---

📜 License

This project is licensed under the Apache License 2.0. See the LICENSE and NOTICE files for details.

Copyright © 2026 Bruno Baketarić.