# LogicMCP Server

> **Before writing code, align the logic.**
>
> 在第一行程式碼出現之前，先確認需求、架構與交付目標指向同一個方向。

LogicMCP Server 是以 [FastMCP 3](https://gofastmcp.com/) 建置的需求工程服務。前三個公開 MCP Tools 將模糊想法整理成可追溯的需求書、架構書與稽核報告；第 4 個 Tool 產生可選的 `SKILL.md`。問題生成、LLM Sampling、Schema 驗證、狀態轉移及文件渲染都封裝在 Server 內部。

- `generate_requirements`：建立並接續需求訪談，完成後產生需求書。
- `generate_architecture`：根據已完成的需求工作階段產生架構書。
- `run_audit`：檢查需求與架構的一致性、覆蓋、風險及追溯關係。
- `generate_skill`：輸出 canonical `SKILL.md`，或在不改變核心規則的前提下加入情境化指引。

完整的專案背景與設計理念請見 [LogicMCP Wiki](https://github.com/mydrego-James/LogicMCP_Server/wiki)。

## 1. 故事

AI 已經能快速產生程式碼、文件、架構與測試，軟體開發的瓶頸也因此改變：執行速度越快，方向錯誤造成的返工成本就越高。

常見問題不是「做不出來」，而是：

- 需求尚未確認，實作就已經開始。
- 需求提出者、開發者與 AI 對目標的理解不同。
- AI 自行補上看似合理、但未經確認的條件。
- 局部功能正確，整體業務邏輯卻偏離原始目的。
- 工作分派後，執行者只看到任務，沒有完整背景與限制。
- 開發中出現新條件，卻沒有重新檢查原始規劃。

LogicMCP 的目的不是限制開發速度，也不取代需求提出者、專案經理、顧問、架構師、開發者或 AI Agent。它提供一套可以重複使用的邏輯校準流程，讓人與 AI 在重要工作開始前先建立共同基線。

這套流程可視為適合軟體開發的遞迴 PDCA：

```text
P — Problem / Purpose：確認問題、目標、範圍與限制
                ↓
D — Design：將需求轉換成可執行的技術與工作規劃
                ↓
C — Check / Challenge：檢查缺漏、矛盾、風險與偏離
                ↓
A — Action：交付開發者或 Agent 執行、測試與驗證
```

它可以套用在整個專案，也可以在模組、API、資料庫、UI、單一功能或錯誤修正中重新啟動。上層已確認的目標與限制會成為下一層工作的基線。

> AI 可以持續執行，LogicMCP 負責持續校準方向。

## 2. 安裝

### 2.1 Git／本機安裝

需求：

- Git
- Windows
- Python 3.11 或更新版本

取得專案：

```powershell
git clone https://github.com/mydrego-James/LogicMCP_Server.git
cd LogicMCP_Server
```

建立本機設定：

```powershell
Copy-Item .env.example .env
```

預設設定如下：

```dotenv
MCP_HOST=127.0.0.1
MCP_PORT=8000
MCP_PATH=/mcp
MCP_TRANSPORT=http
MCP_OUTPUT_ROOT=./output
MCP_STATE_ROOT=./output/.logicmcp/sessions
```

安裝並啟動：

```powershell
.\install.bat
.\run.bat
```

預設 MCP endpoint：

```text
http://127.0.0.1:8000/mcp
```

`MCP_STATE_ROOT` 保存需求訪談狀態。若要在 Client 關閉、隔天或 Server 重啟後繼續，請將它放在持久化磁碟中。

### 2.2 Docker 安裝

需求：Docker Engine；若使用 Compose，需同時安裝 Docker Compose。

```powershell
git clone https://github.com/mydrego-James/LogicMCP_Server.git
cd LogicMCP_Server
Copy-Item .env.example .env
docker compose up --build -d mcp
```

查看狀態與 logs：

```powershell
docker compose ps
docker compose logs -f mcp
```

停止服務：

```powershell
docker compose down
```

Compose 預設將 `./logs` 與 `./output` 掛載到 Container。需求訪談狀態保存在 `output/.logicmcp/sessions/`，重建 Container 後仍可使用原本的 `session_id` 接續。

若需要修改對外 IP、port 或持久化路徑，可調整 `.env`：

```dotenv
LOGICMCP_BIND_HOST=127.0.0.1
LOGICMCP_HOST_PORT=8000
LOGICMCP_LOG_DIR=./logs
LOGICMCP_OUTPUT_DIR=./output
```

完整設定與 `docker run` 範例請見 [docker.md](docker.md)。

## 3. 使用：VS Code 範例

### 3.1 連接 LogicMCP

先啟動 LogicMCP Server，然後在要使用它的 VS Code workspace 建立 `.vscode/mcp.json`：

```json
{
  "servers": {
    "logicmcp": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

接著在 VS Code：

1. 開啟 Command Palette（`Ctrl+Shift+P`）。
2. 執行 `MCP: List Servers`。
3. 啟動 `logicmcp`。
4. 在 Chat 的工具清單中確認可看到四個 LogicMCP Tools。

VS Code 所使用的 MCP Client 必須支援 MCP Sampling，因為 Server 會在封閉流程中請 Client 的模型執行受控推理。

### 3.2 建立需求書

可以直接在 Chat 中描述目標：

```text
請使用 LogicMCP，為「建立一套設備維護管理系統」建立需求書，
使用 professional profile，並逐題向我確認。
```

AI 會呼叫：

```json
{
  "tool": "generate_requirements",
  "arguments": {
    "q0": "建立一套設備維護管理系統",
    "profile": "professional"
  }
}
```

Server 會回傳 `session_id`、目前問題與訪談狀態。回答問題時，AI 會使用同一個 Tool：

```json
{
  "tool": "generate_requirements",
  "arguments": {
    "session_id": "SERVER_RETURNED_SESSION_ID",
    "answer": "由維修主管與現場技師使用。"
  }
}
```

若中斷對話，只要保留 `session_id`，之後可要求：

```text
請使用 session_id「SERVER_RETURNED_SESSION_ID」接續上次的需求訪談。
```

只傳入 `session_id` 時，Server 會讀取上次通過驗證的狀態並回傳目前問題，不會重問已接受的答案。

### 3.3 建立架構書

需求書完成後，在 Chat 中要求：

```text
請使用同一個 LogicMCP session 產生架構書。
```

對應呼叫：

```json
{
  "tool": "generate_architecture",
  "arguments": {
    "session_id": "SERVER_RETURNED_SESSION_ID"
  }
}
```

需求階段與技術架構階段共用同一批 `prompts/profiles/*.txt` 能力定義。需求階段可以依問題切換焦點；架構階段則讀取第一階段完整的問題、答案、判定及 `capability_profile`，只進行一次整體焦點對應，再把相關 TXT 合併成單一 AI 技能邊界加入架構 Prompt，不會再次逐題切換身分。兩階段仍使用不同的 Prompt 契約與 Markdown 渲染模板，因此分別產生需求書與架構書，不會把兩種文件混成同一份模板。

### 3.4 執行稽核

架構書完成後，在 Chat 中要求：

```text
請稽核這個 session 的需求書與架構書，列出缺漏、矛盾、風險及追溯結果。
```

對應呼叫：

```json
{
  "tool": "run_audit",
  "arguments": {
    "session_id": "SERVER_RETURNED_SESSION_ID"
  }
}
```

完成的架構與稽核呼叫具冪等性。再次使用相同 `session_id` 時，Server 會回傳既有產物，不會重複生成。

## 4. 目前架構

LogicMCP 對 MCP Client 公開三個完整開發工作流與一個 Skill 產生工具。內部 Prompts、Policies、Profiles、Schemas、Validators、狀態轉移與 Renderers 都是 Server 私有實作，不會註冊成額外的 MCP Prompts、Resources 或 Tools。

```text
VS Code／其他 MCP Client
        │
        │ MCP + Client LLM Sampling
        ▼
┌─────────────────────────────────────────────┐
│ LogicMCP Server                             │
│                                             │
│  generate_requirements                      │
│  generate_architecture                      │
│  run_audit                                  │
│  generate_skill                             │
│                │                            │
│                ▼                            │
│  Private workflow orchestration             │
│  Prompts / Policies / Schemas / Validators  │
│  State transitions / Renderers              │
└───────────────────┬─────────────────────────┘
                    │
                    ▼
          Persistent session + artifacts
```

### 工作流程

```text
Q0
 ↓
generate_requirements
 ↓ 逐題訪談、驗證並持久化狀態
需求書
 ↓
generate_architecture
 ↓ 需求對齊與技術規劃
架構書
 ↓
run_audit
 ↓ 一致性、覆蓋、追溯與風險檢查
稽核報告
```

MCP 連線本身不是工作狀態。Server 只保存通過驗證的狀態，並以 `session_id` 恢復流程。需求、架構及稽核產物預設位於 `output/<session_id>/`，工作階段位於 `output/.logicmcp/sessions/`，Server logs 位於 `logs/fastmcp/`。

### 專案結構

```text
server/
├─ entrypoint.py
└─ fastmcp_service/
   ├─ public_tools.py       四個公開 MCP Tools
   ├─ skill_service.py      SKILL.md 產生與可選優化
   ├─ workflow_service.py   工作流程與持久化 session
   ├─ prompts.py            私有 Prompt 讀取與組合
   ├─ prompts/              私有 Prompt templates
   ├─ resources.py          私有 Resource 讀取
   ├─ resources/            Policies、Schemas、Templates
   ├─ tools/                私有 Validators 與 Renderers
   ├─ tests/                公開工作流程測試
   └─ docs/                 契約、邊界與工作流程文件

logs/                       Server runtime logs
output/                     Session 狀態與生成文件
tools/                      維護工具與開發計畫
└─ SKILL.md                 Canonical AI Skill 模板

install.bat                 本機安裝
run.bat                     本機啟動
fastmcp.json                FastMCP filesystem deployment
Dockerfile                  Docker image
compose.yaml                Docker Compose service
```

更完整的檔案索引請見 [MAP.MD](MAP.MD)，輸入輸出邊界請見 [IO_BOUNDARY.md](server/fastmcp_service/docs/IO_BOUNDARY.md)。

## 5. 附加工具：SKILL.md

[tools/SKILL.md](tools/SKILL.md) 是可獨立交給 AI 讀取的 canonical 模板。它以原始 PDCA 精神規範三件事：

1. 讓 AI 分辨原始 `Plan → Do → Check → Act`，以及 LogicMCP 專案定義的 `Problem/Purpose → Design → Check/Challenge → Action`。
2. 讓 AI 依目前要做的工作，檢查既有需求、規格、規劃及架構內容是否足夠，而不是只看檔名。
3. 當資料不足且使用者同意時，讓 AI 正確使用 `generate_requirements`、`generate_architecture`、`run_audit` 與 `session_id` 接續規則。

Skill 不是持久服務、背景監控器或 MCP 必要依賴。使用者可以直接呼叫 MCP，也可以將 `SKILL.md` 交給 AI 使用。前三個開發工作流不依賴 Skill。

### Skill 不是必要流程

LogicMCP 的安裝、啟動及前三個開發工作流都不要求使用 Skill。使用者可以依自己的 IDE、Agent、網路 Chat 或開發習慣選擇：

- 直接呼叫 LogicMCP Tools。
- 使用自己編寫的 Prompt 或 Agent 規則。
- 在支援 Skill 的工具中引用 `SKILL.md`。
- 完全不使用 Skill。

`SKILL.md` 只是讓 AI 預先理解兩種 PDCA 的差異、如何判斷目前狀態是否足夠，以及資料不足時如何正確使用 LogicMCP。

### 在 AI 工具中載入 Skill

不同 IDE、Coding Agent 與網路 Chat 對 Skill 的支援方式不同，目前沒有所有工具共用的單一安裝或呼叫標準。請以實際使用工具的說明為準。

在支援以名稱呼叫 Skill 的環境中，使用 Skill 自己的名稱即可。這份模板在 frontmatter 中定義的名稱是 `logicmcp-pdca`，因此可在主要任務開始前這樣引用：

```text
/logicmcp-pdca

請根據目前專案狀態，判斷是否已有足夠的需求、規格與架構內容可開始開發。
```

`/logicmcp-pdca` 不是所有平台共用的制式命令，而是以 Skill 名稱呼叫這份模板的示例。若使用者將 frontmatter 的 `name` 改成其他名稱，則應使用 `/<自訂技能名稱>`，例如 `/my-project-pdca`。不同平台也可能透過 Skill 選單、提及、附件或其他介面載入，因此仍應以實際工具的能力為準。

### MCP 與 Skill 的關係

從 AI 取得能力的角度來看，MCP 也可以視為廣義 Skill 的一種；兩者主要差異在能力被放置與載入的位置：

```text
MCP
→ 能力、Tools 與狀態位於本機或雲端 MCP Server
→ AI 透過 MCP protocol 連線並呼叫

SKILL.md
→ 指令與使用知識被引入本地環境或沙盒
→ 支援名稱呼叫時，可使用 /logicmcp-pdca 或 /<自訂技能名稱>
```

在 LogicMCP 中，MCP Server 提供可執行的需求、架構、稽核與 Skill 產生能力；`SKILL.md` 則讓 AI 在本地或沙盒上下文中理解兩種 PDCA、判斷目前狀態，以及在必要時正確呼叫 MCP。兩者可以一起使用，也可以依使用者環境分開使用。

若使用的 IDE 或網路 Chat 不支援 Skill，也可以將 `SKILL.md` 上傳、拖入對話或貼入內容，明確要求 LLM 先讀取再處理任務：

```text
請先讀取附加的 SKILL.md，確認其中兩種 PDCA 定義與 LogicMCP 使用規則，
再檢查目前專案是否具備足夠的開發基線。
```

直接把 Markdown 放入既有對話不是標準化的 Skill 載入方式。既有對話內容、其他提示及上下文順序都可能影響 LLM 對文件的理解，因此可靠性通常低於平台原生的 Skill 引用方式。重要工作應確認 AI 已正確理解 Skill 的三項責任後再繼續。

第 4 個公開 Tool `generate_skill` 可輸出一份 Skill：

```json
{
  "tool": "generate_skill",
  "arguments": {
    "mode": "template",
    "output_dir": "logicmcp-pdca"
  }
}
```

`template` 模式原樣輸出 canonical 模板。`optimized` 模式可透過 Client LLM Sampling 附加情境化內容：

```json
{
  "tool": "generate_skill",
  "arguments": {
    "mode": "optimized",
    "customization": "加入本專案既有文件位置與命名慣例",
    "output_dir": "logicmcp-pdca-custom"
  }
}
```

情境化內容只能附加，不能覆蓋兩種 PDCA 的差異、前三個開發工具的用途或 `session_id` 規則。`generate_skill` 不建立需求 session。

`generate_skill` 只產生 `SKILL.md` 檔案與回傳內容，不會替任何 IDE、Agent 或 Chat 自動安裝、註冊或啟用 Skill。產生後仍需依使用平台的方式引用：

```text
generate_skill
→ 取得 artifact.path 與 content
→ 安裝到平台指定的 Skill 位置
→ 支援名稱呼叫時，以 /logicmcp-pdca 或 /<自訂技能名稱> 引用
→ 不支援 Skill 時，將 Markdown 明確提供給 LLM
→ AI 讀取後才依 Skill 判斷狀態及選擇是否使用 MCP
```

本機 MCP Client 通常可直接存取 `artifact.path`。若 LogicMCP 部署在遠端，該路徑屬於 Server filesystem，Client 應使用 Tool result 中的 `content` 保存或載入 Skill，不應假設能直接開啟 Server 路徑。

## 6. 未來計畫

目前的 LogicMCP Server 是一個可執行的前哨站，先驗證人與 AI 能否共用一套可重複、可追溯的邏輯校準流程。後續方向包括：

1. **驗證與改良可選的 `SKILL.md`**

   以實際 AI 使用案例驗證狀態判斷、兩種 PDCA 辨識及 MCP 呼叫規則是否清楚。

2. **支援更細緻的遞迴 PDCA**

   讓專案、模組、功能、API、資料庫、UI 與錯誤修正可以建立局部流程，同時繼承上層已確認的目標與限制。

3. **擴充 Profiles、Policies 與 Templates**

   逐步驗證哪些需求欄位、規劃內容與檢查規則真正能降低返工，而不是單純增加文件篇幅。

4. **強化跨階段追溯與變更影響分析**

   將需求、架構決策、風險、測試與交付結果建立更完整的關聯。

5. **增加 Client 範例與相容性驗證**

   驗證 VS Code 以外的 MCP Clients、不同模型及不同 Agent runtime 是否能維持一致流程。

6. **改善測試、可觀測性與部署能力**

   擴充工作流程測試、失敗恢復、記錄與正式部署所需的安全邊界。

LogicMCP 不追求一次建立完整的軟體生命週期管理平台。它會從小型、可驗證的流程開始，逐步確認哪些結構真的能協助開發者與 AI 保持在正確方向上。

---

GitHub 保存程式碼與版本歷史；LogicMCP 保存成果背後的需求、規劃與檢查邏輯。