feat: tool result caching (MCPCache.h, per-tool TTL, bounded eviction) — 29 new tests, fix version sync — bump to v0.36.0

Author: Nicola Spieser

CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.36.0] — 2026-02-22
+
+### Added
+- **Tool Result Caching** (`MCPCache.h`): Per-tool result caching with configurable TTL, bounded memory, and automatic expiration. Ideal for MCU sensor tools where hardware reads are expensive (e.g., DHT sensor needs 2s between reads, I2C scans are slow). Cache keys are computed from tool name + argument hash, so identical calls return cached results within the TTL window.
+  - `ToolResultCache`: Standalone cache with `setToolTTL()`, `get()`, `put()`, `invalidateTool()`, `invalidate()`, `clear()`, `statsJson()`.
+  - `enableCache()` / `isCacheEnabled()` on Server: opt-in caching (disabled by default).
+  - `cache()` accessor on Server for per-tool TTL configuration and stats.
+  - Bounded size with `setMaxEntries()` (default 32) — evicts expired then oldest entries.
+  - Cache-aware tool dispatch: cache hits skip handler execution entirely, cache misses store results automatically.
+  - Works with both simple and rich tool handlers.
+  - After-call hooks still fire on cache hits for consistent metrics/logging.
+  - Programmatic invalidation from within handlers (e.g., a "reset" tool invalidating a "read" tool's cache).
+- **29 new tests**: 20 ToolResultCache unit tests and 9 Server cache integration tests. **Total: 1252 tests**.
+
+### Fixed
+- Version sync: `library.properties` and `library.json` now match `MCPD_VERSION` (previously stuck at 0.31.0).
+
 ## [0.35.0] — 2026-02-22
 
 ### Added

README.md

@@ -33,7 +33,7 @@
 |---|:---:|:---:|:---:|
 | Runs on the MCU | ✅ | ✅ | ❌ CLI tool |
 | MCP spec compliant | ✅ 2025-11-25 | ❌ custom WS | ❌ |
-| Actually compiles | ✅ 1261 tests | ❌ self-described | N/A |
+| Actually compiles | ✅ 1252 tests | ❌ self-described | N/A |
 | Streamable HTTP + SSE | ✅ | ❌ | ❌ |
 | WebSocket transport | ✅ | ✅ | ❌ |
 | Claude Desktop bridge | ✅ | ❌ | ❌ |

docs/API.md

@@ -513,3 +513,42 @@ If a tool's JSON output violates its declared `outputSchema` (wrong types, missi
 This catches handler bugs during development before invalid data reaches the client. Non-JSON output from tools with `outputSchema` gracefully skips validation (no `structuredContent` is generated).
 
 Disabled by default. Enable with `mcp.enableOutputValidation()`.
+
+### Tool Result Caching
+
+Cache tool results with per-tool TTL to avoid expensive hardware reads:
+
+```cpp
+// Configure TTL per tool (only explicitly configured tools are cached)
+mcp.cache().setToolTTL("temperature_read", 2000);  // Cache for 2 seconds
+mcp.cache().setToolTTL("i2c_scan", 10000);          // Cache for 10 seconds
+mcp.cache().setMaxEntries(32);                      // Limit memory (default: 32)
+mcp.enableCache();                                  // Activate caching
+```
+
+Cache keys are computed from tool name + serialized arguments, so `temperature_read({"unit":"C"})` and `temperature_read({"unit":"F"})` are cached independently.
+
+**Programmatic invalidation** (e.g., a "calibrate" tool invalidating a "read" tool):
+
+```cpp
+mcp.addTool("sensor_calibrate", "Calibrate", schema,
+    [&](const JsonObject& args) -> String {
+        // ... calibration logic ...
+        mcp.cache().invalidateTool("sensor_read");  // Clear stale readings
+        return "Calibrated";
+    });
+```
+
+**Cache statistics** for diagnostics:
+
+```cpp
+String stats = mcp.cache().statsJson();
+// {"enabled":true,"entries":5,"maxEntries":32,"hits":42,"misses":12,"hitRate":0.78,"toolCount":3}
+```
+
+**Key behaviors:**
+- Disabled by default (opt-in with `enableCache()`)
+- Only tools with explicit TTL are cached (write/actuator tools are never cached unless configured)
+- Expired entries are evicted automatically; bounded size prevents memory exhaustion
+- After-call hooks still fire on cache hits for consistent metrics
+- Error results are also cached (prevents hammering a failing sensor)

library.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpd",
-  "version": "0.31.0",
+  "version": "0.36.0",
   "description": "MCP Server SDK for Microcontrollers — Expose ESP32/RP2040/STM32 hardware as AI-accessible tools via Model Context Protocol",
   "keywords": [
     "mcp",

library.properties

@@ -1,5 +1,5 @@
 name=mcpd
-version=0.31.0
+version=0.36.0
 author=Nicola Spieser
 maintainer=Nicola Spieser <redbasecap-buiss@users.noreply.github.com>
 sentence=MCP Server SDK for Microcontrollers

src/MCPCache.h

@@ -0,0 +1,265 @@
+/**
+ * mcpd — Tool Result Cache
+ *
+ * Caches tool call results with configurable per-tool TTL.
+ * Ideal for sensor tools on MCU where hardware reads are expensive
+ * (e.g., DHT sensor needs 2s between reads, I2C scans are slow).
+ *
+ * Cache keys are computed from tool name + serialized arguments,
+ * so identical calls return cached results within the TTL window.
+ */
+
+#ifndef MCPD_CACHE_H
+#define MCPD_CACHE_H
+
+#include <Arduino.h>
+#include <ArduinoJson.h>
+#include <map>
+
+namespace mcpd {
+
+struct CacheEntry {
+    String result;          // Cached result string
+    unsigned long cachedAt; // millis() when cached
+    unsigned long ttlMs;    // Time-to-live in milliseconds
+    bool isError;           // Whether the cached result was an error
+
+    bool isValid() const {
+        if (ttlMs == 0) return false;
+        return (millis() - cachedAt) < ttlMs;
+    }
+
+    unsigned long ageMs() const {
+        return millis() - cachedAt;
+    }
+
+    unsigned long remainingMs() const {
+        if (!isValid()) return 0;
+        return ttlMs - ageMs();
+    }
+};
+
+/**
+ * Tool result cache with per-tool TTL and bounded size.
+ *
+ * Usage:
+ *   mcp.cache().setToolTTL("temperature_read", 2000);  // cache for 2s
+ *   mcp.cache().setToolTTL("gpio_read", 500);           // cache for 500ms
+ *   mcp.cache().setMaxEntries(32);                      // limit memory usage
+ *   mcp.enableCache();                                  // activate caching
+ */
+class ToolResultCache {
+public:
+    ToolResultCache() = default;
+
+    /**
+     * Set the cache TTL for a specific tool.
+     * Only tools with explicit TTL are cached.
+     * @param toolName  Tool name
+     * @param ttlMs     Cache duration in milliseconds (0 = disable for this tool)
+     */
+    void setToolTTL(const char* toolName, unsigned long ttlMs) {
+        if (ttlMs == 0) {
+            _toolTTLs.erase(String(toolName));
+        } else {
+            _toolTTLs[String(toolName)] = ttlMs;
+        }
+    }
+
+    /**
+     * Get the configured TTL for a tool (0 = not cached).
+     */
+    unsigned long getToolTTL(const char* toolName) const {
+        auto it = _toolTTLs.find(String(toolName));
+        return (it != _toolTTLs.end()) ? it->second : 0;
+    }
+
+    /**
+     * Check if a tool has caching configured.
+     */
+    bool isToolCached(const char* toolName) const {
+        return _toolTTLs.find(String(toolName)) != _toolTTLs.end();
+    }
+
+    /**
+     * Look up a cached result. Returns true if a valid (non-expired) entry exists.
+     * @param toolName  Tool name
+     * @param argsJson  Serialized arguments JSON
+     * @param[out] result  The cached result string
+     * @param[out] isError Whether the cached result was an error
+     * @return true if cache hit
+     */
+    bool get(const char* toolName, const String& argsJson,
+             String& result, bool& isError) {
+        if (!_enabled) return false;
+
+        String key = _makeKey(toolName, argsJson);
+        auto it = _entries.find(key);
+        if (it == _entries.end()) return false;
+
+        if (!it->second.isValid()) {
+            _entries.erase(it);
+            return false;
+        }
+
+        result = it->second.result;
+        isError = it->second.isError;
+        _hits++;
+        return true;
+    }
+
+    /**
+     * Store a result in the cache.
+     * Only stores if the tool has a configured TTL.
+     */
+    void put(const char* toolName, const String& argsJson,
+             const String& result, bool isError = false) {
+        if (!_enabled) return;
+
+        unsigned long ttl = getToolTTL(toolName);
+        if (ttl == 0) return;
+
+        // Evict expired entries if at capacity
+        if (_entries.size() >= _maxEntries) {
+            _evictExpired();
+        }
+        // If still at capacity, evict oldest
+        if (_entries.size() >= _maxEntries) {
+            _evictOldest();
+        }
+
+        String key = _makeKey(toolName, argsJson);
+        CacheEntry entry;
+        entry.result = result;
+        entry.cachedAt = millis();
+        entry.ttlMs = ttl;
+        entry.isError = isError;
+        _entries[key] = entry;
+        _misses++;
+    }
+
+    /**
+     * Invalidate all cached results for a specific tool.
+     */
+    void invalidateTool(const char* toolName) {
+        String prefix = String(toolName) + ":";
+        auto it = _entries.begin();
+        while (it != _entries.end()) {
+            if (it->first.startsWith(prefix)) {
+                it = _entries.erase(it);
+            } else {
+                ++it;
+            }
+        }
+    }
+
+    /**
+     * Invalidate a specific cached result.
+     */
+    void invalidate(const char* toolName, const String& argsJson) {
+        String key = _makeKey(toolName, argsJson);
+        _entries.erase(key);
+    }
+
+    /**
+     * Clear the entire cache.
+     */
+    void clear() {
+        _entries.clear();
+        _hits = 0;
+        _misses = 0;
+    }
+
+    /**
+     * Enable or disable the cache.
+     */
+    void setEnabled(bool enabled) { _enabled = enabled; }
+    bool isEnabled() const { return _enabled; }
+
+    /**
+     * Set maximum number of cache entries (default: 32).
+     * Keeps memory usage bounded on MCU.
+     */
+    void setMaxEntries(size_t max) { _maxEntries = max; }
+    size_t getMaxEntries() const { return _maxEntries; }
+
+    /**
+     * Get cache statistics.
+     */
+    size_t size() const { return _entries.size(); }
+    unsigned long hits() const { return _hits; }
+    unsigned long misses() const { return _misses; }
+    float hitRate() const {
+        unsigned long total = _hits + _misses;
+        return (total > 0) ? (float)_hits / (float)total : 0.0f;
+    }
+
+    /**
+     * Get stats as JSON string for diagnostics.
+     */
+    String statsJson() const {
+        JsonDocument doc;
+        doc["enabled"] = _enabled;
+        doc["entries"] = _entries.size();
+        doc["maxEntries"] = _maxEntries;
+        doc["hits"] = _hits;
+        doc["misses"] = _misses;
+        doc["hitRate"] = hitRate();
+        doc["toolCount"] = _toolTTLs.size();
+        String out;
+        serializeJson(doc, out);
+        return out;
+    }
+
+private:
+    bool _enabled = false;
+    size_t _maxEntries = 32;
+    unsigned long _hits = 0;
+    unsigned long _misses = 0;
+
+    std::map<String, unsigned long> _toolTTLs;  // tool name → TTL in ms
+    std::map<String, CacheEntry> _entries;       // key → entry
+
+    /**
+     * Build a cache key from tool name and arguments.
+     * Key format: "toolName:argsHash" where argsHash is a simple
+     * string hash to keep keys short on MCU.
+     */
+    String _makeKey(const char* toolName, const String& argsJson) const {
+        // Simple DJB2 hash of the arguments
+        unsigned long hash = 5381;
+        for (size_t i = 0; i < argsJson.length(); i++) {
+            hash = ((hash << 5) + hash) + (unsigned char)argsJson[i];
+        }
+        return String(toolName) + ":" + String(hash);
+    }
+
+    void _evictExpired() {
+        auto it = _entries.begin();
+        while (it != _entries.end()) {
+            if (!it->second.isValid()) {
+                it = _entries.erase(it);
+            } else {
+                ++it;
+            }
+        }
+    }
+
+    void _evictOldest() {
+        if (_entries.empty()) return;
+        auto oldest = _entries.begin();
+        unsigned long oldestAge = 0;
+        for (auto it = _entries.begin(); it != _entries.end(); ++it) {
+            unsigned long age = it->second.ageMs();
+            if (age > oldestAge) {
+                oldestAge = age;
+                oldest = it;
+            }
+        }
+        _entries.erase(oldest);
+    }
+};
+
+} // namespace mcpd
+
+#endif // MCPD_CACHE_H