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

Định nghĩa tools với MCP

📖 Nội dung bài học

Nền phông chữ

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 cho tools, SDK sẽ xử lý tất cả sự phức tạp đó cho bạn bằng các decorator và type hints.

Trong ví dụ này, chúng ta đang tạo một MCP server quản lý các tài liệu được lưu trữ trong bộ nhớ. Server sẽ cung cấp hai tools thiết yếu: một để đọc nội dung tài liệu và một để cập nhật chúng thông qua các thao tác tìm và thay thế.

Thiết lập MCP Server

Python MCP SDK giúp việc tạo server cực kỳ đơn giản. Bạn có thể khởi tạo một MCP server hoàn chỉnh chỉ với một dòng:

from mcp.server.fastmcp import FastMCP

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

Đối với triển khai này, các tài liệu được lưu trữ trong một dictionary Python đơn giản, trong đó các key là ID tài liệu và các value chứa nội dung tài liệu:

docs = {
    "deposition.md": "This deposition covers the testimony of Angela Smith, P.E.",
    "report.pdf": "The report details the state of a 20m condenser tower.",
    "financials.docx": "These financials outline the project's budget and expenditure",
    "outlook.pdf": "This document presents the projected future performance of the",
    "plan.md": "The plan outlines the steps for the project's implementation.",
    "spec.txt": "These specifications define the technical requirements for the equipment"
}

Định nghĩa Tool với Decorators

SDK biến việc tạo tool từ một quy trình dài dòng thành một thứ gì đó rõ ràng và dễ đọc. Thay vì viết các JSON schema dài, bạn sử dụng Python decorators và type hints.

Tạo Tool Đọc Tài liệu

Tool đầu tiên cho phép Claude đọc bất kỳ tài liệu nào theo ID của nó. Đây là triển khai hoàn chỉnh:

@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]

Decorator @mcp.tool tự động tạo JSON schema mà Claude cần. Lớp Field từ Pydantic cung cấp mô tả tham số giúp Claude hiểu từng đối số mong đợi điều gì.

Xây dựng 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:

@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 whitespace."),
    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)

Tool này nhận ba tham số: ID tài liệu, văn bản cần tìm và văn bản thay thế. Việc triển khai sử dụng phương thức replace() tích hợp sẵn của chuỗi Python cho đơn giản.

Xử lý Lỗi

Cả hai tool đều bao gồm xử lý lỗi cơ bản để quản lý các trường hợp Claude yêu cầu một tài liệu không tồn tại. Khi ID tài liệu không hợp lệ được cung cấp, các tool sẽ raise một ValueError với thông báo mô tả mà Claude có thể hiểu và có khả năng hành động dựa trên đó.

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

  • Tự động tạo JSON schema từ Python type hints
  • Mã rõ ràng, dễ đọc, dễ bảo trì
  • Xác thực tham số tích hợp sẵn thông qua Pydantic
  • Giảm thiểu mã lặp lại so với việc viết schema thủ công
  • An toàn kiểu và hỗ trợ IDE cho phát triển

MCP Python SDK biến những gì trước đây là một quy trình phức tạp để viết định nghĩa tool thành một thứ gì đó quen thuộc đối với các nhà phát triển Python. Bạn tập trung vào logic nghiệp vụ trong khi SDK xử lý các chi tiết giao thức.

🔁 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?