GrowthBook

GrowthBook MCP Thin

Một máy chủ MCP mỏng cho GrowthBook với bốn công cụ:

Công cụ	Mục đích
growthbook_list_skills	Liệt kê các điểm vào kỹ năng cấp cao nhất (tên + mô tả)
growthbook_read_skill	Trả về một kỹ năng đã liệt kê hoặc quy trình con đủ điều kiện (feature-flags hoặc feature-flags/references/flag-create)
growthbook_api_read	Chuyển tiếp GET đã xác thực tới API GrowthBook
growthbook_api_write	Chuyển tiếp POST/PUT/PATCH/DELETE đã xác thực

Năng lực nằm trong kho kỹ năng và được đóng gói tại thời điểm xây dựng. Khả năng được chia thành các công cụ API đọc và ghi (không có định dạng theo từng điểm cuối) để máy khách có thể tôn trọng readOnlyHint / destructiveHint một cách chính xác.

Các công cụ được đặt tiền tố growthbook_ để chúng không bị mơ hồ khi máy khách có nhiều máy chủ MCP được tải.

Cài đặt / chạy

npm install
npm run build

Trỏ máy khách MCP của bạn tới điểm vào đã biên dịch:

{
  "mcpServers": {
    "growthbook": {
      "command": "node",
      "args": ["/absolute/path/to/growthbook-mcp/server/index.js"],
      "env": {
        "GB_API_KEY": "your_api_key_or_pat",
        "GB_API_URL": "https://api.growthbook.io"
      }
    }
  }
}

Hoặc chạy gói đã xuất bản:

npx @growthbook/mcp

Biến môi trường

Biến	Bắt buộc	Mặc định	Mục đích
GB_API_KEY	Có cho stdio; tùy chọn cho HTTP OAuth	—	Khóa API GrowthBook hoặc mã thông báo truy cập cá nhân
GB_API_URL	Không	https://api.growthbook.io	URL cơ sở API (tự lưu trữ) và nhà phát hành AS OAuth mặc định
GB_MCP_TRANSPORT	Không	stdio	stdio hoặc http
GB_MCP_PORT	Không	3333	Cổng nghe HTTP (khi transport=http)
GB_MCP_HOST	Không	127.0.0.1	Máy chủ liên kết HTTP
GB_MCP_URL	Có cho HTTP	—	URL cơ sở MCP công khai được đóng dấu vào siêu dữ liệu tài nguyên OAuth (máy chủ từ chối khởi động ở chế độ HTTP nếu thiếu)
GB_MCP_KEEP_ALIVE_TIMEOUT_MS	Không	90000	Thời gian chờ keep-alive nhàn rỗi ở chế độ HTTP. Phải vượt quá thời gian chờ nhàn rỗi của bất kỳ bộ cân bằng tải nào phía trước, nếu không LB có thể tái sử dụng kết nối mà máy chủ đã đóng và yêu cầu thất bại với mã 502
GB_OAUTH_ISSUER	Không	GB_API_URL	URL nhà phát hành AS OAuth GrowthBook
GB_HTTP_HEADER_*	Không	—	Tiêu đề yêu cầu bổ sung (ví dụ: GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	Không	true	Đặt thành false / 0 để vô hiệu hóa các công cụ kỹ năng

Chế độ HTTP + OAuth

OAUTH_AS_ENABLED=1  # on the GrowthBook API
GB_MCP_TRANSPORT=http GB_API_URL=http://localhost:3100 GB_MCP_PORT=3333 npm start

Máy khách kết nối tới:

• http://127.0.0.1:3333/mcp — đầy đủ (kỹ năng + đọc/ghi API)
• http://127.0.0.1:3333/mcp/api — chỉ khả năng (growthbook_api_read + growthbook_api_write)

Các yêu cầu chưa xác thực nhận 401 với WWW-Authenticate trỏ tới /.well-known/oauth-protected-resource, nơi quảng cáo Máy chủ ủy quyền GrowthBook.

Trước khi xử lý MCP, máy chủ thăm dò REST GrowthBook (GET /api/v1/) với bearer. Một 401 từ lần thăm dò đó (hoặc sau đó từ một công cụ API) tạo ra HTTP 401 với error="invalid_token" để máy khách MCP có thể làm mới — thay vì hiển thị "This API key has expired" như một lỗi công cụ. Một 403 được coi là bearer được chấp nhận (từ chối quyền ≠ mã thông báo không hợp lệ) để máy khách không bị buộc vào vòng lặp làm mới.

Chế độ chỉ khả năng

HTTP (khuyến nghị cho từ xa): trỏ máy khách tới /mcp/api thay vì /mcp:

{
  "mcpServers": {
    "growthbook": {
      "url": "http://127.0.0.1:3333/mcp/api"
    }
  }
}

Đường dẫn	Công cụ
/mcp	growthbook_list_skills, growthbook_read_skill, growthbook_api_read, growthbook_api_write (trừ khi GB_SKILLS_ENABLED=false)
/mcp/api	growthbook_api_read, growthbook_api_write chỉ

stdio / toàn tiến trình: đặt env để kỹ năng không bao giờ được đăng ký:

"env": {
  "GB_API_KEY": "...",
  "GB_SKILLS_ENABLED": "false"
}

Khi kỹ năng bị vô hiệu hóa, chỉ các công cụ đọc/ghi API được đăng ký. growthbook_list_skills và growthbook_read_skill không được hiển thị.

Cách các kỹ năng được đóng gói

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs sao chép cây kỹ năng cấp cao nhất từ bản kiểm tra kỹ năng chuẩn, bảo toàn cấu trúc:

skills/<skill>/SKILL.md                   → server/skills/<skill>/SKILL.md
skills/<skill>/references/<workflow>.md   → server/skills/<skill>/references/<workflow>.md

Giải quyết đường dẫn nguồn:

1. SKILLS_SRC biến env (đường dẫn tới gốc kho kỹ năng)
2. agent-skills.local.json — { "path": "../skills" }, tương đối với gốc kho. Được gitignore; sao chép agent-skills.local.json.example
3. skills-src/ — những gì CI và bản dựng Docker cung cấp

Không có tra cứu ngang hàng ngầm. ../skills giải quyết tới bất cứ thứ gì có tại đường dẫn đó, điều này khiến bản dựng cục bộ âm thầm không khớp với cam kết mà CI dựng từ đó.

CI, triển khai đám mây và bản phát hành đều đọc agent-skills.lock.json và kiểm tra chính xác cam kết kỹ năng đó. Để gửi thay đổi kỹ năng thượng nguồn, hãy cập nhật cam kết trong tệp khóa. Phát triển cục bộ có thể trỏ tới bất kỳ bản kiểm tra nào với agent-skills.local.json hoặc SKILLS_SRC.

Kho kỹ năng vẫn là nguồn chân lý — gói này không duy trì bản sao nội dung kỹ năng. Các kỹ năng mới tự động chảy qua, ngoại trừ những kỹ năng được nêu tên trong danh sách chặn nhỏ trong bundle-skills.mjs. Hiện chỉ gb-setup bị chặn vì nó cấu hình bộ điều hợp shell gb-call thay vì GrowthBook chính nó.

Các thư mục scripts/ theo từng kỹ năng không được sao chép. Các liên kết tương đối `references/foo.md` được viết lại thành `feature-flags/references/foo` paths so growthbook_read_skill có thể giải quyết chúng.

Sử dụng kỹ năng với các công cụ API

Các kỹ năng được đóng gói vẫn hiển thị quy trình như:

gb-call GET /api/v1/projects
gb-call POST /api/v2/features ./payload.json

Máy chủ MCP này không gọi ra gb-call. Ánh xạ GET → growthbook_api_read và POST/PUT/PATCH/DELETE → growthbook_api_write với cùng đường dẫn và chuỗi thân JSON tùy chọn. Hướng dẫn máy chủ và đầu ra growthbook_read_skill bao gồm ghi chú cầu nối này.

Chi tiết công cụ

growthbook_api_read / growthbook_api_write

{ "path": "/api/v1/projects" }
{ "method": "POST", "path": "/api/v2/features", "body": "{\"id\":\"my-flag\",...}" }

• Đọc: GET chỉ (readOnlyHint: true)
• Ghi: POST | PUT | PATCH | DELETE (destructiveHint: true)
• Trả về thân phản hồi thô trên 2xx
• Trên không phải 2xx, trả về lỗi có thể hành động (isError: true) bao gồm lỗi xác thực, gợi ý 404 tự lưu trữ và giới hạn tốc độ
• Đường dẫn tự do nhắm tới API REST GrowthBook

growthbook_list_skills / growthbook_read_skill

Chỉ được đăng ký khi GB_SKILLS_ENABLED không bị vô hiệu hóa.

• growthbook_list_skills trả về các điểm vào kỹ năng cấp cao nhất. Một điểm vào có thể chứa quy trình hoàn chỉnh hoặc định tuyến tới các quy trình con.
• growthbook_read_skill chấp nhận tên cấp cao nhất đã liệt kê hoặc đường dẫn con đủ điều kiện được đặt tên bởi một kỹ năng đã tải (feature-flags/references/flag-create) và trả về markdown đầy đủ (quy trình + rào cản).

Phát triển

git clone git@github.com:growthbook/skills.git ../skills
cp agent-skills.local.json.example agent-skills.local.json  # edit if not at ../skills

npm install
npm run build
npm start

Chế độ HTTP độc lập

Theo mặc định, máy chủ chạy qua stdio. Đặt GB_MCP_TRANSPORT=http để chạy nó như một máy chủ HTTP độc lập hiển thị MCP tại /mcp (kỹ năng + công cụ API) và /mcp/api (chỉ khả năng), phía sau bề mặt tài nguyên được bảo vệ OAuth 2.0 (siêu dữ liệu RFC 9728 + WWW-Authenticate RFC 6750).

• GB_MCP_URL (bắt buộc ở chế độ HTTP) — URL cơ sở công khai của máy chủ. Nó được đóng dấu vào tài nguyên OAuth (đối tượng) và siêu dữ liệu tài nguyên được bảo vệ, vì vậy nó không bao giờ được suy ra từ tiêu đề yêu cầu. Máy chủ từ chối khởi động nếu thiếu.
• GB_MCP_PORT (mặc định 3333) và GB_MCP_HOST (mặc định 127.0.0.1).
• Các bearer đến được xác thực bằng cách thăm dò API REST GrowthBook; mã thông báo bị từ chối nhận HTTP 401 + WWW-Authenticate để máy khách có thể làm mới.

Chạy nó trên mạng đáng tin cậy hoặc liên kết với loopback. Đối với triển khai đa khách thuê hoặc công khai, hãy đặt nó phía sau cổng/ xác thực của riêng bạn.

Bản phát hành

Cắt bản phát hành là có chủ đích: tăng phiên bản trong package.json, sau đó đẩy thẻ v* khớp:

git tag v2.0.0
git push origin v2.0.0

Cam kết được gắn thẻ đó (với kỹ năng bị đóng băng tại thời điểm cắt) xuất bản:

• @growthbook/mcp tới npm — bản phát hành trước (phiên bản có -, ví dụ: 2.0.0-beta.1) đi dưới thẻ phân phối beta; phiên bản ổn định trở thành latest
• hình ảnh đa kiến trúc (amd64 + arm64) tới ghcr.io/growthbook/growthbook-mcp (:<version>, cộng :<major>, :<major>.<minor> và :latest cho bản phát hành ổn định)
• một mục trong sổ đăng ký MCP
• một Bản phát hành GitHub

Cài đặt bản phát hành với npx @growthbook/mcp@<version> hoặc kéo ghcr.io/growthbook/growthbook-mcp:<version>.