Máy chủ MCP với Giao thức stdio

⚠️ Cập nhật quan trọng: Kể từ MCP Specification 2025-06-18, giao thức SSE (Server-Sent Events) độc lập đã bị khai tử và được thay thế bằng giao thức "Streamable HTTP". MCP Specification hiện tại định nghĩa hai cơ chế giao tiếp chính:

stdio - Đầu vào/đầu ra tiêu chuẩn (được khuyến nghị cho máy chủ cục bộ)

Streamable HTTP - Dành cho máy chủ từ xa có thể sử dụng SSE nội bộ

Bài học này đã được cập nhật để tập trung vào giao thức stdio, đây là phương pháp được khuyến nghị cho hầu hết các triển khai máy chủ MCP.

Giao thức stdio cho phép các máy chủ MCP giao tiếp với các client thông qua luồng đầu vào và đầu ra tiêu chuẩn. Đây là cơ chế giao tiếp được sử dụng phổ biến nhất và được khuyến nghị trong MCP Specification hiện tại, cung cấp một cách đơn giản và hiệu quả để xây dựng các máy chủ MCP có thể dễ dàng tích hợp với nhiều ứng dụng client khác nhau.

Tổng quan

Bài học này hướng dẫn cách xây dựng và sử dụng máy chủ MCP với giao thức stdio.

Mục tiêu học tập

Sau khi hoàn thành bài học này, bạn sẽ có thể:

Xây dựng một máy chủ MCP sử dụng giao thức stdio.
Gỡ lỗi máy chủ MCP bằng công cụ Inspector.
Sử dụng máy chủ MCP với Visual Studio Code.
Hiểu các cơ chế giao tiếp MCP hiện tại và lý do tại sao stdio được khuyến nghị.

Giao thức stdio - Cách hoạt động

Giao thức stdio là một trong hai loại giao tiếp được hỗ trợ trong MCP Specification hiện tại (2025-06-18). Cách hoạt động như sau:

Giao tiếp đơn giản: Máy chủ đọc các thông điệp JSON-RPC từ đầu vào tiêu chuẩn (stdin) và gửi thông điệp qua đầu ra tiêu chuẩn (stdout).
Dựa trên tiến trình: Client khởi chạy máy chủ MCP như một tiến trình con.
Định dạng thông điệp: Các thông điệp là các yêu cầu, thông báo hoặc phản hồi JSON-RPC riêng lẻ, được phân cách bằng dòng mới.
Ghi nhật ký: Máy chủ CÓ THỂ ghi các chuỗi UTF-8 vào đầu ra lỗi tiêu chuẩn (stderr) để ghi nhật ký.

Yêu cầu chính:

Các thông điệp PHẢI được phân cách bằng dòng mới và KHÔNG ĐƯỢC chứa dòng mới nhúng.
Máy chủ KHÔNG ĐƯỢC ghi bất kỳ thứ gì vào stdout không phải là thông điệp MCP hợp lệ.
Client KHÔNG ĐƯỢC ghi bất kỳ thứ gì vào stdin của máy chủ không phải là thông điệp MCP hợp lệ.

TypeScript

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  {
    name: "example-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

Trong đoạn mã trên:

Chúng ta nhập lớp Server và StdioServerTransport từ MCP SDK.
Chúng ta tạo một instance máy chủ với cấu hình và khả năng cơ bản.

Python

import asyncio
import logging
from mcp.server import Server
from mcp.server.stdio import stdio_server

# Create server instance
server = Server("example-server")

@server.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

async def main():
    async with stdio_server(server) as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            server.create_initialization_options()
        )

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

Trong đoạn mã trên, chúng ta:

Tạo một instance máy chủ sử dụng MCP SDK.
Định nghĩa các công cụ bằng decorators.
Sử dụng context manager stdio_server để xử lý giao thức.

.NET

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol.Server;

var builder = Host.CreateApplicationBuilder(args);

builder.Services
    .AddMcpServer()
    .WithStdioTransport()
    .WithTools<Tools>();

builder.Services.AddLogging(logging => logging.AddConsole());

var app = builder.Build();
await app.RunAsync();

Sự khác biệt chính so với SSE là máy chủ stdio:

Không yêu cầu thiết lập máy chủ web hoặc endpoint HTTP.
Được khởi chạy như các tiến trình con bởi client.
Giao tiếp qua luồng stdin/stdout.
Dễ triển khai và gỡ lỗi hơn.

Bài tập: Tạo một máy chủ stdio

Để tạo máy chủ của chúng ta, cần lưu ý hai điều:

Chúng ta cần sử dụng một máy chủ web để cung cấp các endpoint cho kết nối và thông điệp.

Phòng thí nghiệm: Tạo một máy chủ MCP stdio đơn giản

Trong phòng thí nghiệm này, chúng ta sẽ tạo một máy chủ MCP đơn giản sử dụng giao thức stdio được khuyến nghị. Máy chủ này sẽ cung cấp các công cụ mà client có thể gọi bằng giao thức Model Context Protocol tiêu chuẩn.

Yêu cầu

Python 3.8 hoặc mới hơn
MCP Python SDK: pip install mcp
Hiểu biết cơ bản về lập trình bất đồng bộ

Hãy bắt đầu tạo máy chủ MCP stdio đầu tiên của chúng ta:

import asyncio
import logging
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp import types

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Create the server
server = Server("example-stdio-server")

@server.tool()
def calculate_sum(a: int, b: int) -> int:
    """Calculate the sum of two numbers"""
    return a + b

@server.tool() 
def get_greeting(name: str) -> str:
    """Generate a personalized greeting"""
    return f"Hello, {name}! Welcome to MCP stdio server."

async def main():
    # Use stdio transport
    async with stdio_server(server) as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            server.create_initialization_options()
        )

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

Sự khác biệt chính so với cách tiếp cận SSE đã khai tử

Giao thức Stdio (Tiêu chuẩn hiện tại):

Mô hình tiến trình con đơn giản - client khởi chạy máy chủ như một tiến trình con.
Giao tiếp qua stdin/stdout sử dụng thông điệp JSON-RPC.
Không yêu cầu thiết lập máy chủ HTTP.
Hiệu suất và bảo mật tốt hơn.
Dễ dàng gỡ lỗi và phát triển.

Giao thức SSE (Đã khai tử từ MCP 2025-06-18):

Yêu cầu máy chủ HTTP với các endpoint SSE.
Thiết lập phức tạp hơn với hạ tầng máy chủ web.
Cần xem xét thêm về bảo mật cho các endpoint HTTP.
Hiện đã được thay thế bằng Streamable HTTP cho các kịch bản dựa trên web.

Tạo máy chủ với giao thức stdio

Để tạo máy chủ stdio, chúng ta cần:

Nhập các thư viện cần thiết - Chúng ta cần các thành phần máy chủ MCP và giao thức stdio.
Tạo một instance máy chủ - Định nghĩa máy chủ với các khả năng của nó.
Định nghĩa các công cụ - Thêm các chức năng mà chúng ta muốn cung cấp.
Thiết lập giao thức - Cấu hình giao tiếp stdio.
Chạy máy chủ - Khởi chạy máy chủ và xử lý thông điệp.

Hãy xây dựng từng bước:

Bước 1: Tạo một máy chủ stdio cơ bản

import asyncio
import logging
from mcp.server import Server
from mcp.server.stdio import stdio_server

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Create the server
server = Server("example-stdio-server")

@server.tool()
def get_greeting(name: str) -> str:
    """Generate a personalized greeting"""
    return f"Hello, {name}! Welcome to MCP stdio server."

async def main():
    async with stdio_server(server) as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            server.create_initialization_options()
        )

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

Bước 2: Thêm nhiều công cụ hơn

@server.tool()
def calculate_sum(a: int, b: int) -> int:
    """Calculate the sum of two numbers"""
    return a + b

@server.tool()
def calculate_product(a: int, b: int) -> int:
    """Calculate the product of two numbers"""
    return a * b

@server.tool()
def get_server_info() -> dict:
    """Get information about this MCP server"""
    return {
        "server_name": "example-stdio-server",
        "version": "1.0.0",
        "transport": "stdio",
        "capabilities": ["tools"]
    }

Bước 3: Chạy máy chủ

Lưu mã dưới dạng server.py và chạy từ dòng lệnh:

python server.py

Máy chủ sẽ khởi động và chờ đầu vào từ stdin. Nó giao tiếp bằng thông điệp JSON-RPC qua giao thức stdio.

Bước 4: Kiểm tra với Inspector

Bạn có thể kiểm tra máy chủ của mình bằng công cụ MCP Inspector:

Cài đặt Inspector: npx @modelcontextprotocol/inspector
Chạy Inspector và trỏ nó đến máy chủ của bạn.
Kiểm tra các công cụ bạn đã tạo.

.NET

var builder = WebApplication.CreateBuilder(args);
builder.Services
    .AddMcpServer();

## Debugging your stdio server

### Using the MCP Inspector

The MCP Inspector is a valuable tool for debugging and testing MCP servers. Here's how to use it with your stdio server:

1. **Install the Inspector**:

Những gì bạn nên thấy

Khi máy chủ của bạn khởi động đúng cách, bạn sẽ thấy:

Các khả năng của máy chủ được liệt kê trong Inspector.
Các công cụ có sẵn để kiểm tra.
Các thông điệp JSON-RPC được trao đổi thành công.
Phản hồi của công cụ hiển thị trong giao diện.

Các vấn đề thường gặp và giải pháp

Máy chủ không khởi động:

Kiểm tra xem tất cả các phụ thuộc đã được cài đặt: pip install mcp.
Xác minh cú pháp và thụt lề Python.
Tìm lỗi trong bảng điều khiển.

Công cụ không xuất hiện:

Đảm bảo các decorator @server.tool() được sử dụng.
Kiểm tra rằng các hàm công cụ được định nghĩa trước main().
Xác minh máy chủ được cấu hình đúng cách.

Vấn đề kết nối:

Đảm bảo máy chủ sử dụng giao thức stdio đúng cách.
Kiểm tra rằng không có tiến trình nào khác gây nhiễu.
Xác minh cú pháp lệnh Inspector.

Bài tập

Hãy thử xây dựng máy chủ của bạn với nhiều khả năng hơn. Xem trang này để, ví dụ, thêm một công cụ gọi API. Bạn quyết định máy chủ sẽ trông như thế nào. Chúc vui vẻ :)

Giải pháp

Giải pháp Đây là một giải pháp có mã hoạt động.

Những điểm chính

Những điểm chính từ chương này bao gồm:

Giao thức stdio là cơ chế được khuyến nghị cho các máy chủ MCP cục bộ.
Giao thức stdio cho phép giao tiếp liền mạch giữa máy chủ MCP và client sử dụng luồng đầu vào và đầu ra tiêu chuẩn.
Bạn có thể sử dụng cả Inspector và Visual Studio Code để sử dụng trực tiếp các máy chủ stdio, giúp việc gỡ lỗi và tích hợp trở nên đơn giản.

Mẫu

Tài nguyên bổ sung

Các bước tiếp theo

Bây giờ bạn đã học cách xây dựng máy chủ MCP với giao thức stdio, bạn có thể khám phá các chủ đề nâng cao hơn:

Tiếp theo: HTTP Streaming với MCP (Streamable HTTP) - Tìm hiểu về cơ chế giao tiếp được hỗ trợ khác cho máy chủ từ xa.
Nâng cao: Các thực hành bảo mật tốt nhất cho MCP - Triển khai bảo mật trong các máy chủ MCP của bạn.
Sản xuất: Chiến lược triển khai - Triển khai máy chủ của bạn để sử dụng trong môi trường sản xuất.

Tài nguyên bổ sung

MCP Specification 2025-06-18 - Đặc tả chính thức.
Tài liệu MCP SDK - Tham khảo SDK cho tất cả các ngôn ngữ.
Ví dụ cộng đồng - Thêm các ví dụ máy chủ từ cộng đồng.

Tuyên bố miễn trừ trách nhiệm:
Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI Co-op Translator. Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng các bản dịch tự động có thể chứa lỗi hoặc không chính xác. Tài liệu gốc bằng ngôn ngữ bản địa nên được coi là nguồn thông tin chính thức. Đối với các thông tin quan trọng, khuyến nghị sử dụng dịch vụ dịch thuật chuyên nghiệp bởi con người. Chúng tôi không chịu trách nhiệm cho bất kỳ sự hiểu lầm hoặc diễn giải sai nào phát sinh từ việc sử dụng bản dịch này.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Máy chủ MCP với Giao thức stdio

Tổng quan

Mục tiêu học tập

Giao thức stdio - Cách hoạt động

Yêu cầu chính:

TypeScript

Python

.NET

Bài tập: Tạo một máy chủ stdio

Phòng thí nghiệm: Tạo một máy chủ MCP stdio đơn giản

Yêu cầu

Sự khác biệt chính so với cách tiếp cận SSE đã khai tử

Tạo máy chủ với giao thức stdio

Bước 1: Tạo một máy chủ stdio cơ bản

Bước 2: Thêm nhiều công cụ hơn

Bước 3: Chạy máy chủ

Bước 4: Kiểm tra với Inspector

.NET

Những gì bạn nên thấy

Các vấn đề thường gặp và giải pháp

Bài tập

Giải pháp

Những điểm chính

Mẫu

Tài nguyên bổ sung

Tiếp theo

Các bước tiếp theo

Tài nguyên bổ sung

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Máy chủ MCP với Giao thức stdio

Tổng quan

Mục tiêu học tập

Giao thức stdio - Cách hoạt động

Yêu cầu chính:

TypeScript

Python

.NET

Bài tập: Tạo một máy chủ stdio

Phòng thí nghiệm: Tạo một máy chủ MCP stdio đơn giản

Yêu cầu

Sự khác biệt chính so với cách tiếp cận SSE đã khai tử

Tạo máy chủ với giao thức stdio

Bước 1: Tạo một máy chủ stdio cơ bản

Bước 2: Thêm nhiều công cụ hơn

Bước 3: Chạy máy chủ

Bước 4: Kiểm tra với Inspector

.NET

Những gì bạn nên thấy

Các vấn đề thường gặp và giải pháp

Bài tập

Giải pháp

Những điểm chính

Mẫu

Tài nguyên bổ sung

Tiếp theo

Các bước tiếp theo

Tài nguyên bổ sung