Monte Carlo Simulation Forecasting Mcp

MCS-MCP：面向 Model Context Protocol 的蒙特卡洛模拟

MCS-MCP 是一个 Model Context Protocol（MCP）服务，可将 Claude 等 AI 助手连接到你的 Jira 项目历史记录，实现自然语言交付分析和概率预测。你可以提问，例如 “这 20 个事项什么时候能完成？”、“我们的流程是否越来越可预测？” 或 “事项卡在哪些地方？”，并获得基于团队实际历史表现的回答，而非估算或主观判断。

---

🚀 主要功能

• 交互式图表渲染：每个分析工具都可以渲染交互式图表，通过 localhost HTTP 直接从 MCP 服务提供。图表是独立的 React/Recharts 页面，无需外部依赖。默认启用（MCS_CHARTS_BUFFER_SIZE=20，设为 0 即可禁用）；每个工具响应都包含可在任意浏览器中打开的 chart_url。
• 蒙特卡洛预测：运行 10,000 次以上模拟，以回答“什么时候能完成？”（时长）或“我们能完成多少？”（范围）。使用团队实际历史吞吐量，而非估算。
• 预测回测：通过将预测与自身历史数据进行重放对比，实证验证预测的准确度（滚动前推分析）。
• 可预测性护栏：使用 XmR 控制图检测“特殊原因”变异，评估周期时间、WIP 数量和交付节奏的流程稳定性。
• SLE 达成趋势分析：追踪每周服务级别预期的达成情况和超限严重程度（最大周期时间 + 超限值的 P95）。默认采用滚动窗口 P85 SLE；传入显式的 sle_duration_days 可锁定稳定的 Vacanti 风格基线。
• 工作流语义发现：自动推断每个工作流状态的用途（进行中的工作、等待队列、入口漏斗、终止出口），从而识别真正的瓶颈，而非行政事务带来的开销。
• 流程产出率与放弃分析：通过准确识别工作被丢弃的位置来量化浪费，并按工作类型和工作流阶段进行细分。
• 高保真老化分析：在单个状态级别将当前 WIP 时长与历史常态进行比较，找出“被忽视”的在制事项。
• 分层分析：整个工具套件普遍支持按工作项类型分层。在模拟、吞吐量、周期时间和稳定性分析中将 Bug 与 Story 分开，以揭示产能冲突（“Bug 税”）。
• 样本路径分析（驻留时间）：计算有限 Little 定律恒等式 L(T) = Λ(T) · w(T)，将周期时间、WIP 时长和流动债务统一为连贯的整体视图。还包括 w'(T)（以离开系统的事项为分母的驻留时间）和 Θ(T)（离开率），用于检测流动失衡。驻留时间与逗留时间之间的连贯性差距揭示了活跃事项对系统造成的“端点效应”。
• 战略演变追踪：使用三向控制图（按周／月）进行纵向审查，以检测长期的系统性改进或流程漂移。
• 历史时点回溯：将特定的过去日期设为分析参考点，以重现流程在当时的状态。适用于回顾、事后复盘，或流程变更前后的对比。
• 会话分析窗口：一个 [start, end] 范围可限定所有诊断分析。使用 set_analysis_window 一次设置（例如 {end_date, duration_days} 或两个明确的日期），之后的每项分析——吞吐量、周期时间、流动债务、WIP、产出率、驻留时间等——都会使用相同的窗口。将窗口向前移动“一个月”只需调用一次，而非十次。预测工具使用由自身引擎驱动的样本窗口；其准确度不受诊断分析窗口影响。
• 引导式分析路线图：服务会主动针对特定目标（预测、瓶颈分析、产能规划）建议合适的诊断步骤顺序，避免 AI Agent 猜测正确的分析路径。

---

🧱 局限性与假设

• 服务不会使用 Jira 的工作流相关 REST API。它会根据实际的问题转换推断工作流；如果——这也是前提——看板上的所有工作项类型共用同一工作流，或者更准确地说，按照相同顺序共用相同状态，那么这种方法非常可靠。如果该假设不成立，工作流发现会产生不可预测的结果，分析、诊断和预测功能也可能受到干扰。我不确定是否会处理这类情况，因为在我看来，跨不同工作流分析流程毫无意义（欢迎证明我错了）。
• 出于同样的原因，服务目前基于看板运行，不允许你向它传递 JQL。一个简单的解决方法显而易见：使用你的查询作为看板 JQL 创建看板。请务必留意自己的操作。

---

🛡️ 数据安全与 GRC 原则

Atlassian Jira 这类工作管理系统通常包含敏感的项目和个人数据。MCS-MCP 采用安全设计方法构建，并遵循两项基本治理原则：

1. “按需知悉”原则（数据最小化）

为保护知识产权和隐私，服务会严格限制摄取和持久化的数据。

• 我们摄取并持久化的内容：仅分析元数据——问题键、问题类型、状态转换、时间戳和解决方案名称。这是进行高保真流程分析所需的最少数据。
• 我们丢弃的内容：虽然 Jira API 可能会返回完整的问题对象，但系统经过设计，会立即丢弃标题、描述、验收标准或经办人等敏感内容。

这样一来，即使服务缓存遭到入侵，其中也不包含任何可能泄露项目机密或个人身份信息的可读内容。此外，由于分析引擎不会处理这些数据，也不会将其存储在内存中，因此在交互过程中，敏感内容不可能泄露给 AI Agent。

2. 透明性原则（可审计性）

我们坚持“没有黑箱”。初次摄取后，服务主要通过本地缓存运行。

• 人类可读的缓存：所有持久化数据（事件日志、工作流映射）都以标准的、人类可读的格式（JSON 和 JSON-Lines）存储在数据目录中。
• 逻辑可验证：你可以随时检查或监控这些文件，以确认没有敏感数据泄露到服务的长期记忆中。

---

🛠️ 工作原理（概览）

1. 数据摄取：服务会从项目中的看板获取 Jira 条目，并根据这些条目的状态变更日志重建完整的事件溯源历史记录。

2. 工作流映射：每个 Jira 工作流都各不相同。在开始分析之前，服务需要了解每个状态的_用途_。它会提出一套映射，将工作流映射到四层元工作流：

   • 需求：入口漏斗——尚未承诺处理的想法和待办事项。
   • 上游：分析和细化——已开始处理，但尚未承诺交付的工作。
   • 下游：积极执行——编码、测试、审查。这是“承诺区”。
   • 已完成：终止状态——已完成、已取消、已丢弃。

   服务会自动提出这套映射，同时确定“完成”的含义（已交付还是已放弃），以及承诺点所在的位置（工作正式开始的状态——这决定周期时间和在制品）。你确认后，这些设置会被缓存，因此每个看板只需配置一次。

3. 设置分析窗口：诊断需要一个时间范围，也就是要查看的历史记录片段。每个会话只有一个窗口，供所有诊断共用：吞吐量、周期时间、流程债务、在制品稳定性、产出率、驻留时间、状态持久性、流程稳定性、工作项年龄（在结束日期截取快照），以及流程演变（以结束日期为长期锚点）。窗口默认设为截至今天的滚动 26 周；AI 会调用 set_analysis_window 来更改窗口（使用 {end_date, duration_days} 或两个明确日期），而“向前回退一个月”只需调用一次，不是十次。预测（forecast_monte_carlo、forecast_backtest）则有意不受此限制——它们的样本窗口由模拟引擎选择，以提高预测准确性，并独立于诊断视角。

4. 诊断与预测：有了数据、对各个状态_含义_的清晰理解，以及选定的窗口后，你可以询问 AI 各种有关交付系统健康状况、可预测性和未来吞吐量的问题。

---

🏃 入门

前置条件

• 可访问 Atlassian Jira（Data Center 或 Cloud）
• 一个支持 MCP 的 AI Agent，可与之聊天（我使用 Claude Desktop）
• 如果想自行构建，需要较新版本的 Go；如果下载发行版则无需安装

安装

1. 从源代码构建（参见从源代码构建）或下载一个发行版。
2. 将 mcs-mcp.exe（或 mcs-mcp）复制到你选择的位置（构建者请查看 dist/）。
3. 运行一次。它会在数据文件夹中创建一个带注释的 .env 文件——默认位于所在平台的标准用户目录（Windows 上为 %AppData%\mcs-mcp，macOS 上为 ~/Library/Application Support/mcs-mcp，Linux 上为 ~/.config/mcs-mcp），参见设置的来源——其中预先填入了所有设置及其默认值。编辑该文件：至少需要提供 Jira 实例信息和身份验证方式（参见身份验证）。你的修改不会被覆盖。
4. 如需将数据存放在其他位置，请使用 --data-path /path/to/writable/dir 启动（或设置 DATA_PATH 环境变量），它会将数据（包括 .env）存放在那里。
5. 配置 AI Agent，将其作为 MCP 工具使用（参见Agent 配置）。通常需要重启 Agent 才能使更改生效。
6. 开始对话：
   • 告诉 AI Agent 你要查看哪个项目和哪个看板。
   • 告诉 Agent 发现工作流。仔细检查其方案是否符合你的实际流程。你应确认层级（需求、上游、下游、已完成），哪些解决结果或终止状态代表_已交付_，哪些代表_已放弃_（这决定了哪些内容计入吞吐量），以及你的承诺点是什么（工作正式开始时所处的状态——这决定了周期时间和在制品），当然还要确认工作流状态的顺序。这些选择会被缓存，因此只需确认一次（除非你清空 cache 文件夹）。
   • 请 Agent 提供诊断路线图，以获取目标导向的工具使用顺序（例如，“我想预测 15 个事项”或“我想了解是什么拖慢了我们的进度”）。
   • 如需分析系统在过去某个时间点的状况（例如用于回顾或复盘），可以选择让 Agent 设置一个评估日期。

身份验证

该服务支持 3 种身份验证方式。请在 .env 文件中设置，或通过 Agent 的 env 区块设置。

JIRA_TOKEN_TYPE 会自动推断，通常无需设置：如果存在 JIRA_USER_EMAIL，服务会使用 api（Jira Cloud，Basic 身份验证）；否则使用 pat（Data Center，Bearer 身份验证）。只有需要覆盖此行为时才显式设置。启动时，服务会在日志中记录所选模式（mode=basic|bearer|cookie|none）——如果身份验证失败，请先检查这一行。

不适用的变量可以留空或注释掉；空值会被视为未设置。

选项 A：Jira Datacenter 的个人访问令牌（PAT）

JIRA_TOKEN=your-personal-access-token

选项 B：Jira Cloud 的 API 令牌

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

选项 C：会话 Cookie——备用方式

如果以上方式均不可用，请提供从当前浏览器会话中提取的会话 Cookie：

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

只有未设置令牌时才会使用 Cookie。如果两者都已配置，则优先使用令牌，服务也会在日志中说明这一点。

请注意，Cookie a）可能会不时过期；b）Atlassian 可能会采取措施阻止以这种方式使用会话 Cookie。

从源代码构建

下载源代码或克隆仓库。

在 Windows 上（PowerShell）：

.\build.ps1 build

在 Unix/Linux/MacOS 上（Make）：

未经测试，但应该可用。

make build

生成的二进制文件位于 dist/ 文件夹中，同时还会有一个示例 .env 文件。该示例由 internal/config/template.go 生成——请在那里编辑注册表，而不是编辑 conf/.env-example；测试会确保两者保持同步。

Agent 配置

要将其用作 AI Agent（如 Claude 或 Gemini）的服务，请将 MCP 客户端配置指向编译后的二进制文件：

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

默认情况下，服务会将 cache、logs 和 .env 保存在适用于你平台的用户专属位置（请参阅设置来源）。若要将它们存放在其他位置，请传入 --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"
			}
		}
	}
}

env 块中的任何内容优先级都高于 .env 文件（请参阅设置来源），因此你可以在这里设置凭据，其余设置则留给文件处理。

设置来源

设置按以下顺序解析，优先级从高到低：

1. 进程环境 — MCP 客户端在 env 块中传入的内容
2. 数据文件夹中的 .env — 首次运行时创建的文件；要编辑的就是这个文件
3. 二进制文件旁的 .env — 为向后兼容而支持
4. 工作目录中的 .env — 用于开发
5. 内置默认值 — 显示在生成的 .env 中

启动时，服务会为每项设置记录一行日志，注明其值的来源 — flag、env、dotenv、default 或 inferred — 因此，无需猜测即可追踪与预期不符的值。对于机密信息，日志只会记录其是否存在，不会记录具体值。

数据文件夹本身是个例外。 在找到任何 .env 文件之前，必须先确定数据文件夹，因此它只从 --data-path 标志或 DATA_PATH 环境变量读取 — 按此顺序读取；若两者均未设置，则依次回退到适用于你平台的标准用户专属位置（%AppData%\mcs-mcp、~/Library/Application Support/mcs-mcp、~/.config/mcs-mcp）、二进制文件目录、系统临时文件夹，最后是工作目录。

在 .env 文件中设置 DATA_PATH 不会生效；服务发现此设置时会发出警告。

从 0.21 或更早版本升级？ 默认数据文件夹的位置已更改。早期版本会将 cache、logs 和 .env 保存在二进制文件旁；现在默认使用上文列出的用户专属位置。如果你从未设置 --data-path 或 DATA_PATH，服务启动时会使用空缓存，并从 Jira 重新摄取数据。不会删除任何内容 — 若要保留历史记录，请将 --data-path 指向旧文件夹，或将其内容移至新位置。

如果你在 .env 中设置了 DATA_PATH，请将其移至 --data-path 或真实的环境变量中；它在 .env 中从未生效。服务会检测到这种情况，并在日志中明确说明。

可选设置

可在 .env 文件中设置以下可选变量：

Variable	Default	Description
JIRA_TOKEN_TYPE	(inferred)	api 或 pat。未设置时，根据 JIRA_USER_EMAIL 推断。
JIRA_DEPLOYMENT	(detected)	cloud 或 datacenter。从服务器检测；仅在检测失败时设置。
VERBOSE	false	将详细调试信息写入日志文件。
COMMITMENT_POINT_BACKFLOW_RESET_CLOCK	true	回退越过承诺点时，重置周期时间和 WIP 时长计时。
JIRA_REQUEST_DELAY_SECONDS	10	Jira REST API 请求之间强制等待的时间（秒）。
MCS_CHARTS_BUFFER_SIZE	20	图表渲染缓冲区（0=关闭，1-100=开启）。将在 localhost 上启动 HTTP 服务。
MCS_ENGINE	crude	模拟引擎：crude、bbak（感知状态机制）或 auto（由回测驱动）。
MCS_ENGINE_CRUDE	50	粗略引擎的权重（0=禁用）。在 auto 模式下用于打破平局。
MCS_ENGINE_BBAK	50	bbak 引擎的权重（0=禁用）。在 auto 模式下用于打破平局。
INGESTION_UPDATED_LOOKBACK	24	初始 Jira 填充 JQL 中 updated >= 条件向前回溯的月数。
INGESTION_CREATED_LOOKBACK	36	created >= 条件向前回溯的月数。用于捕获近期未更新的长期存在项目。
INGESTION_MAX_ITEMS	5000	初始填充的分页上限。向前补齐（import_history_update）不设上限。

此处未列出 DATA_PATH，因为在 .env 中设置它不会生效——请使用 --data-path 或环境变量。

命令行标志

Flag	Description
--data-path	cache、logs 和 .env 的基础目录。优先于 DATA_PATH。

---

📊 图表渲染

MCS-MCP 在服务端渲染交互式图表。当 MCS_CHARTS_BUFFER_SIZE 设置为 1 到 100 之间的值时，服务会在随机的 localhost 端口（3000-4000）上启动 HTTP 监听器。

本版本变更： 图表现在默认启用（MCS_CHARTS_BUFFER_SIZE=20）。此前内置默认值为 0，只有因为随附的 .env-example 设置了 20，图表才会启用。如果从未设置此变量，且不希望启动本地监听器，请显式设置 MCS_CHARTS_BUFFER_SIZE=0。每个分析工具的响应都会在 context 字段中包含一个 chart_url。在浏览器中打开该 URL，即可渲染一个包含工具数据的独立 React/Recharts 图表。

服务会缓冲最近的 N 条工具结果（MRU）。缓冲区已满时，会淘汰较早的条目。访问 URL 时才会按需渲染图表。

从 AI Agent 打开图表 URL

该服务提供了一个 open_in_browser 工具，AI Agent 可以调用它，将 chart_url 直接在系统默认浏览器中打开——无需浏览器扩展或手动复制粘贴。运行任意分析工具后，Agent 可以立即接着调用 open_in_browser 来显示图表。

如果 Agent 因任何原因没有调用 open_in_browser，你也可以随时从工具响应中复制 chart_url，然后手动粘贴到任意浏览器中。图表完全独立，初次加载后无需保持与服务的连接。

旧版本用户须知： 旧版基于 Skills 的图表渲染方式（docs/skills/、inject.py）已移除。现在图表完全由服务端渲染。如果你在 Claude Desktop 中安装了 mcs-mcp.skill 文件，请卸载或停用它，以避免冲突。

---

👉 使用技巧

• 在会话开始时，请 Agent 提供诊断路线图。它会返回一系列以目标为导向的工具，让你始终有清晰的分析路径，而不是猜测下一步该运行什么。
• 团队重组、工作流全面调整等重大流程变更后，让 Agent 强制刷新并重新运行工作流发现，以根据当前模式重新评估语义映射。
• 服务会在本地缓存所有事件历史。完成初次导入后，大多数查询都可以完全离线运行——无需连接 Jira。

---

🧪 模拟引擎

预测由可选的模拟引擎运行，通过 MCS_ENGINE 设置：

值	行为
crude（默认）	基于经验吞吐量直方图进行基线蒙特卡洛模拟。
bbak	感知状态的采样——对近期流程状态赋予更高权重。
auto	根据你的历史数据对两种引擎进行回测，并采用评分更准确的引擎。

新的预测方法会作为额外的引擎值推出，在验证可行之前均为选择启用，因此默认行为不会在你不知情的情况下发生变化。之前基于门控的系统（MCS_ALLOW_EXPERIMENTAL 和 set_experimental 工具）已移除——如果你曾使用该系统，现在可改用 MCS_ENGINE=bbak。

有关引擎选择和回测的工作原理，请参阅**架构：多引擎框架** 第 4.6–4.8 节。

---

🎲 离线测试与模拟（mockgen）

如果你没有可用的 Jira 连接（或者只想在不使用敏感公司数据的情况下测试服务的分析能力），MCS-MCP 内置了一个名为 mockgen 的模拟数据生成器。

该工具会生成标准化的模拟数据集，你可以使用 MCSTEST 作为项目键和看板名称来分析这些数据。MCP-Server 随后会根据预期存放在 cache/ 目录中的 MCSTEST_0.jsonl 和 MCSTEST_0_workflow.json 文件运行。

有关如何使用 mockgen、配置数据分布（mild、chaotic、drifted）以及重建缓存模拟数据的详细信息，请参阅 模拟数据生成器指南。

---

⚠️ 概率性质与免责声明

MCS-MCP 是一种统计工具。它根据历史表现生成概率预测，而非保证。

• 并非确定答案：预测称“截至 10 月 12 日的置信度为 85%”，意味着有 15% 的可能需要更长时间。
• 垃圾进，垃圾出：结果完全取决于 Jira 数据的质量和一致性。
• 不承担责任：本工具按“原样”提供。作者和贡献者不对依据其输出作出的任何项目延期、财务损失或商业决策负责。

---

📖 引导式交互

MCS-MCP 专为 AI Agent 作为“技术副驾驶”使用而设计。有关特定工作流的详细指导，请参阅：

• 项目章程：概念基础与架构原则。
• 交互用例：面向 PM 和 AI Agent 的详细场景（时机、范围、瓶颈、回测等）。
• 架构深入解析：内部机制、工具目录、分析流水线和数据流。是 AI Agent 与此服务交互时的主要参考资料。
• 模拟数据生成器：有关使用 mockgen 和操作 MCSTEST 合成沙盒的说明。

---

开发与贡献

坦白说，我还没想好。

如果你想贡献，请与我联系。我欢迎任何反馈，因为这类工具通过接触各种不同的项目才能变得更好。如果任何诊断或预测感觉不准确，请告诉我。

如果你想参与开发，请确保你的编码 Agent 阅读 .agent/rules/preferences.md，尤其是因为该文件还指向其他相关文件。

---

⚖️ 概念完整性

本项目遵循内聚性、一致性和连贯性的核心原则。每个工具和分析模型都旨在提供统一、可靠的交付表现视图，避免行政事务带来的干扰。

---

致谢

• Redidence Time 基于 Krishna Kumar 的工作，我们的实现大量参考了其在 Sample Path Analysis Toolkit 中的参考实现，并以其为基准进行了验证。

---

📜 许可证

本项目根据 Apache License 2.0 许可。详情请参阅 LICENSE 和 NOTICE 文件。

版权所有 © 2026 Bruno Baketarić。