Add RegisterTools API to McpClient for pre-populating tool cache (#1590)

Co-authored-by: Tarek Mahmoud Sayed <tarekms@ntdev.microsoft.com>

src/ModelContextProtocol.Core/Client/McpClient.cs

@@ -70,4 +70,84 @@ public abstract partial class McpClient : McpSession
     /// </para>
     /// </remarks>
     public abstract Task<ClientCompletionDetails> Completion { get; }
+
+    /// <summary>
+    /// Registers one or more tool definitions in the client's tool cache, enabling the transport
+    /// to send <c>Mcp-Param-*</c> headers for those tools without requiring a prior <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/> call.
+    /// </summary>
+    /// <param name="tools">The tool definitions to register.</param>
+    /// <remarks>
+    /// <para>
+    /// This method allows callers who already have tool schema information (e.g., from a previous session,
+    /// hardcoded configuration, or an out-of-band source) to provide it directly to the client. Once registered,
+    /// any <see cref="McpClient.CallToolAsync(string, IReadOnlyDictionary{string, object?}?, IProgress{ProgressNotificationValue}?, RequestOptions?, CancellationToken)"/>
+    /// call for a registered tool will automatically include <c>Mcp-Param-*</c> HTTP headers based on
+    /// the tool's <c>x-mcp-header</c> schema annotations, exactly as if the tool had been discovered
+    /// via <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/>.
+    /// </para>
+    /// <para>
+    /// <b>Cache interaction behavior:</b>
+    /// <list type="bullet">
+    ///   <item>Registered tools are added to the same internal tool cache used by <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/>.</item>
+    ///   <item>Calling <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/> after <see cref="AddKnownTools"/> preserves
+    ///     manually registered tools — only server-discovered tools are cleared and repopulated.</item>
+    ///   <item>If the server returns a tool with the same name as a manually registered tool, the server's
+    ///     definition overwrites the registered one in the cache, but the tool retains its known status
+    ///     and will survive subsequent cache clears. This registration is sticky for the lifetime of the
+    ///     <see cref="McpClient"/>; use <see cref="RemoveKnownTools"/> or <see cref="ClearKnownTools"/> to
+    ///     explicitly drop known tools that are no longer needed.</item>
+    ///   <item>Tools can be registered at any time — before or after <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/>,
+    ///     and across multiple calls.</item>
+    ///   <item>Re-registering a tool with the same name overwrites the previous definition in the cache (last write wins).</item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// Tools with invalid <c>x-mcp-header</c> annotations cause an <see cref="ArgumentException"/> to be thrown.
+    /// No tools are added to the cache if any tool in the batch fails validation (all-or-nothing).
+    /// </para>
+    /// </remarks>
+    /// <exception cref="ArgumentNullException"><paramref name="tools"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException">One or more tools have invalid <c>x-mcp-header</c> annotations.</exception>
+    public virtual void AddKnownTools(IEnumerable<Tool> tools)
+    {
+        Throw.IfNull(tools);
+        throw new NotSupportedException($"{GetType().Name} does not support adding known tools.");
+    }
+
+    /// <summary>
+    /// Removes one or more previously registered tool definitions from the client's tool cache by name.
+    /// </summary>
+    /// <param name="toolNames">The names of the tools to remove.</param>
+    /// <remarks>
+    /// <para>
+    /// This removes the specified tools from both the known-tools set and the internal tool cache.
+    /// After removal, those tools will no longer survive <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/>
+    /// cache clears, and <c>Mcp-Param-*</c> headers will no longer be sent for them unless the server
+    /// re-discovers them via <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/>.
+    /// </para>
+    /// <para>
+    /// Removing a tool name that was not previously added via <see cref="AddKnownTools"/> is a no-op.
+    /// </para>
+    /// </remarks>
+    /// <exception cref="ArgumentNullException"><paramref name="toolNames"/> is <see langword="null"/>.</exception>
+    public virtual void RemoveKnownTools(IEnumerable<string> toolNames)
+    {
+        Throw.IfNull(toolNames);
+        throw new NotSupportedException($"{GetType().Name} does not support removing known tools.");
+    }
+
+    /// <summary>
+    /// Removes all previously registered tool definitions from the client's tool cache.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This clears all tools that were added via <see cref="AddKnownTools"/> from both the known-tools
+    /// set and the internal tool cache. Server-discovered tools that are not also known tools are not affected
+    /// and will remain in the cache until the next <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/> call.
+    /// </para>
+    /// </remarks>
+    public virtual void ClearKnownTools()
+    {
+        throw new NotSupportedException($"{GetType().Name} does not support clearing known tools.");
+    }
 }