feat(parity): fastmcpp 3.1.1 post-v3.1.0 parity sweep (F1-F9)

Squash of feature/parity-v3.1.0-post-sync (commit 6f5406c) onto main.
Implements the seven parity gaps identified in the post-v3.1.0 review
against Python fastmcp v3.1.0-89-g00ed31f2:

- F1 typed query-param coercion on resource templates (mirrors
  Python 9ccaef2b); ValidationError on invalid bool/int/number.
- F2 defensive read_fastmcp_metadata helper for _meta.fastmcp /
  _meta._fastmcp (mirrors 706b56d5). Not yet wired into any
  production path.
- F3 URI-template regex guard rethrowing as ValidationError
  (hardening on top of 5ff64ce2). Runtime path currently unreachable
  via any template string given escape_regex() design.
- F4 CatalogTransform::get_tool_catalog dedup with
  _meta.fastmcp.versions injection + Tool::meta()/set_meta()
  (mirrors 03673d9f + 0142fefe). New util/versions.hpp with
  dedupe_with_versions<T>().
- F5 preflight rename-collision detection in
  build_transformed_schema (mirrors d316f193).
- F6 mount + query-params: N/A under fastmcpp's direct-dispatch
  mount, locked by mount_query_params.cpp regression test.
- F7 FastMCP::add_custom_route / all_custom_routes +
  HttpServerWrapper::set_custom_routes (mirrors 68e76fea; ports
  the @server.custom_route API that didn't previously exist in
  fastmcpp).
- F8 manual-redirect policy comment in StreamableHttpTransport
  (mirrors 226bfb49).
- F9 version bump 3.1.0 -> 3.1.1.

Bonus: fixes pre-existing assertion bug in
tests/mcp/server_handler.cpp where the tools/list size assertion
lagged behind the audio_tool addition in upstream a817ecf.

Verification:
- Submodule ctest Release suite: 101/103 passing (2 pre-existing
  flakes fail identically on clean 9afa99f: fastmcpp_streaming_sse
  and fastmcpp_example_streaming_demo).
- Private monorepo interop (parent ports repo): 20/20 across
  F1/F2/F3/F4/F5/F7; stable over 5 back-to-back runs.

See kb/sync/review_of_parity_branch.md in the parent ports repo
for the full independent review.

Author: 0xeb

CMakeLists.txt

@@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 3.16)
 if(POLICY CMP0169)
   cmake_policy(SET CMP0169 OLD)
 endif()
-project(fastmcpp VERSION 3.1.0 LANGUAGES CXX)
+project(fastmcpp VERSION 3.1.1 LANGUAGES CXX)
 
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
@@ -284,6 +284,10 @@ if(FASTMCPP_BUILD_TESTS)
   target_link_libraries(fastmcpp_settings PRIVATE fastmcpp_core)
   add_test(NAME fastmcpp_settings COMMAND fastmcpp_settings)
 
+  add_executable(fastmcpp_util_metadata_parsing tests/util/metadata_parsing.cpp)
+  target_link_libraries(fastmcpp_util_metadata_parsing PRIVATE fastmcpp_core)
+  add_test(NAME fastmcpp_util_metadata_parsing COMMAND fastmcpp_util_metadata_parsing)
+
   add_executable(fastmcpp_stdio_server tests/transports/stdio_server.cpp)
   target_link_libraries(fastmcpp_stdio_server PRIVATE fastmcpp_core)
   add_test(NAME fastmcpp_stdio_server COMMAND fastmcpp_stdio_server)
@@ -318,6 +322,12 @@ if(FASTMCPP_BUILD_TESTS)
   target_link_libraries(fastmcpp_resources_templates PRIVATE fastmcpp_core)
   add_test(NAME fastmcpp_resources_templates COMMAND fastmcpp_resources_templates)
 
+  add_executable(fastmcpp_resources_template_query_params
+                 tests/resources/template_query_params.cpp)
+  target_link_libraries(fastmcpp_resources_template_query_params PRIVATE fastmcpp_core)
+  add_test(NAME fastmcpp_resources_template_query_params
+           COMMAND fastmcpp_resources_template_query_params)
+
   add_executable(fastmcpp_server_basic tests/server/basic.cpp)
   target_link_libraries(fastmcpp_server_basic PRIVATE fastmcpp_core)
   add_test(NAME fastmcpp_server_basic COMMAND fastmcpp_server_basic)
@@ -490,6 +500,15 @@ if(FASTMCPP_BUILD_TESTS)
   set_tests_properties(fastmcpp_stdio_timeout PROPERTIES TIMEOUT 60)
 
   # App mounting tests
+  add_executable(fastmcpp_app_mount_query_params tests/app/mount_query_params.cpp)
+  target_link_libraries(fastmcpp_app_mount_query_params PRIVATE fastmcpp_core)
+  add_test(NAME fastmcpp_app_mount_query_params COMMAND fastmcpp_app_mount_query_params)
+
+  add_executable(fastmcpp_app_custom_route_forwarding
+                 tests/app/custom_route_forwarding.cpp)
+  target_link_libraries(fastmcpp_app_custom_route_forwarding PRIVATE fastmcpp_core)
+  add_test(NAME fastmcpp_app_custom_route_forwarding COMMAND fastmcpp_app_custom_route_forwarding)
+
   add_executable(fastmcpp_app_mounting tests/app/mounting.cpp)
   target_link_libraries(fastmcpp_app_mounting PRIVATE fastmcpp_core)
   add_test(NAME fastmcpp_app_mounting COMMAND fastmcpp_app_mounting)
@@ -528,6 +547,10 @@ if(FASTMCPP_BUILD_TESTS)
   target_link_libraries(fastmcpp_provider_version_filter PRIVATE fastmcpp_core)
   add_test(NAME fastmcpp_provider_version_filter COMMAND fastmcpp_provider_version_filter)
 
+  add_executable(fastmcpp_provider_catalog_dedup tests/providers/catalog_dedup.cpp)
+  target_link_libraries(fastmcpp_provider_catalog_dedup PRIVATE fastmcpp_core)
+  add_test(NAME fastmcpp_provider_catalog_dedup COMMAND fastmcpp_provider_catalog_dedup)
+
   add_executable(fastmcpp_provider_catalog_search tests/providers/test_catalog_search_transforms.cpp)
   target_link_libraries(fastmcpp_provider_catalog_search PRIVATE fastmcpp_core)
   add_test(NAME fastmcpp_provider_catalog_search COMMAND fastmcpp_provider_catalog_search)

include/fastmcpp/app.hpp

@@ -8,6 +8,7 @@
 #include "fastmcpp/tools/manager.hpp"
 
 #include <chrono>
+#include <functional>
 #include <initializer_list>
 #include <memory>
 #include <optional>
@@ -23,6 +24,36 @@ namespace providers
 class Provider;
 } // namespace providers
 
+/// HTTP request snapshot passed to a custom-route handler.
+/// Kept transport-agnostic so HttpServerWrapper can populate it from
+/// cpp-httplib without leaking that dependency into app.hpp.
+struct CustomRouteRequest
+{
+    std::string method;
+    std::string path;
+    std::string body;
+    std::unordered_map<std::string, std::string> headers;
+};
+
+/// HTTP response returned by a custom-route handler.
+struct CustomRouteResponse
+{
+    int status{200};
+    std::string body;
+    std::string content_type{"text/plain"};
+    std::unordered_map<std::string, std::string> headers;
+};
+
+/// User-registered HTTP endpoint outside the JSON-RPC core.
+/// Parity intent with Python fastmcp `@server.custom_route()` (commit 68e76fea
+/// fixed forwarding from mounted servers).
+struct CustomRoute
+{
+    std::string method;            // GET, POST, etc. (uppercase)
+    std::string path;              // Absolute path, e.g. "/health" — must start with '/'
+    std::function<CustomRouteResponse(const CustomRouteRequest&)> handler;
+};
+
 /// Mounted app reference with prefix (direct mode)
 struct MountedApp
 {
@@ -276,6 +307,23 @@ class FastMCP
         return proxy_mounted_;
     }
 
+    /// Register a custom HTTP route handled outside the JSON-RPC core.
+    /// Parity with Python fastmcp `@server.custom_route()`. Re-registering the
+    /// same (method, path) replaces the previous handler.
+    FastMCP& add_custom_route(CustomRoute route);
+
+    /// Get this app's directly registered custom routes (no mount prefixes).
+    const std::vector<CustomRoute>& custom_routes() const
+    {
+        return custom_routes_;
+    }
+
+    /// Aggregate this app's custom routes plus those of every directly mounted
+    /// child app (paths are prefixed with the mount prefix). Parity with Python
+    /// fastmcp commit 68e76fea (forward custom_route endpoints from mounted
+    /// servers).
+    std::vector<CustomRoute> all_custom_routes() const;
+
     void add_provider(std::shared_ptr<providers::Provider> provider);
     const std::vector<std::shared_ptr<providers::Provider>>& providers() const
     {
@@ -328,6 +376,7 @@ class FastMCP
     std::vector<std::shared_ptr<providers::Provider>> providers_;
     std::vector<MountedApp> mounted_;
     std::vector<ProxyMountedApp> proxy_mounted_;
+    std::vector<CustomRoute> custom_routes_;
     mutable std::vector<tools::Tool> provider_tools_cache_;
     mutable std::vector<prompts::Prompt> provider_prompts_cache_;
     int list_page_size_{0};

include/fastmcpp/providers/transforms/catalog.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "fastmcpp/providers/transforms/transform.hpp"
+#include "fastmcpp/util/versions.hpp"
 
 #include <atomic>
 
@@ -87,10 +88,39 @@ class CatalogTransform : public Transform
     // ---- Catalog accessors (bypass this transform) ----
 
     /// Fetch the real tool catalog, bypassing this transform's transform_tools.
+    ///
+    /// Tools sharing a name are deduplicated by version: only the highest
+    /// version survives. When more than one concrete version was present,
+    /// the surviving Tool's `meta()` is augmented with
+    /// `{"fastmcp": {"versions": [...]}}` listing all available versions in
+    /// descending order. Parity with Python fastmcp commit 03673d9f.
     std::vector<tools::Tool> get_tool_catalog(const ListToolsNext& call_next) const
     {
         BypassGuard guard(bypass_);
-        return call_next();
+        auto raw = call_next();
+
+        auto deduped = util::versions::dedupe_with_versions(
+            raw, [](const tools::Tool& t) { return t.name(); },
+            [](const tools::Tool& t) { return t.version(); });
+
+        std::vector<tools::Tool> result;
+        result.reserve(deduped.size());
+        for (auto& entry : deduped)
+        {
+            if (!entry.available_versions.empty())
+            {
+                fastmcpp::Json meta =
+                    entry.item.meta().has_value() ? *entry.item.meta() : fastmcpp::Json::object();
+                fastmcpp::Json fm = meta.contains("fastmcp") && meta["fastmcp"].is_object()
+                                        ? meta["fastmcp"]
+                                        : fastmcpp::Json::object();
+                fm["versions"] = entry.available_versions;
+                meta["fastmcp"] = std::move(fm);
+                entry.item.set_meta(std::move(meta));
+            }
+            result.push_back(std::move(entry.item));
+        }
+        return result;
     }
 
     std::vector<resources::Resource>

include/fastmcpp/resources/manager.hpp

@@ -68,10 +68,11 @@ class ResourceManager
             auto match_params = templ.match(uri);
             if (match_params)
             {
-                // Merge explicit params with matched params (explicit takes precedence)
-                Json merged_params = Json::object();
-                for (const auto& [key, value] : *match_params)
-                    merged_params[key] = value;
+                // Merge explicit params with matched params (explicit takes precedence).
+                // Matched values are string-typed; coerce them per-param against the
+                // template's parameter schema. Parity with Python fastmcp 9ccaef2b:
+                // invalid booleans / numbers raise ValidationError.
+                Json merged_params = templ.build_typed_params(*match_params);
                 for (const auto& [key, value] : params.items())
                     merged_params[key] = value;
 

include/fastmcpp/resources/template.hpp

@@ -12,12 +12,26 @@
 namespace fastmcpp::resources
 {
 
+/// Type annotation for a URI template parameter.
+///
+/// When a parameter's kind is anything other than String, matched values go
+/// through typed coercion (see build_typed_params()). Invalid literals raise
+/// fastmcpp::ValidationError — parity with Python fastmcp commit 9ccaef2b.
+enum class ParamKind
+{
+    String,
+    Integer,
+    Number,
+    Boolean
+};
+
 /// Parameter extracted from URI template
 struct TemplateParameter
 {
     std::string name;
-    bool is_wildcard{false}; // {var*} vs {var}
-    bool is_query{false};    // {?var} query param
+    bool is_wildcard{false};        // {var*} vs {var}
+    bool is_query{false};           // {?var} query param
+    ParamKind kind{ParamKind::String};
 };
 
 /// MCP Resource Template definition
@@ -56,6 +70,12 @@ struct ResourceTemplate
     /// Create a resource from the template with given parameters
     Resource create_resource(const std::string& uri,
                              const std::unordered_map<std::string, std::string>& params) const;
+
+    /// Build a typed JSON object from a raw string -> string parameter map,
+    /// coercing each value using the per-parameter kind populated by parse().
+    /// Parity with Python fastmcp commit 9ccaef2b — invalid booleans / numbers
+    /// raise fastmcpp::ValidationError instead of silently passing through.
+    Json build_typed_params(const std::unordered_map<std::string, std::string>& raw) const;
 };
 
 /// Extract path parameters from URI template: {var}, {var*}
@@ -73,4 +93,10 @@ std::string url_decode(const std::string& encoded);
 /// URL-encode a string
 std::string url_encode(const std::string& decoded);
 
+/// Coerce a string query-/path-param value into a typed JSON value according to kind.
+/// Throws fastmcpp::ValidationError when the value does not match the declared kind
+/// (e.g., kind == Boolean but the string is "banana").
+/// String kind is a pass-through (returns Json(value)).
+Json coerce_param_value(const std::string& value, ParamKind kind, const std::string& param_name);
+
 } // namespace fastmcpp::resources

include/fastmcpp/server/http_server.hpp

@@ -2,17 +2,24 @@
 #include "fastmcpp/server/server.hpp"
 
 #include <atomic>
+#include <functional>
 #include <memory>
 #include <string>
 #include <thread>
 #include <unordered_map>
+#include <vector>
 
 namespace httplib
 {
 class Server;
 class Response;
 }
 
+namespace fastmcpp
+{
+struct CustomRoute;
+}
+
 namespace fastmcpp::server
 {
 
@@ -36,6 +43,12 @@ class HttpServerWrapper
                       std::unordered_map<std::string, std::string> response_headers = {});
     ~HttpServerWrapper();
 
+    /// Register a custom HTTP route (e.g. `/health`) handled before the
+    /// catch-all JSON-RPC POST. Must be called before start(); routes
+    /// registered after start() take effect on the next start() call. Parity
+    /// hook for Python `FastMCP.custom_route()` aggregation (commit 68e76fea).
+    void set_custom_routes(std::vector<fastmcpp::CustomRoute> routes);
+
     bool start();
     void stop();
     bool running() const
@@ -69,6 +82,7 @@ class HttpServerWrapper
     std::atomic<int> bound_port_ = 0;
     std::string auth_token_; // Optional Bearer token for authentication
     std::unordered_map<std::string, std::string> response_headers_;
+    std::vector<fastmcpp::CustomRoute> custom_routes_;
     std::unique_ptr<httplib::Server> svr_;
     std::thread thread_;
     std::atomic<bool> running_{false};

include/fastmcpp/tools/tool.hpp

@@ -199,6 +199,20 @@ class Tool
         return *this;
     }
 
+    /// Free-form metadata attached to this tool — surfaces in MCP `_meta`
+    /// when a caller chooses to serialize it. Used by CatalogTransform to
+    /// publish `meta.fastmcp.versions` under the dedup contract (Python
+    /// fastmcp commit 03673d9f).
+    const std::optional<fastmcpp::Json>& meta() const
+    {
+        return meta_;
+    }
+    Tool& set_meta(fastmcpp::Json meta)
+    {
+        meta_ = std::move(meta);
+        return *this;
+    }
+
   private:
     static std::string format_timeout_seconds(std::chrono::milliseconds timeout)
     {
@@ -262,6 +276,7 @@ class Tool
     std::optional<fastmcpp::Json> annotations_;
     std::optional<fastmcpp::AppConfig> app_;
     std::optional<std::string> version_;
+    std::optional<fastmcpp::Json> meta_;
 };
 
 } // namespace fastmcpp::tools

include/fastmcpp/tools/tool_transform.hpp

@@ -7,6 +7,7 @@
 /// - TransformedTool: Creates a new Tool by transforming another
 /// - Schema transformation utilities
 
+#include "fastmcpp/exceptions.hpp"
 #include "fastmcpp/tools/tool.hpp"
 #include "fastmcpp/types.hpp"
 
@@ -64,6 +65,11 @@ struct TransformResult
 };
 
 /// Build a transformed schema from parent schema and transforms
+///
+/// Throws fastmcpp::ValidationError if the requested transforms would map two
+/// distinct parent arguments to the same effective name (rename collides with
+/// either another rename or an untouched passthrough param). Parity with
+/// Python fastmcp commit d316f193.
 inline TransformResult
 build_transformed_schema(const Json& parent_schema,
                          const std::unordered_map<std::string, ArgTransform>& transform_args)
@@ -82,6 +88,33 @@ build_transformed_schema(const Json& parent_schema,
                 required_set.insert(r.get<std::string>());
     }
 
+    // Pre-flight: detect effective-name collisions across the FULL parent
+    // param set (renames + passthroughs). Walk parent params in the same order
+    // so the error message names the first colliding pair deterministically.
+    {
+        std::unordered_map<std::string, std::string> seen_owner; // effective_name -> parent_name
+        for (auto& [old_name, _prop] : properties.items())
+        {
+            auto it = transform_args.find(old_name);
+            if (it != transform_args.end() && it->second.hide)
+                continue; // hidden args do not occupy an effective slot
+
+            std::string effective =
+                (it != transform_args.end() && it->second.name.has_value())
+                    ? *it->second.name
+                    : old_name;
+
+            auto inserted = seen_owner.emplace(effective, old_name);
+            if (!inserted.second)
+            {
+                throw fastmcpp::ValidationError(
+                    "Multiple arguments would be mapped to the same name: '" + effective +
+                    "' (from parent params '" + inserted.first->second + "' and '" + old_name +
+                    "')");
+            }
+        }
+    }
+
     // Process transforms
     Json new_properties = Json::object();
     std::unordered_set<std::string> new_required;