Apidog

Nền tảng phát triển API hợp tác tất cả trong một

Thiết kế API

Tài liệu API

Gỡ lỗi API

Giả lập API

Kiểm thử API tự động

Đăng ký miễn phí
Tải xuốngCho Mac hoặc Linux
Home

/

Hướng Dẫn Dành Cho Người Mới Bắt Đầu Sử Dụng FastMCP

Hướng Dẫn Dành Cho Người Mới Bắt Đầu Sử Dụng FastMCP

Minh Triết

Minh Triết

Updated on tháng 4 19, 2025

Cảnh quan của các Mô hình Ngôn ngữ Lớn (LLMs) đang tiến triển nhanh chóng, vượt ra ngoài việc tạo văn bản đơn giản để hướng tới các tương tác phức tạp với các hệ thống bên ngoài và nguồn dữ liệu. Để tạo điều kiện cho sự tương tác này đòi hỏi một cách tiếp cận tiêu chuẩn hóa, một ngôn ngữ chung cho các LLM yêu cầu thông tin và kích hoạt hành động. Đây là lý do mà Giao thức Ngữ cảnh Mô hình (MCP) ra đời, được thiết kế như một tiêu chuẩn toàn cầu – thường được so sánh với "cổng USB-C cho AI" – cho phép giao tiếp liền mạch giữa các LLM và các tài nguyên mà chúng cần.

Trong khi MCP cung cấp cấu hình kỹ thuật, việc xây dựng máy chủ và máy khách tuân thủ điều này có thể liên quan đến một khối lượng mã boilerplate đáng kể và quản lý giao thức. Đó là nơi FastMCP nổi bật. FastMCP là một khung làm việc cấp cao, viết bằng Python được thiết kế để làm đơn giản hóa đáng kể việc tạo ra các máy chủ và máy khách MCP. Nó xử lý những phức tạp cơ bản của giao thức, cho phép các nhà phát triển tập trung vào việc xác định các công cụ giá trị, nguồn dữ liệu và mẫu tương tác mà họ muốn cung cấp cho các LLM.

💡
Bạn muốn một công cụ Kiểm tra API tuyệt vời tạo ra Tài liệu API đẹp mắt?

Bạn muốn một nền tảng tích hợp, Tất cả trong một để đội ngũ phát triển của bạn có thể làm việc cùng nhau với năng suất tối đa?

Apidog đáp ứng tất cả nhu cầu của bạn, và thay thế Postman với một mức giá phải chăng hơn nhiều!
button

Giao thức Ngữ cảnh Mô hình (MCP) là gì?

Trước khi đi sâu hơn vào FastMCP, điều quan trọng là nắm bắt các khái niệm cốt lõi của chính MCP. MCP định nghĩa một cách tiêu chuẩn hóa cho các ứng dụng LLM (máy khách) tương tác với các hệ thống bên ngoài (máy chủ). Một máy chủ MCP có thể cung cấp một số thành phần chính:

  1. Các công cụ: Đây chủ yếu là các hàm mà một LLM có thể yêu cầu máy chủ thực hiện. Hãy coi chúng như các điểm cuối POST trong một API truyền thống. Chúng thực hiện các hành động, có thể tương tác với các hệ thống khác (cơ sở dữ liệu, API, phần cứng) và trả về kết quả. Ví dụ, một công cụ có thể gửi email, truy vấn cơ sở dữ liệu hoặc thực hiện các phép tính.
  2. Tài nguyên: Những tài nguyên này cung cấp dữ liệu mà một LLM có thể đọc hoặc truy xuất. Tương tự như các điểm cuối GET, tài nguyên cung cấp thông tin để làm phong phú thêm ngữ cảnh của LLM. Điều này có thể là bất cứ điều gì từ các tệp cấu hình và hồ sơ người dùng đến các luồng dữ liệu theo thời gian thực.
  3. Các câu lệnh: Đây là các mẫu tái sử dụng để cấu trúc các tương tác với LLM. Chúng giúp hướng dẫn cuộc trò chuyện và đảm bảo xuất ra nhất quán cho các nhiệm vụ cụ thể.
  4. Ngữ cảnh: Các máy chủ có thể cung cấp thông tin ngữ cảnh, bao gồm hướng dẫn về cách tốt nhất để tương tác với các công cụ và tài nguyên có sẵn.

MCP nhằm tạo ra một hệ sinh thái vững chắc và an toàn nơi các LLM có thể tin cậy truy cập và sử dụng các khả năng bên ngoài.

Tại sao chọn FastMCP?

Mặc dù bạn có thể triển khai cấu hình MCP trực tiếp bằng cách sử dụng các SDK cấp thấp hơn, FastMCP mang lại những lợi thế hấp dẫn, đặc biệt cho các nhà phát triển Python:

  • 🚀 Phát triển nhanh: Giao diện cấp cao của nó giảm đáng kể lượng mã cần thiết, tăng tốc quá trình phát triển. Thường thì việc định nghĩa một công cụ hoặc tài nguyên đơn giản như việc trang trí một hàm Python tiêu chuẩn.
  • 🍀 Đơn giản: FastMCP trừu tượng hóa những chi tiết phức tạp về thiết lập máy chủ, xử lý giao thức, loại nội dung và quản lý lỗi, giảm thiểu boilerplate.
  • 🐍 Pythonic: Được thiết kế với các thực tiễn tốt nhất của Python trong tâm trí, nó cảm thấy tự nhiên và trực quan cho các nhà phát triển quen thuộc với ngôn ngữ này, tận dụng các tính năng như gợi ý kiểu và trình trang trí.
  • 🔍 Toàn diện: FastMCP nhằm cung cấp một triển khai toàn diện của cấu hình cốt lõi MCP, đảm bảo tính tương thích và truy cập vào toàn bộ tiềm năng của giao thức.

Phiên bản 1 của FastMCP đã thành công cao và bây giờ đã được tích hợp vào SDK MCP Python chính thức. Phiên bản 2 xây dựng dựa trên nền tảng này, giới thiệu những tính năng tiên tiến tập trung vào việc đơn giản hóa các tương tác máy chủ, chẳng hạn như máy khách linh hoạt, chuyển tiếp máy chủ và mẫu kết hợp.

Cách cài đặt FastMCP

Thiết lập FastMCP trong môi trường Python của bạn rất đơn giản. Phương pháp được khuyến nghị sử dụng uv, một trình cài đặt và giải quyết gói Python nhanh.

1. Sử dụng uv (Khuyến nghị):

Nếu bạn đang quản lý các phụ thuộc cho một dự án, hãy thêm FastMCP bằng cách sử dụng:

uv add fastmcp

Hoặc, cài đặt nó trực tiếp vào môi trường của bạn:

uv pip install fastmcp

2. Sử dụng pip:

Nếu bạn thích sử dụng pip, bạn có thể cài đặt FastMCP với:

pip install fastmcp

3. Xác minh cài đặt:

Sau khi cài đặt, bạn có thể xác minh rằng FastMCP đã được cài đặt đúng cách và kiểm tra phiên bản của nó, cũng như phiên bản SDK MCP cơ bản và chi tiết môi trường Python của bạn, bằng cách chạy:

fastmcp version

Bạn sẽ thấy đầu ra giống như sau:

$ fastmcp version

FastMCP version:   0.4.2.dev41+ga077727.d20250410
MCP version:                                1.6.0
Python version:                            3.12.2
Platform:            macOS-15.3.1-arm64-arm-64bit
FastMCP root path:            ~/Developer/fastmcp

4. Cài đặt để phát triển:

Nếu bạn muốn đóng góp vào dự án FastMCP, bạn sẽ muốn thiết lập một môi trường phát triển:

git clone https://github.com/jlowin/fastmcp.git
cd fastmcp
uv sync

Điều này sao chép kho lưu trữ, điều hướng vào thư mục, và sử dụng uv sync để cài đặt tất cả các phụ thuộc cần thiết, bao gồm cả các công cụ phát triển, trong một môi trường ảo. Bạn có thể sau đó chạy các bài kiểm tra bằng cách sử dụng pytest.

Cách sử dụng FastMCP: Xây dựng Máy chủ đầu tiên của bạn

Giờ đây, hãy đi sâu vào các khía cạnh thực tế của việc sử dụng FastMCP.

1. Tạo một Phiên bản Máy chủ Cơ bản:

Cốt lõi của bất kỳ ứng dụng FastMCP nào là lớp FastMCP. Bạn bắt đầu bằng cách tạo một phiên bản của lớp này.

Tạo một tệp có tên my_server.py:

# my_server.py
from fastmcp import FastMCP
import asyncio # Chúng ta sẽ cần cái này sau cho máy khách

# Khởi tạo máy chủ, đặt tên cho nó
mcp = FastMCP(name="Máy Chủ MCP Đầu Tiên của Tôi")

print("Đối tượng máy chủ FastMCP đã được tạo.")

Tham số tạo FastMCP chấp nhận một số đối số hữu ích:

  • name (str, tùy chọn): Một tên dễ đọc cho máy chủ của bạn (mặc định là "FastMCP"). Hữu ích để xác định trong các ghi log hoặc ứng dụng máy khách.
  • instructions (str, tùy chọn): Một mô tả hướng dẫn cho các máy khách về cách tương tác với máy chủ, giải thích mục đích của nó hoặc làm nổi bật các chức năng chính.
  • lifespan (gọi, tùy chọn): Một trình quản lý ngữ cảnh async để xử lý logic khởi động và tắt máy chủ (ví dụ: khởi tạo kết nối cơ sở dữ liệu).
  • tags (set[str], tùy chọn): Thẻ để phân loại chính máy chủ.
  • **settings: Bạn có thể truyền các đối số từ khóa tương ứng với ServerSettings (như port, host, log_level) trực tiếp vào bộ tạo để cấu hình.

2. Thêm các Thành phần:

Một máy chủ trống không hữu ích lắm. Hãy thêm các thành phần cốt lõi của MCP.

Thêm một Công cụ: Các công cụ là các hàm được cung cấp cho máy khách. Sử dụng trình trang trí @mcp.tool(). FastMCP sử dụng gợi ý kiểu Python để định nghĩa các tham số đầu vào mong đợi và kiểu trả về cho máy khách.

# my_server.py (tiếp tục)
@mcp.tool()
def greet(name: str) -> str:
    """Trả về một lời chào đơn giản."""
    return f"Xin chào, {name}!"

@mcp.tool()
def add(a: int, b: int) -> int:
    """Cộng hai số lại với nhau."""
    return a + b

print("Các công cụ 'greet' và 'add' đã được thêm.")

Thêm một Tài nguyên: Các tài nguyên cung cấp dữ liệu qua một URI. Sử dụng trình trang trí @mcp.resource(), cung cấp chuỗi URI.

# my_server.py (tiếp tục)
APP_CONFIG = {"theme": "dark", "version": "1.1", "feature_flags": ["new_dashboard"]}

@mcp.resource("data://config")
def get_config() -> dict:
    """Cung cấp cấu hình ứng dụng."""
    return APP_CONFIG

print("Tài nguyên 'data://config' đã được thêm.")

Thêm một Mẫu Tài nguyên: Đây giống như các tài nguyên động, trong đó một số phần của URI hoạt động như các tham số.

# my_server.py (tiếp tục)
USER_PROFILES = {
    101: {"name": "Alice", "status": "active"},
    102: {"name": "Bob", "status": "inactive"},
}

@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: int) -> dict:
    """Lấy hồ sơ của người dùng theo ID của họ."""
    # Tham số {user_id} từ URI sẽ được tự động truyền như là một đối số
    return USER_PROFILES.get(user_id, {"error": "Người dùng không tìm thấy"})

print("Mẫu tài nguyên 'users://{user_id}/profile' đã được thêm.")

Thêm một Câu lệnh: Các câu lệnh xác định các mẫu tương tác tái sử dụng.

# my_server.py (tiếp tục)
@mcp.prompt("summarize")
async def summarize_prompt(text: str) -> list[dict]:
    """Tạo một câu lệnh để tóm tắt văn bản đã cung cấp."""
    return [
        {"role": "system", "content": "Bạn là một trợ lý hữu ích có kỹ năng tóm tắt."},
        {"role": "user", "content": f"Xin vui lòng tóm tắt văn bản sau:\n\n{text}"}
    ]

print("Câu lệnh 'summarize' đã được thêm.")

3. Kiểm tra Máy chủ (Trong Quy trình):

Trước khi chạy máy chủ bên ngoài, bạn có thể kiểm tra các thành phần của nó trực tiếp trong cùng một tập lệnh Python bằng cách sử dụng Client. Điều này hữu ích cho các kiểm tra nhanh và kiểm tra đơn vị.

# my_server.py (tiếp tục)
from fastmcp import Client # Nhập máy khách

async def test_server_locally():
    print("\n--- Kiểm tra Máy chủ Tại chỗ ---")
    # Chỉ định máy khách trực tiếp đến đối tượng máy chủ
    client = Client(mcp)

    # Các máy khách là bất đồng bộ, vì vậy hãy sử dụng một trình quản lý ngữ cảnh async
    async with client:
        # Gọi công cụ 'greet'
        greet_result = await client.call_tool("greet", {"name": "Người dùng FastMCP"})
        print(f"giá trị chào: {greet_result}")

        # Gọi công cụ 'add'
        add_result = await client.call_tool("add", {"a": 5, "b": 7})
        print(f"giá trị cộng: {add_result}")

        # Đọc tài nguyên 'config'
        config_data = await client.read_resource("data://config")
        print(f"tài nguyên cấu hình: {config_data}")

        # Đọc hồ sơ người dùng bằng cách sử dụng mẫu
        user_profile = await client.read_resource("users://101/profile")
        print(f"Hồ sơ người dùng 101: {user_profile}")

        # Lấy cấu trúc câu lệnh 'summarize' (không thực thi cuộc gọi LLM ở đây)
        prompt_messages = await client.get_prompt("summarize", {"text": "Đây là một số văn bản."})
        print(f"Cấu trúc câu lệnh Tóm tắt: {prompt_messages}")

# Chạy hàm kiểm tra tại chỗ
# asyncio.run(test_server_locally())
# Đã được nhận xét tạm thời, chúng ta sẽ tập trung vào việc chạy máy chủ tiếp theo

Lưu ý việc sử dụng async và await. Các máy khách FastMCP hoạt động bất đồng bộ, yêu cầu một hàm async và sử dụng async with client: để quản lý vòng đời của máy khách.

4. Chạy Máy chủ:

Để làm cho máy chủ MCP của bạn có thể truy cập đến các máy khách bên ngoài (như một ứng dụng LLM), bạn cần chạy nó. Có hai cách chính:

Thực thi Python Chuẩn (Được Khuyến nghị để Tương thích):
Thêm khối if __name__ == "__main__": sau vào tệp my_server.py của bạn. Đây là thực hành đạt chuẩn của Python để làm cho một tập lệnh có thể thực thi.

# my_server.py (cuối tệp)

if __name__ == "__main__":
    print("\n--- Bắt đầu Máy chủ FastMCP qua __main__ ---")
    # Điều này khởi động máy chủ, thường sử dụng giao thức stdio theo mặc định
    mcp.run()

Để chạy máy chủ, hãy thực thi tập lệnh từ terminal của bạn:

python my_server.py

Lệnh này khởi động máy chủ MCP, lắng nghe các kết nối máy khách sử dụng giao thức mặc định stdio (đầu vào/đầu ra tiêu chuẩn). Phương pháp này đảm bảo máy chủ của bạn chạy đồng nhất cho nhiều máy khách mong đợi thực thi một tập lệnh Python.

Sử dụng FastMCP CLI:
FastMCP cung cấp một giao diện dòng lệnh để chạy các máy chủ, cung cấp nhiều linh hoạt và kiểm soát hơn, đặc biệt liên quan đến các tùy chọn giao thức.

# Chạy máy chủ bằng stdio (mặc định)
fastmcp run my_server.py:mcp

# Chạy máy chủ sử dụng Sự kiện Gửi từ Máy chủ (SSE) trên cổng 8080
fastmcp run my_server.py:mcp --transport sse --port 8080 --host 0.0.0.0

# Chạy với mức log khác
fastmcp run my_server.py:mcp --transport sse --log-level DEBUG

Các điểm chính về CLI:

  • my_server.py:mcp: Xác định tệp (my_server.py) và đối tượng máy chủ FastMCP trong tệp đó (mcp). Nếu bạn bỏ qua :mcp, FastMCP sẽ cố gắng tự động tìm một đối tượng có tên mcp, app, hoặc server.
  • Khối if __name__ == "__main__": không cần thiết khi sử dụng fastmcp run; CLI tìm và chạy trực tiếp đối tượng máy chủ đã chỉ định.
  • --transport: Chọn giao thức giao tiếp (stdio, sse). SSE là thông dụng cho các tương tác dựa trên web.
  • --port, --host, --log-level: Cấu hình vận chuyển và các thiết lập ghi log.

5. Tương tác với máy chủ đang chạy (Máy khách):

Khi máy chủ của bạn đang chạy (dù qua python my_server.py hay fastmcp run), bạn có thể tạo một tập lệnh máy khách riêng để tương tác với nó.

Tạo một tệp mới, my_client.py:

# my_client.py
from fastmcp import Client
import asyncio

async def interact_with_server():
    print("--- Tạo Máy khách ---")

    # Tùy chọn 1: Kết nối tới máy chủ chạy qua `python my_server.py` (sử dụng stdio)
    # client = Client("my_server.py")

    # Tùy chọn 2: Kết nối tới máy chủ chạy qua `fastmcp run ... --transport sse --port 8080`
    client = Client("http://localhost:8080") # Sử dụng URL/cổng chính xác

    print(f"Máy khách đã được cấu hình để kết nối tới: {client.target}")

    try:
        async with client:
            print("--- Máy khách đã kết nối ---")
            # Gọi công cụ 'greet'
            greet_result = await client.call_tool("greet", {"name": "Máy khách từ xa"})
            print(f"giá trị chào: {greet_result}")

            # Đọc tài nguyên 'config'
            config_data = await client.read_resource("data://config")
            print(f"tài nguyên cấu hình: {config_data}")

            # Đọc hồ sơ người dùng 102
            profile_102 = await client.read_resource("users://102/profile")
            print(f"Hồ sơ người dùng 102: {profile_102}")

    except Exception as e:
        print(f"Một lỗi đã xảy ra: {e}")
    finally:
        print("--- Kết thúc tương tác Máy khách ---")

if __name__ == "__main__":
    asyncio.run(interact_with_server())

Chạy tập lệnh máy khách này trong khi máy chủ đang chạy ở terminal khác:

python my_client.py

Máy khách sẽ kết nối với máy chủ đang chạy (đảm bảo rằng mục tiêu Client(...) khớp với cách thức máy chủ đang chạy – đường dẫn tệp cho stdio, URL cho sse), thực thi các cuộc gọi công cụ và đọc tài nguyên, và in kết quả.

6. Cấu hình Máy chủ (ServerSettings):

Bạn có thể điều chỉnh hành vi của máy chủ bằng cách sử dụng ServerSettings. Các thiết lập có thể được áp dụng theo thứ tự ưu tiên:

  1. Các đối số từ khóa trong quá trình khởi tạo FastMCP (ưu tiên cao nhất).
  2. Các biến môi trường (được tiền tố bằng FASTMCP_SERVER_, ví dụ: FASTMCP_SERVER_PORT=8888).
  3. Các giá trị được tải từ tệp .env trong thư mục làm việc.
  4. Các giá trị mặc định (ưu tiên thấp nhất).

Ví dụ cấu hình trong quá trình khởi tạo:

from fastmcp import FastMCP

mcp_configured = FastMCP(
    name="Máy Chủ Đã Cấu Hình",
    port=8080,  # Đặt cổng mặc định SSE
    host="127.0.0.1", # Đặt host mặc định SSE
    log_level="DEBUG", # Đặt mức ghi log
    on_duplicate_tools="warn" # Cảnh báo nếu các công cụ có cùng tên được đăng ký (tùy chọn: 'error', 'warn', 'ignore')
)

# Truy cập các thiết lập thông qua thuộc tính .settings
print(f"Cổng cấu hình: {mcp_configured.settings.port}") # Đầu ra: 8080
print(f"Chính sách Công cụ Trùng lặp: {mcp_configured.settings.on_duplicate_tools}") # Đầu ra: warn

Các tùy chọn cấu hình chính bao gồm host, port, log_level, và các chính sách xử lý tên thành phần trùng lặp (on_duplicate_tools, on_duplicate_resources, on_duplicate_prompts).

Những gì khác bạn có thể làm với FastMCP?

FastMCP cũng hỗ trợ các trường hợp sử dụng nâng cao hơn:

  • Ghép: Kết hợp nhiều máy chủ FastMCP. main.mount("sub", sub_server) tạo ra một liên kết trực tiếp, trong khi main.import_server(sub_server) sao chép các thành phần. Điều này hỗ trợ tính mô-đun.
  • Chuyển tiếp: Sử dụng FastMCP.from_client(client) để tạo một phiên bản máy chủ FastMCP hoạt động như một proxy cho một máy chủ MCP khác (cục bộ hoặc từ xa). Điều này rất hữu ích để cầu nối các giao thức (ví dụ: tiết lộ một máy chủ SSE từ xa qua stdio cục bộ) hoặc thêm một giao diện thống nhất.

Kết luận

FastMCP đáng kể hạ thấp rào cản gia nhập cho việc xây dựng các ứng dụng LLM mạnh mẽ, thông minh về ngữ cảnh bằng cách đơn giản hóa việc thực hiện Giao thức Ngữ cảnh Mô hình. Thiết kế Pythonic của nó, tập trung vào việc giảm thiểu mã boilerplate và bộ tính năng toàn diện khiến nó trở thành một lựa chọn xuất sắc cho các nhà phát triển muốn cung cấp cho các LLM các công cụ tùy chỉnh và truy cập dữ liệu một cách an toàn và hiệu quả.

Bằng cách làm theo các bước đã nêu ở trên – cài đặt FastMCP, tạo một phiên bản máy chủ, thêm công cụ và tài nguyên bằng các trình trang trí đơn giản, và chạy máy chủ – bạn có thể nhanh chóng bắt đầu xây dựng các ứng dụng được hỗ trợ MCP của riêng mình. Bất kể bạn đang tạo các công cụ tiện ích đơn giản hay các tích hợp phức tạp, sử dụng nhiều dữ liệu, FastMCP cung cấp nền tảng cho những tương tác vững chắc và có thể mở rộng giữa LLM.