Lalaleap MCP Server

透過 MCP (Model Context Protocol) 讓 AI 工具直接操作 Lalaleap 專案管理系統。

接上之後，你可以用自然語言請 AI 幫你建需求、查缺陷、管理待辦 — 不需要切到瀏覽器。

---

它是什麼？

你（在 Claude Code / Cursor 裡打字）
  ↓  "幫我在彰基專案建一筆需求：病歷查詢 API"
Claude / Cursor（透過 MCP Protocol 呼叫 tool）
  ↓  callTool("create_requirement", { pno, title, priority })
Lalaleap MCP Server（本專案，TypeScript + stdio）
  ↓  POST /require/add → POST /require/edit
Lalaleap 後端 API（Java）
  ↓
回傳結果 → AI 告訴你「需求已建立，編號 1000160」

一句話：它是 AI 和 Lalaleap 之間的翻譯層。

---

快速上手（3 分鐘）

Step 1：設定你的 AI 工具

不需要手動 clone，直接在 MCP 設定裡指向 GitHub repo，npx 會自動拉、自動 build。

Claude Code — 編輯 ~/.claude/settings.json：

{
  "mcpServers": {
    "lalaleap": {
      "command": "npx",
      "args": ["-y", "github:kuraki5336/tpi_lalaleap_mcp"],
      "env": {
        "LALALEAP_API_URL": "https://your-domain.com/ap2/lalaleap",
        "LALALEAP_EMAIL": "你的email@gmail.com",
        "LALALEAP_PASSWORD": "你的密碼",
        "LALALEAP_UNSAFE_SSL": "1"
      }
    }
  }
}

Cursor — 在 Settings → MCP 中新增 server，欄位同上。

前提：使用者的機器需要有 GitHub repo 的存取權限（private repo 需設定 SSH key 或 personal access token）。 LALALEAP_UNSAFE_SSL=1 是因為 dev 環境 SSL 憑證過期，正式環境不需要。

替代方案：本機安裝

如果不想每次 npx 拉取，也可以 clone 下來：

git clone https://github.com/kuraki5336/tpi_lalaleap_mcp.git
cd tpi_tpad_mcp && npm install

然後 MCP 設定改指向本機路徑：

{
  "mcpServers": {
    "lalaleap": {
      "command": "node",
      "args": ["/你的路徑/tpi_tpad_mcp/dist/index.js"],
      "env": { ... }
    }
  }
}

Step 2：開始用

重啟你的 AI 工具，直接對話就能用了。

---

認證方式

支援兩種，二擇一：

| 方式 | 環境變數 | 說明 | |------|---------|------| | 帳密登入 | LALALEAP_EMAIL + LALALEAP_PASSWORD | 密碼 SHA256 加密由程式處理，你填明文 | | API Token | LALALEAP_API_TOKEN | 未來後端支援後可用，優先度高於帳密 |

全部環境變數：

| 變數 | 必填 | 說明 | |------|------|------| | LALALEAP_API_URL | 是 | API 基礎 URL | | LALALEAP_EMAIL | 擇一 | 登入 Email | | LALALEAP_PASSWORD | 擇一 | 登入密碼 | | LALALEAP_API_TOKEN | 擇一 | API Token（優先於帳密） | | LALALEAP_UNSAFE_SSL | 否 | 1 = 跳過 SSL 驗證 | | LALALEAP_READONLY | 否 | 1 = 唯讀模式，禁止所有寫入操作 | | LALALEAP_ALLOWED_PROJECTS | 否 | 專案白名單（逗號分隔 pno），只允許對這些專案寫入 | | LALALEAP_WRITE_RATE_LIMIT | 否 | 每分鐘最大寫入次數（預設 10） |

---

可用 Tools 一覽

共 14 個 tool，AI 會根據你的指令自動選擇呼叫。

專案

| Tool | 做什麼 | 必填參數 | 可選參數 | |------|--------|---------|---------| | list_projects | 列出你的所有專案 | — | — | | get_project_detail | 看專案詳情 | pno | — | | create_project | 建新專案 | name | type（0 公開/1 私人） |

需求

| Tool | 做什麼 | 必填參數 | 可選參數 | |------|--------|---------|---------| | create_requirement | 建立需求 | pno, title | describe, priority(高/中/低), start_date, end_date | | list_requirements | 查需求清單 | pno | page, limit, keyword | | get_requirement_detail | 看需求詳情 | pno, rno | — | | update_requirement | 改需求 | pno, rno | title, status, priority, describe, start_date, end_date |

缺陷

| Tool | 做什麼 | 必填參數 | 可選參數 | |------|--------|---------|---------| | create_bug | 建立缺陷 | pno, title | describe, priority(高/中/低), serious | | list_bugs | 查缺陷清單 | pno | page, limit |

待辦 / 迭代 / 其他

| Tool | 做什麼 | 必填參數 | 可選參數 | |------|--------|---------|---------| | create_todo | 建待辦 | pno, title | content, priority(high/medium/low), due_date, lane_no | | list_todos | 看待辦看板 | pno | — | | list_sprints | 查迭代清單 | pno | — | | list_project_members | 查專案成員 | pno | — | | search_tags | 搜尋標籤 | pno | keyword |

---

MCP Resources

除了 tool（要主動呼叫），也有 resource（AI 可以當上下文讀取）：

| URI | 內容 | |-----|------| | lalaleap://projects | 專案清單 | | lalaleap://project/{pno}/requirements | 某專案的需求 | | lalaleap://project/{pno}/bugs | 某專案的缺陷 | | lalaleap://project/{pno}/sprints | 某專案的迭代 | | lalaleap://project/{pno}/members | 某專案的成員 |

---

實際對話範例

你：幫我看一下有哪些專案
AI：→ list_projects
    你有 12 個專案：彰基_測試、ProjectC、...

你：在彰基_測試建一筆需求「病歷查詢 API」，優先度高
AI：→ list_projects（找到 pno）
    → create_requirement(pno, title="病歷查詢 API", priority="高")
    需求已建立，編號 1000160

你：列出這個專案所有需求
AI：→ list_requirements(pno)
    共 5 筆需求：
    1. 病歷查詢 API（高）- 規劃中
    2. 使用者登入（中）- 進行中
    ...

你：建一個 bug「登入頁按鈕在 Safari 沒反應」
AI：→ create_bug(pno, title="登入頁按鈕在 Safari 沒反應")
    缺陷已建立，編號 2000005

你：幫我加一個待辦「寫 API 文件」，截止下週五
AI：→ create_todo(pno, title="寫 API 文件", due_date="2026-03-28")
    待辦已建立

---

架構 & 原始碼導覽

tpi_tpad_mcp/
├── src/
│   ├── index.ts            # 入口：啟動 MCP Server、註冊 tools & resources
│   ├── config.ts           # 讀取環境變數
│   ├── api-client.ts       # axios HTTP client，處理登入/token/重試
│   ├── resources.ts        # 5 個 MCP Resources 定義
│   ├── test.ts             # API 整合測試（14 個端點）
│   ├── test-mcp.ts         # MCP Protocol E2E 測試（50 個案例）
│   └── tools/
│       ├── projects.ts     # list_projects, get_project_detail, create_project
│       ├── requirements.ts # create/list/get/update requirement
│       ├── bugs.ts         # create_bug, list_bugs
│       ├── todos.ts        # create_todo, list_todos
│       ├── sprints.ts      # list_sprints
│       ├── tags.ts         # search_tags
│       └── members.ts      # list_project_members
├── docs/
│   └── test-report.md      # QA 測試報告
├── package.json
└── tsconfig.json

關鍵設計

認證自動處理：啟動時自動登入，401 時自動 refresh token，失敗再重新登入
兩步建立：建需求/缺陷時，先 POST /add 拿到編號，再 POST /edit 填欄位（與前端行為一致）
所有錯誤不會 crash：每個 tool 都有 try-catch，回傳友善中文錯誤訊息
寫入防護：WriteGuard 機制保護所有寫入操作（詳見下方）

---

安全防護（WriteGuard）

AI 有可能誤解指令導致批量寫入垃圾資料。所有寫入操作（create / update）都有三道防線：

1. 唯讀模式

完全禁止寫入，AI 只能查詢不能建立/修改任何東西：

{
  "env": {
    "LALALEAP_READONLY": "1"  // 所有 create/update tool 會被直接阻擋
  }
}

適用場景：Demo、新人剛接手不確定 AI 行為時、只需查詢的情境。

2. 專案白名單

限制 AI 只能在特定專案寫入，防止操作到錯誤的專案：

{
  "env": {
    // 只允許對這兩個專案做寫入操作，其他專案的 create/update 會被阻擋
    "LALALEAP_ALLOWED_PROJECTS": "be3fd182-3696-41a6-bce8-7f2e9d88b648,c53f210f-xxxx"
  }
}

適用場景：正式環境只開放測試專案、團隊成員只操作自己負責的專案。

3. 寫入頻率限制

限制每分鐘最多寫入幾次，防止 AI 短時間大量建立項目：

{
  "env": {
    "LALALEAP_WRITE_RATE_LIMIT": "5"  // 每分鐘最多 5 次寫入（預設 10）
  }
}

觸發限制時，AI 會收到明確的錯誤訊息： `` [頻率限制] 過去一分鐘已執行 5 次寫入操作（上限 5 次）。請稍後再試。 ``

適用場景：防止 AI 跑迴圈批量建立、誤解「幫我建 100 個需求」這類指令。

建議設定組合

| 情境 | 設定 | |------|------| | 開發/測試 | 不設限，或 WRITE_RATE_LIMIT=20 | | 日常使用 | ALLOWED_PROJECTS=你的專案pno + WRITE_RATE_LIMIT=10 | | Demo 展示 | READONLY=1 | | 團隊共用 | ALLOWED_PROJECTS=團隊專案 + WRITE_RATE_LIMIT=5 |

---

開發

# 開發模式（tsx 直接跑，不需編譯）
npm run dev

# 編譯
npm run build

# API 整合測試（直接打 API，14 個端點）
npm test

# MCP Protocol E2E 測試（透過 stdio 模擬真實 MCP 連線，50 個案例）
LALALEAP_UNSAFE_SSL=1 npx tsx src/test-mcp.ts

新增一個 Tool

在 src/tools/ 新增或修改對應檔案
用 server.tool(name, description, zodSchema, handler) 註冊
如果是新檔案，在 src/index.ts import 並呼叫 register 函式
跑測試確認

// 範例：新增一個 tool
server.tool(
  'my_new_tool',
  '這個 tool 做什麼',
  {
    pno: z.string().describe('專案編號'),
    someParam: z.string().optional().describe('說明'),
  },
  async ({ pno, someParam }) => {
    try {
      const resp = await api.post('/some/endpoint', { pno, someParam });
      return {
        content: [{ type: 'text', text: JSON.stringify(resp.data, null, 2) }],
      };
    } catch (err) {
      return {
        content: [{ type: 'text', text: formatError(err) }],
        isError: true,
      };
    }
  }
);

---

Troubleshooting

| 問題 | 解法 | |------|------| | certificate has expired | 設定 LALALEAP_UNSAFE_SSL=1 | | Need to change password (601) | 已自動處理（server 會用 keepCipher='Y' 重試） | | LALALEAP_API_URL 環境變數未設定 | 確認 MCP client 設定中的 env 區塊有帶 | | 連不上 server | 確認 npm run build 過了，dist/index.js 存在 | | tool 沒出現 | 重啟 AI 工具，確認 settings.json 格式正確 |

---

技術棧

| 項目 | 版本 | |------|------| | Node.js | 18+ | | TypeScript | 5.9 | | MCP SDK | @modelcontextprotocol/sdk 1.27 | | HTTP Client | axios 1.13 | | Schema Validation | zod 4.3 | | 傳輸方式 | stdio（標準輸入輸出） |

---

測試覆蓋

| 類別 | 數量 | 通過率 | |------|------|--------| | MCP Protocol E2E（含 tools + resources + 邊界條件） | 50 | 100% | | API 整合測試 | 14 | 100% | | TypeScript 型別檢查 | — | 零錯誤 |

完整測試報告見 docs/test-report.md。

Lalaleap MCP Server