Neon
chính thứcTươ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_projectvàcreate_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_sqlhoặcrun_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_tableshoặc lấy định nghĩa đầy đủ về cột/ràng buộc của bảng quadescribe_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ớicomplete_database_migration. - Điều chỉnh truy vấn chậm — Xác định điểm nghẽn bằng
list_slow_querieshoặc lấy kế hoạch thực thi quaexplain_sql_statement, sau đó kiểm thử các bản sửa lỗi bằngprepare_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ằngquery_logsvàlist_log_fields.
Tài liệu
Neon MCP Server
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.
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:
- 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. - 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.
- 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.46và23.22.233.166vào danh sách cho phép của bạn (mcp.neon.techstatic 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_idhoặcproject_idtrong 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 và * (* 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:
- 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.
- Tham số truy vấn
readonly: Thêm?readonly=truevà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=truelà 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=trueghi đè 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_sqlvẫ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ụ |
|---|---|---|
readonly | Bật chế độ chỉ đọc (true/false) | ?readonly=true |
category | Giới hạn các danh mục công cụ cụ thể (lặp lại hoặc CSV) | ?category=querying&category=schema |
projectId | Phạ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_organizationsdescribe_branch,list_branch_computes,compare_database_schemarun_sql,run_sql_transaction,get_database_tables,describe_table_schemalist_slow_queries,explain_sql_statementget_connection_stringget_neon_auth_configquery_logs,list_log_fields,list_log_field_valuessearch,fetch,list_docs_resources,get_doc_resource
Các công cụ yêu cầu quyền ghi:
create_project,delete_projectcreate_branch,delete_branch,reset_from_parentprovision_neon_auth,configure_neon_auth,provision_neon_data_apiprepare_database_migration,complete_database_migrationprepare_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 OAuthapp/.well-known/: Các điểm cuối siêu dữ liệu khám phá OAuthmcp/: MCP server, công cụ, trình xử lý, phân tích và tích hợp Sentrylib/: 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
- Hướng dẫn Neon MCP Server
- Kết nối MCP Clients với Neon
- Cursor với Neon MCP Server
- Claude Code với Neon MCP Server
- Claude Desktop với Neon MCP Server
- Cline với Neon MCP Server
- Windsurf với Neon MCP Server
- Zed với Neon MCP Server
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à:
projectsbranchesschemaqueryingneon_authdata_apiobservabilitydocsnull(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ướischema.provision_neon_data_apiđược phân loại dướidata_api(tách biệt vớineon_auth).- Việc thực thi chỉ đọc vẫn dựa vào
readOnlySafevà logic chỉ đọc phía máy chủ;scopelà 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=...),searchvàfetchkhô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_textvàscope_name. Sử dụng trướcquery_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 choquery_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_resourcestrướ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:
| Variable | Description |
|---|---|
SERVER_HOST | Server URL (defaults to VERCEL_URL) |
UPSTREAM_OAUTH_HOST | Neon OAuth provider URL |
CLIENT_ID | OAuth client ID |
CLIENT_SECRET | OAuth client secret |
COOKIE_SECRET | Secret for signed cookies |
KV_URL | Vercel KV (Upstash Redis) URL |
OAUTH_DATABASE_URL | Postgres URL for token storage |
Tùy chọn:
| Variable | Description |
|---|---|
LOG_LEVEL | Winston 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.