Unleash MCP Server

ทางการ

เซิร์ฟเวอร์ MCP สำหรับจัดการฟีเจอร์แฟล็กของ Unleash และทำให้แนวทางปฏิบัติที่ดีที่สุดเป็นอัตโนมัติ

GitHub
18

เอกสาร

Unleash MCP Server

เซิร์ฟเวอร์ Model Context Protocol (MCP) ที่ขับเคลื่อนด้วยวัตถุประสงค์ สำหรับการจัดการฟีเจอร์แฟล็กของ Unleash เซิร์ฟเวอร์นี้ช่วยให้ผู้ช่วยเขียนโค้ดที่ขับเคลื่อนด้วย LLM สามารถสร้างและจัดการฟีเจอร์แฟล็กตามแนวทางปฏิบัติที่ดีที่สุดของ Unleash

หากต้องการแบ่งปันความคิดเห็น เข้าร่วม community Slack ของเรา หรือเปิด issue on GitHub

ภาพรวม

เซิร์ฟเวอร์ MCP นี้มีเครื่องมือที่ผสานรวมกับ Unleash Admin API ช่วยให้ผู้ช่วยเขียนโค้ด AI สามารถ:

  • สร้างฟีเจอร์แฟล็ก พร้อมการตรวจสอบและระบุประเภทที่ถูกต้อง
  • ตรวจจับแฟล็กที่มีอยู่ เพื่อป้องกันการซ้ำซ้อนหรือส่งเสริมการนำกลับมาใช้ใหม่
  • ประเมินการเปลี่ยนแปลง เพื่อตัดสินใจว่าเมื่อใดจำเป็นต้องใช้ฟีเจอร์แฟล็ก
  • สตรีมความคืบหน้า เพื่อให้มองเห็นได้ระหว่างการดำเนินการ
  • จัดการข้อผิดพลาด อย่างสง่างามพร้อมคำแนะนำที่เป็นประโยชน์
  • ปฏิบัติตามแนวทางปฏิบัติที่ดีที่สุด จาก Unleash documentation

เครื่องมือที่พร้อมใช้งาน

เซิร์ฟเวอร์ MCP มีเครื่องมือดังต่อไปนี้:

  • create_flag: สร้างฟีเจอร์แฟล็กใน Unleash
  • evaluate_change: ให้คะแนนความเสี่ยงและแนะนำการใช้ฟีเจอร์แฟล็ก
  • detect_flag: ค้นพบฟีเจอร์แฟล็กที่มีอยู่เพื่อหลีกเลี่ยงการซ้ำซ้อน
  • wrap_change: ให้คำแนะนำเกี่ยวกับวิธีการครอบการเปลี่ยนแปลงด้วยฟีเจอร์แฟล็ก
  • set_flag_rollout: กำหนดค่ากลยุทธ์การเปิดตัวสำหรับฟีเจอร์แฟล็ก (ไม่เปิดใช้งานแฟล็ก)
  • get_flag_state: แสดงข้อมูลเมตาของฟีเจอร์แฟล็กและกลยุทธ์การเปิดใช้งาน
  • list_flags: แสดงรายการฟีเจอร์แฟล็กทั้งหมดในโปรเจกต์ พร้อมตัวเลือกการแบ่งหน้าและการเรียงลำดับ
  • list_projects: แสดงรายการโปรเจกต์ Unleash ที่พร้อมใช้งานสำหรับโทเค็นที่กำหนดค่าไว้ พร้อมตัวเลือกการแบ่งหน้า
  • toggle_flag_environment: เปิดหรือปิดใช้งานฟีเจอร์แฟล็กในสภาพแวดล้อม
  • remove_flag_strategy: ลบกลยุทธ์ของฟีเจอร์แฟล็กออกจากสภาพแวดล้อม
  • cleanup_flag: สร้างคำแนะนำสำหรับการลบเส้นทางโค้ดที่มีแฟล็กอย่างปลอดภัย

เวิร์กโฟลว์หลัก

เวิร์กโฟลว์หลักสำหรับผู้ช่วย AI ได้รับการออกแบบให้เป็น:

  1. evaluate_change: ขั้นแรก ประเมินการเปลี่ยนแปลงโค้ดเพื่อดูว่าจำเป็นต้องใช้แฟล็กหรือไม่
  2. detect_flag: มักถูกเรียกโดยอัตโนมัติโดย evaluate_change เพื่อป้องกันการสร้างแฟล็กที่ซ้ำกัน
  3. create_flag: หากจำเป็นต้องใช้แฟล็กใหม่ เครื่องมือนี้จะสร้างแฟล็กใน Unleash
  4. wrap_change: สุดท้าย เครื่องมือนี้จะให้โค้ดเฉพาะภาษาเพื่อนำแฟล็กใหม่ไปใช้

ดูข้อมูลเพิ่มเติมเกี่ยวกับเครื่องมือเวิร์กโฟลว์หลักได้ในส่วน Tool reference

ข้อกำหนดเบื้องต้น

ก่อนที่คุณจะสามารถรันเซิร์ฟเวอร์ได้ คุณต้องมีสิ่งต่อไปนี้:

  • Node.js 22 หรือสูงกว่า
  • ตัวจัดการแพ็คเกจ pnpm หรือ npm
  • อินสแตนซ์ Unleash (โฮสต์หรือโฮสต์เอง)
  • personal access token ที่มีสิทธิ์ในการสร้างฟีเจอร์แฟล็ก

เริ่มต้นใช้งาน

ส่วนนี้ครอบคลุมวิธีการต่างๆ ในการติดตั้งและรันเซิร์ฟเวอร์ Unleash MCP คุณสามารถทำตามการตั้งค่าสำหรับ agents (เช่น Claude Code และ Codex) รัน MCP เป็น standalone process โดยใช้ npx หรือใช้การตั้งค่า local development

การตั้งค่าเอเจนต์

คุณสามารถเพิ่มเซิร์ฟเวอร์ MCP ลงใน Claude Code หรือ Codex ได้โดยตรง การกำหนดค่าเอเจนต์นั้นเฉพาะเจาะจงกับพาธ คุณต้องรันคำสั่งต่อไปนี้จากไดเรกทอรีรากของโปรเจกต์ที่คุณต้องการใช้ MCP

สำหรับ Claude Code:

claude mcp add unleash \
    --env UNLEASH_BASE_URL={{your-instance-url}} \
    --env UNLEASH_PAT={{your-personal-access-token}} \
    -- npx -y @unleash/mcp@latest --log-level error

สำหรับ Codex:

codex mcp add unleash \
    --env UNLEASH_BASE_URL={{your-instance-url}} \
    --env UNLEASH_PAT={{your-personal-access-token}} \
    -- npx -y @unleash/mcp@latest --log-level error

การตั้งค่าเอเจนต์ระยะไกล (ทดลอง)

แทนที่จะรันเซิร์ฟเวอร์ MCP ในเครื่อง คุณสามารถเชื่อมต่อโดยตรงกับเซิร์ฟเวอร์ MCP ระยะไกลในตัวของอินสแตนซ์ Unleash ผ่าน HTTP ซึ่งใช้ Streamable HTTP transport — ไม่จำเป็นต้องมีกระบวนการในเครื่อง

หมายเหตุ: Remote MCP เป็นฟีเจอร์ทดลองที่ต้องเปิดใช้งานบนอินสแตนซ์ Unleash ของคุณ ติดต่อทีม Unleash เพื่อเปิดใช้งาน

OAuth

โฟลว์ OAuth จะเปิดเบราว์เซอร์ของคุณ ให้คุณเข้าสู่ระบบ Unleash และสร้าง PAT อายุสั้นโดยอัตโนมัติ ไม่จำเป็นต้องจัดการโทเค็นด้วยตนเอง

สำหรับ Claude Code:

claude mcp add unleash https://{{your-instance-url}}/api/admin/mcp --transport http

สำหรับ Codex:

codex mcp add unleash https://{{your-instance-url}}/api/admin/mcp --transport http

ในการใช้งานครั้งแรก ไคลเอนต์จะเปิดเบราว์เซอร์ของคุณโดยอัตโนมัติเพื่อเข้าสู่ระบบ หลังจากตรวจสอบสิทธิ์กับ Unleash แล้ว PAT จะถูกสร้างขึ้นและใช้สำหรับคำขอที่ตามมาทั้งหมด

PAT จะหมดอายุหลังจาก 24 ชั่วโมงตามค่าเริ่มต้น

Personal Access Token (PAT)

ใช้วิธีนี้เมื่อคุณมี PAT อยู่แล้วหรือต้องการการเข้าถึงแบบไม่มีส่วนหัว/ไม่โต้ตอบ (CI pipelines, สภาพแวดล้อมนักพัฒนาที่ใช้ร่วมกัน, ไคลเอนต์ที่ไม่รองรับ OAuth)

วิธีสร้าง PAT: เข้าสู่ระบบอินสแตนซ์ Unleash ของคุณ ไปที่ Profile > Personal Access Tokens และสร้างโทเค็นใหม่

สำหรับ Claude Code:

claude mcp add unleash https://{{your-instance-url}}/api/admin/mcp \
  --transport http \
  --header "Authorization: Bearer {{your-personal-access-token}}"

สำหรับ Codex:

codex mcp add unleash https://{{your-instance-url}}/api/admin/mcp \
  --transport http \
  --header "Authorization: Bearer {{your-personal-access-token}}"

แฟล็ก --header จะส่ง PAT โดยตรง โดยข้ามโฟลว์ OAuth ไปเลย

เริ่มต้นอย่างรวดเร็วด้วย npx

คุณสามารถรันเซิร์ฟเวอร์ MCP เป็นกระบวนการแบบสแตนด์อโลนโดยไม่ต้องโคลนที่เก็บโดยใช้ npx ระบุการกำหนดค่าผ่านตัวแปรสภาพแวดล้อมหรือไฟล์ .env ในเครื่องในไดเรกทอรีที่คุณรันคำสั่ง:

UNLEASH_BASE_URL={{your-instance-url}} \
UNLEASH_PAT={{your-personal-access-token}} \
UNLEASH_DEFAULT_PROJECT={{default_project_id}} \
npx unleash-mcp --log-level debug

CLI รองรับแฟล็กเดียวกันกับบิลด์ในเครื่อง (ตัวอย่างเช่น --dry-run, --log-level)

การตั้งค่าการพัฒนาในเครื่อง

ทำตามขั้นตอนเหล่านี้เพื่อตั้งค่าโปรเจกต์สำหรับการพัฒนาในเครื่อง

  1. ติดตั้งการพึ่งพา

โคลนที่เก็บและติดตั้งการพึ่งพาโดยใช้ pnpm Corepack ช่วยให้ทุกคนใช้ pnpm เวอร์ชันเดียวกัน:

git clone https://github.com/Unleash/unleash-mcp.git
cd unleash-mcp

# Enable Corepack once per machine, then prepare the pnpm this repo expects
corepack enable
corepack prepare [email protected] --activate

pnpm install
  1. รันในโหมด dev โดยตรงจาก Claude หรือ Codex

หลีกเลี่ยงเอาต์พุต npm run และแบนเนอร์ tsx watch เนื่องจาก stdout พิเศษใดๆ จะทำให้การจับมือ MCP เสียหาย มีสองตัวเลือกที่เงียบ:

A) ใช้ JS ที่คอมไพล์แล้ว (น่าเชื่อถือที่สุด)

npm run build
# or keep it hot in another terminal: npm run build:watch

claude mcp add unleash-dev \
  --env UNLEASH_BASE_URL={{your-instance-url}} \
  --env UNLEASH_PAT={{your-personal-access-token}} \
  --env LOG_LEVEL=debug \
  --env APP_LOG_FILE="$(pwd)/app.log" \
  --env MCP_STDIO_LOG_FILE="$(pwd)/mcp-stdio.log" \
  -- node "$(pwd)/dist/index.js"

codex mcp add unleash-dev \
  --env UNLEASH_BASE_URL={{your-instance-url}} \
  --env UNLEASH_PAT={{your-personal-access-token}} \
  --env LOG_LEVEL=debug \
  --env APP_LOG_FILE="$(pwd)/app.log" \
  --env MCP_STDIO_LOG_FILE="$(pwd)/mcp-stdio.log" \
  -- node "$(pwd)/dist/index.js"

B) ใช้ TypeScript โดยตรง (ไม่ต้องบิลด์)

claude mcp add unleash-dev \
  --env UNLEASH_BASE_URL={{your-instance-url}} \
  --env UNLEASH_PAT={{your-personal-access-token}} \
  --env LOG_LEVEL=debug \
  --env APP_LOG_FILE="$(pwd)/app.log" \
  --env MCP_STDIO_LOG_FILE="$(pwd)/mcp-stdio.log" \
  -- node --no-warnings --import tsx "$(pwd)/src/index.ts"

codex mcp add unleash-dev \
  --env UNLEASH_BASE_URL={{your-instance-url}} \
  --env UNLEASH_PAT={{your-personal-access-token}} \
  --env LOG_LEVEL=debug \
  --env APP_LOG_FILE="$(pwd)/app.log" \
  --env MCP_STDIO_LOG_FILE="$(pwd)/mcp-stdio.log" \
  -- node --no-warnings --import tsx "$(pwd)/src/index.ts"

หมายเหตุ:

  • node --import tsx เงียบ (ไม่มีเอาต์พุตวงจรชีวิต npm) และรัน TS โดยตรง ใช้เมื่อคุณต้องการหลีกเลี่ยงการบิลด์
  • node dist/index.js เป็นตัวเลือกที่ปลอดภัยที่สุด จับคู่กับ npm run build:watch เพื่อสร้างใหม่เมื่อมีการเปลี่ยนแปลงในขณะที่คำสั่งเอเจนต์ยังคงเสถียร
  • บันทึกจะอยู่ในรากของที่เก็บ (app.log, mcp-stdio.log) ทั้งคู่ถูก gitignored

การควบคุมการบันทึก

  • LOG_LEVEL (แนะนำ): ควบคุมความละเอียดของการบันทึกแอปพลิเคชัน (debug, info, warn, error) ค่าเริ่มต้นเป็น error เมื่อไม่ได้ตั้งค่า
  • แฟล็ก CLI --log-level: การแทนที่เสริมสำหรับ LOG_LEVEL เมื่อคุณต้องการเปลี่ยนแปลงครั้งเดียว
  • APP_LOG_FILE (ไม่บังคับ): หากตั้งค่า บันทึกแอปพลิเคชันจะถูกเขียนลงในไฟล์นี้ (ไม่ใช่ stdout) หากไม่ได้ตั้งค่า บันทึกจะไปที่ stderr
  • MCP_STDIO_LOG_FILE (ไม่บังคับ): หากตั้งค่า MCP stdin/stdout/stderr จะถูกทีลงในไฟล์เดียวนี้พร้อมคำนำหน้าช่องสัญญาณ ข้อความโปรโตคอลยังคงไหลผ่าน stdout ตามปกติ

การระบุแหล่งที่มาของไคลเอนต์

เมื่อไคลเอนต์ MCP ส่ง clientInfo ระหว่างการเริ่มต้น (Claude Code, Cursor, Copilot, Windsurf, Codex, Kiro และไคลเอนต์ที่สอดคล้องอื่นๆ) เซิร์ฟเวอร์จะเพิ่มส่วนหัว User-Agent ในการเรียก Unleash Admin API ขาออก:

User-Agent: unleash-mcp/<version> (MCP Server; client=claude-code/1.2.3)

สิ่งนี้ทำให้บันทึกเหตุการณ์ Unleash ตอบคำถาม "เครื่องมือ AI ใดที่สร้างหรือสลับแฟล็กนี้" โดยไม่ต้องเปลี่ยนแปลงฝั่งเซิร์ฟเวอร์ ค่าการระบุแหล่งที่มาจะถูกทำให้สะอาดเพื่อไม่ให้ส่วนหัว User-Agent เสียหาย

ตั้งค่า UNLEASH_MCP_CLIENT_ATTRIBUTION=off เพื่อปิดใช้งานการเพิ่มคุณค่าและเปลี่ยนกลับเป็น unleash-mcp/<version> (MCP Server) ค่าเริ่มต้น: เปิดใช้งาน

การอ้างอิงเครื่องมือ

ส่วนนี้อธิบายรายละเอียดของเครื่องมือหลักแต่ละตัว รวมถึงวัตถุประสงค์ พารามิเตอร์ และเอาต์พุต

สร้างแฟล็ก

เครื่องมือ create_flag สร้างฟีเจอร์แฟล็กใหม่ใน Unleash พร้อมการตรวจสอบที่ครอบคลุมและการติดตามความคืบหน้า

เมื่อใดควรใช้

ใช้เครื่องมือนี้เมื่อคุณได้พิจารณาแล้วว่าจำเป็นต้องใช้ฟีเจอร์แฟล็ก (ตัวอย่างเช่น หลังจากรัน evaluate_change) และคุณพร้อมที่จะสร้างด้วยประเภทและข้อมูลเมตาที่ถูกต้อง

พารามิเตอร์

เครื่องมือยอมรับพารามิเตอร์ต่อไปนี้:

  • name (จำเป็น): ชื่อฟีเจอร์แฟล็กที่ไม่ซ้ำกันภายในโปรเจกต์
  • type (จำเป็น): ประเภทฟีเจอร์แฟล็กที่ระบุวงจรชีวิตและความตั้งใจ
    • release: การเปิดตัวฟีเจอร์แบบค่อยเป็นค่อยไปให้กับผู้ใช้
    • experiment: การทดสอบ A/B และการทดลอง
    • operational: พฤติกรรมของระบบและสวิตช์การดำเนินงาน
    • kill-switch: การปิดระบบฉุกเฉินหรือเซอร์กิตเบรกเกอร์
    • permission: ควบคุมการเข้าถึงฟีเจอร์ตามบทบาทหรือสิทธิ์ของผู้ใช้
  • description (จำเป็น): คำอธิบายที่ชัดเจนว่าแฟล็กควบคุมอะไรและเหตุใดจึงมีอยู่
  • projectId (ไม่บังคับ): โปรเจกต์เป้าหมาย (ค่าเริ่มต้นเป็น UNLEASH_DEFAULT_PROJECT)
  • impressionData (ไม่บังคับ): เปิดใช้งานการติดตามการวิเคราะห์ (ค่าเริ่มต้นเป็น false)

ตัวอย่างการใช้งาน

พร้อมท์เอเจนต์

Use create_flag with:
- name: "new-checkout-flow"
- type: "release"
- description: "Gradual rollout of the redesigned checkout experience"
- projectId: "ecommerce"

เพย์โหลดเครื่องมือ

{
  "name": "new-checkout-flow",
  "type": "release",
  "description": "Gradual rollout of the redesigned checkout experience with improved conversion tracking",
  "projectId": "ecommerce",
  "impressionData": true
}

เอาต์พุตเครื่องมือ

เมื่อสำเร็จ เครื่องมือจะส่งคืนออบเจกต์ JSON ที่มี URL ของฟีเจอร์แฟล็กใหม่ใน Unleash Admin UI, ลิงก์ทรัพยากร MCP สำหรับการเข้าถึงเชิงโปรแกรม, เวลาที่สร้าง และรายละเอียดการกำหนดค่า

ประเมินการเปลี่ยนแปลง

เครื่องมือ evaluate_change ประเมินว่าการเปลี่ยนแปลงโค้ดควรอยู่หลังฟีเจอร์แฟล็กหรือไม่ โดยตรวจสอบโครงสร้าง บริบท และความเสี่ยงที่อาจเกิดขึ้นของการเปลี่ยนแปลง และส่งคืนคำแนะนำพร้อมคำอธิบายและขั้นตอนถัดไป

เมื่อใดควรใช้

ใช้ evaluate_change เมื่อเริ่มต้นฟีเจอร์หรือการแก้ไข เมื่อคุณต้องการทำความเข้าใจว่างานนั้นจำเป็นต้องใช้ฟีเจอร์แฟล็กหรือไม่ เครื่องมือนี้ยังมีประโยชน์เมื่อคุณไม่แน่ใจว่าควรใช้แฟล็กประเภทใด หรือต้องการคำแนะนำในการวางแผนการเปิดตัว

วิธีการทำงาน

เครื่องมือส่งคืนคำแนะนำโดยละเอียดที่จัดรูปแบบเป็น markdown สำหรับผู้ช่วย LLM ตาม Unleash best practices

คำแนะนำรวมถึง:

  • การตรวจจับแฟล็กหลัก: ตรวจสอบว่าโค้ดได้รับการป้องกันโดยแฟล็กที่มีอยู่แล้วหรือไม่
  • การประเมินความเสี่ยง: วิเคราะห์รูปแบบโค้ดเพื่อระบุการดำเนินการที่มีความเสี่ยง
  • การประเมินประเภทโค้ด: จำแนกประเภทการเปลี่ยนแปลง (ตัวอย่างเช่น การทดสอบ การกำหนดค่า ฟีเจอร์ หรือการแก้ไขข้อบกพร่อง)
  • คำแนะนำ: แนะนำว่าควรสร้างแฟล็ก ใช้แฟล็กที่มีอยู่ หรือข้ามแฟล็ก
  • การดำเนินการถัดไป: ให้คำแนะนำเฉพาะเกี่ยวกับสิ่งที่ต้องทำต่อไป

เมื่อ evaluate_change ระบุว่าจำเป็นต้องใช้แฟล็ก จะให้คำแนะนำที่ชัดเจนเพื่อ:

  1. เรียกเครื่องมือ create_flag เพื่อสร้างฟีเจอร์แฟล็ก
  2. เรียกเครื่องมือ wrap_change เพื่อรับคำแนะนำการครอบโค้ดเฉพาะภาษา
  3. นำโค้ดที่ครอบไปใช้ตามรูปแบบที่ตรวจพบ

กระบวนการประเมิน

เครื่องมือทำตามกระบวนการประเมินที่ชัดเจน:

Step 1: Gather code changes (git diff, read files)
        ↓
Step 2: Check for parent flags (avoiding nesting)
        ↓
Step 3: Assess code type (test? config? feature?)
        ↓
Step 4: Evaluate risk (auth? payments? API changes?)
        ↓
Step 5: Calculate risk score
        ↓
Step 6: Make recommendation
        ↓
Step 7: Take action (create flag or proceed without)

การประเมินความเสี่ยง

เครื่องมือใช้รูปแบบที่ไม่ขึ้นกับภาษาเพื่อให้คะแนนความเสี่ยง:

  • ความเสี่ยงวิกฤต (คะแนน +5): ตัวอย่างเช่น การตรวจสอบสิทธิ์ การชำระเงิน ความปลอดภัย และการดำเนินการฐานข้อมูล
  • ความเสี่ยงสูง (คะแนน +3): ตัวอย่างเช่น การเปลี่ยนแปลง API, บริการภายนอก หรือคลาสใหม่
  • ความเสี่ยงปานกลาง (คะแนน +2): ตัวอย่างเช่น การดำเนินการแบบอะซิงโครนัสหรือการจัดการสถานะ
  • ความเสี่ยงต่ำ (คะแนน +1): ตัวอย่างเช่น การแก้ไขข้อบกพร่อง การปรับโครงสร้างใหม่ หรือการเปลี่ยนแปลงเล็กน้อย

คะแนนสะสมข้ามหมวดหมู่ที่ตรงกัน คะแนนรวมจะแมปกับระดับความเสี่ยง:

  • วิกฤต: คะแนน ≥ 5
  • สูง: คะแนน ≥ 3
  • ปานกลาง: คะแนน ≥ 2
  • ต่ำ: คะแนน < 2

เอาต์พุตรวมถึงคะแนน confidence (0-1) ที่แสดงถึงความแน่ใจที่ประเมินตนเองของ LLM ซึ่งเพิ่มขึ้นตามบริบทที่ให้มากขึ้น

หมวดหมู่ ยกเว้น ครอบคลุมไฟล์ที่ไม่จำเป็นต้องใช้ฟีเจอร์แฟล็กโดยไม่คำนึงถึงเนื้อหา: ไฟล์ทดสอบ (*.test.ts, *_test.go ฯลฯ), ไฟล์การกำหนดค่า (*.config.js, .env, *.yaml) และไฟล์เอกสาร (*.md, docs/**) การเปลี่ยนแปลงที่จำกัดเฉพาะไฟล์ที่ยกเว้นจะไม่ทำให้เกิดคำแนะนำแฟล็ก

คำจำกัดความรูปแบบทั้งหมด รวมถึงคำสำคัญต่อหมวดหมู่, ไฟล์ globs, รูปแบบโค้ด และเหตุผล อยู่ใน src/evaluation/riskPatterns.ts

การตรวจจับแฟล็กหลัก

เครื่องมือมองหารูปแบบทั่วไปในภาษาต่างๆ เช่น:

  • เงื่อนไข: if (isEnabled('flag')), if client.is_enabled('flag'):
  • การกำหนดค่า: const enabled = useFlag('flag')
  • ฮุก: const enabled = useFlag('flag') → {enabled && <Component />}
  • การ์ด: if (!isEnabled('flag')) return;
  • แรปเปอร์: withFeatureFlag('flag', () => {...})

พารามิเตอร์

พารามิเตอร์ทั้งหมดเป็นตัวเลือก แต่บริบทที่มากขึ้นจะนำไปสู่คำแนะนำที่ดีกว่า:

  • repository (string): ชื่อหรือเส้นทางของ Repository
  • branch (string): ชื่อ branch ปัจจุบัน
  • files (array): รายการไฟล์ที่กำลังเปลี่ยนแปลง
  • description (string): คำอธิบายการเปลี่ยนแปลง
  • riskLevel (enum): low, medium, high, หรือ critical, ตามที่ผู้ใช้ประเมิน
  • codeContext (string): โค้ดโดยรอบสำหรับการตรวจจับ flag หลัก

ตัวอย่างการใช้งาน

ข้อความแจ้ง Agent

การใช้งานแบบง่ายที่ให้ agent รวบรวมบริบท:

Use evaluate_change to help me determine if I need a feature flag

คำแนะนำที่ชัดเจน:

Use evaluate_change with:
- description: "Add Stripe payment processing"
- riskLevel: "high"

ข้อมูล payload ของเครื่องมือ

{
  "repository": "my-app",
  "branch": "feature/stripe-integration",
  "files": ["src/payments/stripe.ts"],
  "description": "Add Stripe payment processing",
  "riskLevel": "high",
  "codeContext": "surrounding code for parent flag detection"
}

ผลลัพธ์ของเครื่องมือ

ส่งคืนออบเจ็กต์ JSON พร้อมผลการประเมิน รวมถึง boolean needsFlag, recommendation (เช่น "create_new"), ชื่อ flag ที่แนะนำ, ระดับความเสี่ยง, และ explanation โดยละเอียด

{
  "needsFlag": true,
  "reason": "new_feature",
  "recommendation": "create_new",
  "suggestedFlag": "stripe-payment-integration",
  "riskLevel": "critical",
  "riskScore": 5,
  "explanation": "This change integrates Stripe payments, which is critical risk...",
  "confidence": 0.9
}

ตรวจจับ flag

เครื่องมือ detect_flag ค้นหา feature flag ที่มีอยู่ใน codebase เพื่อให้คุณสามารถนำกลับมาใช้ใหม่แทนการสร้างซ้ำ เครื่องมือนี้ถูกรวมเข้ากับเวิร์กโฟลว์ evaluate_change โดยอัตโนมัติ แต่ก็สามารถใช้งานด้วยตนเองได้เช่นกัน

เมื่อใดควรใช้

ใช้เครื่องมือนี้ก่อนสร้าง feature flag ใหม่ หรือระหว่างการประเมินโค้ดเพื่อตรวจสอบ flag ที่มีอยู่ซึ่งอาจครอบคลุมกรณีการใช้งานของคุณแล้ว ซึ่งช่วยป้องกันการสร้าง flag ซ้ำซ้อน

วิธีการทำงาน

เครื่องมือจะส่งคืนคำแนะนำการค้นหาที่ครอบคลุมและใช้กลยุทธ์การตรวจจับหลายแบบ:

  • การตรวจจับตามไฟล์: ค้นหา flag ที่มีอยู่ในไฟล์ที่คุณกำลังแก้ไข
  • การวิเคราะห์ประวัติ Git: มองหา flag ที่เพิ่งเพิ่มในประวัติ commit
  • การจับคู่ชื่อเชิงความหมาย: จับคู่คำอธิบายกับชื่อ flag ที่มีอยู่
  • การวิเคราะห์บริบทโค้ด: ตรวจสอบโค้ดรอบๆ การเปลี่ยนแปลง

จากนั้นเครื่องมือจะดำเนินการตามกระบวนการให้คะแนน:

Step 1: Execute file-based search (grep for flag patterns in target files)
        ↓
Step 2: Search git history for recent flag additions
        ↓
Step 3: Perform semantic matching (description → flag names)
        ↓
Step 4: Analyze code context (if provided)
        ↓
Step 5: Combine scores from all methods
        ↓
Step 6: Return best candidate with confidence score

ระดับความเชื่อมั่น

เครื่องมือจะส่งคืนตัวเลือกพร้อมคะแนนความเชื่อมั่น:

  • สูง ≥0.7: การจับคู่ที่แข็งแกร่ง; แนะนำให้นำกลับมาใช้ใหม่
  • ปานกลาง 0.4-0.7: การจับคู่ที่เป็นไปได้; ตรวจสอบด้วยตนเอง
  • ต่ำ <0.4: การจับคู่ที่อ่อน; มีแนวโน้มที่จะสร้าง flag ใหม่

พารามิเตอร์

  • description (จำเป็น): คำอธิบายการเปลี่ยนแปลงหรือฟีเจอร์ ตัวอย่างเช่น "payment processing with Stripe", "new checkout flow"
  • files (ตัวเลือก): ไฟล์ที่กำลังแก้ไข ตัวอย่างเช่น ["src/payments/stripe.ts", "src/checkout/flow.ts"]
  • codeContext (ตัวเลือก): โค้ดใกล้เคียงเพื่อสแกนหา flag

ตัวอย่างการใช้งาน

ข้อความแจ้ง Agent

ตรวจสอบ flag ที่มีอยู่ก่อนสร้าง flag:

Use detect_flag with description "payment processing with Stripe"

รวมเข้ากับการประเมินโดยอัตโนมัติ:

Use evaluate_change - automatically searches for existing flags

ข้อมูล payload ของเครื่องมือ

{
  "description": "payment processing with Stripe",
  "files": ["src/payments/stripe.ts"]
}

ผลลัพธ์ของเครื่องมือ

ส่งคืนออบเจ็กต์ JSON ที่ระบุว่าพบ flag หรือไม่ หาก flagFound เป็น true จะรวมออบเจ็กต์ candidate พร้อมชื่อ flag, ตำแหน่งที่ตั้ง, คะแนนความเชื่อมั่น, และเหตุผลในการจับคู่

พบการจับคู่:

{
  "flagFound": true,
  "candidate": {
    "name": "stripe-payment-integration",
    "location": "src/payments/stripe.ts:42",
    "context": "if (client.isEnabled('stripe-payment-integration')) {",
    "confidence": 0.85,
    "reasoning": "Found in same file you're modifying, added 2 days ago",
    "detectionMethod": "file-based"
  }
}

ไม่พบการจับคู่:

{
  "flagFound": false,
  "candidate": null
}

ห่อหุ้มการเปลี่ยนแปลง

เครื่องมือ wrap_change สร้างตัวอย่างโค้ดเฉพาะภาษาและคำแนะนำสำหรับการห่อหุ้มโค้ดด้วย feature flag ช่วยให้ LLM และนักพัฒนาปฏิบัติตามรูปแบบที่มีอยู่ใน codebase และใช้ flag ได้อย่างถูกต้อง

เมื่อใดควรใช้

ใช้เครื่องมือนี้หลังจากที่คุณสร้าง feature flag (ด้วย create_flag) และจำเป็นต้องนำไปใช้ในโค้ดของคุณ มีประโยชน์อย่างยิ่งเมื่อคุณต้องการให้แน่ใจว่าคุณกำลังปฏิบัติตามรูปแบบ codebase ที่มีอยู่ หรือต้องการตัวอย่างเฉพาะเฟรมเวิร์ก (เช่น React, Django)

วิธีการทำงาน

เครื่องมือนี้เป็นขั้นตอนสุดท้ายในเวิร์กโฟลว์ evaluate_change → create_flag → wrap_change

เครื่องมือให้คำแนะนำต่อไปนี้ในการตอบกลับ:

  1. คำแนะนำการค้นหา: คำแนะนำทีละขั้นตอนสำหรับการค้นหารูปแบบ flag ที่มีอยู่ใน codebase ของคุณโดยใช้ grep
  2. การตรวจจับรูปแบบ: ระบุรูปแบบทั่วไป (เช่น การ import, ชื่อตัวแปร client, ชื่อเมธอด, หรือรูปแบบการห่อหุ้ม)
  3. เทมเพลตเริ่มต้น: ตัวอย่างโค้ดสำรองหากไม่พบรูปแบบ
  4. ตัวอย่างเฉพาะเฟรมเวิร์ก: รูปแบบเฉพาะสำหรับ React, Express, Django และอื่นๆ
  5. หลายรูปแบบ: if-blocks, guard clauses, hooks, decorators, middleware และอื่นๆ

ภาษาและเฟรมเวิร์กที่รองรับ:

  • TypeScript/JavaScript: Node.js, React Hooks, Express middleware
  • Python: FastAPI, Django, Flask decorators
  • Go: if-blocks มาตรฐาน, HTTP middleware
  • Ruby: Rails controllers
  • PHP: Laravel controllers
  • C#: .NET/ASP.NET controllers
  • Java: Spring Boot
  • Rust: Actix/Rocket handlers

พารามิเตอร์

  • flagName (จำเป็น): ชื่อ feature flag ที่จะใช้ห่อหุ้มโค้ด ตัวอย่างเช่น: "new-checkout-flow", หรือ "stripe-integration"
  • language (ตัวเลือก): ภาษาโปรแกรม (ตรวจหาอัตโนมัติจาก fileName หากไม่ระบุ) รองรับ: typescript, javascript, python, go, ruby, php, csharp, java, rust
  • fileName (ตัวเลือก): ชื่อไฟล์ที่กำลังแก้ไข (ช่วยตรวจจับภาษา) ตัวอย่างเช่น: "checkout.ts", "payment.py", หรือ "handler.go"
  • codeContext (ตัวเลือก): โค้ดโดยรอบเพื่อช่วยตรวจจับรูปแบบที่มีอยู่
  • frameworkHint (ตัวเลือก): เฟรมเวิร์กสำหรับเทมเพลตเฉพาะ ตัวอย่างเช่น "React", "Express", "Django", "Rails", หรือ "Spring Boot"

ตัวอย่างการใช้งาน

ข้อความแจ้ง Agent

Use wrap_change with:
- flagName: "new-checkout-flow"
- fileName: "src/components/checkout.ts"
- frameworkHint: "React"

ข้อมูล payload ของเครื่องมือ

{
  "flagName": "new-checkout-flow",
  "fileName": "checkout.ts",
  "frameworkHint": "React"
}

ผลลัพธ์ของเครื่องมือ

ส่งคืนสตริงที่จัดรูปแบบ markdown อย่างครอบคลุมซึ่งแนะนำผู้ใช้เกี่ยวกับวิธีการห่อหุ้มโค้ด ซึ่งรวมถึง quickstart, คำแนะนำการค้นหา, คำแนะนำการห่อหุ้มพร้อมตัวยึดตำแหน่ง, เทมเพลตที่มีอยู่ทั้งหมดสำหรับภาษา, และลิงก์ไปยังเอกสาร SDK

# Feature Flag Wrapping Guide: "new-checkout-flow"

**Language:** TypeScript
**Framework:** React

## Quick Start
[Recommended pattern with import and usage]

## How to Search for Existing Flag Patterns
[Step-by-step Grep instructions]

## How to Wrap Code with Feature Flag
[Wrapping instructions with examples]

## All Available Templates
[If-block, guard clause, hooks, ternary, etc.]

ตั้งค่าการเปิดตัว flag

เครื่องมือ set_flag_rollout กำหนดค่ากลยุทธ์ flexibleRollout บนสภาพแวดล้อม feature flag โดยตั้งค่าเปอร์เซ็นต์การเปิดตัว, ความเหนียวแน่น (stickiness), และ variants ระดับกลยุทธ์ที่เป็นตัวเลือก การดำเนินการนี้ไม่ได้เปิดใช้งาน flag; ใช้ toggle_flag_environment เพื่อเปิดใช้งาน

เมื่อใดควรใช้

ใช้เครื่องมือนี้หลังจากสร้าง flag ด้วย create_flag เพื่อกำหนดค่าวิธีการกระจายทราฟฟิกก่อนเปิดใช้งาน นอกจากนี้ยังใช้เพื่ออัปเดตเปอร์เซ็นต์การเปิดตัวที่มีอยู่หรือเพิ่ม variants

พารามิเตอร์

  • featureName (จำเป็น): ชื่อ feature flag
  • environment (จำเป็น): สภาพแวดล้อมเป้าหมาย (ตัวอย่างเช่น "production", "development")
  • rolloutPercentage (จำเป็น): เปอร์เซ็นต์ของทราฟฟิกที่จะได้รับฟีเจอร์ (0-100)
  • projectId (ตัวเลือก): Project ID (ค่าเริ่มต้นคือ UNLEASH_DEFAULT_PROJECT)
  • groupId (ตัวเลือก): คีย์การจัดกลุ่มความเหนียวแน่น (ค่าเริ่มต้นคือชื่อฟีเจอร์)
  • stickiness (ตัวเลือก): ฟิลด์ความเหนียวแน่น (ค่าเริ่มต้นคือ "default")
  • title (ตัวเลือก): ชื่อที่อธิบายสำหรับกลยุทธ์
  • disabled (ตัวเลือก): สร้างกลยุทธ์ในสถานะปิดใช้งาน (ค่าเริ่มต้นคือ false)
  • variants (ตัวเลือก): รายการ variants ระดับกลยุทธ์ แต่ละรายการมี name, weight (0-1000), weightType ที่เป็นตัวเลือก ("variable" หรือ "fix"), stickiness, และ payload ({type, value})

ตัวอย่างการใช้งาน

ข้อความแจ้ง Agent

Use set_flag_rollout with:
- featureName: "new-checkout-flow"
- environment: "production"
- rolloutPercentage: 25

ข้อมูล payload ของเครื่องมือ

{
  "featureName": "new-checkout-flow",
  "environment": "production",
  "rolloutPercentage": 25,
  "projectId": "ecommerce",
  "stickiness": "userId"
}

ผลลัพธ์ของเครื่องมือ

ส่งคืนการยืนยันพร้อมเปอร์เซ็นต์ที่กำหนดค่า, ลิงก์ไปยัง flag ใน Unleash Admin UI, URL กลยุทธ์ Admin API, และลิงก์ทรัพยากร MCP สำหรับ flag

รับสถานะ flag

เครื่องมือ get_flag_state ดึงข้อมูล metadata ปัจจุบันและกลยุทธ์สภาพแวดล้อมของ feature flag จาก Unleash Admin API โดยส่งคืนประเภทของ flag, สถานะเปิดใช้งาน/เก็บถาวร, การตั้งค่าข้อมูล impression, และสรุปกลยุทธ์และ variants ที่ใช้งานอยู่ต่อสภาพแวดล้อม

เมื่อใดควรใช้

ใช้เครื่องมือนี้เพื่อตรวจสอบ flag ก่อนแก้ไข, เพื่อตรวจสอบจำนวนกลยุทธ์ที่ใช้งานอยู่ในสภาพแวดล้อมต่างๆ, หรือเพื่อค้นหา strategy IDs ก่อนเรียกใช้ remove_flag_strategy

พารามิเตอร์

  • featureName (จำเป็น): ชื่อ feature flag
  • projectId (ตัวเลือก): Project ID (ค่าเริ่มต้นคือ UNLEASH_DEFAULT_PROJECT)
  • environment (ตัวเลือก): กรองผลลัพธ์ให้เหลือสภาพแวดล้อมเดียว (ไม่คำนึงถึงตัวพิมพ์เล็กใหญ่)

ตัวอย่างการใช้งาน

ข้อความแจ้ง Agent

Use get_flag_state with:
- featureName: "new-checkout-flow"
- environment: "production"

ข้อมูล payload ของเครื่องมือ

{
  "featureName": "new-checkout-flow",
  "projectId": "ecommerce",
  "environment": "production"
}

ผลลัพธ์ของเครื่องมือ

ส่งคืนสรุปข้อความของ flag (ประเภท, เปิดใช้งาน/เก็บถาวร/ข้อมูล impression, โปรเจกต์, สรุปสภาพแวดล้อมพร้อมจำนวนกลยุทธ์) พร้อมกับลิงก์ UI และ API ผลลัพธ์ที่มีโครงสร้างรวมถึงออบเจ็กต์ฟีเจอร์เต็มรูปแบบพร้อมสภาพแวดล้อมและรายละเอียดกลยุทธ์ทั้งหมด

แสดงรายการ flag

เครื่องมือ list_flags แจกแจง feature flag ในโปรเจกต์และส่งคืนรายการที่มีโครงสร้างพร้อมการแบ่งหน้าและลำดับการจัดเรียง flag ที่ใช้งานอยู่และเก็บถาวรจะถูกส่งคืนแยกกัน: เรียกใช้ครั้งเดียวด้วย archived: false (ค่าเริ่มต้น) และอีกครั้งด้วย archived: true เพื่อรวบรวมรายการทั้งหมดสำหรับเวิร์กโฟลว์การตรวจสอบ

เมื่อใดควรใช้

ใช้เครื่องมือนี้เมื่อ agent ต้องการค้นพบว่ามี flag ใดอยู่แล้ว ตัวอย่างเช่น เพื่อตรวจสอบโปรเจกต์, ค้นหาตัวเลือกสำหรับการล้างข้อมูล, หรือสร้างบริบทก่อนสร้างหรือห่อหุ้ม flag เป็นเครื่องมือที่ agent เรียกใช้ได้เทียบเท่ากับทรัพยากร unleash://projects/{projectId}/feature-flags (ดู ทรัพยากร MCP)

พารามิเตอร์

  • projectId (ตัวเลือก): โปรเจกต์ที่จะแสดงรายการ flag (ค่าเริ่มต้นคือ UNLEASH_DEFAULT_PROJECT; แก้ไขอัตโนมัติเมื่อมีโปรเจกต์เดียว)
  • archived (ตัวเลือก): true เพื่อแสดงรายการ flag ที่เก็บถาวรแทนที่จะเป็น flag ที่ใช้งานอยู่ ค่าเริ่มต้นคือ false ไม่สามารถส่งคืน flag ที่ใช้งานอยู่และเก็บถาวรในการตอบกลับเดียวกันได้
  • limit (ตัวเลือก): จำนวน flag สูงสุดต่อหน้า (ค่าเริ่มต้น: ขนาดหน้าของเซิร์ฟเวอร์ โดยทั่วไปคือ 50)
  • order (ตัวเลือก): ลำดับการจัดเรียงตามชื่อ flag, asc หรือ desc (ค่าเริ่มต้น: asc)
  • offset (ตัวเลือก): จำนวน flag ที่จะข้ามสำหรับการแบ่งหน้า (ค่าเริ่มต้น: 0)

ตัวอย่างการใช้งาน

ข้อความแจ้ง Agent

Use list_flags with:
- projectId: "ecommerce"
- archived: false

ข้อมูล payload ของเครื่องมือ

{
  "projectId": "ecommerce",
  "archived": false,
  "limit": 50,
  "order": "asc"
}

ผลลัพธ์ของเครื่องมือ

ส่งคืนสรุปข้อความพร้อมเนื้อหาที่มีโครงสร้างด้วย projectId, archived, order, limit, offset, nextOffset, totalFlags, และอาร์เรย์ flags (แต่ละรายการมีชื่อ, ประเภท, โปรเจกต์, สถานะเก็บถาวร, และลิงก์) ใช้ nextOffset เพื่อเลื่อนดูหน้าในโปรเจกต์ขนาดใหญ่

แสดงรายการโปรเจกต์

เครื่องมือ list_projects แจกแจงโปรเจกต์ Unleash ที่พร้อมใช้งานสำหรับโทเค็นที่กำหนดค่าไว้ พร้อมการแบ่งหน้าและลำดับการจัดเรียง

เมื่อใดควรใช้

ใช้เครื่องมือนี้เมื่อไม่ทราบโปรเจกต์เป้าหมาย หรือเมื่อ agent ต้องการเลือกโปรเจกต์ก่อนแสดงรายการหรือสร้าง flag เป็นเครื่องมือที่ agent เรียกใช้ได้เทียบเท่ากับทรัพยากร unleash://projects (ดู ทรัพยากร MCP)

พารามิเตอร์

  • limit (ตัวเลือก): จำนวนโปรเจกต์สูงสุดต่อหน้า (ค่าเริ่มต้น: ขนาดหน้าของเซิร์ฟเวอร์ โดยทั่วไปคือ 20)
  • order (ตัวเลือก): ลำดับการจัดเรียงตามเวลาการสร้างโปรเจกต์, asc หรือ desc (ค่าเริ่มต้น: desc, ใหม่สุดก่อน)
  • offset (ตัวเลือก): จำนวนโปรเจกต์ที่จะข้ามสำหรับการแบ่งหน้า (ค่าเริ่มต้น: 0)

ตัวอย่างการใช้งาน

ข้อความแจ้ง Agent

Use list_projects to see which projects are available.

ข้อมูล payload ของเครื่องมือ

{
  "limit": 20,
  "order": "desc"
}

ผลลัพธ์ของเครื่องมือ

ส่งคืนสรุปข้อความพร้อมเนื้อหาที่มีโครงสร้างด้วย order, limit, offset, nextOffset, totalProjects, และอาร์เรย์ projects (แต่ละรายการมี id, ชื่อ, คำอธิบาย, โหมด, เวลาการสร้าง, และ URL)

สลับสภาพแวดล้อม flag

เครื่องมือ toggle_flag_environment เปิดหรือปิดใช้งาน feature flag ในสภาพแวดล้อมเฉพาะ สำหรับการเปิดตัวแบบค่อยเป็นค่อยไป ให้กำหนดค่ากลยุทธ์ด้วย set_flag_rollout ก่อนเปิดใช้งาน

เมื่อใดควรใช้

ใช้เครื่องมือนี้เพื่อเปิด flag หลังจากกำหนดค่ากลยุทธ์การเปิดตัว หรือเพื่อปิดใช้งาน flag ระหว่างเหตุการณ์หรือหลังจากเสร็จสิ้นการเปิดตัว

พารามิเตอร์

  • featureName (จำเป็น): ชื่อ feature flag
  • environment (จำเป็น): สภาพแวดล้อมที่จะสลับสถานะ (เช่น "production")
  • enabled (จำเป็น): true เพื่อเปิดใช้งาน, false เพื่อปิดใช้งาน
  • projectId (ไม่บังคับ): รหัสโปรเจกต์ (ค่าเริ่มต้นคือ UNLEASH_DEFAULT_PROJECT)

ตัวอย่างการใช้งาน

พรอมต์ของเอเจนต์

Use toggle_flag_environment with:
- featureName: "new-checkout-flow"
- environment: "production"
- enabled: true

เพย์โหลดของเครื่องมือ

{
  "featureName": "new-checkout-flow",
  "environment": "production",
  "enabled": true,
  "projectId": "ecommerce"
}

ผลลัพธ์ของเครื่องมือ

ส่งคืนการยืนยันสถานะใหม่, สรุปสภาพแวดล้อม (เปิด/ปิด, จำนวนกลยุทธ์) และลิงก์ไปยัง flag ใน Unleash Admin UI และ Admin API

ลบกลยุทธ์ของ flag

เครื่องมือ remove_flag_strategy จะลบการกำหนดค่ากลยุทธ์ออกจากสภาพแวดล้อมของ feature flag ใช้ get_flag_state ก่อนเพื่อค้นหา ID ของกลยุทธ์

เมื่อใดควรใช้

ใช้เครื่องมือนี้เพื่อล้างกลยุทธ์ที่ค้างอยู่ หรือเพื่อแทนที่กลยุทธ์เดิมโดยการลบอันเก่าและกำหนดค่าอันใหม่ด้วย set_flag_rollout

พารามิเตอร์

  • featureName (จำเป็น): ชื่อ feature flag
  • environment (จำเป็น): สภาพแวดล้อมที่จะลบกลยุทธ์ออก
  • strategyId (จำเป็น): ID ของกลยุทธ์ที่จะลบ (ค้นหาผ่าน get_flag_state)
  • projectId (ไม่บังคับ): รหัสโปรเจกต์ (ค่าเริ่มต้นคือ UNLEASH_DEFAULT_PROJECT)

ตัวอย่างการใช้งาน

พรอมต์ของเอเจนต์

Use get_flag_state to find strategy IDs for "new-checkout-flow" in production,
then use remove_flag_strategy to delete the old strategy.

เพย์โหลดของเครื่องมือ

{
  "featureName": "new-checkout-flow",
  "environment": "production",
  "strategyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "projectId": "ecommerce"
}

ผลลัพธ์ของเครื่องมือ

ส่งคืนการยืนยันการลบ, จำนวนกลยุทธ์ที่เหลือในสภาพแวดล้อม และลิงก์ไปยัง flag ใน Unleash Admin UI และ Admin API

ล้าง flag

เครื่องมือ cleanup_flag จะสร้างคำแนะนำทีละขั้นตอนสำหรับการลบโค้ด feature flag ออกจากโค้ดเบสอย่างปลอดภัย โดยคงเส้นทางโค้ดที่ต้องการไว้

เมื่อใดควรใช้

ใช้เครื่องมือนี้เมื่อ feature flag เสร็จสิ้นวงจรชีวิต:

  • หลังจากการเปิดตัวถึง 100% และไม่ต้องการ flag อีกต่อไป
  • เมื่อเลิกใช้ฟีเจอร์ทดลอง (คงเส้นทางที่ปิดใช้งานไว้)
  • เมื่อลบ kill switch ที่ไม่จำเป็นอีกต่อไป
  • ระหว่างการล้างหนี้ทางเทคนิคของ flag เก่า

วิธีการทำงาน

เครื่องมือจะส่งคืนคำแนะนำการล้างที่ครอบคลุมซึ่งแนะนำ LLM ผ่าน:

  1. การค้นหาทุกตำแหน่งที่ flag ปรากฏโดยใช้รูปแบบ grep
  2. การระบุรูปแบบการใช้งาน (บล็อก if-else, นิพจน์ ternary, guard clause, hooks, decorators, middleware)
  3. การลบการตรวจสอบ flag โดยคงเส้นทางโค้ดที่ถูกต้องไว้
  4. การล้าง import ที่ไม่ได้ใช้ด้วยคำแนะนำเฉพาะภาษา
  5. การตรวจสอบการเปลี่ยนแปลงด้วยขั้นตอนการค้นหาหลังการล้างและการทดสอบ

หากไม่ได้ระบุ preservePath เครื่องมือจะส่งคืนคำแนะนำให้ถามผู้ใช้ว่าต้องการคงเส้นทางใดก่อนดำเนินการต่อ

พารามิเตอร์

  • flagName (จำเป็น): ชื่อของ feature flag ที่จะลบ (เช่น "new-checkout-flow")
  • preservePath (ไม่บังคับ): "enabled" เพื่อคงเส้นทางโค้ดเมื่อ flag เปิด (โดยทั่วไปสำหรับการเปิดตัวที่เสร็จสมบูรณ์) หรือ "disabled" เพื่อคงเส้นทางเมื่อ flag ปิด (สำหรับการทดลองที่ถูกลบ) หากละไว้ เครื่องมือจะแจ้งให้คุณถามผู้ใช้
  • files (ไม่บังคับ): ไฟล์เฉพาะที่จะล้าง หากละไว้ จะค้นหาทั้งโค้ดเบส
  • language (ไม่บังคับ): ภาษาโปรแกรมสำหรับคำแนะนำการล้าง import เฉพาะทาง (เช่น "typescript", "python") ตรวจหาอัตโนมัติจาก files หากไม่ได้ระบุ

ตัวอย่างการใช้งาน

พรอมต์ของเอเจนต์

Use cleanup_flag with:
- flagName: "new-checkout-flow"
- preservePath: "enabled"

เพย์โหลดของเครื่องมือ

{
  "flagName": "new-checkout-flow",
  "preservePath": "enabled",
  "files": ["src/components/checkout.tsx", "src/api/checkout.ts"],
  "language": "typescript"
}

ผลลัพธ์ของเครื่องมือ

ส่งคืนคู่มือ markdown ที่ครอบคลุมขอบเขตการล้างและเส้นทางที่คงไว้, คำสั่ง grep เพื่อค้นหาทุกตำแหน่ง, คำแนะนำการลบตามรูปแบบ, การล้าง import เฉพาะภาษา และขั้นตอนการตรวจสอบหลังการล้าง (ค้นหาซ้ำ, รันการทดสอบ, ตรวจสอบด้วยตนเอง)

ทรัพยากร MCP

เซิร์ฟเวอร์ลงทะเบียน MCP resources สำหรับการอ่านข้อมูลโปรเจกต์และ feature flag ทรัพยากรทั้งหมดส่งคืน JSON และถูกแคชเป็นเวลา 60 วินาที

เทมเพลต URIคำอธิบาย
unleash://projects{?limit,order,offset}แสดงรายการโปรเจกต์ ขนาดหน้าเริ่มต้น: 20, เรียงตามเวลาที่สร้าง (ใหม่สุดก่อน)
unleash://projects/{projectId}/feature-flags{?limit,order,offset}แสดงรายการ flag ในโปรเจกต์ ขนาดหน้าเริ่มต้น: 50, เรียงตามตัวอักษร
unleash://projects/{projectId}/feature-flags/{flagName}ข้อมูลเมตาของ feature flag เดี่ยว

สองเทมเพลตแรกยอมรับพารามิเตอร์คิวรีเพิ่มเติม: limit (ขนาดหน้า), order (asc หรือ desc) และ offset (จุดเริ่มต้นการแบ่งหน้า) การตอบกลับรวมถึงฟิลด์ fetchedAt, cached, totalProjects หรือ totalFlags และ nextOffset

ทรัพยากร vs. เครื่องมือ: ทรัพยากร MCP ถูกควบคุมโดยแอปพลิเคชัน ดังนั้นไคลเอนต์จำนวนมากจึงแสดงผ่าน UI ที่ขับเคลื่อนโดยผู้ใช้เท่านั้น (เช่น การกล่าวถึง #) และไม่อนุญาตให้เอเจนต์เรียก resources/read ด้วยตนเอง เมื่อเอเจนต์ต้องการแจกแจงโปรเจกต์หรือ flag โดยทางโปรแกรม ให้ใช้เครื่องมือ list_projects และ list_flags ซึ่งส่งคืนข้อมูลเดียวกันผ่านอินเทอร์เฟซเครื่องมือ การวิเคราะห์สินค้าคงคลัง detect_flag ใช้เส้นทางเดียวกัน

ตัวอย่างการอ่านทรัพยากร

Read unleash://projects/ecommerce/feature-flags?limit=10&order=asc

ส่งคืน feature flag 10 รายการแรกในโปรเจกต์ ecommerce เรียงตามตัวอักษร พร้อมข้อมูลเมตาการแบ่งหน้า

สถาปัตยกรรม

เซิร์ฟเวอร์ปฏิบัติตามการออกแบบที่มุ่งเน้นและขับเคลื่อนด้วยวัตถุประสงค์

โครงสร้าง

src/
├── index.ts                     # Stdio CLI entry point
├── server.ts                    # Transport-agnostic server factory
├── remote.ts                    # HTTP request handler for embedded mode
├── config.ts                    # Configuration loading and validation
├── context.ts                   # Shared runtime context
├── version.ts                   # Version constant
├── unleash/
│   └── client.ts                # Unleash Admin API client
├── tools/
│   ├── types.ts                 # Shared ToolDefinition type
│   ├── createFlag.ts            # create_flag tool
│   ├── evaluateChange.ts        # evaluate_change tool
│   ├── detectFlag.ts            # detect_flag tool
│   ├── wrapChange.ts            # wrap_change tool
│   ├── cleanupFlag.ts           # cleanup_flag tool
│   ├── setFlagRollout.ts        # set_flag_rollout tool
│   ├── getFlagState.ts          # get_flag_state tool
│   ├── toggleFlagEnvironment.ts # toggle_flag_environment tool
│   └── removeFlagStrategy.ts    # remove_flag_strategy tool
├── resources/
│   └── unleashResources.ts      # MCP resource handlers (projects, flags)
├── prompts/
│   └── promptBuilder.ts         # Markdown formatting utilities
├── evaluation/
│   ├── riskPatterns.ts          # Risk assessment patterns
│   └── flagDetectionPatterns.ts # Parent flag detection patterns
├── detection/
│   ├── flagDiscovery.ts         # Flag discovery strategies
│   └── flagScoring.ts           # Scoring and ranking logic
├── knowledge/
│   └── unleashBestPractices.ts  # Best practices knowledge base
├── templates/
│   ├── languages.ts             # Language detection and metadata
│   ├── wrapperTemplates.ts      # Code wrapping templates
│   ├── searchGuidance.ts        # Pattern search instructions
│   └── cleanupGuidance.ts       # Flag cleanup instructions
└── utils/
    ├── errors.ts                # Error normalization
    ├── streaming.ts             # Progress notifications
    └── stdioLogging.ts          # Stdio protocol traffic logging

หลักการออกแบบ

  • พื้นที่ผิวบาง: เฉพาะจุดสิ้นสุดที่จำเป็นสำหรับความสามารถหลัก
  • ขับเคลื่อนด้วยวัตถุประสงค์: แต่ละโมดูลมีวัตถุประสงค์เฉพาะที่กำหนดไว้อย่างดี
  • การตรวจสอบอย่างชัดเจน: Zod schemas ตรวจสอบอินพุตทั้งหมดก่อนการเรียก API
  • การทำให้ข้อผิดพลาดเป็นมาตรฐาน: ข้อผิดพลาดทั้งหมดถูกแปลงเป็นรูปแบบ {code, message, hint}
  • การสตรีมความคืบหน้า: การดำเนินการที่ใช้เวลานานให้การมองเห็น
  • การรวมแนวปฏิบัติที่ดีที่สุด: คำแนะนำจากเอกสาร Unleash ฝังอยู่ในคำอธิบายเครื่องมือ

การกำหนดค่า

ส่วนนี้ให้ข้อมูลอ้างอิงอย่างรวดเร็วสำหรับตัวเลือกการกำหนดค่าทั้งหมด

ตัวแปรสภาพแวดล้อม:

  • UNLEASH_BASE_URL: URL อินสแตนซ์ Unleash ของคุณ (จำเป็น) ยอมรับทั้ง https://your-instance.getunleash.io และ https://your-instance.getunleash.io/api — เซิร์ฟเวอร์จะตัด /api ต่อท้ายออกหากมี ดังนั้นคุณจึงสามารถวางค่าเดียวกับที่ Unleash SDK ส่วนใหญ่คาดหวังได้
  • UNLEASH_PAT: โทเค็นการเข้าถึงส่วนบุคคล (จำเป็น)
  • UNLEASH_DEFAULT_PROJECT: รหัสโปรเจกต์เริ่มต้นที่ MCP ควรใช้ (ไม่บังคับ)

แฟล็ก CLI:

  • --dry-run: จำลองการดำเนินการโดยไม่ทำการเรียก API จริง
  • --log-level: ตั้งค่าระดับความละเอียดของการบันทึก (debug, info, warn, error)

แนวปฏิบัติที่ดีที่สุด

เซิร์ฟเวอร์นี้สนับสนุนแนวปฏิบัติที่ดีที่สุดของ Unleash จาก เอกสารอย่างเป็นทางการ:

วงจรชีวิตของ flag

  1. สร้างด้วยเจตนา: เลือกประเภท flag ที่เหมาะสมเพื่อส่งสัญญาณวัตถุประสงค์
  2. จัดทำเอกสารอย่างชัดเจน: เขียนคำอธิบายที่อธิบาย "เหตุผล"
  3. วางแผนการล้าง: Feature flag เป็นสิ่งชั่วคราว วางแผนการลบออก
  4. ตรวจสอบการใช้งาน: เปิดใช้งานข้อมูล impression สำหรับ flag ที่สำคัญ

ประเภทของ flag

  • Release flags: สำหรับการเปิดตัวฟีเจอร์แบบค่อยเป็นค่อยไป (ลบหลังจากการเปิดตัวเต็มรูปแบบ)
  • Experiment flags: สำหรับการทดสอบ A/B (ลบหลังจากการวิเคราะห์)
  • Operational flags: สำหรับพฤติกรรมของระบบ (มีอายุยาวนานกว่า ตรวจสอบเป็นระยะ)
  • Kill switches: สำหรับการควบคุมฉุกเฉิน (คงไว้จนกว่าฟีเจอร์จะเสถียร)
  • Permission flags: สำหรับการควบคุมการเข้าถึง (มีอายุยาวนานกว่า ตรวจสอบสิทธิ์)

หลักการตั้งชื่อ

  • ใช้ kebab-case: new-checkout-flow
  • ตั้งชื่อให้สื่อความหมาย: enable-ai-recommendations ไม่ใช่ flag1
  • รวมขอบเขตเมื่อจำเป็น: mobile-push-notifications

ข้อมูลอ้างอิง API

เซิร์ฟเวอร์นี้ใช้ Unleash Admin API สำหรับเอกสาร API ฉบับสมบูรณ์ ดู:

จุดสิ้นสุดที่ใช้

  • GET /api/admin/projects - แสดงรายการโปรเจกต์
  • GET /api/admin/projects/{projectId}/features - แสดงรายการ feature flag
  • POST /api/admin/projects/{projectId}/features - สร้าง feature flag
  • GET /api/admin/projects/{projectId}/features/{featureName} - รับรายละเอียด flag
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies - เพิ่มกลยุทธ์การเปิดตัว
  • DELETE /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies/{strategyId} - ลบกลยุทธ์
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/on - เปิดใช้งาน flag
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/off - ปิดใช้งาน flag

การแก้ไขปัญหา

ปัญหาการกำหนดค่า

ข้อผิดพลาด: "UNLEASH_BASE_URL must be a valid URL": ตรวจสอบว่า URL พื้นฐานของคุณสมบูรณ์ รวมถึงโปรโตคอล ตัวอย่างเช่น https://app.unleash-hosted.com/instance ลบเครื่องหมายทับต่อท้ายออก

ข้อผิดพลาด: "UNLEASH_PAT is required": ตรวจสอบว่าไฟล์ .env ของคุณมีอยู่และมี UNLEASH_PAT={{your-personal-access-token}} ตรวจสอบว่าโทเค็นถูกต้องใน Unleash

ปัญหา API

ข้อผิดพลาด: "HTTP_401": โทเค็นการเข้าถึงส่วนบุคคลของคุณอาจไม่ถูกต้องหรือหมดอายุ สร้างโทเค็นใหม่ภายใต้ Profile > View Profile settings > Personal API tokens > New token

ข้อผิดพลาด: "HTTP_403": โทเค็นของคุณไม่มีสิทธิ์ในการสร้าง flag ในโปรเจกต์นี้ ตรวจสอบบทบาทและสิทธิ์ของคุณใน Unleash

ข้อผิดพลาด: "HTTP_404": รหัสโปรเจกต์ไม่มีอยู่ ยืนยันรหัสโปรเจกต์ใน Unleash Admin UI

ข้อผิดพลาด: "HTTP_409": มี flag ที่มีชื่อนี้อยู่แล้วในโปรเจกต์ ใช้ชื่ออื่นหรือใช้ flag ที่มีอยู่ซ้ำ

ใบอนุญาต

MIT

การมีส่วนร่วม

นี่เป็นโปรเจกต์ที่ขับเคลื่อนด้วยวัตถุประสงค์และมีขอบเขตที่มุ่งเน้น การมีส่วนร่วมควร:

  • สอดคล้องกับพื้นผิวเครื่องมือและโมเดลทรัพยากร MCP ที่มีอยู่
  • รักษาสถาปัตยกรรมที่บางและขับเคลื่อนด้วยวัตถุประสงค์
  • ปฏิบัติตามแนวปฏิบัติที่ดีที่สุดของ Unleash
  • รวมเอกสารที่ชัดเจน