Blueprint MCP Server

ทางการ

ระบบอัตโนมัติของเบราว์เซอร์ผ่าน MCP สำหรับ Chrome และ Firefox

เอกสาร

Blueprint MCP

ควบคุมเบราว์เซอร์จริงของคุณด้วย AI ผ่าน Model Context Protocol

นี่คืออะไร?

เซิร์ฟเวอร์ MCP (Model Context Protocol) ที่ให้ผู้ช่วย AI ควบคุมเบราว์เซอร์จริงของคุณ (Chrome, Firefox หรือ Opera) ผ่านส่วนขยายเบราว์เซอร์ แตกต่างจากเครื่องมืออัตโนมัติแบบ headless ตรงที่ใช้โปรไฟล์เบราว์เซอร์จริงของคุณ พร้อมเซสชันที่ล็อกอินไว้ คุกกี้ และส่วนขยายทั้งหมด

เหมาะสำหรับ: เอเจนต์ AI ที่ต้องการโต้ตอบกับเว็บไซต์ที่คุณล็อกอินอยู่แล้ว หรือต้องการหลีกเลี่ยงการตรวจจับบอต

ทำไมต้องใช้แทน Playwright/Puppeteer?

Blueprint MCP	Playwright/Puppeteer
✅ เบราว์เซอร์จริง (ไม่ใช่ headless)	❌ Headless หรืออินสแตนซ์เบราว์เซอร์ใหม่
✅ ยังคงล็อกอินอยู่ในทุกเว็บไซต์ของคุณ	❌ ต้องยืนยันตัวตนใหม่ทุกเซสชัน
✅ หลีกเลี่ยงการตรวจจับบอต (ใช้ลายนิ้วมือจริง)	⚠️ มักถูกตรวจจับว่าเป็นเบราว์เซอร์อัตโนมัติ
✅ ทำงานร่วมกับส่วนขยายเบราว์เซอร์ที่มีอยู่	❌ ไม่รองรับส่วนขยาย
✅ ไม่ต้องตั้งค่า - ใช้งานได้ทันที	⚠️ ต้องติดตั้งเบราว์เซอร์
✅ รองรับ Chrome, Firefox, Edge, Opera	✅ รองรับ Chrome, Firefox, Safari

การติดตั้ง

1. ติดตั้งเซิร์ฟเวอร์ MCP

npm install -g @railsblueprint/blueprint-mcp

2. ติดตั้งส่วนขยายเบราว์เซอร์

เลือกเบราว์เซอร์ของคุณ:

Chrome / Edge / Opera

Chrome Web Store (ใช้ได้กับทุกเบราว์เซอร์ Chromium)
แบบกำหนดเอง: ดาวน์โหลดจาก Releases จากนั้นโหลดแบบ unpacked ที่ chrome://extensions/ (Chrome), edge://extensions/ (Edge) หรือ opera://extensions/ (Opera)

Firefox

Firefox Add-ons
แบบกำหนดเอง: ดาวน์โหลดจาก Releases จากนั้นโหลดที่ about:debugging#/runtime/this-firefox

3. กำหนดค่าไคลเอนต์ MCP ของคุณ

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["@railsblueprint/blueprint-mcp@latest"]
    }
  }
}

Claude Code (CLI ที่ขับเคลื่อนด้วย AI):

claude mcp add browser npx @railsblueprint/blueprint-mcp@latest

VS Code / Cursor (.vscode/settings.json):

{
  "mcp.servers": {
    "browser": {
      "command": "npx",
      "args": ["@railsblueprint/blueprint-mcp@latest"]
    }
  }
}

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

เริ่มไคลเอนต์ MCP ของคุณ (Claude Desktop, Cursor ฯลฯ)
คลิกไอคอนส่วนขยาย Blueprint MCP ในเบราว์เซอร์ของคุณ
ส่วนขยายจะเชื่อมต่อกับเซิร์ฟเวอร์ MCP โดยอัตโนมัติ
ขอให้ผู้ช่วย AI ของคุณท่องเว็บ!

ตัวอย่างบทสนทนา:

You: "Go to GitHub and check my notifications"
AI: *navigates to github.com, clicks notifications, reads content*

You: "Fill out this form with my info"
AI: *reads form fields, fills them in, submits*

You: "Take a screenshot of this page"
AI: *captures screenshot and shows you*

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

┌─────────────────────────┐
│   AI Assistant          │
│   (Claude, GPT, etc)    │
└───────────┬─────────────┘
            │
            │ MCP Protocol
            ↓
┌─────────────────────────┐
│   MCP Client            │
│   (Claude Desktop, etc) │
└───────────┬─────────────┘
            │
            │ stdio/JSON-RPC
            ↓
┌─────────────────────────┐
│   blueprint-mcp         │
│   (this package)        │
└───────────┬─────────────┘
            │
            │ WebSocket (localhost:5555 or cloud relay)
            ↓
┌─────────────────────────┐
│   Browser Extension     │
└───────────┬─────────────┘
            │
            │ Browser Extension APIs
            ↓
┌─────────────────────────┐
│   Your Browser          │
│   (real profile)        │
└─────────────────────────┘

ฟรี vs PRO

ระดับฟรี (ค่าเริ่มต้น)

✅ การเชื่อมต่อ WebSocket ในเครื่อง (พอร์ต 5555)
✅ อินสแตนซ์เบราว์เซอร์เดียว
✅ ฟีเจอร์อัตโนมัติของเบราว์เซอร์ทั้งหมด
✅ ไม่ต้องมีบัญชี
❌ จำกัดเฉพาะเครื่องเดียวกัน

ระดับ PRO

✅ Cloud relay - เชื่อมต่อจากที่ไหนก็ได้
✅ หลายเบราว์เซอร์ - ควบคุมอินสแตนซ์เบราว์เซอร์หลายตัว
✅ การเข้าถึงร่วมกัน - ไคลเอนต์ AI หลายตัวสามารถใช้เบราว์เซอร์เดียวกันได้
✅ เชื่อมต่อใหม่อัตโนมัติ - รักษาการเชื่อมต่อผ่านการเปลี่ยนแปลงเครือข่าย
✅ การสนับสนุนลำดับความสำคัญ

อัปเกรดเป็น PRO

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

เซิร์ฟเวอร์ MCP มอบเครื่องมือเหล่านี้ให้กับผู้ช่วย AI:

การจัดการการเชื่อมต่อ

enable - เปิดใช้งานระบบอัตโนมัติของเบราว์เซอร์ (ขั้นตอนแรกที่จำเป็น)
disable - ปิดใช้งานระบบอัตโนมัติของเบราว์เซอร์
status - ตรวจสอบสถานะการเชื่อมต่อ
auth - เข้าสู่ระบบบัญชี PRO (สำหรับฟีเจอร์ cloud relay)

การจัดการแท็บ

browser_tabs - แสดงรายการ สร้าง แนบ หรือปิดแท็บเบราว์เซอร์

การนำทาง

browser_navigate - นำทางไปยัง URL
browser_navigate_back - ย้อนกลับในประวัติ

เนื้อหาและการตรวจสอบ

browser_snapshot - รับเนื้อหาหน้าที่เข้าถึงได้ (แนะนำสำหรับการอ่านหน้า)
browser_take_screenshot - จับภาพหน้าจอ
browser_console_messages - รับบันทึกคอนโซลเบราว์เซอร์
browser_network_requests - เครื่องมือตรวจสอบและเล่นซ้ำเครือข่ายที่มีประสิทธิภาพ พร้อมการดำเนินการหลายอย่าง:
- โหมดรายการ (ค่าเริ่มต้น): ภาพรวมแบบเบาพร้อมการกรองและการแบ่งหน้า (ค่าเริ่มต้น: 20 คำขอ)
  - ตัวกรอง: urlPattern (สตริงย่อย), method (GET/POST), status (200/404), resourceType (xhr/fetch/script)
  - การแบ่งหน้า: limit (ค่าเริ่มต้น: 20), offset (ค่าเริ่มต้น: 0)
  - ตัวอย่าง: action='list', urlPattern='api/users', method='GET', limit=10
- โหมดรายละเอียด: ข้อมูลคำขอ/การตอบกลับแบบเต็มสำหรับคำขอเฉพาะ รวมถึงส่วนหัวและเนื้อหา
- การกรอง JSONPath: สืบค้นการตอบกลับ JSON ขนาดใหญ่โดยใช้ไวยากรณ์ JSONPath (เช่น $.data.items[0])
- โหมดเล่นซ้ำ: ดำเนินการคำขอที่บันทึกไว้ใหม่ด้วยส่วนหัวและการยืนยันตัวตนเดิม
- โหมดล้าง: ล้างประวัติที่บันทึกไว้เพื่อเพิ่มหน่วยความจำ
- ตัวอย่าง: action='details', requestId='12345.67', jsonPath='$.data.users[0]'
browser_extract_content - แยกเนื้อหาหน้าเป็น markdown

การโต้ตอบ

browser_interact - ดำเนินการหลายอย่างตามลำดับ (คลิก พิมพ์ โฮเวอร์ รอ ฯลฯ)
browser_click - คลิกที่องค์ประกอบ
browser_type - พิมพ์ข้อความลงในช่องป้อนข้อมูล
browser_hover - โฮเวอร์เหนือองค์ประกอบ
browser_select_option - เลือกตัวเลือกดรอปดาวน์
browser_fill_form - กรอกข้อมูลหลายฟิลด์ในฟอร์มพร้อมกัน
browser_press_key - กดปุ่มคีย์บอร์ด
browser_drag - ลากและวางองค์ประกอบ

ขั้นสูง

browser_evaluate - รัน JavaScript ในบริบทของหน้า
browser_handle_dialog - จัดการไดอะล็อก alert/confirm/prompt
browser_file_upload - อัปโหลดไฟล์ผ่านช่องป้อนข้อมูลไฟล์
browser_window - ปรับขนาด ย่อ ขยายหน้าต่างเบราว์เซอร์
browser_pdf_save - บันทึกหน้าปัจจุบันเป็น PDF
browser_performance_metrics - รับเมตริกประสิทธิภาพ
browser_verify_text_visible - ตรวจสอบว่ามีข้อความปรากฏอยู่ (สำหรับการทดสอบ)
browser_verify_element_visible - ตรวจสอบว่ามีองค์ประกอบอยู่ (สำหรับการทดสอบ)

การจัดการส่วนขยาย

browser_list_extensions - แสดงรายการส่วนขยายเบราว์เซอร์ที่ติดตั้ง
browser_reload_extensions - โหลดส่วนขยายแบบ unpacked ใหม่ (มีประโยชน์ระหว่างการพัฒนา)

การพัฒนา

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

Node.js 18+
เบราว์เซอร์ที่รองรับ (Chrome, Firefox, Edge หรือ Opera)
npm หรือ yarn

การตั้งค่า

# Clone the repository
git clone https://github.com/railsblueprint/blueprint-mcp.git
cd blueprint-mcp

# Install server dependencies
cd server
npm install
cd ..

# Install Chrome extension dependencies
cd extensions/chrome
npm install
cd ../..

การรันในโหมดพัฒนา

เทอร์มินัล 1: เริ่มเซิร์ฟเวอร์ MCP ในโหมดดีบัก

cd server
node cli.js --debug

เทอร์มินัล 2: สร้างส่วนขยาย Chrome

cd extensions/chrome
npm run build
# or for watch mode:
npm run dev

หมายเหตุ: ส่วนขยาย Firefox ไม่ต้องมีขั้นตอนการสร้าง - ใช้ JavaScript วานิลลาและสามารถโหลดได้โดยตรงจาก extensions/firefox/

โหลดส่วนขยายในเบราว์เซอร์ของคุณ:

สำหรับเบราว์เซอร์ Chromium (Chrome, Edge, Opera):

เปิด chrome://extensions/ (Chrome), edge://extensions/ (Edge) หรือ opera://extensions/ (Opera)
เปิดใช้งาน "โหมดนักพัฒนา"
คลิก "โหลด unpacked"
เลือกโฟลเดอร์ extensions/chrome/dist

สำหรับ Firefox:

เปิด about:debugging#/runtime/this-firefox
คลิก "โหลดส่วนเสริมชั่วคราว"
เลือกไฟล์ใดก็ได้จากโฟลเดอร์ extensions/firefox

โครงสร้างโปรเจกต์

blueprint-mcp/
├── server/                     # MCP Server
│   ├── cli.js                  # Server entry point
│   ├── src/
│   │   ├── statefulBackend.js  # Connection state management
│   │   ├── unifiedBackend.js   # MCP tool implementations
│   │   ├── extensionServer.js  # WebSocket server for extension
│   │   ├── mcpConnection.js    # Proxy/relay connection handling
│   │   ├── transport.js        # Transport abstraction layer
│   │   ├── oauth.js            # OAuth2 client for PRO features
│   │   └── fileLogger.js       # Debug logging
│   └── tests/                  # Server test suites
├── extensions/                 # Browser Extensions
│   ├── chrome/                 # Chrome extension (TypeScript + Vite)
│   │   └── src/
│   │       ├── background.ts   # Extension service worker
│   │       ├── content-script.ts # Page content injection
│   │       └── utils/          # Utility functions
│   ├── firefox/                # Firefox extension (Vanilla JS)
│   │   └── src/
│   │       ├── background.js   # Service worker
│   │       └── content-script.js # Page injection
│   ├── shared/                 # Shared code between extensions
│   └── build-*.js              # Build scripts for each browser
├── docs/                       # Documentation
│   ├── testing/                # Test documentation
│   ├── architecture/           # Architecture docs
│   └── stores/                 # Browser store assets
└── releases/                   # Built extensions for distribution
    ├── chrome/
    ├── firefox/
    ├── edge/
    └── opera/

การทดสอบ

# Run tests
npm test

# Run with coverage
npm run test:coverage

เอกสารประกอบ:

ขั้นตอนการทดสอบด้วยตนเอง - คู่มือการทดสอบด้วยตนเองที่ครอบคลุม
ข้อกำหนดคุณสมบัติ - เอกสารคุณสมบัติที่สมบูรณ์
ความคืบหน้าการทดสอบ - สถานะความครอบคลุมการทดสอบปัจจุบัน

การกำหนดค่า

เซิร์ฟเวอร์ทำงานได้ทันทีด้วยค่าเริ่มต้นที่เหมาะสม สำหรับการกำหนดค่าขั้นสูง:

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

สร้างไฟล์ .env ในรูทของโปรเจกต์:

# Authentication server (PRO features)
AUTH_BASE_URL=https://blueprint-mcp.railsblueprint.com

# Local WebSocket port (Free tier)
MCP_PORT=5555

# Debug mode
DEBUG=false

ตัวเลือกบรรทัดคำสั่ง

blueprint-mcp --debug              # Enable verbose logging
blueprint-mcp --port 8080          # Use custom WebSocket port (default: 5555)
blueprint-mcp --debug --port 8080  # Combine options

หมายเหตุ: หากคุณเปลี่ยนพอร์ต คุณจะต้องอัปเดตการตั้งค่าส่วนขยายเบราว์เซอร์ให้ตรงกัน

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

ส่วนขยายไม่เชื่อมต่อ

ตรวจสอบว่าส่วนขยายติดตั้งและเปิดใช้งานอยู่
คลิกไอคอนส่วนขยาย - ควรแสดง "Connected"
ตรวจสอบว่าเซิร์ฟเวอร์ MCP กำลังทำงานอยู่ (มองหากระบวนการบนพอร์ต 5555)
ลองโหลดส่วนขยายใหม่

"พอร์ต 5555 ถูกใช้งานอยู่แล้ว"

มีอีกอินสแตนซ์กำลังทำงานอยู่ คุณสามารถ:

ฆ่ากระบวนการที่มีอยู่:

lsof -ti:5555 | xargs kill -9

ใช้พอร์ตอื่น:

blueprint-mcp --port 8080

เครื่องมือเบราว์เซอร์ไม่ทำงาน

ตรวจสอบให้แน่ใจว่าคุณได้เรียก enable ก่อน
ตรวจสอบว่าคุณได้แนบกับแท็บด้วย browser_tabs
ตรวจสอบว่าแท็บยังคงอยู่ (ไม่ได้ถูกปิด)

การขอความช่วยเหลือ

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

เรายินดีรับการมีส่วนร่วม! ดู CONTRIBUTING.md สำหรับแนวทาง

ความปลอดภัย

เครื่องมือนี้ให้ผู้ช่วย AI ควบคุมเบราว์เซอร์ของคุณ โปรดตรวจสอบ:

เซิร์ฟเวอร์ MCP ยอมรับเฉพาะการเชื่อมต่อในเครื่องตามค่าเริ่มต้น (localhost:5555)
การเชื่อมต่อ PRO relay ได้รับการยืนยันตัวตนผ่าน OAuth
ส่วนขยายต้องการการดำเนินการจากผู้ใช้อย่างชัดเจนเพื่อเชื่อมต่อ
การดำเนินการเบราว์เซอร์ทั้งหมดผ่านระบบสิทธิ์ของเบราว์เซอร์

พบปัญหาด้านความปลอดภัย? โปรดอีเมล [email protected] แทนการยื่น issue สาธารณะ

เครดิต

โปรเจกต์นี้ได้รับแรงบันดาลใจมาจากการใช้งาน Playwright MCP ของ Microsoft แต่ถูกเขียนใหม่ทั้งหมดเพื่อใช้ระบบอัตโนมัติผ่านส่วนขยายเบราว์เซอร์แทน Playwright สถาปัตยกรรม การใช้งาน และแนวทางแตกต่างกันโดยพื้นฐาน

ความแตกต่างที่สำคัญ:

ใช้ส่วนขยายเบราว์เซอร์กับ DevTools Protocol (ไม่ใช่ Playwright)
ทำงานกับโปรไฟล์เบราว์เซอร์จริง (ไม่ใช่บริบทแยก)
การสื่อสารผ่าน WebSocket (ไม่ใช่ CDP relay)
ตัวเลือก cloud relay สำหรับการเข้าถึงระยะไกล
โมเดลระดับฟรีและ PRO
รองรับหลายเบราว์เซอร์ (Chrome, Firefox, Edge, Opera)

เราขอขอบคุณทีม Playwright ที่บุกเบิกระบบอัตโนมัติของเบราว์เซอร์ผ่าน MCP

ใบอนุญาต

Apache License 2.0 - ดู LICENSE

สร้างด้วย ❤️ โดย Rails Blueprint

เว็บไซต์ • GitHub • NPM