feat: server instructions, custom version, tool enable/disable — bump to v0.30.0

- Add setInstructions() for MCP 2025-03-26 'instructions' field in initialize response
- Add setVersion() to override server version string in server info
- Add enableTool()/disableTool()/isToolEnabled() for runtime tool visibility control
- Disabled tools are hidden from tools/list and rejected on tools/call
- Add 9 integration tests for all new features
- Total: 1037 tests, all passing

Author: Nicola Spieser

README.md

@@ -33,7 +33,7 @@
 |---|:---:|:---:|:---:|
 | Runs on the MCU | ✅ | ✅ | ❌ CLI tool |
 | MCP spec compliant | ✅ 2025-03-26 | ❌ custom WS | ❌ |
-| Actually compiles | ✅ 1028 tests | ❌ self-described | N/A |
+| Actually compiles | ✅ 1037 tests | ❌ self-described | N/A |
 | Streamable HTTP + SSE | ✅ | ❌ | ❌ |
 | WebSocket transport | ✅ | ✅ | ❌ |
 | Claude Desktop bridge | ✅ | ❌ | ❌ |
@@ -44,6 +44,8 @@
 | Elicitation (server requests user input) | ✅ | ❌ | ❌ |
 | Audio content type | ✅ | ❌ | ❌ |
 | Tool Annotations (readOnly, destructive hints) | ✅ | ❌ | ❌ |
+| Server Instructions (LLM guidance) | ✅ | ❌ | ❌ |
+| Runtime Tool Enable/Disable | ✅ | ❌ | ❌ |
 | Structured Content (text, image, resource) | ✅ | ❌ | ❌ |
 | Progress Notifications | ✅ | ❌ | ❌ |
 | Request Cancellation | ✅ | ❌ | ❌ |
@@ -314,6 +316,31 @@ mcp.notifyToolsChanged();  // Notify connected clients
 
 mcp.removeTool("old_sensor");
 mcp.notifyToolsChanged();
+
+// Enable/disable tools without removing them
+mcp.disableTool("maintenance_tool");   // Hidden from clients
+mcp.enableTool("maintenance_tool");    // Visible again
+```
+
+### 📋 Server Instructions
+
+Guide the LLM's behavior with your device using server instructions (MCP 2025-03-26):
+
+```cpp
+mcp.setInstructions(
+    "This device controls a greenhouse. Always read temperature "
+    "before adjusting fans. Never set irrigation above 80%."
+);
+```
+
+Instructions are sent in the `initialize` response and help the model understand the context and constraints of your hardware.
+
+### 🏷️ Custom Version
+
+Override the version string in server info (useful for firmware versioning):
+
+```cpp
+mcp.setVersion("2.1.0-greenhouse");
 ```
 
 ### 📊 Prometheus Metrics

src/mcpd.cpp

@@ -82,6 +82,27 @@ void Server::addRoot(const char* uri, const char* name) {
 void Server::setEndpoint(const char* path) { _endpoint = path; }
 void Server::setMDNS(bool enabled) { _mdnsEnabled = enabled; }
 
+bool Server::enableTool(const char* name, bool enabled) {
+    // Verify tool exists
+    bool found = false;
+    for (const auto& t : _tools) {
+        if (t.name == name) { found = true; break; }
+    }
+    if (!found) return false;
+
+    if (enabled) {
+        _disabledTools.erase(String(name));
+    } else {
+        _disabledTools.insert(String(name));
+    }
+    notifyToolsChanged();
+    return true;
+}
+
+bool Server::isToolEnabled(const char* name) const {
+    return _disabledTools.find(String(name)) == _disabledTools.end();
+}
+
 bool Server::removeTool(const char* name) {
     for (auto it = _tools.begin(); it != _tools.end(); ++it) {
         if (it->name == name) {
@@ -586,7 +607,12 @@ String Server::_handleInitialize(JsonVariant params, JsonVariant id) {
 
     JsonObject serverInfo = result["serverInfo"].to<JsonObject>();
     serverInfo["name"] = _name;
-    serverInfo["version"] = MCPD_VERSION;
+    serverInfo["version"] = _version ? _version : MCPD_VERSION;
+
+    // MCP 2025-03-26: instructions guide the LLM's behavior with this server
+    if (_instructions) {
+        result["instructions"] = _instructions;
+    }
 
     JsonObject capabilities = result["capabilities"].to<JsonObject>();
 
@@ -663,6 +689,8 @@ String Server::_handleToolsList(JsonVariant params, JsonVariant id) {
     }
 
     for (size_t i = startIdx; i < endIdx; i++) {
+        // Skip disabled tools
+        if (_disabledTools.count(_tools[i].name)) continue;
         JsonObject obj = tools.add<JsonObject>();
         _tools[i].toJson(obj);
     }
@@ -698,6 +726,14 @@ String Server::_handleToolsCall(JsonVariant params, JsonVariant id) {
         _requestTracker.trackRequest(requestId, progressToken);
     }
 
+    // Reject disabled tools
+    if (_disabledTools.count(String(toolName))) {
+        if (!requestId.isEmpty()) {
+            _requestTracker.completeRequest(requestId);
+        }
+        return _jsonRpcError(id, -32602, "Tool not found");
+    }
+
     // Find the tool
     for (const auto& tool : _tools) {
         if (tool.name == toolName) {

src/mcpd.h

@@ -44,7 +44,7 @@
 #include "MCPTransportBLE.h"
 #endif
 
-#define MCPD_VERSION "0.29.1"
+#define MCPD_VERSION "0.30.0"
 #define MCPD_MCP_PROTOCOL_VERSION "2025-03-26"
 
 namespace mcpd {
@@ -155,6 +155,28 @@ class Server {
     /** Enable/disable mDNS advertisement (default: enabled) */
     void setMDNS(bool enabled);
 
+    /**
+     * Set server instructions for the LLM (MCP 2025-03-26 spec).
+     * Included in the initialize response to guide the model's behavior.
+     * Example: "This device controls a greenhouse. Use temperature_read before adjusting fans."
+     */
+    void setInstructions(const char* instructions) { _instructions = instructions; }
+
+    /**
+     * Set a custom version string (overrides MCPD_VERSION in server info).
+     */
+    void setVersion(const char* version) { _version = version; }
+
+    /**
+     * Enable or disable a tool at runtime by name.
+     * Disabled tools are hidden from tools/list and cannot be called.
+     * Emits tools/list_changed notification.
+     * @return true if the tool was found
+     */
+    bool enableTool(const char* name, bool enabled = true);
+    bool disableTool(const char* name) { return enableTool(name, false); }
+    bool isToolEnabled(const char* name) const;
+
     /** Get server name */
     const char* getName() const { return _name; }
 
@@ -377,7 +399,10 @@ class Server {
     const char* _name;
     uint16_t _port;
     const char* _endpoint = "/mcp";
+    const char* _instructions = nullptr;
+    const char* _version = nullptr;
     bool _mdnsEnabled = true;
+    std::set<String> _disabledTools;  // tools hidden from listing/calling
     String _sessionId;
     bool _initialized = false;
     size_t _pageSize = 0;  // 0 = no pagination

test/test_infrastructure.cpp

@@ -719,7 +719,7 @@ TEST(completion_manager_no_providers) {
 // ═══════════════════════════════════════════════════════════════════════
 
 TEST(version_constants) {
-    ASSERT_EQ(String(MCPD_VERSION), String("0.29.1"));
+    ASSERT_EQ(String(MCPD_VERSION), String("0.30.0"));
     ASSERT_EQ(String(MCPD_MCP_PROTOCOL_VERSION), String("2025-03-26"));
 }
 

test/test_integration.cpp

@@ -779,6 +779,115 @@ TEST(error_with_data_preserves_id) {
     ASSERT(err.indexOf("field_x") >= 0);
 }
 
+// ════════════════════════════════════════════════════════════════════════
+// Instructions & Version Tests
+// ════════════════════════════════════════════════════════════════════════
+
+TEST(instructions_included_in_initialize) {
+    Server server("test", 80);
+    server.setInstructions("Read temperature before adjusting fans.");
+
+    String res = server._processJsonRpc(
+        R"({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"test"}}})");
+    ASSERT(res.indexOf("Read temperature before adjusting fans.") >= 0);
+    ASSERT(res.indexOf("\"instructions\"") >= 0);
+}
+
+TEST(instructions_absent_when_not_set) {
+    Server server("test", 80);
+
+    String res = server._processJsonRpc(
+        R"({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"test"}}})");
+    ASSERT(res.indexOf("\"instructions\"") < 0);
+}
+
+TEST(custom_version_in_initialize) {
+    Server server("test", 80);
+    server.setVersion("1.2.3-custom");
+
+    String res = server._processJsonRpc(
+        R"({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"test"}}})");
+    ASSERT(res.indexOf("1.2.3-custom") >= 0);
+}
+
+TEST(default_version_when_not_overridden) {
+    Server server("test", 80);
+
+    String res = server._processJsonRpc(
+        R"({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"test"}}})");
+    ASSERT(res.indexOf(MCPD_VERSION) >= 0);
+}
+
+// ════════════════════════════════════════════════════════════════════════
+// Tool Enable/Disable Tests
+// ════════════════════════════════════════════════════════════════════════
+
+TEST(disable_tool_hides_from_list) {
+    Server server("test", 80);
+    server.addTool("visible", "A tool", "{}", [](const JsonObject&) { return String("ok"); });
+    server.addTool("hidden", "Another", "{}", [](const JsonObject&) { return String("ok"); });
+
+    server._processJsonRpc(
+        R"({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"test"}}})");
+
+    // Both visible initially
+    String res = server._processJsonRpc(
+        R"({"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}})");
+    ASSERT(res.indexOf("\"visible\"") >= 0);
+    ASSERT(res.indexOf("\"hidden\"") >= 0);
+
+    // Disable one
+    ASSERT(server.disableTool("hidden"));
+    res = server._processJsonRpc(
+        R"({"jsonrpc":"2.0","id":3,"method":"tools/list","params":{}})");
+    ASSERT(res.indexOf("\"visible\"") >= 0);
+    ASSERT(res.indexOf("\"hidden\"") < 0);
+}
+
+TEST(disabled_tool_cannot_be_called) {
+    Server server("test", 80);
+    server.addTool("mytool", "A tool", "{}", [](const JsonObject&) { return String("ok"); });
+
+    server._processJsonRpc(
+        R"({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"test"}}})");
+
+    server.disableTool("mytool");
+    String res = server._processJsonRpc(
+        R"({"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"mytool","arguments":{}}})");
+    ASSERT(res.indexOf("\"error\"") >= 0);
+    ASSERT(res.indexOf("Tool not found") >= 0);
+}
+
+TEST(re_enable_tool_makes_it_visible) {
+    Server server("test", 80);
+    server.addTool("toggle", "Togglable", "{}", [](const JsonObject&) { return String("ok"); });
+
+    server._processJsonRpc(
+        R"({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"test"}}})");
+
+    server.disableTool("toggle");
+    ASSERT(server.isToolEnabled("toggle") == false);
+
+    server.enableTool("toggle");
+    ASSERT(server.isToolEnabled("toggle") == true);
+
+    String res = server._processJsonRpc(
+        R"({"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}})");
+    ASSERT(res.indexOf("\"toggle\"") >= 0);
+}
+
+TEST(enable_nonexistent_tool_returns_false) {
+    Server server("test", 80);
+    ASSERT(server.enableTool("nonexistent") == false);
+    ASSERT(server.disableTool("nonexistent") == false);
+}
+
+TEST(is_tool_enabled_default_true) {
+    Server server("test", 80);
+    server.addTool("mytool", "test", "{}", [](const JsonObject&) { return String("ok"); });
+    ASSERT(server.isToolEnabled("mytool") == true);
+}
+
 // ════════════════════════════════════════════════════════════════════════
 
 int main() {

test/test_jsonrpc.cpp

@@ -712,7 +712,7 @@ TEST(version_is_0_11_0_compat) {
     auto* s = makeTestServer();
     String req = R"({"jsonrpc":"2.0","id":250,"method":"initialize","params":{}})";
     String resp = s->_processJsonRpc(req);
-    ASSERT_STR_CONTAINS(resp.c_str(), "\"version\":\"0.29.1\"");
+    ASSERT_STR_CONTAINS(resp.c_str(), "\"version\":\"0.30.0\"");
 }
 
 // ── v0.6.0 Tests: Tool Annotations ────────────────────────────────────
@@ -1567,7 +1567,7 @@ TEST(version_0_11_0) {
     Server* s = makeTestServer();
     String req = R"({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"test"}}})";
     String resp = s->_processJsonRpc(req);
-    ASSERT_STR_CONTAINS(resp.c_str(), "0.29.1");
+    ASSERT_STR_CONTAINS(resp.c_str(), "0.30.0");
 }
 
 // ── Watchdog Tool Tests ────────────────────────────────────────────────
@@ -1811,7 +1811,7 @@ TEST(diagnostics_version_macros) {
     ASSERT(strlen(MCPD_VERSION) > 0);
     ASSERT(strlen(MCPD_MCP_PROTOCOL_VERSION) > 0);
     ASSERT_STR_CONTAINS(MCPD_MCP_PROTOCOL_VERSION, "2025");
-    ASSERT_STR_CONTAINS(MCPD_VERSION, "0.29.1");
+    ASSERT_STR_CONTAINS(MCPD_VERSION, "0.30.0");
 }
 
 // ── Batch JSON-RPC edge cases ──────────────────────────────────────────