Neon

chính thức

Tương tác với nền tảng Postgres serverless Neon

Bạn có thể làm gì với Neon MCP?

  • Tạo dự án và nhánh — Yêu cầu tạo một dự án hoặc nhánh Neon mới, ví dụ: "tạo một cơ sở dữ liệu Postgres tên là my-database," thông qua create_projectcreate_branch.
  • Chạy truy vấn SQL và giao dịch — Thực thi SQL đơn hoặc đa câu lệnh trên cơ sở dữ liệu bằng run_sql hoặc run_sql_transaction, bao gồm cả ghi khi không ở chế độ chỉ đọc.
  • Kiểm tra lược đồ và bảng — Liệt kê các bảng bằng get_database_tables hoặc lấy định nghĩa đầy đủ về cột/ràng buộc của bảng qua describe_table_schema.
  • Lên kế hoạch và áp dụng di trú an toàn — Bắt đầu di trú bằng prepare_database_migration để kiểm thử trên nhánh tạm, sau đó hoàn tất với complete_database_migration.
  • Điều chỉnh truy vấn chậm — Xác định điểm nghẽn bằng list_slow_queries hoặc lấy kế hoạch thực thi qua explain_sql_statement, sau đó kiểm thử các bản sửa lỗi bằng prepare_query_tuning.
  • Khám phá dự án và nhật ký — Tìm kiếm trên các tổ chức, dự án và nhánh bằng search, hoặc lọc nhật ký có cấu trúc bằng query_logslist_log_fields.

Tài liệu

Neon Logo fallback

Neon MCP Server

Install MCP Server in Cursor Add to Kiro

Neon MCP Server là một công cụ mã nguồn mở cho phép bạn tương tác với các cơ sở dữ liệu Lakebase Postgres trên Neon bằng ngôn ngữ tự nhiên.

License: MIT

Giao thức Ngữ cảnh Mô hình (Model Context Protocol - MCP) là một giao thức chuẩn hóa được thiết kế để quản lý ngữ cảnh giữa các mô hình ngôn ngữ lớn (LLM) và các hệ thống bên ngoài. Kho lưu trữ này cung cấp một MCP Server từ xa cho Neon.

MCP server của Neon hoạt động như một cầu nối giữa các yêu cầu ngôn ngữ tự nhiên và Neon API. Được xây dựng trên MCP, nó dịch các yêu cầu của bạn thành các lệnh gọi API cần thiết, cho phép bạn quản lý các tác vụ như tạo dự án và nhánh, chạy truy vấn và thực hiện di trú cơ sở dữ liệu một cách liền mạch.

Một số tính năng chính của Neon MCP server bao gồm:

  • Tương tác bằng ngôn ngữ tự nhiên: Quản lý cơ sở dữ liệu Neon bằng các lệnh hội thoại trực quan, dễ hiểu.
  • Đơn giản hóa việc quản lý cơ sở dữ liệu: Thực hiện các thao tác phức tạp mà không cần viết SQL hoặc sử dụng trực tiếp Neon API.
  • Khả năng tiếp cận cho người không phải nhà phát triển: Trao quyền cho người dùng có nền tảng kỹ thuật khác nhau để tương tác với cơ sở dữ liệu Neon.
  • Hỗ trợ di trú cơ sở dữ liệu: Tận dụng khả năng phân nhánh của Neon cho các thay đổi lược đồ cơ sở dữ liệu được khởi tạo qua ngôn ngữ tự nhiên.

Ví dụ: trong Claude Code hoặc bất kỳ MCP Client nào, bạn có thể sử dụng ngôn ngữ tự nhiên để thực hiện các tác vụ với Neon, chẳng hạn như:

  • Let's create a new Postgres database, and call it "my-database". Let's then create a table called users with the following columns: id, name, email, and password.
  • I want to run a migration on my project called "my-project" that alters the users table to add a new column called "created_at".
  • Can you give me a summary of all of my Neon projects and what data is in each one?

[!WARNING]
Cân nhắc bảo mật Neon MCP Server
Neon MCP Server cung cấp các khả năng quản lý cơ sở dữ liệu mạnh mẽ thông qua các yêu cầu ngôn ngữ tự nhiên. Luôn xem xét và phê duyệt các hành động được LLM yêu cầu trước khi thực thi. Đảm bảo chỉ những người dùng và ứng dụng được ủy quyền mới có quyền truy cập vào Neon MCP Server.

Neon MCP Server chỉ dành cho phát triển cục bộ và tích hợp IDE. Chúng tôi không khuyến nghị sử dụng Neon MCP Server trong môi trường sản xuất. Nó có thể thực thi các thao tác mạnh mẽ có thể dẫn đến các thay đổi ngoài ý muốn hoặc trái phép.

Để biết thêm thông tin, hãy xem Hướng dẫn bảo mật MCP →.

Thiết lập Neon MCP Server

Có một số tùy chọn để thiết lập Neon MCP Server:

  1. Thiết lập nhanh với API Key (Cursor, VS Code và Claude Code): Chạy neon@latest init để tự động cấu hình MCP Server của Neon, agent skills và tiện ích mở rộng VS Code chỉ với một lệnh.
  2. MCP Server từ xa (Xác thực dựa trên OAuth): Kết nối với MCP server được quản lý của Neon bằng OAuth để xác thực. Phương pháp này thuận tiện hơn vì loại bỏ nhu cầu quản lý API key. Ngoài ra, bạn sẽ tự động nhận được các tính năng và cải tiến mới nhất ngay khi chúng được phát hành.
  3. MCP Server từ xa (Xác thực dựa trên API Key): Kết nối với MCP server được quản lý của Neon bằng API key để xác thực. Phương pháp này hữu ích nếu bạn muốn kết nối một agent từ xa với Neon khi OAuth không khả dụng. Ngoài ra, bạn sẽ tự động nhận được các tính năng và cải tiến mới nhất ngay khi chúng được phát hành.

Điều kiện tiên quyết

  • Một ứng dụng MCP Client.
  • Một tài khoản Neon.
  • Node.js (>= v18.0.0): Tải xuống từ nodejs.org.
  • Nếu IP Allow được bật, hãy thêm 34.192.103.4623.22.233.166 vào danh sách cho phép của bạn (mcp.neon.tech static IPs).

Đối với phát triển, bạn cần Node.js 22+ (pnpm được cung cấp qua Corepack — chạy corepack enable để kích hoạt).

Tùy chọn 1. Thiết lập nhanh với API Key

Không muốn tự tạo API key?

Chạy neon@latest init để tự động cấu hình MCP Server của Neon chỉ với một lệnh:

npx neon@latest init

Cách này hoạt động với Cursor, VS Code (GitHub Copilot) và Claude Code. Nó sẽ xác thực qua OAuth, tạo API key Neon cho bạn và tự động cấu hình trình soạn thảo của bạn.

Tùy chọn 2. MCP Server từ xa được lưu trữ (Xác thực dựa trên OAuth)

Kết nối với MCP server được quản lý của Neon bằng OAuth để xác thực. Đây là cách thiết lập dễ nhất, không yêu cầu cài đặt cục bộ server này và không cần cấu hình API key Neon trong client.

Chạy lệnh sau để thêm Neon MCP Server cho tất cả các agent và trình soạn thảo được phát hiện trong không gian làm việc của bạn:

npx add-mcp https://mcp.neon.tech/mcp

Thêm cờ -g để thêm Neon MCP Server vào danh sách MCP server toàn cục thay vì phạm vi dự án.

Ngoài ra, bạn có thể thêm mục "Neon" sau vào tệp cấu hình MCP server của client (ví dụ: mcp.json, mcp_config.json):

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

Kiro: Thêm nội dung sau vào tệp cấu hình MCP Kiro của bạn (~/.kiro/settings/mcp.json cho toàn cục hoặc .kiro/settings/mcp.json cho phạm vi dự án):

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

Hoặc sử dụng nút cài đặt một lần ở đầu README này. Để biết thêm thông tin, hãy xem tài liệu MCP Kiro.

  • Khởi động lại hoặc làm mới MCP client của bạn.
  • Một cửa sổ OAuth sẽ mở trong trình duyệt của bạn. Làm theo các hướng dẫn để ủy quyền cho MCP client truy cập tài khoản Neon của bạn.

Với xác thực dựa trên OAuth, MCP server theo mặc định sẽ hoạt động trên các dự án thuộc tài khoản Neon cá nhân của bạn. Để truy cập hoặc quản lý các dự án thuộc về một tổ chức, bạn phải cung cấp rõ ràng org_id hoặc project_id trong lời nhắc của bạn cho MCP client.

Tùy chọn 3. MCP Server từ xa được lưu trữ (Xác thực dựa trên API Key)

MCP Server từ xa cũng hỗ trợ xác thực bằng API key trong tiêu đề Authorization nếu client của bạn hỗ trợ.

Tạo API key Neon trong Neon Console. Tiếp theo, chạy lệnh sau để thêm Neon MCP Server cho tất cả các agent và trình soạn thảo được phát hiện trong không gian làm việc của bạn:

npx add-mcp https://mcp.neon.tech/mcp --header "Authorization: Bearer <$NEON_API_KEY>"

Ngoài ra, bạn có thể thêm mục "Neon" sau vào tệp cấu hình MCP server của client (ví dụ: mcp.json, mcp_config.json):

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

Cung cấp API key của tổ chức để giới hạn quyền truy cập chỉ vào các dự án thuộc tổ chức đó.

Phạm vi và Chế độ chỉ đọc

Neon MCP hỗ trợ các phạm vi OAuth read, write* (* nghĩa là cả hai). MCP client của bạn có thể yêu cầu các phạm vi này trực tiếp hoặc bạn có thể chọn trong giao diện quyền OAuth.

Chế độ chỉ đọc giới hạn các công cụ khả dụng, vô hiệu hóa các thao tác ghi như tạo dự án, nhánh hoặc chạy di trú. Các công cụ chỉ đọc bao gồm liệt kê dự án, mô tả lược đồ, truy vấn dữ liệu và xem các chỉ số hiệu suất.

Bạn có thể đặt chế độ chỉ đọc theo hai cách:

  1. Chọn phạm vi OAuth (khuyến nghị): Trong OAuth, chọn chỉ đọc bằng cách bỏ chọn Full access trong giao diện ủy quyền.
  2. Tham số truy vấn readonly: Thêm ?readonly=true vào URL MCP server của bạn:
{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true"
    }
  }
}

Cách hoạt động của tham số truy vấn:

  • Luồng API key: readonly=true là cách để bật chế độ chỉ đọc (không có trao đổi phạm vi OAuth trong luồng này).
  • Luồng OAuth: readonly=true ghi đè phạm vi OAuth. Nếu không có nó, chế độ chỉ đọc được xác định bởi phạm vi được chọn trong giao diện đồng ý OAuth.

Tiêu đề HTTP kế thừa x-read-only cũng được hỗ trợ như một phương án dự phòng (ưu tiên thấp hơn tham số truy vấn).

Lưu ý: Chế độ chỉ đọc giới hạn các công cụ khả dụng. Hơn nữa, công cụ run_sql vẫn khả dụng chỉ cho các truy vấn chỉ đọc.

Tham số truy vấn URL để kiểm soát truy cập

Ngữ cảnh cấp quyền (danh mục phạm vi, phạm vi dự án, chế độ chỉ đọc) được cấu hình qua các tham số truy vấn URL trên URL MCP server. Cấu hình đi kèm với mọi yêu cầu và có hiệu lực ngay lập tức — không cần xác thực lại.

Tham sốMô tảVí dụ
readonlyBật chế độ chỉ đọc (true/false)?readonly=true
categoryGiới hạn các danh mục công cụ cụ thể (lặp lại hoặc CSV)?category=querying&category=schema
projectIdPhạm vi tất cả thao tác vào một dự án duy nhất?projectId=proj-123

Ví dụ chỉ đọc + phạm vi dự án:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true&projectId=my-project-id"
    }
  }
}

Ví dụ lọc theo danh mục (chỉ công cụ truy vấn và lược đồ):

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?category=querying&category=schema"
    }
  }
}

Bạn có thể xem trước các công cụ hiển thị cho bất kỳ cấu hình nào bằng điểm cuối /api/list-tools (không cần xác thực):

curl "https://mcp.neon.tech/api/list-tools?readonly=true&category=querying"
Các công cụ khả dụng trong chế độ chỉ đọc
  • list_projects, list_shared_projects, describe_project, list_organizations
  • describe_branch, list_branch_computes, compare_database_schema
  • run_sql, run_sql_transaction, get_database_tables, describe_table_schema
  • list_slow_queries, explain_sql_statement
  • get_connection_string
  • get_neon_auth_config
  • query_logs, list_log_fields, list_log_field_values
  • search, fetch, list_docs_resources, get_doc_resource

Các công cụ yêu cầu quyền ghi:

  • create_project, delete_project
  • create_branch, delete_branch, reset_from_parent
  • provision_neon_auth, configure_neon_auth, provision_neon_data_api
  • prepare_database_migration, complete_database_migration
  • prepare_query_tuning, complete_query_tuning

Truyền tải Server-Sent Events (SSE) (Không dùng nữa)

MCP hỗ trợ hai phương thức truyền tải server từ xa: Server-Sent Events (SSE) không dùng nữa và Streamable HTTP mới hơn, được khuyến nghị. Nếu LLM client của bạn chưa hỗ trợ Streamable HTTP, bạn có thể chuyển điểm cuối từ https://mcp.neon.tech/mcp sang https://mcp.neon.tech/sse để sử dụng SSE.

Chạy lệnh sau để thêm Neon MCP Server cho tất cả các agent và trình soạn thảo được phát hiện trong không gian làm việc của bạn bằng phương thức truyền tải SSE:

npx add-mcp https://mcp.neon.tech/sse --type sse

Kiến trúc Server từ xa

Server từ xa chạy như một ứng dụng Next.js App Router trên Vercel tại mcp.neon.tech.

[!NOTE] Đường dẫn gốc / chuyển hướng đến tài liệu Neon MCP Server. Không có trang đích.

Các khu vực triển khai cốt lõi:

  • app/api/[transport]/route.ts: Điểm cuối truyền tải MCP cho Streamable HTTP (/mcp) và SSE (/sse)
  • app/api/authorize/, app/callback/, app/api/token/, app/api/revoke/: Các điểm cuối luồng OAuth
  • app/.well-known/: Các điểm cuối siêu dữ liệu khám phá OAuth
  • mcp/: MCP server, công cụ, trình xử lý, phân tích và tích hợp Sentry
  • lib/: Các trình trợ giúp tương thích Next.js (OAuth, cấu hình, xử lý lỗi)
  • mcp/utils/read-only.ts: Xử lý chế độ chỉ đọc và phạm vi

Hướng dẫn

Tính năng

Các công cụ được hỗ trợ

Neon MCP Server cung cấp các hành động sau, được hiển thị dưới dạng "công cụ" cho MCP Clients. Bạn có thể sử dụng các công cụ này để tương tác với các dự án và cơ sở dữ liệu Neon của mình bằng các lệnh ngôn ngữ tự nhiên.

Siêu dữ liệu phạm vi công cụ

Mỗi định nghĩa công cụ bao gồm một danh mục scope được sử dụng để lọc công cụ dựa trên quyền và trải nghiệm người dùng đồng ý. Các danh mục hiện tại là:

  • projects
  • branches
  • schema
  • querying
  • neon_auth
  • data_api
  • observability
  • docs
  • null (các công cụ không có danh mục phạm vi)

Ghi chú:

  • compare_database_schema được phân loại dưới schema.
  • provision_neon_data_api được phân loại dưới data_api (tách biệt với neon_auth).
  • Việc thực thi chỉ đọc vẫn dựa vào readOnlySafe và logic chỉ đọc phía máy chủ; scope là siêu dữ liệu danh mục, không phải một công tắc đọc/ghi độc lập.
  • Trong chế độ phạm vi dự án (?projectId=...), searchfetch không khả dụng.

Quản lý dự án:

  • list_projects: Liệt kê 10 dự án Neon đầu tiên trong tài khoản của bạn, cung cấp tóm tắt về từng dự án. Nếu bạn không tìm thấy một dự án cụ thể, hãy tăng giới hạn bằng cách truyền giá trị cao hơn cho tham số limit.
  • list_shared_projects: Liệt kê các dự án Neon được chia sẻ với người dùng hiện tại. Hỗ trợ tham số tìm kiếm và giới hạn số lượng dự án được trả về (mặc định: 10).
  • describe_project: Truy xuất thông tin chi tiết về một dự án Neon cụ thể, bao gồm ID, tên, cùng các nhánh và cơ sở dữ liệu liên quan.
  • create_project: Tạo một dự án Neon mới trong tài khoản Neon của bạn. Một dự án hoạt động như một vùng chứa cho các nhánh, cơ sở dữ liệu, vai trò và compute.
  • delete_project: Xóa một dự án Neon hiện có và tất cả tài nguyên liên quan của nó.
  • list_organizations: Liệt kê tất cả các tổ chức mà người dùng hiện tại có quyền truy cập. Có thể lọc theo tên hoặc ID tổ chức bằng tham số tìm kiếm.

Quản lý nhánh:

  • create_branch: Tạo một nhánh mới trong một dự án Neon được chỉ định. Tận dụng tính năng nhánh của Neon để phát triển, kiểm thử hoặc di chuyển (migrations).
  • delete_branch: Xóa một nhánh hiện có khỏi một dự án Neon.
  • describe_branch: Truy xuất chi tiết về một nhánh cụ thể, chẳng hạn như tên, ID và nhánh cha của nó.
  • list_branch_computes: Liệt kê các compute endpoint cho một dự án hoặc nhánh cụ thể, bao gồm ID compute, loại, kích thước, thời gian hoạt động gần nhất và thông tin tự động mở rộng (autoscaling).
  • compare_database_schema: Hiển thị sự khác biệt về schema giữa nhánh con và nhánh cha của nó.
  • reset_from_parent: Đặt lại nhánh hiện tại về trạng thái của nhánh cha, loại bỏ các thay đổi cục bộ. Tự động lưu lại bản sao lưu nếu nhánh có nhánh con, hoặc tùy chọn lưu lại theo yêu cầu với tên tùy chỉnh.

Thực thi truy vấn SQL:

  • get_connection_string: Trả về chuỗi kết nối cơ sở dữ liệu của bạn.
  • run_sql: Thực thi một truy vấn SQL đơn lẻ trên một cơ sở dữ liệu Neon được chỉ định. Hỗ trợ cả thao tác đọc và ghi.
  • run_sql_transaction: Thực thi một chuỗi các truy vấn SQL trong một giao dịch (transaction) duy nhất trên một cơ sở dữ liệu Neon.
  • get_database_tables: Liệt kê tất cả các bảng trong một cơ sở dữ liệu Neon được chỉ định.
  • describe_table_schema: Truy xuất định nghĩa schema của một bảng cụ thể, mô tả chi tiết các cột, kiểu dữ liệu và ràng buộc.

Di chuyển cơ sở dữ liệu (Thay đổi schema):

  • prepare_database_migration: Khởi tạo quá trình di chuyển cơ sở dữ liệu. Điều quan trọng là nó tạo một nhánh tạm thời để áp dụng và kiểm thử quá trình di chuyển một cách an toàn trước khi ảnh hưởng đến nhánh chính.
  • complete_database_migration: Hoàn tất và áp dụng quá trình di chuyển cơ sở dữ liệu đã chuẩn bị vào nhánh chính. Hành động này hợp nhất các thay đổi từ nhánh di chuyển tạm thời và dọn dẹp các tài nguyên tạm thời.

Truy vấn SQL và tối ưu hóa:

  • list_slow_queries: Xác định các điểm nghẽn hiệu suất bằng cách tìm các truy vấn chậm nhất trong một cơ sở dữ liệu. Yêu cầu tiện ích mở rộng pg_stat_statements.
  • explain_sql_statement: Cung cấp kế hoạch thực thi chi tiết cho các truy vấn SQL để giúp xác định các điểm nghẽn hiệu suất.
  • prepare_query_tuning: Phân tích hiệu suất truy vấn và đề xuất các tối ưu hóa, như tạo index. Tạo một nhánh tạm thời để kiểm thử các tối ưu hóa này một cách an toàn.
  • complete_query_tuning: Hoàn tất việc tinh chỉnh truy vấn bằng cách áp dụng các tối ưu hóa vào nhánh chính hoặc loại bỏ chúng. Dọn dẹp nhánh tinh chỉnh tạm thời.

Neon Auth:

  • provision_neon_auth: Cấp phát Neon Auth cho một dự án Neon. Cho phép các nhà phát triển dễ dàng thiết lập hạ tầng xác thực bằng cách tạo tích hợp với một nhà cung cấp Auth.
  • configure_neon_auth: Cấu hình tích hợp Neon Auth hiện có cho một nhánh — quản lý các nguồn gốc đáng tin cậy (trusted origins), quyền truy cập localhost, phương thức xác thực, nhà cung cấp OAuth và nhà cung cấp email giao dịch.
  • get_neon_auth_config: Đọc toàn bộ cấu hình Neon Auth cho một nhánh, bao gồm siêu dữ liệu tích hợp và các cài đặt có thể cấu hình (các bí mật được che giấu).

Neon Data API:

  • provision_neon_data_api: Cấp phát Neon Data API để truy cập cơ sở dữ liệu qua HTTP với xác thực JWT tùy chọn thông qua Neon Auth hoặc các nhà cung cấp JWKS bên ngoài.

Tìm kiếm và khám phá:

  • search: Tìm kiếm trên các tổ chức, dự án và nhánh khớp với một truy vấn. Trả về ID, tiêu đề và liên kết trực tiếp đến Neon Console.
  • fetch: Truy xuất thông tin chi tiết về một tổ chức, dự án hoặc nhánh cụ thể bằng ID (thường từ công cụ tìm kiếm).

Khả năng quan sát:

  • query_logs: Truy vấn nhật ký (logs) do các hàm serverless Neon và các dịch vụ khác của bạn phát ra bằng các bộ lọc có cấu trúc (nguồn, tên dịch vụ, mức độ nghiêm trọng, khung thời gian). Nhật ký dựa trên OpenTelemetry.
  • list_log_fields: Liệt kê các trường nhật ký (nhãn) bạn có thể lọc cho một nhánh, chẳng hạn như service_name, severity_textscope_name. Sử dụng trước query_logs.
  • list_log_field_values: Liệt kê các giá trị riêng biệt của một trường nhật ký trong một nhánh và khung thời gian, để khám phá các giá trị cụ thể truyền cho query_logs.

Tài liệu và tài nguyên:

  • list_docs_resources: Liệt kê tất cả các trang tài liệu Neon khả dụng bằng cách truy xuất chỉ mục từ https://neon.com/docs/llms.txt. Trả về URL và tiêu đề trang có thể được truy xuất riêng lẻ bằng công cụ get_doc_resource.
  • get_doc_resource: Truy xuất một trang tài liệu Neon cụ thể dưới dạng nội dung markdown. Sử dụng công cụ list_docs_resources trước để khám phá các slug trang khả dụng, sau đó truyền slug vào công cụ này.

Di chuyển (Migrations)

Di chuyển (Migrations) là một cách quản lý các thay đổi đối với schema cơ sở dữ liệu của bạn theo thời gian. Với máy chủ Neon MCP, các LLM có thể thực hiện di chuyển một cách an toàn với các lệnh "Start" (prepare_database_migration) và "Commit" (complete_database_migration) riêng biệt.

Lệnh "Start" nhận một quá trình di chuyển và chạy nó trong một nhánh tạm thời mới. Khi trả về, lệnh này gợi ý cho LLM rằng nó nên kiểm thử quá trình di chuyển trên nhánh này. LLM sau đó có thể chạy lệnh "Commit" để áp dụng quá trình di chuyển vào nhánh gốc.

Phát triển

Dự án này sử dụng pnpm làm trình quản lý gói, được khóa phiên bản qua Corepack.

Cấu trúc dự án

Mã máy chủ MCP nằm tại thư mục gốc của kho lưu trữ, một ứng dụng Next.js được triển khai lên Vercel tại mcp.neon.tech.

corepack enable
pnpm install

Phát triển cục bộ

# Start the Next.js dev server (for the remote MCP server)
pnpm dev

Kiểm tra lint và kiểu (Type Checking)

pnpm lint
pnpm typecheck

Biến môi trường

Bắt buộc cho thời gian chạy máy chủ từ xa:

VariableDescription
SERVER_HOSTServer URL (defaults to VERCEL_URL)
UPSTREAM_OAUTH_HOSTNeon OAuth provider URL
CLIENT_IDOAuth client ID
CLIENT_SECRETOAuth client secret
COOKIE_SECRETSecret for signed cookies
KV_URLVercel KV (Upstash Redis) URL
OAUTH_DATABASE_URLPostgres URL for token storage

Tùy chọn:

VariableDescription
LOG_LEVELWinston log level: error, warn, info (default), debug, verbose, silly

Tháp kiểm thử (Testing Pyramid)

Tất cả các kiểm thử chạy từ thư mục gốc của kho lưu trữ.

# Unit tests
pnpm test:unit

# Integration tests
pnpm test:integration

# MCP protocol end-to-end tests (real MCP client/server tool calls)
pnpm test:e2e:mcp

# Website end-to-end tests (Playwright; provisions/validates ephemeral DB first)
pnpm test:e2e:web

# Full end-to-end suite
pnpm test:e2e

# Full test pyramid (unit + integration + e2e; used in CI)
pnpm test

Chiến lược kiểm thử:

  • Ưu tiên E2E cho giao thức vận chuyển và hành vi người dùng thấy được.
  • Sử dụng kiểm thử tích hợp cho các hợp đồng công cụ xác định và hành vi quy trình làm việc.
  • Sử dụng kiểm thử đơn vị cho logic thuần túy và các trường hợp biên.
  • Tránh phụ thuộc vào thời gian hoạt động của bên thứ ba trong các kiểm thử chặn hợp nhất (merge-gating); giả lập (mock) các phụ thuộc bên ngoài ở các tầng tích hợp/đơn vị.

Triển khai

Vercel tự động triển khai máy chủ từ xa từ cấu hình nhánh của kho lưu trữ. Các môi trường xem trước (preview) có sẵn cho các pull request.