WPORT MCP Server + Claude Connector + TS/JS SDK（pm_48）PRD

PRD 代號：pm_48
延續：pm_37（Enterprise REST + wpk_live_）、pm_41（@wport/cli 企業線）、pm_47（求職者 OAuth／CLI，求職者 MCP 解鎖閘門）
產品原則：CLI 能做什麼，MCP／SDK／Connector 就做什麼，也因為cli已經做完，因此補上AI friendly的最後一哩路，mcp與sdk，claude connector雖然也是mcp但要另外加工，目的是讓大家覺得我們也擁抱主流ai agent；BR-040 核彈 deny list 永久排除；BR-039 通道寫入必標 source；絕不開後門提高額度。
本 PRD 無 dashboard mockup：屬 API／Agent 整合產品。Storybook = 無。Claude Connector listing 文案對齊 @wport/cli npm。OAuth 同意頁（求職者）沿用 pm_47，不另開。

1. 文件資訊

• 文件類型：MCP + Claude Connector + SDK 需求規格書
• 適用對象：後端、CLI／SDK 工程、產品、QA、資安、AI Agent 整合
• 最後更新：2026/08/17
• 版本：1.1.0
• 對應 Storybook：無（CLI／API／MCP 產品，無 mockup）
• Storybook（local-prd）：N/A
• Storybook（online）：N/A
• 建立日期：2026/07/17
• 對應 Coda rowId：i-S6oB4_3Q2D
• Coda backlog 名稱：WPORT MCP Server + Claude Connector
• PRD 識別（backlog PRD 欄）：pm_48

2. 開發進度與設計來源

開發進度

• MCP／SDK PR #：SDK 線 ✅ 已出貨（2026/08/17）——wport-cli repo PR #16（monorepo 轉型＋@wport/core＋@wport/sdk）、#18（發布素材）、#19（cli 0.9.1）、#20（0.1.1 exports 修正，已 merge 未發）。npm：@wport/sdk@0.1.0、@wport/core@0.1.0、@wport/cli@0.9.1。MCP 未動工。
• 後端（audit source／MCP gateway）PR #：audit source 進行中（2026/08/17 已 dispatch talent 分支 crazysYao/pm48-delivery-a-source-audit，需求對齊中）；MCP gateway 未動工
• Claude Directory 送審：[TBD]（🚨 組織權限為 PM blocker；官方認證模式已查證，見 DR-2 回寫）

設計來源

• CLI SoT：@wport/cli（現況 0.7.0+）＋ exec-wport-cli skill
• 內部 MCP 先例：Hypelink remote MCP（Bearer + scopes + dry-run／confirm；非產品 SoT）
• Claude：Connectors Directory 送審、Authentication、Review criteria
• BR：business-rules.md v1.8.0（BR-039、BR-040）

3. 功能摘要（Feature Summary）

3.1 功能概述

• 功能名稱：WPORT MCP Server + Claude Connector + TypeScript／JS SDK
• 主要使用者角色：
  • 企業 HR／Manager（wpk_live_）：v1 主打可出貨
  • 公開／未登入：jobs search／view
  • 求職者（pm_47 OAuth）：v1 介面預留 + Mock／Staging；prod 解鎖閘門 = pm_47 Ready
• 核心目標：
  • 為「不想用 CLI、但要用 AI Agent」補一條路徑（Cursor custom connector + Claude Connector）
  • 讓 WPORT 進入 Claude Connectors Directory 生態
  • 官方 TS／JS SDK 與 MCP／CLI 共用同一 REST 語意與錯誤碼（實作結構由 RD 選）

3.2 範圍界定

✅ v1 包含（P0 可上 Directory／Cursor）

🔲 v1 預留／Staging（不 block P0 上線）

❌ 排除範圍

3.3 成功條件（KPI，上線後 3 個月）

3.4 設計決策依據（Design Rationale）

DR-1：通道 = CLI parity，情境不新開

• CLI（pm_41／47）已覆蓋北極星（建職缺、上架履歷等）。本 PRD 只補通道，不發明新業務流程。

DR-2：企業認證 v1 = Bearer API key；OAuth 不鎖死

• 採用：Authorization: Bearer wpk_live_...，與 REST／CLI 一致。
• Claude Directory：可先以 request header（static_headers，beta）送審；若審核要求 OAuth，RD 可改選企業 OAuth／雙軌（利弊見附錄 A）。PM 不假裝已完全權衡所有 Directory 認證細節。
• 回寫（2026/08/17，官方文件查證）：認證模式官方支援度＝none（無認證）正式支援、static_headers Beta、custom_connection 需與 mcp-review 協調、OAuth 三式（DCR／CIMD／anthropic_creds）。含義：純公開線 connector 可用 none 直上 Directory，零 OAuth 工程；企業線 v1 走 static_headers 與本 DR 原判一致。組織前置＝Team／Enterprise + Owner（或 Enterprise 自訂 Directory 角色）。Anthropic egress 160.79.104.0/21。來源：claude.com/docs/connectors/building/{submission,authentication}。

DR-3：求職者線不 block 企業 Directory

• pm_47 OAuth 尚未達第三方 Connector 託管完備 → v1 企業主打；求職者 Mock／Staging。

DR-4：Batch = partial（三端統一）

• 捨棄 MCP all-or-nothing。對齊 CLI／API partial；回傳結構化失敗項，利於 Agent 對使用者解釋單筆失敗（如 quota）。

DR-5：寫入安全 = confirm + annotations（方案 C）

• MCP：兩階段 confirmToken + hints；SDK：顯式 confirm；CLI：既有 --confirm。

DR-6：託管／傳輸／包名／是否薄封裝 REST — 全部 RD 選

• PM 只卡：serverless（CF Workers 或 AWS 輕量）、HTTPS、可被 Claude／Cursor 連、audit source 可注入。
• 建議（非強制）：薄封裝同一 OpenAPI client（對齊 Hypelink）；包名建議 @wport/mcp／@wport/sdk；傳輸建議 Streamable HTTP——皆可由 RD 改。

DR-7：Listing 文案對齊 npm

• Connector name／tagline／description 以 @wport/cli 產品定位為 SoT（W101 Talent Search Hub；公開搜尋 + 企業管理；agent／token-friendly）。

4. 商業規則對齊（Business Rules Alignment）

4.1 本功能使用到的業務規則

4.2 補充說明

• BR-039／BR-040 已於 2026/07/17 回寫 business-rules.md v1.8.0（本功能提案並經 Eric 確認落地）。
• 企業金鑰治理仍遵循 pm_41 BR-API-CLI-004～010（不另開第二套 key）。

5. 資料實體與欄位（Data Entities & Fields）

Rule 30：描述 WHAT／WHY；JSON 欄位名由 OpenAPI／RD 決定。

5.1 實體列表

5.2 求職者 Mock（v1）

• Staging／Mock 可回固定履歷結構；禁止寫入 production 真實個人資料。
• Prod 呼叫未解鎖 personal tool → 明確錯誤（例如 PERSONAL_MCP_NOT_ENABLED），引導依賴 pm_47。

6. 產品表面與資料需求（對應原「畫面區塊」）

無 GUI；以下為 Agent／Connector 表面。

Connector listing 文案錨點（對齊 npm，送審可微調）

• Name（≤100）：WPORT（W101 Talent Search Hub）
• Tagline（≤55，建議）：Search Taiwan jobs & manage hiring with AI
• Description 要點：terminal／agent interface to W101；public job search／view without login；enterprise job／talent／campaign management with wpk_live_；token-efficient field projection for agents；see npm @wport/cli for command parity reference.

7. 使用者動作與後端需求（Actions）

8. API Hints（需求，非最終 path）

8.1 Read

• HINT-GET-1：公開職缺搜尋／單筆 view（既有 public API）
• HINT-GET-2：企業 jobs／talents／campaigns／company／usage／keys list／view（既有 enterprise API）
• HINT-GET-3：MCP tools/list 回傳完整 annotations

8.2 Write

• HINT-MUTATION-1：企業職缺 create／update／publish／unpublish／delete／copy／batch（idempotency 沿用 pm_37）
• HINT-MUTATION-2：破壞性操作兩階段 confirm（token TTL 由 RD 定，建議短效 ≤10 分鐘）
• HINT-MUTATION-3：所有寫入 audit 必帶 source（BR-039）
• HINT-MUTATION-4：personal 寫入僅 staging／P1

8.3 錯誤與契約（不得 TBD）

9. 導航／交付 Map

• Storybook：無（CLI／API／MCP 產品）
• PRD（local）：file:///Users/Eric/Documents/Github/prd/doc/feature/pm_48/wport-mcp-connector-prd.md
• npm 參考：https://www.npmjs.com/package/@wport/cli
• 隱私：站上既有隱私頁（填 Directory manifest）
• OAuth 同意（求職者）：pm_47 W-1／W-2（P1）
• Cursor：custom connector／MCP 設定（RD 文件化）
• Claude：Directory submission portal（需 Team／Enterprise + Directory management）

10. Flowcharts

10.1 User Flow（Agent／人資連線與建職缺）

flowchart TD
  Start([使用者在 Claude 或 Cursor 新增 WPORT Connector]) --> Lazy{呼叫的 tool 類型}
  Lazy -->|公開 jobs.search/view| Pub[執行公開 API]
  Lazy -->|企業寫入或企業讀取| Auth{已有有效 Bearer wpk_live_?}
  Auth -->|否| Prompt[要求貼上／設定 API key]
  Prompt --> Auth
  Auth -->|是| Scope{權限與公司狀態 OK?}
  Scope -->|否| Err403[回傳 403／停權錯誤]
  Scope -->|是| Dest{是否破壞性或對外發送?}
  Dest -->|否| Exec[執行 REST 等價操作]
  Dest -->|是| Phase1[回傳摘要 + confirmToken]
  Phase1 --> Phase2{第二步帶 confirmToken?}
  Phase2 -->|否| Stop[拒執行]
  Phase2 -->|是| Exec
  Exec --> Audit[寫 audit source=mcp_server]
  Audit --> Partial{是否 batch?}
  Partial -->|是| PartJSON[回傳 success_count + failed_items]
  Partial -->|否| Done[回傳成功或業務錯誤]
  Pub --> Done
  Err403 --> End([結束])
  Stop --> End
  PartJSON --> End
  Done --> End

10.2 System Flow（MCP tool → REST → audit）

sequenceDiagram
  participant Agent as Claude/Cursor Agent
  participant MCP as WPORT MCP Server
  participant API as Enterprise/Public API
  participant Audit as Audit Log

  Agent->>MCP: tools/call (e.g. enterprise.jobs.create)
  alt missing/invalid key on protected tool
    MCP-->>Agent: 401 + re-auth hint
  else ok
    alt destructive without confirmToken
      MCP-->>Agent: CONFIRM_REQUIRED + summary + token
      Agent->>MCP: tools/call with confirmToken
    end
    MCP->>API: REST equivalent + Idempotency if required
    API->>Audit: write event source=mcp_server
    API-->>MCP: success / partial / error
    MCP-->>Agent: structured JSON (incl. failed_items if batch)
  end

10.3 出貨切分（Navigation of releases）

flowchart LR
  P0[P0: Public + Enterprise MCP/SDK + Directory 送審] --> P05[P0.5: Personal tools Mock/Staging]
  P05 --> P1[P1: pm_47 Ready → Personal prod 解鎖]

10.4 Edge Case Coverage

11. Mock／Staging Schema（求職者線 v1）

• 資料來源：Mock 固定 fixture 或 Staging 專用帳；不打 prod 個人寫入。
• 切換：環境旗標／feature flag（RD）；prod 預設 OFF。
• CRUD：Mock 僅行程式記憶體或 staging DB；不得污染 prod。

12. 實作備註（Implementation Notes）

12.1 禁止事項

• ❌ 不開高於 BR／Enterprise quota 的後門
• ❌ 不實作 BR-040 核彈能力
• ❌ 不以 query string 傳 API key（Claude 文件亦禁止）
• ❌ 不把本 PRD 當最終 OpenAPI path 定義（Hints only）
• ❌ v1 prod 不啟用求職者真寫入

12.2 RD 決策清單（本 PRD 明確放權）

12.3 PM 立即行動（非 RD）

• 本週申請／升級 Claude Team 或 Enterprise + Directory management
• 與設計準備 icon、文件頁、Demo 企業 key 帳、（預留）求職者 Demo 帳說明
• Directory listing 文案定稿（對齊 npm）

12.4 遷移／相容

• 既有 CLI／API 使用者：無破壞性變更；僅 audit 新增／強制 source（既有呼叫應標 enterprise_api／cli）。
• 回滾：feature flag 關閉 MCP 路由即可；不影響 GUI。

12.5 Sync-fix 清單

13. 一致性表與版本凍結（Stage 5–6）

13.1 欄位／語意對照

13.2 Constants

13.3 Event dictionary

13.4 術語 dictionary

13.5 Version freeze

13.6 PRD 問題清單

（若 Claude Directory 組織權限本週未取得，視為交付 blocker，非 PRD 規格缺陷。）

14. 下一步（Next Steps）

1. Stage 8：使用者確認本 PRD 後 → Stage 9 commit／push（Coda 已有 pm_48）
2. RD：開 MCP／SDK／audit source 實作；填 RD 決策清單
3. PM：Claude org＋Directory；Demo 帳與 listing 資產
4. 可選：gen-trello-project-setup 建 goal＋delivery 卡（無 Storybook 欄位填「無」）
5. P1：pm_47 Ready → 解鎖 personal tools

附錄 A：企業 API key vs OAuth（供 RD／送審參考，v1 不強制）

附錄 B：Stage 2 情境 ID 對照

S1–S12 見對話 Stage 2；已納入 §10.1／§10.4。

文件結束