Chuyển tới nội dung chính

{/* Trang này được tạo tự động từ SKILL.md của kỹ năng bởi website/scripts/generate-skill-docs.py. Chỉnh sửa nguồn SKILL.md, không phải trang này. */}

FastMCP

Xây dựng, kiểm tra, kiểm tra, cài đặt và triển khai máy chủ MCP với FastMCP bằng Python. Sử dụng khi tạo máy chủ MCP mới, gói API hoặc cơ sở dữ liệu dưới dạng công cụ MCP, hiển thị tài nguyên hoặc lời nhắc hoặc chuẩn bị máy chủ FastMCP để triển khai Mã Claude, Con trỏ hoặc HTTP.

Siêu dữ liệu kỹ năng​

NguồnTùy chọn — cài đặt với
`Hermes skills install official/MCP/fastMCP
`
Đường dẫn

optional-skills/MCP/fastMCP ` | | Phiên bản |

1.0.0 ` | | Tác giả | Đại lý Hermes | | Giấy phép | MIT | | Nền tảng | Linux, macOS, Windows | | Thẻ |

MCP

, `FastMCP

,


, 
`Tools

, 
`Resources

, 
`Prompts

, 
`Deployment
` |
| Kỹ năng liên quan | [XPROTECTX21XPROTECTX](/docs/user-guide/skills/bundled/MCP/MCP-native-MCP), [XPROTECTX22XPROTECTX](/docs/user-guide/skills/optional/MCP/MCP-MCPorter) |

## Tham khảo: đầy đủ SKILL.md

:::info
Sau đây là định nghĩa kỹ năng đầy đủ mà Hermes tải khi kỹ năng này được kích hoạt. Đây là những gì tác nhân coi là hướng dẫn khi kỹ năng được kích hoạt.

:::

# FastMCP

Xây dựng máy chủ MCP bằng Python với FastMCP, xác thực chúng cục bộ, cài đặt chúng vào máy khách MCP và triển khai chúng dưới dạng điểm cuối HTTP.

## Khi nào nên sử dụng

Hãy sử dụng kỹ năng này khi nhiệm vụ là:
- tạo máy chủ MCP mới bằng Python
- gói API, cơ sở dữ liệu, CLI hoặc quy trình xử lý tệp dưới dạng công cụ MCP
- hiển thị các tài nguyên hoặc lời nhắc ngoài các công cụ
- kiểm tra máy chủ bằng FastMCP CLI trước khi kết nối nó với Hermes hoặc máy khách khác
- cài đặt máy chủ vào Claude Code, Claude Desktop, Cursor hoặc máy khách MCP tương tự
- chuẩn bị kho lưu trữ máy chủ FastMCP để triển khai HTTP

Sử dụng 
`native-MCP
` khi máy chủ đã tồn tại và chỉ cần kết nối với Hermes. Sử dụng 
`MCPorter
` khi mục tiêu là quyền truy cập CLI đặc biệt vào máy chủ MCP hiện có thay vì xây dựng một máy chủ.

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

Trước tiên hãy cài đặt FastMCP trong môi trường làm việc:

``` bash
pip install fastMCP
fastMCP version

`
``Đối với mẫu API, hãy cài đặt 
`httpx
` nếu chưa có:

`bash
pip install httpx

`

## Tệp được bao gồm

### Mẫu
- 
`templates/API_wrapper.py

 - Trình bao bọc API REST có hỗ trợ tiêu đề xác thực

- 
`templates/database_server.py

 - máy chủ truy vấn SQLite chỉ đọc
- 
`templates/file_processor.py

 - máy chủ kiểm tra và tìm kiếm tệp văn bản

### Tập lệnh
- 
`scripts/scaffold_fastMCP.py

 - sao chép mẫu khởi động và thay thế trình giữ chỗ tên máy chủ

### Tài liệu tham khảo
- 
`references/fastMCP-CLI.md

 - Quy trình làm việc FastMCP CLI, mục tiêu cài đặt và kiểm tra triển khai

## Quy trình làm việc

### 1. Chọn hình dạng máy chủ khả thi nhỏ nhất

Trước tiên hãy chọn diện tích bề mặt hữu ích hẹp nhất:
- Trình bao bọc API: bắt đầu với 1-3 điểm cuối có giá trị cao, không phải toàn bộ API
- máy chủ cơ sở dữ liệu: hiển thị phần nội tâm chỉ đọc và đường dẫn truy vấn bị ràng buộc
- bộ xử lý tệp: hiển thị các hoạt động xác định với các đối số đường dẫn rõ ràng
- lời nhắc/tài nguyên: chỉ thêm khi khách hàng cần các mẫu lời nhắc có thể sử dụng lại hoặc các tài liệu có thể khám phá

Thích một máy chủ mỏng có tên, chuỗi tài liệu và lược đồ hay hơn một máy chủ lớn với các công cụ mơ hồ.

### 2. Giàn giáo từ Mẫu

Sao chép mẫu trực tiếp hoặc sử dụng trình trợ giúp giàn giáo:

``` bash
Python ~/.Hermes/skills/MCP/fastMCP/scripts/scaffold_fastMCP.py \

  --template API_wrapper \
  --name "Acme API" \
  --output ./acme_server.py

`
``Các mẫu có sẵn:

``` bash
Python ~/.Hermes/skills/MCP/fastMCP/scripts/scaffold_fastMCP.py --list

`
``Nếu sao chép thủ công, hãy thay thế 
`__SERVER_NAME__
` bằng tên máy chủ thực.

### 3. Triển khai công cụ trước tiên

Bắt đầu với các hàm 

@MCP.tool
` trước khi thêm tài nguyên hoặc lời nhắc.

Nguyên tắc thiết kế công cụ:
- Đặt cho mọi công cụ một tên dựa trên động từ cụ thể

- Viết tài liệu dưới dạng mô tả công cụ hướng tới người dùng
- Giữ các tham số rõ ràng và được gõ
- Trả về dữ liệu có cấu trúc an toàn JSON nếu có thể
- Xác thực sớm các đầu vào không an toàn
- Ưu tiên hành vi chỉ đọc theo mặc định cho các phiên bản đầu tiên

Ví dụ về công cụ tốt:
- 
`get_customer

- 
`search_tickets

- 
`describe_table

- 
`summarize_text_file
``Ví dụ về công cụ yếu:
- 
`run

- 
`process

- 
`do_thing

### 4. Chỉ thêm tài nguyên và lời nhắc khi chúng trợ giúp

Thêm 

@MCP.resource
` khi khách hàng được hưởng lợi từ việc tìm nạp nội dung chỉ đọc ổn định như lược đồ, tài liệu chính sách hoặc báo cáo được tạo.

Thêm 

@MCP.prompt
` khi máy chủ cần cung cấp mẫu lời nhắc có thể sử dụng lại cho quy trình làm việc đã biết.

Đừng biến mọi tài liệu thành một lời nhắc. Thích:
- công cụ thực hiện hành động
- tài nguyên để truy xuất dữ liệu/tài liệu
- lời nhắc về hướng dẫn LLM có thể sử dụng lại

### 5. Kiểm tra máy chủ trước khi tích hợp ở mọi nơi

Sử dụng FastMCP CLI để xác thực cục bộ:

`
``` bash
fastMCP inspect acme_server.py:MCP
fastMCP list acme_server.py --JSON
fastMCP call acme_server.py search_resources query=router limit=5 --JSON

`
``Để gỡ lỗi lặp lại nhanh chóng, hãy chạy máy chủ cục bộ:

`bash
fastMCP run acme_server.py:MCP

`
``Để kiểm tra vận chuyển HTTP cục bộ:

`bash
fastMCP run acme_server.py:MCP --transport http --host 127.0.0.1 --port 8000
fastMCP list http://127.0.0.1:8000/MCP --JSON
fastMCP call http://127.0.0.1:8000/MCP search_resources query=router --JSON

`
``Luôn chạy ít nhất một 
`fastMCP call
` thực đối với mỗi công cụ mới trước khi xác nhận rằng máy chủ hoạt động.

### 6. Cài đặt vào máy khách khi xác thực cục bộ vượt qua

FastMCP có thể đăng ký máy chủ với các máy khách MCP được hỗ trợ:

`bash
fastMCP install Claude-code acme_server.py
fastMCP install Claude-desktop acme_server.py
fastMCP install Cursor acme_server.py -e .

`
``Sử dụng 
`fastMCP discover
` để kiểm tra các máy chủ MCP có tên đã được định cấu hình trên máy.

Khi mục tiêu là tích hợp Hermes:
- định cấu hình máy chủ trong 

~/.Hermes/config.yaml
` bằng kỹ năng 
`native-MCP
` hoặc

- tiếp tục sử dụng các lệnh FastMCP CLI trong quá trình phát triển cho đến khi giao diện ổn định

### 7. Triển khai sau khi Local Contract ổn định

Đối với quản lý lưu trữ, Prefect Horizon là đường dẫn tài liệu FastMCP trực tiếp nhất. Trước khi triển khai:

``` bash
fastMCP inspect acme_server.py:MCP

`
``Hãy chắc chắn rằng repo chứa:
- một tệp Python với đối tượng máy chủ FastMCP

- 
`requirements.txt
` hoặc 
`pyproject.TOML

- mọi tài liệu về biến môi trường cần thiết để triển khai

Đối với lưu trữ HTTP chung, trước tiên hãy xác thực truyền tải HTTP cục bộ, sau đó triển khai trên bất kỳ nền tảng tương thích với Python nào có thể hiển thị cổng máy chủ.

## Các mẫu phổ biến

### Mẫu trình bao bọc API

Sử dụng khi hiển thị API REST hoặc HTTP dưới dạng công cụ MCP.

Phần đầu tiên được đề xuất:
- một đường dẫn đọc
- một danh sách/đường dẫn tìm kiếm
- kiểm tra sức khỏe tùy chọn

Ghi chú thực hiện:
- giữ auth trong các biến môi trường, không được mã hóa cứng
- tập trung logic yêu cầu vào một người trợ giúp
- lỗi API bề mặt với ngữ cảnh ngắn gọn
- bình thường hóa các tải trọng ngược dòng không nhất quán trước khi trả lại chúng

Bắt đầu từ 
`templates/API_wrapper.py

.

### Mẫu cơ sở dữ liệu

Sử dụng khi bộc lộ khả năng truy vấn và kiểm tra an toàn.

Phần đầu tiên được đề xuất:
- 
`list_tables

- 
`describe_table

- một công cụ truy vấn đọc bị hạn chế

Ghi chú thực hiện:
- mặc định là truy cập DB chỉ đọc
- từ chối SQL không phải 
`SELECT
` trong các phiên bản đầu
- giới hạn số lượng hàng
- trả về hàng cộng với tên cột

Bắt đầu từ 
`templates/database_server.py

.

### Mẫu bộ xử lý tệp

Sử dụng khi máy chủ cần kiểm tra hoặc chuyển đổi tệp theo yêu cầu.

Phần đầu tiên được đề xuất:
- tóm tắt nội dung tập tin
- tìm kiếm trong tập tin
- trích xuất siêu dữ liệu xác định

Ghi chú thực hiện:
- chấp nhận đường dẫn tập tin rõ ràng
- kiểm tra các tập tin bị thiếu và lỗi mã hóa
- xem trước giới hạn và đếm kết quả
- tránh pháo kích trừ khi cần một công cụ bên ngoài cụ thể

Bắt đầu từ 
`templates/file_processor.py

.`##Thanh chất lượng

Trước khi bàn giao máy chủ FastMCP, hãy xác minh tất cả những điều sau:
- máy chủ nhập sạch
- 
`fastMCP inspect <file.py:MCP
` thành công
- 
`fastMCP list <server spec --JSON
` thành công
- mọi công cụ mới đều có ít nhất một 
`fastMCP call
` thực
- các biến môi trường được ghi lại
- bề mặt dụng cụ đủ nhỏ để hiểu mà không cần phỏng đoán

## Khắc phục sự cố

### Thiếu lệnh FastMCP

Cài đặt gói trong môi trường hoạt động:

``` bash
pip install fastMCP
fastMCP version

`

### 
`fastMCP inspect
` không thành công

Kiểm tra xem:
- tập tin nhập mà không có tác dụng phụ bị lỗi

- phiên bản FastMCP được đặt tên chính xác trong 

<file.py:object>

- các phụ thuộc tùy chọn từ mẫu đã được cài đặt

### Công cụ hoạt động bằng Python nhưng không thông qua CLI

Chạy:

``` bash
fastMCP list server.py --JSON
fastMCP call server.py your_tool_name --JSON

`
``Điều này thường dẫn đến việc đặt tên không khớp, thiếu đối số bắt buộc hoặc giá trị trả về không thể tuần tự hóa.

### Hermes không thể thấy máy chủ đã triển khai

Phần xây dựng máy chủ có thể đúng trong khi cấu hình Hermes thì không. Tải kỹ năng 
`native-MCP
` và định cấu hình máy chủ trong 

~/.Hermes/config.yaml

, sau đó khởi động lại Hermes.

## Tài liệu tham khảo

Để biết chi tiết CLI, mục tiêu cài đặt và kiểm tra triển khai, hãy đọc 
`references/fastMCP-CLI.md

.