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

Định nghĩa tool với MCP

📖 Nội dung bài học

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 tool, bạn có thể định nghĩa chúng bằng decorator 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 MCP server quản lý các thao tác với tài liệu. Server sẽ có hai tool chính: một để đọc nội dung 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 đó key là ID tài liệu và value là chuỗi nội dung.

Lợi ích của MCP Python SDK

Dự án MCP cung cấp các SDK chính thức để xây dựng server và client trên nhiều ngôn ngữ lập trình. Sử dụng Python SDK mang lại nhiều lợi thế:

  • Tạo MCP server với mã boilerplate tối thiểu
  • Tự động tạo JSON schema từ chữ ký hàm Python
  • Đơn giản hóa việc định nghĩa tool thông qua decorator
  • Xử lý xác thực kiểu dữ liệu và xử lý lỗi

Đây là cách dễ dàng để định nghĩa một tool với SDK. Decorator @mcp.tool, kết hợp với type hints và mô tả trường, tự động tạo ra schema tool phù hợp mà Claude có thể hiểu và sử dụng.

Thiết lập Server

Thiết lập server cơ bản chỉ cần vài dòng:

from mcp.server.fastmcp import FastMCP
from pydantic import Field

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

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"
}

Triển khai Tool Đọc

Tool đầu tiên cho phép Claude đọc nội dung tài liệu bằng cách cung cấp ID tài liệu:

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

Định nghĩa tool bao gồm:

  • Một tên rõ ràng mô tả hành động
  • Một mô tả giải thích tool làm gì
  • Các tham số được định kiểu với mô tả trường
  • Xử lý lỗi cho các ID tài liệu không hợp lệ

Triển khai Tool Chỉnh sửa

Tool thứ hai thực hiện các thao tác tìm và thay thế đơn giản trên nội dung 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.

Chi tiết Triển khai Chính

Khi định nghĩa tool với MCP SDK, hãy nhớ những điểm quan trọng sau:

  • Import Field từ pydantic để thêm mô tả tham số
  • Sử dụng type hints để chỉ định kiểu tham số
  • Bao gồm xử lý lỗi cho các trường hợp biên
  • Viết tên và mô tả tool rõ ràng, súc tích
  • SDK tự động chuyển đổi chữ ký hàm của bạn thành JSON schema phù hợp

MCP Python SDK giảm đáng kể độ phức tạp của việc tạo tool so với việc tự viết JSON schema. Những gì trước đây đòi hỏi hàng chục dòng định nghĩa schema giờ đây chỉ mất vài dòng hàm Python được trang trí bằng decorator.

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