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

Defining tools with MCP

📖 Nội dung bài học

Gia đình phông chữ

Tóm tắt

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

Trong ví dụ này, bạn đang tạo một server quản lý tài liệu 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 tồn tại trong bộ nhớ dưới dạng một dictionary đơn giản, trong đó các key là ID tài liệu và các value là nội dung.

Thiết lập Server MCP

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

from mcp.server.fastmcp import FastMCP

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

Tài liệu của bạn có thể được lưu trữ trong một cấu trúc dictionary đơn giản:

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 expenditures",
    "outlook.pdf": "This document presents the projected future performance of the system",
    "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 công cụ với Decorator

SDK dùng decorator để định nghĩa công cụ. Thay vì viết schema JSON thủ công, bạn có thể dùng type hint Python và mô tả trường. SDK tự động tạo schema phù hợp mà Claude có thể hiểu.

Tạo công cụ Đọc tài liệu

Công cụ đầu tiên đọc nội dung tài liệu theo ID. Đây là triển khai đầy đủ:

@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 chỉ định tên và mô tả công cụ, trong khi các tham số hàm định nghĩa các đối số cần thiết. Lớp Field từ Pydantic cung cấp mô tả đối số giúp Claude hiểu mỗi tham số mong đợi điều gì.

Xây dựng công cụ Chỉnh sửa tài liệu

Công cụ 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)

Công cụ 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 bao gồm xử lý lỗi cho các tài liệu bị thiếu và thực hiện thay thế chuỗi đơn giản.

Lợi ích chính của phương pháp SDK

  • Không cần viết schema JSON thủ công
  • Type hint cung cấp xác thực tự động
  • Mô tả tham số rõ ràng giúp Claude hiểu cách dùng công cụ
  • Xử lý lỗi tích hợp tự nhiên với các exception Python
  • Đăng ký công cụ diễn ra tự động thông qua decorator

SDK Python MCP chuyển đổi việc tạo công cụ 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ách tiếp cận này giúp bạn dễ dàng xây dựng và bảo trì server MCP hơn, đồng thời đảm bảo Claude nhận được các thông số kỹ thuật công cụ được định dạng chính xá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?