Fix/mcp tool discovery flow

[simongdavies]

This pull request introduces significant improvements to the MCP (Model Context Protocol) integration, focusing on safer, more discoverable, and auditable external tool usage. The changes refine the workflow for accessing MCP tools, add a new mcp_tool_info tool for focused schema lookup, and enhance command extraction and error handling throughout the agent. Documentation and code now guide users to always discover tool schemas before usage, and handler code receives more robust, structured results.

Key changes:

MCP Tool Usage Workflow & Documentation

• Updated the recommended workflow in SKILL.md to require using the new mcp_tool_info tool for focused tool/schema discovery before writing handler code, discouraging direct tool invocation from LLM tools and emphasizing handler-based execution for auditability. The documentation now details best practices, error handling, and response envelopes for MCP tool calls.

New and Enhanced MCP Tools

• Added a new mcp_tool_info tool to the agent, allowing users to query for specific tool schemas on a server using tool names or natural language queries, returning only relevant schemas and TypeScript declarations. This tool is now included in the allowed tools and recommended workflow.
• Enhanced mcp_server_info to support filtering tools by name, query, or limit, and to recommend using mcp_tool_info for focused schema lookup.

Improved Tool Call Results and Error Handling

• Standardized MCP tool call results to return a structured envelope (ok, data, text, raw, meta, error, truncated), ensuring handler code can reliably check for errors and parse results.
• Updated documentation and handler code examples to reflect the new result envelope and error handling requirements.

Command Extraction Robustness

• Improved the logic for extracting actionable commands from assistant responses, handling commands wrapped in various markdown formats (backticks, bold, etc.), and cleaning up extraneous formatting.

CLI and Miscellaneous Updates

• Added the mcp-network profile to the CLI options and documentation, clarifying its use for extending wall-clock time during MCP handler execution.

These changes together make MCP tool usage more robust, discoverable, and secure, while improving the developer and user experience.

[Copilot]

Pull request overview

This PR refines HyperAgent’s MCP (Model Context Protocol) integration to make external tool usage more discoverable and safer, by adding focused tool/schema discovery (mcp_tool_info), improving MCP tool result normalization, and introducing a dedicated execution profile for MCP network latency.

Changes:

• Added mcp_tool_info (and enhanced mcp_server_info filtering) to support focused schema discovery before writing handler code.
• Standardized MCP tool-call results into an { ok, data, text, raw, meta, error, truncated } envelope and updated guidance/tests accordingly.
• Introduced the mcp-network profile (longer wall timeout, no plugins) and updated CLI/docs/tests to include it.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/profiles.test.ts	Updates expectations for the new mcp-network profile and profile count/stacking behavior.
tests/mcp.test.ts	Adds tests for MCP tool selection/read-only inference helpers and tool result normalization.
tests/command-suggestions.test.ts	Adds coverage for extracting markdown-bold suggested commands.
src/agent/tool-gating.ts	Allows the new mcp_tool_info tool through the tool gate.
src/agent/system-message.ts	Updates system guidance for MCP “handler-only” workflow and tool discovery.
src/agent/profiles.ts	Adds the mcp-network resource profile (wall-time bump without plugins).
src/agent/mcp/tool-utils.ts	New helper utilities for tool lookup, selection, scoring, and read-only inference.
src/agent/mcp/plugin-adapter.ts	Uses read-only inference for the write-safety gate; updates MCP hints/declarations to async.
src/agent/mcp/client-manager.ts	Introduces the MCP result envelope and normalization logic for tool calls.
src/agent/index.ts	Enhances mcp_server_info, adds mcp_tool_info, and wires it into the session tool list.
src/agent/command-suggestions.ts	Improves command extraction robustness (bold markdown + cleaning).
src/agent/cli-parser.ts	Documents the new mcp-network profile in CLI help text.
skills/mcp-services/SKILL.md	Updates the recommended MCP workflow to use mcp_tool_info, handler-only execution, and mcp-network.