feat: tool call hooks, structured error data, fix param shadowing — bump to v0.29.1

- Add onBeforeToolCall/onAfterToolCall middleware hooks with ToolCallContext
  (toolName, args, timing, error state). Before-hook can reject calls.
- Add jsonRpcErrorWithData() for JSON-RPC errors with structured data field
- Fix parameter shadowing in _handleResourcesRead (params → templateVars)
- Fix 4 version-mismatch test failures (0.28.0 → 0.29.1)
- Add 11 new tests (hooks: 8, error data: 3)
- Total: 1028 tests, all passing

Author: Nicola Spieser

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.29.1] - 2026-02-21
+
+### Features
+- **Tool call hooks** — `onBeforeToolCall()` and `onAfterToolCall()` middleware for logging, access control, metrics, and auditing. Before-hook can reject calls; after-hook receives timing and error info via `ToolCallContext`.
+- **Structured JSON-RPC error data** — `jsonRpcErrorWithData()` public API for returning errors with an optional `data` field per JSON-RPC spec.
+
+### Fixes
+- **Fix parameter shadowing** in `_handleResourcesRead()` — local `params` variable renamed to `templateVars` to avoid shadowing the function parameter (could cause issues on strict compilers).
+- **Fix version mismatch in tests** — 4 tests were checking for "0.28.0" instead of the current version.
+
+### Tests
+- Added **11 new tests** for tool call hooks (8) and structured error data (3):
+  - Before-hook allow/reject, after-hook context/error detection, hook ordering, rejection skips after-hook, argument forwarding
+  - Error-with-data serialization, empty data, ID preservation
+- **Total: 1028 tests** (1017 → 1028)
+
 ## [0.29.0] - 2026-02-21
 
 ### Features

README.md

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

src/mcpd.cpp

@@ -703,6 +703,24 @@ String Server::_handleToolsCall(JsonVariant params, JsonVariant id) {
         if (tool.name == toolName) {
             JsonObject arguments = params["arguments"].as<JsonObject>();
 
+            // Before-call hook: allow rejection
+            if (_beforeToolCallHook) {
+                ToolCallContext ctx;
+                ctx.toolName = toolName;
+                ctx.args = &arguments;
+                ctx.startMs = millis();
+                ctx.durationMs = 0;
+                ctx.isError = false;
+                if (!_beforeToolCallHook(ctx)) {
+                    if (!requestId.isEmpty()) {
+                        _requestTracker.completeRequest(requestId);
+                    }
+                    return _jsonRpcError(id, -32600, "Tool call rejected");
+                }
+            }
+
+            unsigned long callStartMs = millis();
+
             // Check if this tool has a rich handler
             MCPRichToolHandler richHandler = nullptr;
             for (const auto& rh : _richTools) {
@@ -713,6 +731,7 @@ String Server::_handleToolsCall(JsonVariant params, JsonVariant id) {
             }
 
             String resultStr;
+            bool callIsError = false;
 
             if (richHandler) {
                 // Use rich handler for structured content
@@ -721,34 +740,46 @@ String Server::_handleToolsCall(JsonVariant params, JsonVariant id) {
                     toolResult = richHandler(arguments);
                 } catch (...) {
                     toolResult = MCPToolResult::error("Internal tool error");
+                    callIsError = true;
                 }
 
                 JsonDocument result;
                 JsonObject resultObj = result.to<JsonObject>();
                 toolResult.toJson(resultObj);
                 serializeJson(result, resultStr);
+                if (toolResult.isError) callIsError = true;
             } else {
                 // Use simple handler (backward compatible)
                 String handlerResult;
-                bool isError = false;
                 try {
                     handlerResult = tool.handler(arguments);
                 } catch (...) {
                     handlerResult = "Internal tool error";
-                    isError = true;
+                    callIsError = true;
                 }
 
                 JsonDocument result;
                 JsonArray content = result["content"].to<JsonArray>();
                 JsonObject textContent = content.add<JsonObject>();
                 textContent["type"] = "text";
                 textContent["text"] = handlerResult;
-                if (isError) {
+                if (callIsError) {
                     result["isError"] = true;
                 }
                 serializeJson(result, resultStr);
             }
 
+            // After-call hook: logging/metrics
+            if (_afterToolCallHook) {
+                ToolCallContext ctx;
+                ctx.toolName = toolName;
+                ctx.args = &arguments;
+                ctx.startMs = callStartMs;
+                ctx.durationMs = millis() - callStartMs;
+                ctx.isError = callIsError;
+                _afterToolCallHook(ctx);
+            }
+
             // Complete request tracking
             if (!requestId.isEmpty()) {
                 _requestTracker.completeRequest(requestId);
@@ -816,9 +847,9 @@ String Server::_handleResourcesRead(JsonVariant params, JsonVariant id) {
 
     // Try matching against resource templates
     for (const auto& tmpl : _resourceTemplates) {
-        std::map<String, String> params;
-        if (tmpl.match(String(uri), params)) {
-            String content = tmpl.handler(params);
+        std::map<String, String> templateVars;
+        if (tmpl.match(String(uri), templateVars)) {
+            String content = tmpl.handler(templateVars);
 
             JsonDocument result;
             JsonArray contents = result["contents"].to<JsonArray>();
@@ -1114,6 +1145,30 @@ String Server::_jsonRpcResult(JsonVariant id, const String& resultJson) {
     return output;
 }
 
+String Server::jsonRpcErrorWithData(JsonVariant id, int code, const char* message,
+                                    const String& dataJson) {
+    JsonDocument doc;
+    doc["jsonrpc"] = "2.0";
+    if (!id.isNull()) {
+        doc["id"] = id;
+    } else {
+        doc["id"] = nullptr;
+    }
+    JsonObject error = doc["error"].to<JsonObject>();
+    error["code"] = code;
+    error["message"] = message;
+
+    if (!dataJson.isEmpty()) {
+        JsonDocument dataDoc;
+        deserializeJson(dataDoc, dataJson);
+        error["data"] = dataDoc.as<JsonVariant>();
+    }
+
+    String output;
+    serializeJson(doc, output);
+    return output;
+}
+
 String Server::_jsonRpcError(JsonVariant id, int code, const char* message) {
     JsonDocument doc;
     doc["jsonrpc"] = "2.0";

src/mcpd.h

@@ -44,7 +44,7 @@
 #include "MCPTransportBLE.h"
 #endif
 
-#define MCPD_VERSION "0.29.0"
+#define MCPD_VERSION "0.29.1"
 #define MCPD_MCP_PROTOCOL_VERSION "2025-03-26"
 
 namespace mcpd {
@@ -263,6 +263,46 @@ class Server {
     /** Access the Prometheus metrics module */
     Metrics& metrics() { return _metrics; }
 
+    // ── Tool Call Hooks ─────────────────────────────────────────────────
+
+    /**
+     * Context passed to tool call hooks.
+     */
+    struct ToolCallContext {
+        String toolName;          // Name of the tool being called
+        const JsonObject* args;   // Tool arguments (read-only in before hook)
+        unsigned long startMs;    // millis() when call started (after hook only)
+        unsigned long durationMs; // Call duration in ms (after hook only)
+        bool isError;             // Whether the tool returned an error (after hook only)
+    };
+
+    /**
+     * Before-call hook. Return true to proceed, false to reject the call.
+     * When rejected, the server returns a "Tool call rejected" error.
+     */
+    using BeforeToolCallHook = std::function<bool(const ToolCallContext& ctx)>;
+
+    /**
+     * After-call hook. Called after tool execution completes.
+     * Useful for logging, metrics, auditing.
+     */
+    using AfterToolCallHook = std::function<void(const ToolCallContext& ctx)>;
+
+    /** Set a hook called before every tool call. Return false to reject. */
+    void onBeforeToolCall(BeforeToolCallHook hook) { _beforeToolCallHook = hook; }
+
+    /** Set a hook called after every tool call completes. */
+    void onAfterToolCall(AfterToolCallHook hook) { _afterToolCallHook = hook; }
+
+    // ── JSON-RPC Error Data ────────────────────────────────────────────
+
+    /**
+     * Create a JSON-RPC error response with optional structured data.
+     * Per JSON-RPC spec, errors may include a "data" field with additional info.
+     */
+    String jsonRpcErrorWithData(JsonVariant id, int code, const char* message,
+                                const String& dataJson);
+
     // ── Lifecycle Hooks ────────────────────────────────────────────────
 
     using LifecycleCallback = std::function<void()>;
@@ -369,6 +409,10 @@ class Server {
     LifecycleCallback _onConnectCb;
     LifecycleCallback _onDisconnectCb;
 
+    // Tool call hooks
+    BeforeToolCallHook _beforeToolCallHook;
+    AfterToolCallHook _afterToolCallHook;
+
     std::vector<MCPTool> _tools;
     std::vector<std::pair<String, MCPRichToolHandler>> _richTools;  // name → handler
     std::vector<MCPResource> _resources;

test/test_infrastructure.cpp

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