Merge pull request #34 from 0xeb/feature/instructions

Restore constructor backward compatibility for instructions

Author: 0xeb

CMakeLists.txt

@@ -268,6 +268,10 @@ if(FASTMCPP_BUILD_TESTS)
   target_link_libraries(fastmcpp_mcp_handler PRIVATE fastmcpp_core)
   add_test(NAME fastmcpp_mcp_handler COMMAND fastmcpp_mcp_handler)
 
+  add_executable(fastmcpp_mcp_instructions tests/mcp/test_instructions.cpp)
+  target_link_libraries(fastmcpp_mcp_instructions PRIVATE fastmcpp_core)
+  add_test(NAME fastmcpp_mcp_instructions COMMAND fastmcpp_mcp_instructions)
+
   add_executable(fastmcpp_mcp_server_handler tests/mcp/server_handler.cpp)
   target_link_libraries(fastmcpp_mcp_server_handler PRIVATE fastmcpp_core)
   add_test(NAME fastmcpp_mcp_server_handler COMMAND fastmcpp_mcp_server_handler)
@@ -446,6 +450,13 @@ if(FASTMCPP_BUILD_TESTS)
   target_link_libraries(fastmcpp_stdio_client PRIVATE fastmcpp_core)
   add_test(NAME fastmcpp_stdio_client COMMAND fastmcpp_stdio_client)
 
+  add_executable(fastmcpp_stdio_instructions_e2e tests/transports/stdio_instructions_e2e.cpp)
+  target_link_libraries(fastmcpp_stdio_instructions_e2e PRIVATE fastmcpp_core)
+  add_test(NAME fastmcpp_stdio_instructions_e2e COMMAND fastmcpp_stdio_instructions_e2e)
+  set_tests_properties(fastmcpp_stdio_instructions_e2e PROPERTIES
+    WORKING_DIRECTORY "$<TARGET_FILE_DIR:fastmcpp_stdio_instructions_e2e>"
+  )
+
   add_executable(fastmcpp_stdio_failure tests/transports/stdio_failure.cpp)
   target_link_libraries(fastmcpp_stdio_failure PRIVATE fastmcpp_core)
   add_test(NAME fastmcpp_stdio_failure COMMAND fastmcpp_stdio_failure)
@@ -567,6 +578,12 @@ if(FASTMCPP_BUILD_TESTS)
     target_link_libraries(fastmcpp_example_stdio_mcp_server PRIVATE fastmcpp_core)
   endif()
 
+  # Stdio server with instructions for E2E test
+  if(NOT TARGET fastmcpp_example_stdio_instructions_server)
+    add_executable(fastmcpp_example_stdio_instructions_server examples/stdio_instructions_server.cpp)
+    target_link_libraries(fastmcpp_example_stdio_instructions_server PRIVATE fastmcpp_core)
+  endif()
+
   option(FASTMCPP_ENABLE_STREAMING_TESTS "Enable streaming SSE tests (experimental)" OFF)
   if(FASTMCPP_ENABLE_STREAMING_TESTS)
     add_executable(fastmcpp_streaming_sse tests/server/streaming_sse.cpp)
@@ -624,6 +641,10 @@ if(FASTMCPP_BUILD_EXAMPLES)
   add_executable(fastmcpp_example_mcp_apps examples/mcp_apps.cpp)
   target_link_libraries(fastmcpp_example_mcp_apps PRIVATE fastmcpp_core)
 
+  # Instructions HTTP server (E2E test target)
+  add_executable(fastmcpp_example_instructions_server examples/instructions_server.cpp)
+  target_link_libraries(fastmcpp_example_instructions_server PRIVATE fastmcpp_core)
+
   # Skills provider example
   add_executable(fastmcpp_example_skills_provider examples/skills_provider.cpp)
   target_link_libraries(fastmcpp_example_skills_provider PRIVATE fastmcpp_core)

examples/instructions_server.cpp

@@ -0,0 +1,74 @@
+// instructions_server.cpp
+// Minimal FastMCP HTTP/SSE server with instructions field set.
+// Used by test_mcp_instructions_e2e.py for cross-implementation E2E validation.
+
+#include "fastmcpp/app.hpp"
+#include "fastmcpp/mcp/handler.hpp"
+#include "fastmcpp/server/sse_server.hpp"
+
+#include <atomic>
+#include <chrono>
+#include <csignal>
+#include <iostream>
+#include <string>
+#include <thread>
+
+using fastmcpp::FastMCP;
+using fastmcpp::Json;
+using fastmcpp::server::SseServerWrapper;
+
+static std::atomic<bool> g_running{true};
+
+static void signal_handler(int)
+{
+    g_running = false;
+}
+
+int main(int argc, char* argv[])
+{
+    std::signal(SIGINT, signal_handler);
+    std::signal(SIGTERM, signal_handler);
+
+    int port = 8082;
+    for (int i = 1; i < argc; ++i)
+    {
+        std::string arg = argv[i];
+        if ((arg == "--port" || arg == "-p") && i + 1 < argc)
+            port = std::stoi(argv[++i]);
+    }
+
+    FastMCP app("instructions_http_server", "2.0.0",
+                /*website_url=*/std::nullopt,
+                /*icons=*/std::nullopt,
+                /*instructions=*/std::string(
+                    "This server provides echo and add tools. "
+                    "Use 'echo' to repeat a message, and 'add' to sum two numbers."));
+
+    app.tool(
+        "echo",
+        Json{{"type", "object"},
+             {"properties", Json{{"message", Json{{"type", "string"}}}}},
+             {"required", Json::array({"message"})}},
+        [](const Json& args) { return args.at("message"); });
+
+    app.tool(
+        "add",
+        Json{{"type", "object"},
+             {"properties", Json{{"a", Json{{"type", "number"}}}, {"b", Json{{"type", "number"}}}}},
+             {"required", Json::array({"a", "b"})}},
+        [](const Json& args)
+        { return args.at("a").get<double>() + args.at("b").get<double>(); });
+
+    auto handler = fastmcpp::mcp::make_mcp_handler(app);
+
+    SseServerWrapper server(handler, "127.0.0.1", port);
+    server.start();
+
+    std::cout << "[READY] Instructions HTTP server listening on port " << port << std::endl;
+
+    while (g_running)
+        std::this_thread::sleep_for(std::chrono::milliseconds(100));
+
+    server.stop();
+    return 0;
+}

examples/server_metadata.cpp

@@ -47,8 +47,9 @@ int main()
 
     std::cout << "2. Creating server with full metadata...\n";
 
-    // Server constructor signature (v2.13.0+):
-    //   Server(name, version, website_url, icons, strict_input_validation)
+    // Server constructor signatures:
+    //   Preferred: Server(name, version, website_url, icons, instructions, strict_input_validation)
+    //   Legacy-compatible: Server(name, version, website_url, icons, strict_input_validation)
     auto server = std::make_shared<server::Server>("example_server",      // name (required)
                                                    "1.2.3",               // version (required)
                                                    "https://example.com", // website_url (optional)

examples/stdio_instructions_server.cpp

@@ -0,0 +1,38 @@
+/// @file stdio_instructions_server.cpp
+/// @brief Minimal stdio MCP server with instructions field set.
+/// Used as E2E test target for instructions wire-format validation.
+
+#include "fastmcpp/app.hpp"
+#include "fastmcpp/mcp/handler.hpp"
+#include "fastmcpp/server/stdio_server.hpp"
+
+int main()
+{
+    using Json = fastmcpp::Json;
+
+    fastmcpp::FastMCP app("instructions_e2e_server", "1.0.0",
+                          /*website_url=*/std::nullopt,
+                          /*icons=*/std::nullopt,
+                          /*instructions=*/std::string("This server provides echo and math tools. "
+                                                       "Use 'echo' to repeat input and 'add' to sum two numbers."));
+
+    app.tool(
+        "echo",
+        Json{{"type", "object"},
+             {"properties", Json{{"message", Json{{"type", "string"}}}}},
+             {"required", Json::array({"message"})}},
+        [](const Json& args) { return args.at("message"); });
+
+    app.tool(
+        "add",
+        Json{{"type", "object"},
+             {"properties", Json{{"a", Json{{"type", "number"}}}, {"b", Json{{"type", "number"}}}}},
+             {"required", Json::array({"a", "b"})}},
+        [](const Json& args)
+        { return args.at("a").get<double>() + args.at("b").get<double>(); });
+
+    auto handler = fastmcpp::mcp::make_mcp_handler(app);
+    fastmcpp::server::StdioServerWrapper server(handler);
+    server.run();
+    return 0;
+}

include/fastmcpp/app.hpp

@@ -8,6 +8,7 @@
 #include "fastmcpp/tools/manager.hpp"
 
 #include <chrono>
+#include <initializer_list>
 #include <memory>
 #include <optional>
 #include <string>
@@ -114,8 +115,19 @@ class FastMCP
     explicit FastMCP(std::string name = "fastmcpp_app", std::string version = "1.0.0",
                      std::optional<std::string> website_url = std::nullopt,
                      std::optional<std::vector<Icon>> icons = std::nullopt,
+                     std::optional<std::string> instructions = std::nullopt,
                      std::vector<std::shared_ptr<providers::Provider>> providers = {},
                      int list_page_size = 0, bool dereference_schemas = true);
+    /// Backward-compatible constructor overload (legacy parameter order).
+    FastMCP(std::string name, std::string version, std::optional<std::string> website_url,
+            std::optional<std::vector<Icon>> icons,
+            std::vector<std::shared_ptr<providers::Provider>> providers,
+            int list_page_size = 0, bool dereference_schemas = true);
+    /// Backward-compatible constructor overload for `{}` provider arguments.
+    FastMCP(std::string name, std::string version, std::optional<std::string> website_url,
+            std::optional<std::vector<Icon>> icons,
+            std::initializer_list<std::shared_ptr<providers::Provider>> providers,
+            int list_page_size = 0, bool dereference_schemas = true);
 
     // Metadata accessors
     const std::string& name() const
@@ -134,6 +146,14 @@ class FastMCP
     {
         return server_.icons();
     }
+    const std::optional<std::string>& instructions() const
+    {
+        return server_.instructions();
+    }
+    void set_instructions(std::optional<std::string> val)
+    {
+        server_.set_instructions(std::move(val));
+    }
     int list_page_size() const
     {
         return list_page_size_;

include/fastmcpp/mcp/handler.hpp

@@ -38,7 +38,8 @@ using SessionAccessor = std::function<std::shared_ptr<server::ServerSession>(con
 std::function<fastmcpp::Json(const fastmcpp::Json&)> make_mcp_handler(
     const std::string& server_name, const std::string& version, const tools::ToolManager& tools,
     const std::unordered_map<std::string, std::string>& descriptions = {},
-    const std::unordered_map<std::string, fastmcpp::Json>& input_schemas_override = {});
+    const std::unordered_map<std::string, fastmcpp::Json>& input_schemas_override = {},
+    const std::optional<std::string>& instructions = std::nullopt);
 
 // Overload: build a handler from a generic Server plus explicit tool metadata.
 // tools_meta: vector of (tool_name, description, inputSchema)

include/fastmcpp/proxy.hpp

@@ -44,7 +44,8 @@ class ProxyApp
 
     /// Construct proxy with client factory
     explicit ProxyApp(ClientFactory client_factory, std::string name = "proxy_app",
-                      std::string version = "1.0.0");
+                      std::string version = "1.0.0",
+                      std::optional<std::string> instructions = std::nullopt);
 
     // Metadata accessors
     const std::string& name() const
@@ -55,6 +56,14 @@ class ProxyApp
     {
         return version_;
     }
+    const std::optional<std::string>& instructions() const
+    {
+        return instructions_;
+    }
+    void set_instructions(std::optional<std::string> val)
+    {
+        instructions_ = std::move(val);
+    }
 
     // Local manager accessors (for adding local-only items)
     tools::ToolManager& local_tools()
@@ -132,6 +141,7 @@ class ProxyApp
     ClientFactory client_factory_;
     std::string name_;
     std::string version_;
+    std::optional<std::string> instructions_;
     tools::ToolManager local_tools_;
     resources::ResourceManager local_resources_;
     prompts::PromptManager local_prompts_;

include/fastmcpp/server/server.hpp

@@ -18,6 +18,7 @@ namespace fastmcpp::server
 /// - version: Server version (optional)
 /// - website_url: Optional URL to server website
 /// - icons: Optional list of icons for UI display
+/// - instructions: Optional instructions shown during initialize
 /// - strict_input_validation: Flag for input validation behavior (optional)
 class Server
 {
@@ -28,12 +29,21 @@ class Server
     explicit Server(std::string name = "fastmcpp_server", std::string version = "1.0.0",
                     std::optional<std::string> website_url = std::nullopt,
                     std::optional<std::vector<fastmcpp::Icon>> icons = std::nullopt,
+                    std::optional<std::string> instructions = std::nullopt,
                     std::optional<bool> strict_input_validation = std::nullopt)
         : name_(std::move(name)), version_(std::move(version)),
           website_url_(std::move(website_url)), icons_(std::move(icons)),
+          instructions_(std::move(instructions)),
           strict_input_validation_(std::move(strict_input_validation))
     {
     }
+    /// Backward-compatible constructor overload (legacy parameter order).
+    Server(std::string name, std::string version, std::optional<std::string> website_url,
+           std::optional<std::vector<fastmcpp::Icon>> icons, bool strict_input_validation)
+        : Server(std::move(name), std::move(version), std::move(website_url), std::move(icons),
+                 std::nullopt, strict_input_validation)
+    {
+    }
 
     // Route registration
     void route(const std::string& name, Handler h)
@@ -69,6 +79,14 @@ class Server
     {
         return icons_;
     }
+    const std::optional<std::string>& instructions() const
+    {
+        return instructions_;
+    }
+    void set_instructions(std::optional<std::string> val)
+    {
+        instructions_ = std::move(val);
+    }
     const std::optional<bool>& strict_input_validation() const
     {
         return strict_input_validation_;
@@ -80,6 +98,7 @@ class Server
     std::string version_;
     std::optional<std::string> website_url_;
     std::optional<std::vector<fastmcpp::Icon>> icons_;
+    std::optional<std::string> instructions_;
     std::optional<bool> strict_input_validation_;
 
     // Routing and middleware

src/app.cpp

@@ -17,9 +17,11 @@ namespace fastmcpp
 
 FastMCP::FastMCP(std::string name, std::string version, std::optional<std::string> website_url,
                  std::optional<std::vector<Icon>> icons,
+                 std::optional<std::string> instructions,
                  std::vector<std::shared_ptr<providers::Provider>> providers, int list_page_size,
                  bool dereference_schemas)
-    : server_(std::move(name), std::move(version), std::move(website_url), std::move(icons)),
+    : server_(std::move(name), std::move(version), std::move(website_url), std::move(icons),
+              std::move(instructions)),
       providers_(std::move(providers)), list_page_size_(list_page_size),
       dereference_schemas_(dereference_schemas)
 {
@@ -30,6 +32,25 @@ FastMCP::FastMCP(std::string name, std::string version, std::optional<std::strin
             throw ValidationError("provider cannot be null");
 }
 
+FastMCP::FastMCP(std::string name, std::string version, std::optional<std::string> website_url,
+                 std::optional<std::vector<Icon>> icons,
+                 std::vector<std::shared_ptr<providers::Provider>> providers, int list_page_size,
+                 bool dereference_schemas)
+    : FastMCP(std::move(name), std::move(version), std::move(website_url), std::move(icons),
+              std::nullopt, std::move(providers), list_page_size, dereference_schemas)
+{
+}
+
+FastMCP::FastMCP(std::string name, std::string version, std::optional<std::string> website_url,
+                 std::optional<std::vector<Icon>> icons,
+                 std::initializer_list<std::shared_ptr<providers::Provider>> providers,
+                 int list_page_size, bool dereference_schemas)
+    : FastMCP(std::move(name), std::move(version), std::move(website_url), std::move(icons),
+              std::nullopt, std::vector<std::shared_ptr<providers::Provider>>(providers),
+              list_page_size, dereference_schemas)
+{
+}
+
 namespace
 {
 fastmcpp::Json schema_from_schema_or_simple(const fastmcpp::Json& schema_or_simple)