模型上下文协议 (Model Context Protocol, MCP)

[English]

支持的芯片

ESP32

ESP32-C2

ESP32-C3

ESP32-S3

MCP 组件为访问常用 MCP 功能提供了简化的 API 接口。它支持 HTTP 等常见场景。

示例

  1. MCP 服务示例: mcp/mcp_server.

API 参考

Header File

Functions

esp_err_t esp_mcp_mgr_init(esp_mcp_mgr_config_t config, esp_mcp_mgr_handle_t *handle)

Initialize MCP transport manager.

Initializes an MCP (Model Context Protocol) transport manager with the specified transport (HTTP, BLE, etc.). The transport manager handles communication between ESP32 devices and AI applications using the MCP protocol.

参数

  • config – [in] MCP transport manager configuration (transport, config, server instance)

  • handle – [out] Pointer to store the created MCP transport manager handle

返回

  • ESP_OK: MCP transport manager initialized successfully

  • ESP_ERR_INVALID_ARG: Invalid arguments (NULL handle or invalid transport functions)

  • ESP_ERR_NO_MEM: Out of memory

esp_err_t esp_mcp_mgr_deinit(esp_mcp_mgr_handle_t handle)

Deinitialize MCP transport manager.

Deinitializes the MCP transport manager and releases all associated resources, including transport instances and configurations. The transport must be stopped (via esp_mcp_mgr_stop()) before deinitialization.

参数

handle – [in] MCP transport manager handle

返回

  • ESP_OK: MCP transport manager deinitialized successfully

  • ESP_ERR_INVALID_ARG: Invalid handle

esp_err_t esp_mcp_mgr_start(esp_mcp_mgr_handle_t handle)

Start MCP transport layer.

Starts the underlying transport layer (e.g., HTTP server, BLE service) to begin accepting MCP protocol messages from AI applications. The transport manager must be initialized before calling this function.

参数

handle – [in] MCP transport manager handle

返回

  • ESP_OK: Transport layer started successfully

  • ESP_ERR_INVALID_ARG: Invalid handle

  • ESP_ERR_FAIL: Failed to start transport layer (e.g., port already in use)

esp_err_t esp_mcp_mgr_stop(esp_mcp_mgr_handle_t handle)

Stop MCP transport layer.

Stops the underlying transport layer (e.g., HTTP server, BLE service) and stops accepting new MCP protocol messages. Existing connections may be gracefully closed.

参数

handle – [in] MCP transport manager handle

返回

  • ESP_OK: Transport layer stopped successfully

  • ESP_ERR_INVALID_ARG: Invalid handle

esp_err_t esp_mcp_mgr_register_endpoint(esp_mcp_mgr_handle_t handle, const char *ep_name, void *priv_data)

Register an MCP endpoint.

Registers an endpoint (e.g., “tools/list”, “tools/call”) for routing MCP protocol messages. Endpoints are used to organize different types of MCP operations. The endpoint will be accessible via the transport layer (e.g., HTTP path).

参数

  • handle – [in] MCP transport manager handle

  • ep_name – [in] Endpoint name (e.g., “mcp_server”, “tools/list”)

  • priv_data – [in] Private data passed to the endpoint handler (typically NULL or MCP engine instance)

返回

  • ESP_OK: Endpoint registered successfully

  • ESP_ERR_INVALID_ARG: Invalid arguments

  • ESP_ERR_INVALID_STATE: Endpoint already exists

  • ESP_ERR_NO_MEM: Memory allocation failed

esp_err_t esp_mcp_mgr_unregister_endpoint(esp_mcp_mgr_handle_t handle, const char *ep_name)

Unregister an MCP endpoint.

Removes an endpoint from the MCP transport manager. The endpoint will no longer accept MCP protocol messages. All associated resources are freed.

参数

  • handle – [in] MCP transport manager handle

  • ep_name – [in] Endpoint name to remove

返回

  • ESP_OK: Endpoint removed successfully

  • ESP_ERR_INVALID_ARG: Invalid arguments

  • ESP_ERR_NOT_FOUND: Endpoint not found

esp_err_t esp_mcp_mgr_req_handle(esp_mcp_mgr_handle_t handle, const char *ep_name, const uint8_t *inbuf, uint16_t inlen, uint8_t **outbuf, uint16_t *outlen)

Handle an MCP protocol request.

Processes an incoming MCP protocol message (JSON-RPC 2.0 format) and routes it to the appropriate endpoint handler. The handler parses the message, executes the requested MCP operation (e.g., initialize, tools/list, tools/call), and returns the response. This function is typically called by transport layer implementations (e.g., HTTP handler) when receiving MCP protocol messages from AI applications.

备注

The caller is responsible for freeing the outbuf using cJSON_free() after sending the response.

备注

If the function returns an error, outbuf may be NULL or contain an error response.

参数

  • handle – [in] MCP transport manager handle

  • ep_name – [in] Endpoint name to route the request to (e.g., “mcp_server”)

  • inbuf – [in] Input buffer containing the MCP protocol message (JSON-RPC 2.0 format, null-terminated)

  • inlen – [in] Length of the input buffer in bytes

  • outbuf – [out] Pointer to store the output buffer containing the MCP response JSON (caller must free with cJSON_free after use)

  • outlen – [out] Pointer to store the output buffer length in bytes

返回

  • ESP_OK: Request handled successfully, response available in outbuf

  • ESP_ERR_INVALID_ARG: Invalid arguments (NULL pointer or empty endpoint name)

  • ESP_ERR_NOT_FOUND: Endpoint not found

  • ESP_FAIL: Failed to process MCP request (parse error, tool execution error, etc.)

esp_err_t esp_mcp_mgr_req_destroy_response(esp_mcp_mgr_handle_t handle, uint8_t *response_buffer)

Destroy a MCP response buffer.

Destroys a MCP response buffer and frees the memory. This function uses the message ID from the last request processed by the handler.

备注

This function uses the msg_id from the last request. For more precise control, use esp_mcp_mgr_req_destroy_response_by_id() instead.

参数

  • handle – [in] MCP transport manager handle

  • response_buffer – [in] MCP response buffer to destroy (currently unused, kept for API compatibility)

返回

  • ESP_OK: Response buffer destroyed successfully

  • ESP_ERR_INVALID_ARG: Invalid arguments

  • ESP_ERR_NOT_FOUND: Message ID not found

esp_err_t esp_mcp_mgr_req_destroy_response_by_id(esp_mcp_mgr_handle_t handle, uint16_t id)

Destroy a MCP response buffer by message ID.

Destroys a MCP response buffer for the specified message ID and frees the memory. This is the recommended way to free response buffers when you know the message ID.

备注

This function should be called after sending the response to prevent memory leaks. Each handled request may allocate a response buffer that must be freed using this function or esp_mcp_mgr_req_destroy_response().

参数

  • handle – [in] MCP transport manager handle

  • id – [in] Message ID of the response to destroy

返回

  • ESP_OK: Response buffer destroyed successfully

  • ESP_ERR_INVALID_ARG: Invalid arguments

  • ESP_ERR_NOT_FOUND: Message ID not found

Structures

struct esp_mcp_transport_s

MCP transport function table.

Structure defining the function callbacks for a specific MCP transport implementation. Each transport (HTTP, BLE, etc.) provides its own implementation of these functions to handle protocol-specific operations like starting/stopping the transport layer and managing endpoints for MCP message routing.

Public Members

esp_err_t (*init)(esp_mcp_mgr_handle_t handle, esp_mcp_transport_handle_t *transport_handle)

Create a new transport instance

esp_err_t (*deinit)(esp_mcp_transport_handle_t handle)

Destroy a transport instance

esp_err_t (*start)(esp_mcp_transport_handle_t handle, void *config)

Start the transport layer (e.g., start HTTP server)

esp_err_t (*stop)(esp_mcp_transport_handle_t handle)

Stop the transport layer (e.g., stop HTTP server)

esp_err_t (*create_config)(const void *config, void **config_out)

Create transport-specific configuration

esp_err_t (*delete_config)(void *config)

Destroy transport-specific configuration

esp_err_t (*register_endpoint)(esp_mcp_transport_handle_t handle, const char *ep_name, void *priv_data)

Register an MCP endpoint for message routing

esp_err_t (*unregister_endpoint)(esp_mcp_transport_handle_t handle, const char *ep_name)

Unregister an MCP endpoint

struct esp_mcp_mgr_config_t

MCP transport manager configuration structure.

Configuration structure for initializing an MCP transport manager instance. Specifies the transport to use (HTTP, BLE, etc.) and associated configuration.

Public Members

esp_mcp_transport_t transport

Transport function table (e.g., esp_mcp_transport_http)

void *config

Transport-specific configuration (e.g., HTTP server port, BLE service UUID)

void *instance

MCP instance context (esp_mcp_t *) for handling MCP protocol messages

Type Definitions

typedef uint32_t esp_mcp_mgr_handle_t

MCP transport manager handle type.

Opaque handle representing an initialized MCP (Model Context Protocol) transport manager instance. The transport manager handles communication between ESP32 devices and AI applications using the MCP protocol over various transport layers (HTTP, BLE, etc.). Created by esp_mcp_mgr_init() and used for all subsequent MCP transport operations.

typedef uint32_t esp_mcp_transport_handle_t

MCP transport handle type.

Opaque handle representing an initialized MCP transport instance. A transport defines how MCP protocol messages are transmitted (e.g., HTTP, BLE). Created by the transport’s new() function and used for transport-specific operations.

typedef struct esp_mcp_transport_s esp_mcp_transport_t

MCP transport function table.

Structure defining the function callbacks for a specific MCP transport implementation. Each transport (HTTP, BLE, etc.) provides its own implementation of these functions to handle protocol-specific operations like starting/stopping the transport layer and managing endpoints for MCP message routing.

提供有关此文档的反馈