{"id":44485892,"url":"https://github.com/bbak/mcs-mcp","last_synced_at":"2026-04-02T00:12:51.833Z","repository":{"id":337226687,"uuid":"1141255403","full_name":"bbak/mcs-mcp","owner":"bbak","description":"Provide Monte-Carlo-Simulation and Flow Data diagnostics to AI Agents","archived":false,"fork":false,"pushed_at":"2026-03-06T00:25:27.000Z","size":1271,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-06T02:41:48.252Z","etag":null,"topics":["analysis","cycle-time","diagnostics","flow-metrics","forecasting","mcs","stratified","throughput","wip","xmr"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-24T14:39:00.000Z","updated_at":"2026-03-05T22:09:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bbak/mcs-mcp","commit_stats":null,"previous_names":["bbak/mcs-mcp"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/bbak/mcs-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbak%2Fmcs-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbak%2Fmcs-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbak%2Fmcs-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbak%2Fmcs-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbak","download_url":"https://codeload.github.com/bbak/mcs-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbak%2Fmcs-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30238246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T23:52:25.683Z","status":"ssl_error","status_checked_at":"2026-03-07T23:52:25.373Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["analysis","cycle-time","diagnostics","flow-metrics","forecasting","mcs","stratified","throughput","wip","xmr"],"created_at":"2026-02-13T01:59:37.600Z","updated_at":"2026-04-02T00:12:51.821Z","avatar_url":"https://github.com/bbak.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCS-MCP: Monte-Carlo Simulation for Model Context Protocol\n\n**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.\n\n\u003e [!WARNING]\n\u003e Currently, this must be considered _beta_. While it works quite well,\n\u003e the Math is not thoroughly verified. Don't bet your bonus on the\n\u003e forecasts and analysis done by it. Concepts are subject to change, if necessary\n\u003e to make an AI Agent behave the way I envision.\n\u003e I run it in Claude Desktop and Antigravity Agents.\n\n---\n\n## 🚀 Key Capabilities\n\n- **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.\n- **Forecast Backtesting**: Empirically validate how accurate the forecasts would have been by replaying them against your own historical data (Walk-Forward Analysis).\n- **Predictability Guardrails**: Detect \"Special Cause\" variation using XmR Control Charts — assesses process stability for Cycle Time, WIP populations, and Delivery Cadence.\n- **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.\n- **Process Yield \u0026 Abandonment**: Quantify waste by identifying exactly where work is discarded — broken down by work type and workflow stage.\n- **High-Fidelity Aging Analysis**: Identify \"neglected\" inventory by comparing current WIP age against historical norms at the individual status level.\n- **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\").\n- **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.\n- **Strategic Evolution Tracking**: Longitudinal audits using Three-Way Control Charts (weekly/monthly) detect systemic improvements or process drift over time.\n- **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.\n- **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.\n\n---\n\n## 🧱 Limitations and Assumptions\n\n- 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).\n- 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.\n\n---\n\n## 🛡️ Data Security \u0026 GRC Principles\n\nWork-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:\n\n### 1. The \"Need-to-Know\" Principle (Data Minimization)\n\nTo protect intellectual property and privacy, the server strictly minimizes the data it ingests and persists.\n\n- **What we ingest \u0026 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.\n- **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**.\n\nThis 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.\n\n### 2. The Transparency Principle (Auditability)\n\nWe believe in \"No Black Boxes.\" The server operates primarily from its local caches after the initial ingestion.\n\n- **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.\n- **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.\n\n---\n\n## 🛠️ How it Works (high-level)\n\n1. **Ingestion**: The server fetches Jira items from a Board within a Project and reconstructs a complete, event-sourced history from their transition logs.\n\n2. **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:\n   - **Demand**: The entry funnel — ideas and backlog items not yet committed to.\n   - **Upstream**: Analysis and refinement — work that has been picked up but not yet committed to delivery.\n   - **Downstream**: Active execution — coding, testing, review. This is the \"commitment zone.\"\n   - **Finished**: Terminal states — done, cancelled, discarded.\n\n   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.\n\n3. **Diagnostics \u0026 Forecasting**: With the data and a clear understanding of what each status _means_, you can ask the AI a wide range of questions about your delivery system's health, predictability, and future throughput.\n\n---\n\n## 🏃 Getting Started\n\n### Prerequisites\n\n- Access to Atlassian Jira (Data Center or Cloud)\n- A MCP-capable AI Agent to chat with (Claude Desktop is mine)\n- Recent Version of Go if you want to build yourself\n\n### How-To\n\n1. Build from sources (see [Building from Sources](#building-from-sources)) or download a release.\n2. Copy `mcs-mcp.exe` (or `mcs-mcp`) and `.env-example` to a location of your choice (for builders, look into `dist/`).\n3. Rename `.env-example` to `.env` and modify it accordingly. At a minimum, you need to provide information about your Jira instance and how to authenticate (see [Authentication](#authentication)).\n4. Especially for **MacOS Users**: Make sure that the MCP-Server either has write permissions on the path of the binary (`mcs-mcp`) or use the `DATA_PATH` setting in `.env` to point to directory, where it has, because it needs to create two folders (`cache` and `logs`) and write files to it.\n5. Configure an AI Agent to use it as an MCP tool (see [Agent Configuration](#agent-configuration)). Typically, you need to restart the Agent for the changes to take effect.\n6. Chat:\n   - Tell the AI Agent which Project and which Board you want to look at.\n   - 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).\n   - 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\"_).\n   - 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).\n\n### Authentication\n\nThe server supports 3 ways of Authentication through setting variables in the `.env` file.\n\nNote: Please make sure that those auth-related variables, that don't apply, are commented out.\n\n#### Option A: Personal Access Token (PAT) for Jira Datacenter\n\n```env\nJIRA_TOKEN_TYPE=pat\nJIRA_TOKEN=your-personal-access-token\n```\n\n#### Option B: API Token for Jira Cloud\n\n```env\nJIRA_TOKEN_TYPE=api\nJIRA_TOKEN=your-api-token\nJIRA_USER_EMAIL=your-jira-account-email\n```\n\n#### Option C: Session Cookies - Fallback\n\nIf neither is available, provide session cookies extracted from an active browser session:\n\n```env\nJIRA_SESSION_ID=jira-session-ID\nJIRA_XSRF_TOKEN=XSRF-token\nJIRA_REMEMBERME_COOKIE=Jira-RememberMe-cookie\nJIRA_GCILB=optional-google-cloud-load-balancer-cookie-GCILB\nJIRA_GCLB=optional-google-cloud-load-balancer-cookie-GCLB\n```\n\nNote that Cookies a) might expire from time to time and b) Atlassian may take measures to prevent the use of session cookies this way.\n\n### Building from Sources\n\nDownload Sources or clone the repository.\n\n**On Windows (PowerShell):**\n\n```powershell\n.\\build.ps1 build\n```\n\n**On Unix/Linux/MacOS (Make):**\n\nUntested, but should work.\n\n```bash\nmake build\n```\n\nThe resulting binary will be located in the `dist/` folder along with a exemplary `.env` file.\n\n### Agent Configuration\n\nTo use as a server for an AI Agent (like Claude or Gemini), point your MCP client configuration to the compiled binary:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"mcs-mcp\": {\n\t\t\t\"command\": \"/path/to/mcs-mcp/mcs-mcp.exe\",\n\t\t\t\"args\": []\n\t\t}\n\t}\n}\n```\n\nMake sure that the Server can write to this directory to create `cache` and `logs` folders - or reconfigure using `DATA_PATH`.\n\n### Optional Settings\n\nThese optional variables can be set in the `.env` file:\n\n| Variable                                | Default      | Description                                                                                 |\n| :-------------------------------------- | :----------- | :------------------------------------------------------------------------------------------ |\n| `DATA_PATH`                             | (binary dir) | Base folder for logs and cache.                                                             |\n| `VERBOSE`                               | `false`      | Write detailed debug information to the log file.                                           |\n| `ENABLE_MERMAID_CHARTS`                 | `false`      | Include text-based Mermaid.js charts in analytical tool results.                            |\n| `COMMITMENT_POINT_BACKFLOW_RESET_CLOCK` | `true`       | Reset Cycle Time and WIP Age clock on backflow past commitment point.                       |\n| `JIRA_REQUEST_DELAY_SECONDS`            | `5`          | Enforced delay (in seconds) between requests to the Jira REST API.                          |\n| `MCS_ALLOW_EXPERIMENTAL`                | `false`      | Enable the experimental feature gate. See [Experimental Features](#-experimental-features). |\n\n---\n\n## 🧩 Skills\n\nMCS-MCP comes with Skills that can be used by an Agent to create Charts from the data sent by the MCP-Server. All tools are covered.\n\nThis is tested only in Claude Desktop. And even though I did my best to make it Agent agnostic, the approach taken was necessary to prevent high Token consumption, context window bloat and achieve a acceptable performance.\n\nYet, a `.skill` file is just a ZIP-Archive with another file extension. Feel free to adopt them to your (visual) needs.\n\n1. Import `mcs-mcp.skill` as SKILL file.\n2. Start a new session.\n3. Run some analysis or forecast and tell the Agent (Claude) to also create a Chart.\n\n---\n\n## 👉 Usage Tips\n\n- Many Agents can create Charts directly from the data returned by the MCP-Server. In Claude Desktop, a prompt like _\"Please create a Chart for WIP\"_ works well. For specific chart types, install the relevant Skill from the `docs/skills/` directory.\n- 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.\n- 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.\n- The server caches all event history locally. After the initial ingestion, most queries run entirely offline — no Jira connection needed.\n\n---\n\n## 🧪 Experimental Features\n\nMCS-MCP includes an experimental feature system for testing improvements to the forecasting engine before they become the default. Experimental features are **off by default** and require two deliberate steps to activate:\n\n1. **Operator enables the gate** by setting `MCS_ALLOW_EXPERIMENTAL=true` in `.env`.\n2. **The AI Agent activates experimental mode** for the current session by calling the `set_experimental` tool. This persists until explicitly disabled — it is not reset when switching boards.\n\nWhen both steps are satisfied, the forecasting tools gain access to experimental code paths. When either step is missing, the server behaves identically to stable production mode.\n\nFor details on active experiments — what they do, parameters, known limitations, and graduation criteria — see **[Experimental Features Documentation](docs/experimental.md)**.\n\n---\n\n## 🎲 Offline Testing \u0026 Simulation (mockgen)\n\nIf 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`.\n\nThis 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.\n\nFor 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](docs/mockdata.md)**.\n\n---\n\n## ⚠️ Probabilistic Nature \u0026 Disclaimer\n\nMCS-MCP is a statistical tool. It generates **probabilistic forecasts** based on historical performance, not guarantees.\n\n- **No Direct Answer**: A forecast saying \"85% confidence by Oct 12\" means there is a 15% chance it will take longer.\n- **Garbage In, Garbage Out**: Results are strictly dependent on the quality and consistency of your Jira data.\n- **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.\n\n---\n\n## 📖 Guided Interaction\n\nMCS-MCP is designed to be used by AI Agents as a \"Technical Co-Pilot\". For detailed guidance on specific workflows, refer to:\n\n- **[Project Charter](docs/charter.md)**: Conceptual foundations and architectural principles.\n- **[Interaction Use Cases](docs/use-cases.md)**: Detailed scenarios for PMs and AI Agents (When, Scope, Bottlenecks, Backtesting, etc.).\n- **[Architecture Deep-Dive](docs/architecture.md)**: Internal mechanics, tool directory, analytical pipeline, and data flow. The primary reference for AI Agents interacting with this server.\n- **[Mock Data Generator](docs/mockdata.md)**: Instructions for using `mockgen` and manipulating the `MCSTEST` synthetic sandbox.\n\n---\n\n## Developing \u0026 Contributing\n\nTo be honest, I havent thought that through.\n\nIf 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.\n\nIf you want to develop, make sure your Coding Agent reads `.agent/rules/preferences.md` - especially since this points to further relevant files.\n\n---\n\n## ⚖️ Conceptual Integrity\n\nThis 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.\n\n---\n\n## Acknowledgements\n\n- **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](https://github.com/presence-calculus/samplepath-flow).\n\n---\n\n## 📜 License\n\nThis project is licensed under the **Apache License 2.0**. See the [LICENSE](LICENSE) and [NOTICE](NOTICE) files for details.\n\nCopyright © 2026 Bruno Baketarić.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbak%2Fmcs-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbak%2Fmcs-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbak%2Fmcs-mcp/lists"}