Unleash

ทางการ

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

GitHub
22

คุณทำอะไรได้บ้างด้วย Unleash MCP?

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

เอกสาร

เซิร์ฟเวอร์ MCP ของ Unleash

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

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

ภาพรวม

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

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

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

เซิร์ฟเวอร์ 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 ที่มีสิทธิ์ในการสร้างฟีเจอร์แฟล็ก

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

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

การตั้งค่าสำหรับ Agent

คุณสามารถเพิ่มเซิร์ฟเวอร์ MCP ลงใน Claude Code หรือ Codex ได้โดยตรง การกำหนดค่า Agent ขึ้นอยู่กับเส้นทางเฉพาะ คุณต้องรันคำสั่งต่อไปนี้จากไดเรกทอรีรากของโปรเจกต์ที่คุณต้องการใช้ 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

การตั้งค่า Agent ระยะไกล (ทดลอง)

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

หมายเหตุ: 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 อยู่แล้วหรือต้องการการเข้าถึงแบบ headless/ไม่โต้ตอบ (ไปป์ไลน์ CI สภาพแวดล้อมการพัฒนาที่ใช้ร่วมกัน ไคลเอนต์ที่ไม่รองรับ 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@latest --log-level debug

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

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

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

  1. ติดตั้ง dependencies

โคลนที่เก็บและติดตั้ง dependencies โดยใช้ 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 pnpm@11.0.8 --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 เพื่อบิลด์ใหม่เมื่อมีการเปลี่ยนแปลงในขณะที่คำสั่ง agent คงที่
  • โลจิสต์อยู่ในรากของที่เก็บ (app.log, mcp-stdio.log) ทั้งคู่ถูก gitignore

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

  • LOG_LEVEL (แนะนำ): ควบคุมระดับความละเอียดของการบันทึกแอปพลิเคชัน (debug, info, warn, error) ค่าเริ่มต้นคือ error เมื่อไม่ได้ตั้งค่า
  • แฟล็ก CLI --log-level: การแทนที่แบบไม่บังคับสำหรับ LOG_LEVEL เมื่อคุณต้องการการเปลี่ยนแปลงครั้งเดียว
  • APP_LOG_FILE (ไม่บังคับ): หากตั้งค่า โลจิสต์แอปพลิเคชันจะถูกเขียนไปยังไฟล์นี้ (ไม่ใช่ stdout) หากไม่ได้ตั้งค่า โลจิสต์จะไปที่ stderr
  • MCP_STDIO_LOG_FILE (ไม่บังคับ): หากตั้งค่า stdin/stdout/stderr ของ MCP จะถูก tee ลงในไฟล์เดียวนี้พร้อมคำนำหน้าช่องทาง ข้อความโปรโตคอลยังคงไหลผ่าน 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: การปิดระบบฉุกเฉินหรือ circuit breakers
    • permission: ควบคุมการเข้าถึงฟีเจอร์ตามบทบาทผู้ใช้หรือสิทธิ์
  • description (จำเป็น): คำอธิบายที่ชัดเจนว่าแฟล็กควบคุมอะไรและเหตุใดจึงมีอยู่
  • projectId (ไม่บังคับ): โปรเจกต์เป้าหมาย (ค่าเริ่มต้นคือ UNLEASH_DEFAULT_PROJECT)
  • impressionData (ไม่บังคับ): เปิดใช้งานการติดตามการวิเคราะห์ (ค่าเริ่มต้นคือ false)

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

พรอมต์ Agent

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

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

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

เมื่อ 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): ตัวอย่างเช่น การดำเนินการแบบ async หรือการจัดการสถานะ
  • ความเสี่ยงต่ำ (คะแนน +1): ตัวอย่างเช่น การแก้ไขบั๊ก การรีแฟกเตอร์ หรือการเปลี่ยนแปลงเล็กน้อย

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

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

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

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

คำจำกัดความรูปแบบทั้งหมด รวมถึงคำหลักต่อหมวดหมู่ glob ของไฟล์ รูปแบบโค้ด และเหตุผล อยู่ใน 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 (สตริง): ชื่อหรือเส้นทางของ repository
  • branch (สตริง): ชื่อ branch ปัจจุบัน
  • files (อาร์เรย์): รายการไฟล์ที่กำลังเปลี่ยนแปลง
  • description (สตริง): คำอธิบายของการเปลี่ยนแปลง
  • riskLevel (enum): low, medium, high, หรือ critical ตามที่ผู้ใช้ประเมิน
  • codeContext (สตริง): โค้ดโดยรอบสำหรับการตรวจจับ flag ของ parent

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

พรอมต์สำหรับ 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 flags ที่มีอยู่แล้วใน codebase เพื่อให้คุณนำมาใช้ซ้ำแทนการสร้างซ้ำซ้อน เครื่องมือนี้ถูกรวมเข้ากับเวิร์กโฟลว์ evaluate_change โดยอัตโนมัติ แต่ยังสามารถใช้งานด้วยตนเองได้

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

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

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

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

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

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

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 (ตัวเลือก): โค้ดใกล้เคียงเพื่อสแกนหา flags

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

พรอมต์สำหรับ agent

ตรวจสอบ flags ที่มีอยู่ก่อนสร้าง 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 flags ช่วยให้ LLM และนักพัฒนาปฏิบัติตามรูปแบบที่มีอยู่ใน codebase และใช้ flags อย่างถูกต้อง

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

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

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

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

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

  1. คำแนะนำการค้นหา: คำแนะนำทีละขั้นตอนสำหรับการค้นหารูปแบบ flags ที่มีอยู่ใน codebase ของคุณโดยใช้ grep
  2. การตรวจจับรูปแบบ: ระบุรูปแบบทั่วไป (เช่น imports, ชื่อตัวแปร 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, คำแนะนำการค้นหา, คำแนะนำการห่อหุ้มพร้อม placeholders, เทมเพลตทั้งหมดที่มีสำหรับภาษา, และลิงก์ไปยังเอกสาร 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.]

ตั้งค่า rollout ของ 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 (ตัวเลือก): คีย์ bucketing ของ stickiness (ค่าเริ่มต้นคือชื่อฟีเจอร์)
  • stickiness (ตัวเลือก): ฟิลด์ 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 ดึงข้อมูลเมตาปัจจุบันของ 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 ผลลัพธ์แบบมีโครงสร้างรวมถึงออบเจกต์ฟีเจอร์ทั้งหมดพร้อมรายละเอียดสภาพแวดล้อมและกลยุทธ์ทั้งหมด

รายการ flags

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

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

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

พารามิเตอร์

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

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

ใช้เครื่องมือนี้เมื่อไม่ทราบโปรเจกต์เป้าหมาย หรือเมื่อ agent จำเป็นต้องเลือกโปรเจกต์ก่อนแสดงรายการหรือสร้าง flags เป็นเครื่องมือที่ 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 (จำเป็น): ชื่อฟีเจอร์แฟล็ก
  • 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"
}

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

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

ลบกลยุทธ์ของแฟล็ก

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

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

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

พารามิเตอร์

  • featureName (จำเป็น): ชื่อฟีเจอร์แฟล็ก
  • environment (จำเป็น): สภาพแวดล้อมที่จะลบกลยุทธ์ออก
  • strategyId (จำเป็น): รหัสของกลยุทธ์ที่จะลบ (ค้นหาได้ผ่าน 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"
}

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

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

ทำความสะอาดแฟล็ก

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

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

ใช้เครื่องมือนี้เมื่อฟีเจอร์แฟล็กสิ้นสุดวงจรชีวิตแล้ว:

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

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

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

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

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

พารามิเตอร์

  • flagName (จำเป็น): ชื่อของฟีเจอร์แฟล็กที่จะลบ (เช่น "new-checkout-flow")
  • preservePath (ไม่บังคับ): "enabled" เพื่อเก็บเส้นทางโค้ดเมื่อเปิดแฟล็ก (ทั่วไปสำหรับการเปิดตัวที่เสร็จสมบูรณ์) หรือ "disabled" เพื่อเก็บเส้นทางเมื่อปิดแฟล็ก (สำหรับการทดลองที่ถูกลบ) หากละเว้น เครื่องมือจะแจ้งให้ถามผู้ใช้
  • 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 สำหรับการอ่านข้อมูลโปรเจกต์และฟีเจอร์แฟล็ก ทรัพยากรทั้งหมดส่งกลับ JSON และถูกแคชเป็นเวลา 60 วินาที

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

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

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

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

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

ส่งกลับฟีเจอร์แฟล็ก 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 ตรวจสอบอินพุตทั้งหมดก่อนเรียก 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 จาก เอกสารอย่างเป็นทางการ:

วงจรชีวิตของแฟล็ก

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

ประเภทของแฟล็ก

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

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

  • ใช้ 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 - รายการฟีเจอร์แฟล็ก
  • POST /api/admin/projects/{projectId}/features - สร้างฟีเจอร์แฟล็ก
  • GET /api/admin/projects/{projectId}/features/{featureName} - ดูรายละเอียดแฟล็ก
  • 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 - เปิดใช้งานแฟล็ก
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/off - ปิดใช้งานแฟล็ก

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

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

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

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

ปัญหา API

ข้อผิดพลาด: "HTTP_401": โทเค็นการเข้าถึงส่วนบุคคลของคุณอาจไม่ถูกต้องหรือหมดอายุ สร้างโทเค็นใหม่ภายใต้ โปรไฟล์ > ดูการตั้งค่าโปรไฟล์ > โทเค็น API ส่วนบุคคล > โทเค็นใหม่

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

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

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

สัญญาอนุญาต

MIT

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

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

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