内容
# 精益计划MCP
[](https://github.com/jeffmodeler/lean-planning-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/downloads/)
> 美国英语 · 巴西葡萄牙语 [Português](README.pt-BR.md)
模型上下文协议（MCP）服务器，暴露项目进度计划 — **Microsoft Project, Primavera P6 和 Synchro Scheduler** — 给LLM客户端，如Claude Desktop和Claude Code。读取进度计划、资源、依赖关系、关键路径数据和基准差异 — 并添加 **AWP** （高级工作包装，CII）和 **LPS** （最后计划者系统，精益）层用于工作包计划、约束、每周承诺和PPC跟踪。所有操作都在本地进行，无需云调用，也无需进度计划工具许可证。
## 为什么
建筑、工程和BIM工作流程都依赖于Microsoft Project进度计划。该服务器允许您的LLM：
- 检查项目进度计划并回答相关问题（截止日期、关键路径、资源超载）。
- 将任务数据与BIM模型中的数量或与Power BI仪表板中的成本数据进行交叉引用。
- 为下游自动化生成JSON导出（仪表板、报告、ETL管道）。
它设计为只读的。项目编辑保留在其应有的位置：Microsoft Project本身。
## 需求
- Python 3.11+
- 兼容MCP的客户端（Claude Desktop，Claude Code等）
- 对于`.xml`（MSPDI）：无需额外依赖
- 对于其他格式：可选的`[mpp]`额外依赖（需要通过`mpxj`包的JVM）
## 支持的格式
| 格式 | 扩展名 | 需要 `[mpp]` 额外依赖 |
|---|---|---|
| Microsoft Project MSPDI XML | `.xml` | 否 |
| Microsoft Project本地 | `.mpp`, `.mpx` | 是 |
| Primavera P6导出 | `.xer` | 是 |
| Primavera P6 XML（PMXML） | `.pmxml`, `.xml`* | 是 |
| Synchro Scheduler | `.sp` | 是 |
| Asta Powerproject | `.pp` | 是 |
*`.xml`文件如果不是MSPDI，则会自动尝试通过通用读取器（mpxj）进行读取，因此保存为`.xml`的P6 XML导出也支持。
Synchro注意：mpxj读取Synchro Scheduler `.sp`文件直到它支持的版本；对于最近的Synchro 4D Pro项目，从Synchro导出XER或MS Project XML是最可靠的路径。一旦加载，**所有49种工具 — 包括AWP和LPS层 — 都能独立于源格式工作**，因为它们操作于任务UID。
## 安装
### 选项A — `uv`（推荐）
```bash
git clone https://github.com/jeffmodeler/lean-planning-mcp.git
cd lean-planning-mcp
uv sync
```
### 选项B — `pip`
```bash
pip install git+https://github.com/jeffmodeler/lean-planning-mcp.git
```
对于`.mpp`支持：
```bash
uv sync --extra mpp
# 或
pip install "lean-planning-mcp[mpp] @ git+https://github.com/jeffmodeler/lean-planning-mcp.git"
```
## Claude Desktop集成
将以下内容添加到您的`claude_desktop_config.json`：
```json
{
"mcpServers": {
"lean-planning-mcp": {
"command": "uv",
"args": [
"--directory",
"C:\\path\\to\\lean-planning-mcp",
"run",
"lean-planning-mcp"
]
}
}
}
```
重启Claude Desktop。 49种工具在任何对话中都可用（14种核心MS Project + 17种AWP + 18种LPS）。
## 工具
| 工具 | 用途 |
|---|---|
| `load_project` | 加载进度计划到内存 — MSPDI `.xml`, `.mpp`, P6 `.xer`/`.pmxml`, Synchro `.sp`, Asta `.pp` |
| `open_in_ms_project` | 在Microsoft Project中打开已加载（或给定）的项目文件 |
| `project_info` | 标题、作者、进度计划窗口、货币、汇总计数 |
| `list_tasks` | 按类型、关键性、名称子字符串、顶部N筛选任务 |
| `get_task` | 通过UID、ID或名称获取单个任务的完整记录 |
| `list_resources` | 资源，可选地按类型或超负荷筛选 |
| `get_resource_assignments` | 一个或所有资源的分配 |
| `find_overallocated_resources` | 被标记为超负荷的资源 |
| `get_critical_path` | 关键路径上的任务，按开始日期排序 |
| `get_predecessors_successors` | 任务的依赖网络 |
| `get_baseline_variance` | 当前与基准日期和持续时间比较 |
| `get_gantt_data` | 为Gantt图表库格式化的任务 |
| `export_to_json` | 到JSON文件的完整项目导出（或内联） |
| `generate_pbip_dashboard` | 生成Power BI项目（.pbip）并在Power BI Desktop中打开 |
## 导出`.mpp`到MSPDI XML
如果您不想为可选的`mpp`额外依赖安装Java，请从Microsoft Project以XML格式导出进度计划：
1. 在Microsoft Project中打开`.mpp`文件。
2. **文件 → 另存为 → 保存类型 → XML格式（*.xml）**。
3. 将`load_project`指向生成的`.xml`文件。
XML格式是官方的Microsoft Project数据交换（MSPDI）模式，包含任务、资源、分配、前任、基准和大部分项目元数据。
## 示例提示
加载项目后，询问Claude：
```
加载位于C:\schedules\obra-acme.xml的项目
给我关键路径，单位为天。
哪些资源超负荷，超负荷多少？
列出5个基准差异最大的任务。
将整个项目导出到C:\reports\obra-acme.json
```
## 两层，刻意分离
AWP和LPS生活在同一个服务器中，但作为**独立层**在同一个进度计划上运行。它们持久化到单独的侧边栏文件（`awp.json`和`lps.json`），不共享状态，彼此不依赖：
- **AWP** 组织*范围*：构建内容、位置和包（CWA → CWP → IWP，由工程和采购包提供）。
- **LPS** 组织*承诺流*：团队每周承诺的内容、阻碍因素和计划系统的可靠性。
您可以单独使用任一层，或在同一个`.mpp`上同时使用两者。它们是互补的方法论 — AWP回答“工作包是否准备好发布？”，LPS回答“团队本周是否会实际执行？” — 但在这个服务器中，它们被刻意独立运行。
## AWP — 高级工作包装
建筑业协会（CII RT-272 / RT-319）方法论。将执行分解为工程、采购和现场的对齐包：
```
CWA（施工工作区）→ CWP（施工工作包）
↓
IWP（安装工作包）
EWP（工程工作包） ─┐
├→ 门控CWP就绪
PWP（采购工作包） ─┘
```
重点：施工路径作为*规划输入* + 无约束发布。CWP仅在其手动要求可用、所有链接的EWP都已*发布*且所有链接的PWP都已*交付*时才准备就绪。IWP只能在**通过就绪检查后发布到现场** — 工作面规划黄金规则。
### AWP工具
| 工具 | 用途 |
|---|---|
| `awp_list_cwa` | 列出施工工作区 |
| `awp_upsert_cwa` | 创建或更新CWA |
| `awp_list_cwp` | 列出CWP，包含`task_count`, `total_hours`, `any_critical` |
| `awp_upsert_cwp` | 创建或更新CWP（状态：planned/ready/in-progress/complete/on-hold） |
| `awp_assign_task_to_cwp` | 将任务UID链接到CWP（如果已在其他地方，则移动它） |
| `awp_set_cwp_requirements` | 设置CWP需求（材料、文档、访问） |
| `awp_upsert_ewp` | 创建/更新工程工作包（planned/in-progress/issued） |
| `awp_list_ewp` | 列出EWP，可选按CWP |
| `awp_upsert_pwp` | 创建/更新采购工作包（planned/ordered/delivered） |
| `awp_list_pwp` | 列出PWP，可选按CWP |
| `awp_readiness_check` | CWP就绪：需求 + EWP发布 + PWP交付。门控IWP发布 |
| `awp_set_path_of_construction` | 将PoC定义为规划输入（施工团队的决定顺序） |
| `awp_path_of_construction` | 返回PoC — 如果设置了手动顺序，否则从进度计划中派生 |
| `awp_generate_iwps` | 将CWP分解为IWP（默认500小时 — CII团队周大小；标记学科/团队；保留已发布的IWP） |
| `awp_release_iwp` | 将IWP发布到现场 — **如果CWP未通过就绪检查，则阻止** |
| `awp_update_iwp_progress` | 0-100％的现场进度，赚取小时；100％标记完成 |
| `awp_export_wpr` | 生成工作包发布 — 自包含的JSON用于现场团队 |
## LPS — 最后计划者系统
精益施工方法，包含五个规划级别 — 全部实现：
```
主 → 阶段（拉动计划）→ 展望（N周，清除约束）
→ WWP（每周工作计划）→ 每日团队会议
```
**强制核心规则（屏蔽生产，Ballard 1998）**：只有无约束的任务才能进入每周工作计划。`lps_add_commitment`拒绝具有开放约束的任务，除非显式覆盖 — 且覆盖被记录为承诺的风险。
**指标**：**PPC** （计划完成百分比 — 保持承诺），以及 **TA** （预期任务）和 **TMR** （已准备任务），从展望快照中计算 — 这些衡量准备就绪过程的健康状况，而不仅仅是上周的可靠性。
### LPS工具
| 工具 | 用途 |
|---|---|
| `lps_list_phases` | 列出项目阶段 |
| `lps_upsert_phase` | 创建或更新阶段（包含开始/结束日期） |
| `lps_set_pull_plan` | 设置执行顺序（拉动计划）与任务UID |
| `lps_get_pull_plan` | 检索阶段的拉动计划 |
| `lps_annotate_pull_plan` | 在拉动计划条目上记录交接 + 满意条件 |
| `lps_register_constraint` | 注册约束（材料/文档/劳动力/设备/访问/许可/…） |
| `lps_clear_constraint` | 标记约束为已解决 |
| `lps_list_constraints` | 列出约束，并按任务、状态、类型筛选 |
| `lps_lookahead` | N周范围内的待准备/阻塞任务 + 延迟约束警报（`due_date`在任务开始后） |
| `lps_snapshot_lookahead` | 持久化展望快照 — 提供TA/TMR。 每周审查时调用 |
| `lps_add_commitment` | 添加承诺 — **阻塞具有开放约束的任务** （覆盖：`allow_constrained`） |
| `lps_mark_complete` | 用`variance_reason` + 可选`corrective_action` （PDCA）关闭承诺 |
| `lps_log_daily` | 对已承诺的任务（级别5）进行每日团队会议记录 |
| `lps_get_daily_log` | 读取一周的每日团队会议记录 |
| `lps_get_wwp` | 读取每周工作计划 |
| `lps_workable_backlog` | 待准备但未承诺的任务 — 周的备用缓冲区 |
| `lps_reliability` | TA / TMR系列 — 准备就绪过程的健康状况 |
| `lps_ppc` | 计算单个周或最近N周的PPC |
**约束类型**：材料、文档、信息、设计、劳动力、设备、访问、许可、前置条件、其他。
**差异原因**：天气、设计变更、材料延迟、劳动力不可用、设备故障、返工、许可、前置条件未完成、范围变更、其他。
## 配套技能（Claude Code，Claude Desktop，claude.ai）
仓库提供了一个版本化的**自适应技能**，位于
[skills/lean-planning/SKILL.md](skills/lean-planning/SKILL.md)。它检测会话中是否可用MCP工具：
- **操作模式** （MCP存在）：按正确顺序驱动49种工具 — AWP设置顺序、每周LPS仪式（展望 + 快照、二进制关闭 + PPC/差异）、发布门控、指标解释。
- **顾问模式** （MCP不存在）：纯方法论 — 手动PPC/TA/TMR计算从粘贴数据、导出MSPDI XML、IWP大小审查、跨层洞察。技能宣布活动模式并在服务器配置但离线时优雅地回退。
### 安装 — Claude Code
```bash
# Windows
xcopy /E /I skills\lean-planning %USERPROFILE%\.claude\skills\lean-planning
# macOS / Linux
cp -r skills/lean-planning ~/.claude/skills/lean-planning
```
### 安装 — Claude Desktop / claude.ai
上传 [dist/lean-planning-skill.zip](dist/lean-planning-skill.zip) 至
**设置 → 功能 → 技能**。 无MCP服务器时，技能以顾问模式运行； 在配置了MCP服务器的Claude Desktop中，它以完整操作模式运行。
## 侧边栏存储
`.mpp`/`.xml`文件保持权威（保留只读）。在项目文件旁边，一个`<name>.awp/`文件夹保存Microsoft Project不表示良好的元数据：
```
C:\schedules\
├── obra-acme.mpp ← 权威进度计划（从不修改）
└── obra-acme.awp/ ← 侧边栏文件夹，按需创建
├── awp.json ← CWA / CWP / IWP / EWP / PWP + 施工路径
└── lps.json ← 阶段、拉动计划、约束、WWP、快照
```
每次写入都更新 `updated_at` （ISO 8601 UTC）在JSON中。
## 开发
```bash
uv sync --extra dev
uv run pytest -v
uv run ruff check src tests
```
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
