工具与数据 API

本节包含工具定义/执行接口，以及公共数据与属性接口。

工具接口

Header File

Functions

esp_mcp_tool_t *esp_mcp_tool_create(const char *name, const char *description, esp_mcp_tool_callback_t callback)

Create a new MCP tool.

参数

  • name – [in] Tool name (must not be NULL)

  • description – [in] Tool description (must not be NULL)

  • callback – [in] Tool callback function (must not be NULL)

返回

Pointer to the created tool, or NULL on failure

esp_mcp_tool_t *esp_mcp_tool_create_ex(const char *name, const char *title, const char *description, esp_mcp_tool_callback_ex_t callback)

Create a new MCP tool with extended callback.

参数

  • name – [in] Tool name

  • title – [in] Optional display title (can be NULL)

  • description – [in] Tool description

  • callback – [in] Extended callback

返回

Pointer to tool or NULL

esp_err_t esp_mcp_tool_set_title(esp_mcp_tool_t *tool, const char *title)

Set tool title.

参数

  • tool – [in] Tool instance

  • title – [in] Tool title (nullable)

返回

ESP_OK on success

esp_err_t esp_mcp_tool_set_icons_json(esp_mcp_tool_t *tool, const char *icons_json)

Set tool icons metadata JSON.

参数

  • tool – [in] Tool instance

  • icons_json – [in] JSON array/object string for icons (nullable)

返回

ESP_OK on success

esp_err_t esp_mcp_tool_set_output_schema_json(esp_mcp_tool_t *tool, const char *schema_json)

Set tool output schema JSON.

参数

  • tool – [in] Tool instance

  • schema_json – [in] JSON schema object string (nullable)

返回

ESP_OK on success

esp_err_t esp_mcp_tool_set_annotations_json(esp_mcp_tool_t *tool, const char *annotations_json)

Set tool annotations JSON.

参数

  • tool – [in] Tool instance

  • annotations_json – [in] JSON object string (nullable)

返回

ESP_OK on success

esp_err_t esp_mcp_tool_set_task_support(esp_mcp_tool_t *tool, const char *task_support)

Set task support mode for the tool.

参数

  • tool – [in] Tool instance

  • task_support – [in] “required”, “optional”, or “forbidden”

返回

ESP_OK on success

esp_mcp_tool_result_t *esp_mcp_tool_result_create(void)

Create tool result builder.

返回

Tool result builder instance, or NULL on failure

esp_err_t esp_mcp_tool_result_destroy(esp_mcp_tool_result_t *result)

Destroy tool result builder.

参数

result – [in] Tool result builder

返回

ESP_OK on success

esp_err_t esp_mcp_tool_result_set_is_error(esp_mcp_tool_result_t *result, bool is_error)

Set result isError flag.

参数

  • result – [in] Tool result builder

  • is_error – [in] True for application-level error

返回

ESP_OK on success

esp_err_t esp_mcp_tool_result_add_text(esp_mcp_tool_result_t *result, const char *text)

Add text content block.

参数

  • result – [in] Tool result builder

  • text – [in] Text content

返回

ESP_OK on success

esp_err_t esp_mcp_tool_result_add_image_base64(esp_mcp_tool_result_t *result, const char *mime_type, const char *base64_data)

Add base64 image content block.

参数

  • result – [in] Tool result builder

  • mime_type – [in] Image MIME type

  • base64_data – [in] Base64-encoded image payload

返回

ESP_OK on success

esp_err_t esp_mcp_tool_result_add_audio_base64(esp_mcp_tool_result_t *result, const char *mime_type, const char *base64_data)

Add base64 audio content block.

参数

  • result – [in] Tool result builder

  • mime_type – [in] Audio MIME type

  • base64_data – [in] Base64-encoded audio payload

返回

ESP_OK on success

esp_err_t esp_mcp_tool_result_add_resource_link(esp_mcp_tool_result_t *result, const char *uri, const char *name, const char *description, const char *mime_type)

Add resource_link content block.

参数

  • result – [in] Tool result builder

  • uri – [in] Resource URI

  • name – [in] Resource display name

  • description – [in] Resource description (nullable)

  • mime_type – [in] Resource MIME type (nullable)

返回

ESP_OK on success

esp_err_t esp_mcp_tool_result_add_embedded_resource_text(esp_mcp_tool_result_t *result, const char *uri, const char *mime_type, const char *text)

Add embedded text resource content block.

参数

  • result – [in] Tool result builder

  • uri – [in] Resource URI

  • mime_type – [in] Resource MIME type

  • text – [in] Text payload

返回

ESP_OK on success

esp_err_t esp_mcp_tool_result_add_embedded_resource_blob(esp_mcp_tool_result_t *result, const char *uri, const char *mime_type, const char *base64_blob)

Add embedded base64 blob resource content block.

参数

  • result – [in] Tool result builder

  • uri – [in] Resource URI

  • mime_type – [in] Resource MIME type

  • base64_blob – [in] Base64 blob payload

返回

ESP_OK on success

esp_err_t esp_mcp_tool_result_set_structured_json(esp_mcp_tool_result_t *result, const char *structured_json_object)

Set structuredContent JSON object.

参数

  • result – [in] Tool result builder

  • structured_json_object – [in] JSON object string

返回

ESP_OK on success

esp_err_t esp_mcp_tool_destroy(esp_mcp_tool_t *tool)

Destroy a tool.

参数

tool – [in] Pointer to the tool (must not be NULL)

返回

ESP_OK if successful, otherwise an error code

  • ESP_ERR_INVALID_ARG: Invalid parameter

  • ESP_ERR_INVALID_STATE: Tool is not initialized

  • ESP_ERR_NO_MEM: Memory allocation failed

  • ESP_ERR_INTERNAL: Internal error

esp_err_t esp_mcp_tool_add_property(esp_mcp_tool_t *tool, esp_mcp_property_t *property)

Add a property to a tool.

参数

  • tool – [in] Pointer to the tool (must not be NULL)

  • property – [in] Pointer to the property (must not be NULL)

返回

ESP_OK if successful, otherwise an error code

esp_err_t esp_mcp_tool_remove_property(esp_mcp_tool_t *tool, esp_mcp_property_t *property)

Remove a property from a tool.

参数

  • tool – [in] Pointer to the tool (must not be NULL)

  • property – [in] Pointer to the property (must not be NULL)

返回

ESP_OK if successful, otherwise an error code

Type Definitions

typedef struct esp_mcp_tool_s esp_mcp_tool_t

MCP tool definition object.

typedef struct esp_mcp_tool_result_s esp_mcp_tool_result_t

Builder object for MCP tool call result payload.

typedef esp_mcp_value_t (*esp_mcp_tool_callback_t)(const esp_mcp_property_list_t *properties)

Tool callback function type.

Callback function called when a tool is executed. Receives the input properties and returns the execution result as a MCP value.

Param properties

[in] Tool input properties (can be NULL)

Return

MCP value containing the tool execution result

typedef esp_err_t (*esp_mcp_tool_callback_ex_t)(const esp_mcp_property_list_t *properties, esp_mcp_tool_result_t *result)

Extended tool callback allowing full MCP CallToolResult.

Implementations can populate a tool result with multiple content blocks, structuredContent, and isError flag.

Param properties

[in] Tool input properties (can be NULL)

Param result

[out] Tool result builder instance

Return

ESP_OK on success

属性接口

Header File

Functions

esp_mcp_property_t *esp_mcp_property_create(const char *name, esp_mcp_property_type_t type)

Create a MCP property.

Creates a new MCP property with the specified name and type.

参数

  • name – [in] Property name (must not be NULL)

  • type – [in] Property type

返回

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_bool(const char *name, bool default_value)

Create a MCP property with a default boolean value.

参数

  • name – [in] Property name (must not be NULL)

  • default_value – [in] Default boolean value

返回

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_int(const char *name, int default_value)

Create a MCP property with a default integer value.

参数

  • name – [in] Property name (must not be NULL)

  • default_value – [in] Default integer value

返回

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_float(const char *name, float default_value)

Create a MCP property with a default float value.

参数

  • name – [in] Property name (must not be NULL)

  • default_value – [in] Default float value

返回

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_string(const char *name, const char *default_value)

Create a MCP property with a default string value.

参数

  • name – [in] Property name (must not be NULL)

  • default_value – [in] Default string value (must not be NULL)

返回

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_array(const char *name, const char *default_value)

Create a MCP property with a default JSON array value.

参数

  • name – [in] Property name (must not be NULL)

  • default_value – [in] Default JSON array string (must be valid JSON, must not be NULL)

返回

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_object(const char *name, const char *default_value)

Create a MCP property with a default JSON object value.

参数

  • name – [in] Property name (must not be NULL)

  • default_value – [in] Default JSON object string (must be valid JSON, must not be NULL)

返回

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_range(const char *name, int min_value, int max_value)

Create a MCP property with a range constraint.

Creates an integer property with minimum and maximum value constraints.

参数

  • name – [in] Property name (must not be NULL)

  • min_value – [in] Minimum allowed value

  • max_value – [in] Maximum allowed value (must be >= min_value)

返回

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_int_and_range(const char *name, int default_value, int min_value, int max_value)

Create a MCP property with a default value and range constraint.

Creates an integer property with a default value and minimum/maximum constraints.

参数

  • name – [in] Property name (must not be NULL)

  • default_value – [in] Default integer value (must be within [min_value, max_value])

  • min_value – [in] Minimum allowed value

  • max_value – [in] Maximum allowed value (must be >= min_value)

返回

Pointer to the created property, or NULL on failure

esp_err_t esp_mcp_property_destroy(esp_mcp_property_t *property)

Destroy a MCP property.

Frees all resources associated with the property.

参数

property – [in] Pointer to the property to destroy (must not be NULL)

返回

  • ESP_OK: Property destroyed successfully

  • ESP_ERR_INVALID_ARG: Invalid parameter

bool esp_mcp_property_list_get_property_bool(const esp_mcp_property_list_t *list, const char *name)

Get a boolean property value from a property list.

参数

  • list – [in] Pointer to the property list (must not be NULL)

  • name – [in] Property name (must not be NULL)

返回

Boolean value, or false if property not found or type mismatch

int esp_mcp_property_list_get_property_int(const esp_mcp_property_list_t *list, const char *name)

Get an integer property value from a property list.

参数

  • list – [in] Pointer to the property list (must not be NULL)

  • name – [in] Property name (must not be NULL)

返回

Integer value, or 0 if property not found or type mismatch

float esp_mcp_property_list_get_property_float(const esp_mcp_property_list_t *list, const char *name)

Get a float property value from a property list.

参数

  • list – [in] Pointer to the property list (must not be NULL)

  • name – [in] Property name (must not be NULL)

返回

Float value, or 0.0 if property not found or type mismatch

const char *esp_mcp_property_list_get_property_array(const esp_mcp_property_list_t *list, const char *name)

Get a JSON array property value from a property list.

参数

  • list – [in] Pointer to the property list (must not be NULL)

  • name – [in] Property name (must not be NULL)

返回

Pointer to the JSON array string (internal pointer, do not free), or NULL if not found or type mismatch

const char *esp_mcp_property_list_get_property_object(const esp_mcp_property_list_t *list, const char *name)

Get a JSON object property value from a property list.

参数

  • list – [in] Pointer to the property list (must not be NULL)

  • name – [in] Property name (must not be NULL)

返回

Pointer to the JSON object string (internal pointer, do not free), or NULL if not found or type mismatch

const char *esp_mcp_property_list_get_property_string(const esp_mcp_property_list_t *list, const char *name)

Get a string property value from a property list.

参数

  • list – [in] Pointer to the property list (must not be NULL)

  • name – [in] Property name (must not be NULL)

返回

Pointer to the string value (internal pointer, do not free), or NULL if not found or type mismatch

Type Definitions

typedef enum esp_mcp_property_type_e esp_mcp_property_type_t

MCP property type enumeration.

Supported data types for MCP properties. Properties support boolean, integer, float, string, JSON array, and JSON object types.

typedef struct esp_mcp_property_s esp_mcp_property_t

MCP property structure.

Opaque structure representing a single MCP property with its name, type, and optional default value.

typedef struct esp_mcp_property_list_s esp_mcp_property_list_t

MCP property list structure.

Opaque structure representing a collection of MCP properties.

Enumerations

enum esp_mcp_property_type_e

MCP property type enumeration.

Supported data types for MCP properties. Properties support boolean, integer, float, string, JSON array, and JSON object types.

Values:

enumerator ESP_MCP_PROPERTY_TYPE_BOOLEAN

Boolean property type

enumerator ESP_MCP_PROPERTY_TYPE_INTEGER

Integer property type

enumerator ESP_MCP_PROPERTY_TYPE_FLOAT

Float property type

enumerator ESP_MCP_PROPERTY_TYPE_STRING

String property type

enumerator ESP_MCP_PROPERTY_TYPE_ARRAY

JSON array property type

enumerator ESP_MCP_PROPERTY_TYPE_OBJECT

JSON object property type

enumerator ESP_MCP_PROPERTY_TYPE_MAX

Maximum property type (reserved)

数据值接口

Header File

Functions

esp_mcp_value_t esp_mcp_value_create_bool(bool value)

Create a MCP value with a boolean value.

参数

value – [in] Boolean value to store

返回

MCP value structure with type ESP_MCP_VALUE_TYPE_BOOLEAN

esp_mcp_value_t esp_mcp_value_create_int(int value)

Create a MCP value with an integer value.

参数

value – [in] Integer value to store (signed 32-bit)

返回

MCP value structure with type ESP_MCP_VALUE_TYPE_INTEGER

esp_mcp_value_t esp_mcp_value_create_float(float value)

Create a MCP value with a float value.

参数

value – [in] Floating-point value to store (32-bit)

返回

MCP value structure with type ESP_MCP_VALUE_TYPE_FLOAT

esp_mcp_value_t esp_mcp_value_create_string(const char *value)

Create a MCP value with a string value.

Creates a copy of the input string. The string will be automatically freed when esp_mcp_value_destroy() is called.

备注

The input string is duplicated internally. The caller can safely free or modify the original string after this call.

备注

Always check if the returned type is ESP_MCP_VALUE_TYPE_INVALID before using.

参数

value – [in] Pointer to a null-terminated C string (must not be NULL)

返回

MCP value structure:

  • type ESP_MCP_VALUE_TYPE_STRING: Success

  • type ESP_MCP_VALUE_TYPE_INVALID: value is NULL or memory allocation failed

esp_err_t esp_mcp_value_destroy(esp_mcp_value_t *value)

Destroy a MCP value.

Releases all resources associated with the MCP value, including dynamically allocated string memory for STRING type values.

备注

After calling this function, the value structure should not be used again.

参数

value – [inout] Pointer to the MCP value structure to destroy (must not be NULL)

返回

  • ESP_OK: Value destroyed successfully

  • ESP_ERR_INVALID_ARG: Invalid parameter

Unions

union esp_mcp_value_data_t
#include <esp_mcp_data.h>

MCP value data union.

Union containing the actual data for MCP values. The active member is determined by the type field in the parent esp_mcp_value_t structure.

备注

Only access the member corresponding to the value type.

Public Members

bool bool_value

Boolean data value

int int_value

Integer data value (signed 32-bit)

float float_value

Floating-point data value (32-bit)

char *string_value

String data value (pointer to null-terminated C string)

Structures

struct esp_mcp_value_t

MCP value structure.

Complete MCP value with its type and associated data. Provides a unified way to handle different data types in the MCP protocol.

备注

The type field determines which member of the data union is valid.

备注

For STRING type, string_value points to dynamically allocated memory that will be freed by esp_mcp_value_destroy().

Public Members

esp_mcp_value_type_t type

Type of the value (boolean, integer, float, or string)

esp_mcp_value_data_t data

Union containing the actual value data

Enumerations

enum esp_mcp_value_type_t

MCP value type enumeration.

Supported data types for MCP values. Each type represents a different data representation that can be stored and transmitted.

Values:

enumerator ESP_MCP_VALUE_TYPE_INVALID

Invalid value (error state)

enumerator ESP_MCP_VALUE_TYPE_BOOLEAN

Boolean value

enumerator ESP_MCP_VALUE_TYPE_INTEGER

Integer value (signed 32-bit)

enumerator ESP_MCP_VALUE_TYPE_FLOAT

Floating-point value (32-bit)

enumerator ESP_MCP_VALUE_TYPE_STRING

String value (null-terminated)

提供有关此文档的反馈