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

[English]

支持的芯片

ESP32

ESP32-C2

ESP32-C3

ESP32-C6

ESP32-S3

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

示例

  1. MCP 服务示例: mcp/mcp_server. 在 ESP32 系列芯片上运行 MCP 服务器，通过 HTTP 暴露 JSON-RPC 工具，用于简单的设备控制（音量、亮度、主题、HSV/RGB 颜色）。

  2. MCP 客户端示例: mcp/mcp_client. 在 ESP32 系列芯片上运行 MCP 客户端，通过 HTTP 访问远程 MCP 服务器。

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_perform_handle(esp_mcp_mgr_handle_t handle, const uint8_t *inbuf, uint16_t inlen)

Perform an outbound MCP request via the configured transport (client-side)

Sends a JSON-RPC request to a remote MCP server endpoint over the configured transport. The transport must implement the optional transport.request callback.

参数

  • handle – [in] MCP transport manager handle

  • inbuf – [in] Input buffer containing the MCP protocol message (JSON-RPC request)

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

返回

  • ESP_OK: Request performed successfully (fire-and-forget)

  • ESP_ERR_INVALID_ARG: Invalid arguments

  • ESP_ERR_NOT_SUPPORTED: Transport does not support outbound requests

  • Other: Transport-specific failure

esp_err_t esp_mcp_mgr_post_info_init(esp_mcp_mgr_handle_t handle, const esp_mcp_mgr_req_t *req)

Build and send initialize request to remote MCP server.

Constructs and sends an MCP initialize request to establish a session with a remote MCP server. The response will be delivered via the callback specified in the request structure.

参数

  • handle – [in] MCP transport manager handle

  • req – [in] Request structure containing endpoint name, callback, and initialization parameters (protocol_version, name, version)

返回

  • ESP_OK: Request sent successfully

  • ESP_ERR_INVALID_ARG: Invalid arguments (NULL handle or request)

  • ESP_ERR_NOT_SUPPORTED: Transport does not support outbound requests

  • Other: Transport-specific failure

esp_err_t esp_mcp_mgr_post_tools_list(esp_mcp_mgr_handle_t handle, const esp_mcp_mgr_req_t *req)

Build and send tools/list request to remote MCP server.

Constructs and sends an MCP tools/list request to retrieve available tools from a remote MCP server. Supports cursor-based pagination. The response will be delivered via the callback specified in the request structure.

参数

  • handle – [in] MCP transport manager handle

  • req – [in] Request structure containing endpoint name, callback, and optional cursor for pagination

返回

  • ESP_OK: Request sent successfully

  • ESP_ERR_INVALID_ARG: Invalid arguments (NULL handle or request)

  • ESP_ERR_NOT_SUPPORTED: Transport does not support outbound requests

  • Other: Transport-specific failure

esp_err_t esp_mcp_mgr_post_tools_call(esp_mcp_mgr_handle_t handle, const esp_mcp_mgr_req_t *req)

Build and send tools/call request to remote MCP server.

Constructs and sends an MCP tools/call request to execute a tool on a remote MCP server. The tool name and arguments (as JSON string) must be provided. The response will be delivered via the callback specified in the request structure.

参数

  • handle – [in] MCP transport manager handle

  • req – [in] Request structure containing endpoint name, callback, tool name, and arguments JSON

返回

  • ESP_OK: Request sent successfully

  • ESP_ERR_INVALID_ARG: Invalid arguments (NULL handle, request, or missing tool_name)

  • ESP_ERR_NOT_SUPPORTED: Transport does not support outbound requests

  • Other: Transport-specific failure

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_mgr_req_t

MCP request structure.

Structure for transmitting MCP requests.

Public Members

const char *ep_name

Endpoint name

esp_mcp_mgr_resp_cb_t cb

Response callback

void *user_ctx

User context

const char *protocol_version

Protocol version string, default “2024-11-05” if NULL

const char *name

Client name

const char *version

Client version

struct esp_mcp_mgr_req_t::[anonymous]::[anonymous] init

Parameters for initialize request

const char *cursor

Cursor

struct esp_mcp_mgr_req_t::[anonymous]::[anonymous] list

Parameters for tools/list request

const char *tool_name

Tool name

const char *args_json

Tool arguments JSON

struct esp_mcp_mgr_req_t::[anonymous]::[anonymous] call

Parameters for tools/call request

union esp_mcp_mgr_req_t::[anonymous] u

Union containing request-specific parameters

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

esp_err_t (*request)(esp_mcp_transport_handle_t handle, const uint8_t *inbuf, uint16_t inlen)

Perform an outbound MCP request (client-side), optional, fire-and-forget

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 esp_err_t (*esp_mcp_mgr_resp_cb_t)(int error_code, const char *ep_name, const char *resp_json, void *user_ctx)

Response callback type for outbound requests.

This callback is invoked when a response is received for an outbound MCP request. The meaning of parameters depends on the response type:

备注

The callback is called synchronously. The ep_name and resp_json pointers are valid only during the callback execution. The framework will free these resources after the callback returns. The callback should NOT attempt to free these strings.

Param error_code

Error indicator or error code, meaning depends on resp_json:

  • If resp_json is not NULL and contains application result:

    • 0: Application-level success (result.isError = false or not present)

    • 1: Application-level error (result.isError = true)

  • If resp_json is not NULL and contains protocol error:

    • JSON-RPC error code (negative integer, e.g., -32601 for “Method not found”)

    • See MCP_ERROR_CODE_* constants in esp_mcp_error.h

  • If resp_json is NULL (parse failure):

    • esp_err_t error code (e.g., ESP_ERR_INVALID_ARG, ESP_ERR_NO_MEM)

Param ep_name

Endpoint name or tool name (may be NULL); valid only during callback execution, do NOT free

Param resp_json

Response JSON body, meaning depends on error_code:

  • If error_code is 0 or 1: Contains result object JSON (application-level response)

  • If error_code is negative (JSON-RPC error code): Contains error message string (protocol-level error)

  • If error_code is positive esp_err_t: NULL (parse failure) Valid only during callback execution, do NOT free

Param user_ctx

User context provided when sending the request

Return

ESP_OK on success, or error code if callback processing failed

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.

提供有关此文档的反馈