Bỏ qua đến nội dung chính

Định nghĩa tools với MCP

📖 Nội dung bài học

Bật/Tắt

Tóm tắt

Việc xây dựng một MCP server trở nên đơn giản hơn nhiều khi bạn sử dụng SDK Python chính thức. Thay vì tự viết các JSON schema phức tạp, bạn có thể định nghĩa tools bằng decorators và để SDK xử lý phần việc nặng nhọc.

Trong ví dụ này, chúng ta đang tạo một document management server với hai công cụ cốt lõi: một để đọc tài liệu và một để cập nhật chúng. Tất cả tài liệu đều tồn tại trong bộ nhớ dưới dạng một dictionary đơn giản, trong đó các khóa là ID tài liệu và các giá trị là nội dung.

Thiết lập MCP Server

Python MCP SDK giúp việc tạo server trở nên dễ dàng. Bạn có thể khởi tạo một server chỉ với một dòng lệnh:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("DocumentMCP", log_level="ERROR")

Điều này tạo ra một MCP server hoạt động đầy đủ, có khả năng xử lý định nghĩa tool, kết nối client và định tuyến tin nhắn.

Định nghĩa Tool với Decorators

Cách tiếp cận decorator của SDK loại bỏ nhu cầu viết JSON schema thủ công. Đây là cách bạn định nghĩa một tool đơn giản:

@mcp.tool(
    name="add_ints",
    description="Add two integers together",
)
def tool_fn(
    a=Field(description="First number to add"),
    b=Field(description="Second number to add"),
) -> int:
    return a + b

Bên dưới, MCP tự động tạo ra lược đồ tool hoàn chỉnh mà Claude cần để hiểu khi nào và làm thế nào để sử dụng tool của bạn.

Xây dựng Tool Đọc Tài liệu

Tool đầu tiên đọc nội dung tài liệu theo ID. Nó nhận một định danh tài liệu và trả về nội dung tương ứng từ dictionary trong bộ nhớ của chúng ta:

@mcp.tool(
    name="read_doc_contents",
    description="Read the contents of a document and return it as a string."
)
def read_document(
    doc_id: str = Field(description="Id of the document to read")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    return docs[doc_id]

Hàm này bao gồm xử lý lỗi cơ bản để bắt các yêu cầu cho tài liệu không tồn tại. Khi Claude gọi tool này với một ID tài liệu hợp lệ, nó sẽ nhận được toàn bộ nội dung tài liệu dưới dạng một chuỗi.

Tạo Tool Chỉnh sửa Tài liệu

Tool thứ hai thực hiện các thao tác tìm và thay thế đơn giản trên tài liệu. Nó yêu cầu ba tham số: ID tài liệu, văn bản cần tìm và văn bản thay thế:

@mcp.tool(
    name="edit_document",
    description="Edit a document by replacing a string in the documents content with a new string."
)
def edit_document(
    doc_id: str = Field(description="Id of the document that will be edited"),
    old_str: str = Field(description="The text to replace. Must match exactly, including white space."),
    new_str: str = Field(description="The new text to insert in place of the old text.")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    docs[doc_id] = docs[doc_id].replace(old_str, new_str)

Việc triển khai này sử dụng phương thức replace tích hợp sẵn của Python, yêu cầu khớp chính xác bao gồm cả khoảng trắng. Tool này sửa đổi tài liệu tại chỗ trong dictionary của chúng ta.

Lợi ích chính của Cách tiếp cận SDK

  • Không cần viết JSON schema thủ công
  • Type hints cung cấp xác thực tham số tự động
  • Mô tả trường giúp Claude hiểu cách sử dụng tool
  • Xử lý lỗi tích hợp tự nhiên với các ngoại lệ Python
  • Đăng ký tool diễn ra tự động thông qua decorators

MCP Python SDK biến việc tạo tool từ một bài tập viết schema phức tạp thành các định nghĩa hàm Python đơn giản. Các tool của bạn trở nên dễ bảo trì và dễ kiểm tra hơn, trong khi Claude nhận được tất cả siêu dữ liệu cần thiết để sử dụng chúng một cách hiệu quả.

🔁 Bài học liên quan

📚 Nguồn & ghi nhận

Bài học có hữu ích không?

Góp ý / Báo lỗiPhát hiện sai sót hoặc có ý tưởng cải thiện?