类class io.agentscope.core.tool.mcp 2.x

McpTool

public class McpTool extends ToolBase

源码Source io/agentscope/core/tool/mcp/McpTool.java:51–409

MCP 工具，封装可被智能体调用的能力。位于 io.agentscope.core.tool.mcp 包，继承自 ToolBase。核心成员包括 getOutputSchema、checkPermissions、callAsync、isPropagateMeta、setPropagateMeta、getClientName。

ToolBase subclass that wraps an MCP (Model Context Protocol) tool.

Bridges remote MCP tools to the AgentScope tool system so they participate in permission evaluation and the agent's pending-confirmation flow alongside built-in and @Tool tools.

Features:

Translates AgentScope tool calls into MCP protocol calls.
Merges caller arguments with preset arguments configured at registration time.
Converts MCP results into AgentScope ToolResultBlocks.
Surfaces permission policy via #checkPermissions(Map, PermissionContextState): read-only MCP tools auto-allow; everything else requires explicit user authorization (matches the Python MCPTool default).

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `McpTool(String name, String description, Map<String, Object> parameters, Map<String, Object> outputSchema, McpClientWrapper clientWrapper, Map<String, Object> presetArguments, String mcpName, boolean readOnly)`	初始化 `McpTool` 实例。 Preferred constructor used by `io.agentscope.core.tool.McpClientManager`.
`public` `McpTool(String name, String remoteToolName, String description, Map<String, Object> parameters, Map<String, Object> outputSchema, McpClientWrapper clientWrapper, Map<String, Object> presetArguments, String mcpName, boolean readOnly)`	初始化 `McpTool` 实例。 Registers a namespaced model-facing name while calling the original MCP tool name.
`public` `McpTool(String name, String description, Map<String, Object> parameters, McpClientWrapper clientWrapper)` deprecated	初始化 `McpTool` 实例。 Creates a new instance.
`public` `McpTool(String name, String description, Map<String, Object> parameters, McpClientWrapper clientWrapper, Map<String, Object> presetArguments)` deprecated	初始化 `McpTool` 实例。 Creates a new instance.
`public` `McpTool(String name, String description, Map<String, Object> parameters, Map<String, Object> outputSchema, McpClientWrapper clientWrapper, Map<String, Object> presetArguments)` deprecated	初始化 `McpTool` 实例。 Creates a new instance.

方法摘要Method Summary

方法Method	说明Description
`public Map<String, Object> getOutputSchema()`	获取输出模式。 Returns the output schema.
`public Mono<PermissionDecision> checkPermissions(Map<String, Object> toolInput, PermissionContextState context)`	检查权限。 Performs the check permissions operation.
`public Mono<ToolResultBlock> callAsync(ToolCallParam param)`	调用异步。 Executes this MCP tool asynchronously with the given parameters.
`public boolean isPropagateMeta()`	判断是否 `isPropagateMeta`。 Checks whether this tool allows request metadata propagation.
`public void setPropagateMeta(boolean propagateMeta)`	设置 `setPropagateMeta`。 Configures whether this tool allows request metadata propagation.
`public String getClientName()`	获取客户端名称。 Gets the name of the MCP client that provides this tool.
`public Map<String, Object> getPresetArguments()`	获取 `getPresetArguments`。 Gets the preset arguments configured for this tool.
`public static Map<String, Object> convertMcpSchemaToParameters(McpSchema.JsonSchema inputSchema, Set<String> excludeParams)` static	转换MCP JsonSchema 到 AgentScope 参数格式。 Converts MCP JsonSchema to AgentScope parameters format.

构造器详情Constructor Detail

McpTool

public McpTool(String name, String description, Map<String, Object> parameters, Map<String, Object> outputSchema, McpClientWrapper clientWrapper, Map<String, Object> presetArguments, String mcpName, boolean readOnly)

初始化 McpTool 实例。

Preferred constructor used by io.agentscope.core.tool.McpClientManager.

参数Parameters

名称Name	类型Type	说明Description
`name`	String	名称（类型 `String`）。The name.
`description`	String	描述（类型 `String`）。The description.
`parameters`	Map<String, Object>	参数（类型 `Map`）。The parameters.
`outputSchema`	Map<String, Object>	输出模式（类型 `Map`）。The output schema.
`clientWrapper`	McpClientWrapper	客户端包装器（类型 `McpClientWrapper`）。The client wrapper.
`presetArguments`	Map<String, Object>	preset 参数（类型 `Map`）。The preset arguments.
`mcpName`	String	MCP 名称（类型 `String`）。The mcp name.
`readOnly`	boolean	读取 Only（类型 `boolean`）。The read only.

源码Source io/agentscope/core/tool/mcp/McpTool.java:76–95

McpTool

public McpTool(String name, String remoteToolName, String description, Map<String, Object> parameters, Map<String, Object> outputSchema, McpClientWrapper clientWrapper, Map<String, Object> presetArguments, String mcpName, boolean readOnly)

初始化 McpTool 实例。

Registers a namespaced model-facing name while calling the original MCP tool name.

参数Parameters

名称Name	类型Type	说明Description
`name`	String	名称（类型 `String`）。The name.
`remoteToolName`	String	远程工具名称（类型 `String`）。The remote tool name.
`description`	String	描述（类型 `String`）。The description.
`parameters`	Map<String, Object>	参数（类型 `Map`）。The parameters.
`outputSchema`	Map<String, Object>	输出模式（类型 `Map`）。The output schema.
`clientWrapper`	McpClientWrapper	客户端包装器（类型 `McpClientWrapper`）。The client wrapper.
`presetArguments`	Map<String, Object>	preset 参数（类型 `Map`）。The preset arguments.
`mcpName`	String	MCP 名称（类型 `String`）。The mcp name.
`readOnly`	boolean	读取 Only（类型 `boolean`）。The read only.

源码Source io/agentscope/core/tool/mcp/McpTool.java:98–120

McpTool

public McpTool(String name, String description, Map<String, Object> parameters, McpClientWrapper clientWrapper)

deprecated

初始化 McpTool 实例。

Creates a new instance.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。Use `#McpTool(String, String, Map, Map, McpClientWrapper, Map, String, boolean)` so the MCP server name and read-only hint are propagated. Kept for source compatibility with callers that pre-date the `ToolBase` integration.

参数Parameters

名称Name	类型Type	说明Description
`name`	String	名称（类型 `String`）。The name.
`description`	String	描述（类型 `String`）。The description.
`parameters`	Map<String, Object>	参数（类型 `Map`）。The parameters.
`clientWrapper`	McpClientWrapper	客户端包装器（类型 `McpClientWrapper`）。The client wrapper.

源码Source io/agentscope/core/tool/mcp/McpTool.java:127–142

McpTool

public McpTool(String name, String description, Map<String, Object> parameters, McpClientWrapper clientWrapper, Map<String, Object> presetArguments)

deprecated

初始化 McpTool 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`name`	String	名称（类型 `String`）。The name.
`description`	String	描述（类型 `String`）。The description.
`parameters`	Map<String, Object>	参数（类型 `Map`）。The parameters.
`clientWrapper`	McpClientWrapper	客户端包装器（类型 `McpClientWrapper`）。The client wrapper.
`presetArguments`	Map<String, Object>	preset 参数（类型 `Map`）。The preset arguments.

源码Source io/agentscope/core/tool/mcp/McpTool.java:148–164

McpTool

public McpTool(String name, String description, Map<String, Object> parameters, Map<String, Object> outputSchema, McpClientWrapper clientWrapper, Map<String, Object> presetArguments)

deprecated

初始化 McpTool 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`name`	String	名称（类型 `String`）。The name.
`description`	String	描述（类型 `String`）。The description.
`parameters`	Map<String, Object>	参数（类型 `Map`）。The parameters.
`outputSchema`	Map<String, Object>	输出模式（类型 `Map`）。The output schema.
`clientWrapper`	McpClientWrapper	客户端包装器（类型 `McpClientWrapper`）。The client wrapper.
`presetArguments`	Map<String, Object>	preset 参数（类型 `Map`）。The preset arguments.

源码Source io/agentscope/core/tool/mcp/McpTool.java:170–187

方法详情Method Detail

getOutputSchema

public Map<String, Object> getOutputSchema()

获取输出模式。

Returns the output schema.

返回Returns Map<String, Object>

返回映射。Returns map.

源码Source io/agentscope/core/tool/mcp/McpTool.java:189–192

checkPermissions

public Mono<PermissionDecision> checkPermissions(Map<String, Object> toolInput, PermissionContextState context)

检查权限。

Performs the check permissions operation.

参数Parameters

名称Name	类型Type	说明Description
`toolInput`	Map<String, Object>	工具输入（类型 `Map`）。The tool input.
`context`	PermissionContextState	上下文（类型 `PermissionContextState`）。The context.

返回Returns Mono<PermissionDecision>

返回Mono。Returns mono.

源码Source io/agentscope/core/tool/mcp/McpTool.java:194–207

callAsync

public Mono<ToolResultBlock> callAsync(ToolCallParam param)

调用异步。

Executes this MCP tool asynchronously with the given parameters.

参数Parameters

名称Name	类型Type	说明Description
`param`	ToolCallParam	参数（类型 `ToolCallParam`）。The tool call parameters containing toolUseBlock, input, and agent

返回Returns Mono<ToolResultBlock>

返回Mono。a Mono that emits the tool result when the MCP call completes

源码Source io/agentscope/core/tool/mcp/McpTool.java:224–253

isPropagateMeta

public boolean isPropagateMeta()

判断是否 isPropagateMeta。

Checks whether this tool allows request metadata propagation.

返回Returns boolean

返回布尔值，表示判断结果。true if this tool permits user `McpMeta` entries and the tool-call id to be included in tool call requests, false otherwise

源码Source io/agentscope/core/tool/mcp/McpTool.java:264–266

setPropagateMeta

public void setPropagateMeta(boolean propagateMeta)

设置 setPropagateMeta。

Configures whether this tool allows request metadata propagation.

参数Parameters

名称Name	类型Type	说明Description
`propagateMeta`	boolean	propagate 元数据（类型 `boolean`）。true to allow metadata propagation for this tool (default), false to omit the `meta` field entirely from this tool's requests

源码Source io/agentscope/core/tool/mcp/McpTool.java:279–281

getClientName

public String getClientName()

获取客户端名称。

Gets the name of the MCP client that provides this tool.

返回Returns String

MCP 客户端名称。the MCP client name

源码Source io/agentscope/core/tool/mcp/McpTool.java:288–290

getPresetArguments

public Map<String, Object> getPresetArguments()

获取 getPresetArguments。

Gets the preset arguments configured for this tool.

返回Returns Map<String, Object>

返回映射。the preset arguments, or null if none configured

源码Source io/agentscope/core/tool/mcp/McpTool.java:297–299

convertMcpSchemaToParameters

public static Map<String, Object> convertMcpSchemaToParameters(McpSchema.JsonSchema inputSchema, Set<String> excludeParams)

static

转换MCP JsonSchema 到 AgentScope 参数格式。

Converts MCP JsonSchema to AgentScope parameters format.

参数Parameters

名称Name	类型Type	说明Description
`inputSchema`	McpSchema.JsonSchema	输入模式（类型 `McpSchema.JsonSchema`）。the MCP JsonSchema
`excludeParams`	Set<String>	exclude 参数（类型 `Set`）。The exclude params.

返回Returns Map<String, Object>

返回映射。parameters map in AgentScope format

源码Source io/agentscope/core/tool/mcp/McpTool.java:365–408

继承成员Inherited Members

继承自Members inherited from ToolBase

getName, getDescription, getParameters, isConcurrencySafe, isReadOnly, isReturnDirect, isExternalTool, isStateInjected, isMcp, getMcpName, matchRule, generateSuggestions, isDangerousPath, builder, dangerousFiles, dangerousDirectories

继承自Methods inherited from AgentTool

getStrict