feat: improve tool response representation in Claude Desktop

Author: mathislucka

src/deepset_mcp/tool_factory.py

@@ -363,4 +363,4 @@ def register_tools(
                 object_store,
             )
 
-        mcp_server_instance.add_tool(enhanced_tool, name=tool_name, structured_output=False)
+        mcp_server_instance.add_tool(enhanced_tool, name=tool_name)

src/deepset_mcp/tools/tokonomics/__init__.py

@@ -2,69 +2,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-"""
-Tokonomics: Explorable and Referenceable Tools for LLM Agents.
-
-=============================================================
-
-A library that provides token-efficient object exploration and reference
-passing capabilities for LLM agents.
-
-Key Features:
-- TTL-based object storage for temporary results
-- Rich object exploration with multiple rendering modes
-- Reference-based parameter passing (@obj_id.path.to.value)
-- Type-safe decorators that preserve function signatures
-- Configurable preview truncation and custom rendering callbacks
-
-Usage:
-------
-
-Basic explorable tool:
-
-    >>> from deepset_mcp.tools.tokonomics import explorable
-    >>>
-    >>> @explorable
-    >>> def get_data():
-    ...     return {"users": [{"name": "Alice", "age": 30}]}
-    >>>
-    >>> result = get_data()
-    >>> print(result)  # Shows rich preview
-    >>> result.obj_id  # "obj_123"
-    >>> result.value   # Original data
-
-Referenceable tool that accepts references:
-
-    >>> from deepset_mcp.tools.tokonomics import referenceable
-    >>>
-    >>> @referenceable
-    >>> def process_users(users: list) -> str:
-    ...     return f"Processed {len(users)} users"
-    >>>
-    >>> # Use with direct data
-    >>> process_users([{"name": "Bob"}])
-    >>>
-    >>> # Use with reference
-    >>> process_users("@obj_123.users")
-
-Exploration utilities:
-
-    >>> from deepset_mcp.tools.tokonomics import explore, search
-    >>>
-    >>> # Explore object structure
-    >>> explore("obj_123", mode="tree")
-    >>>
-    >>> # Search within objects
-    >>> search("obj_123", "Alice")
-"""
-
 from .decorators import explorable, explorable_and_referenceable, referenceable
 from .explorer import RichExplorer
-from .object_store import Explorable, InMemoryBackend, ObjectStore
+from .object_store import InMemoryBackend, ObjectStore
 
 __all__ = [
     # Core classes
-    "Explorable",
     "InMemoryBackend",
     "ObjectStore",
     "RichExplorer",
@@ -73,5 +16,3 @@
     "referenceable",
     "explorable_and_referenceable",
 ]
-
-__version__ = "0.1.0"

src/deepset_mcp/tools/tokonomics/decorators.py

@@ -20,7 +20,7 @@
 from glom import GlomError, glom
 
 from deepset_mcp.tools.tokonomics.explorer import RichExplorer
-from deepset_mcp.tools.tokonomics.object_store import Explorable, ObjectStore
+from deepset_mcp.tools.tokonomics.object_store import ObjectStore
 
 F = TypeVar("F", bound=Callable[..., Any])
 
@@ -148,26 +148,29 @@ def decorator(func: F) -> F:
         if inspect.iscoroutinefunction(func):
 
             @wraps(func)
-            async def async_wrapper(*args: Any, **kwargs: Any) -> Explorable[Any]:
+            async def async_wrapper(*args: Any, **kwargs: Any) -> str:
                 result = await func(*args, **kwargs)
                 obj_id = object_store.put(result)
                 preview = explorer.explore(obj_id)
-                return Explorable(obj_id, result, preview)
+
+                return preview
 
             # Enhance docstring
             async_wrapper.__doc__ = _enhance_docstring_for_explorable(func.__doc__ or "", func.__name__)
+            async_wrapper.__annotations__["return"] = str
             return async_wrapper  # type: ignore[return-value]
         else:
 
             @wraps(func)
-            def sync_wrapper(*args: Any, **kwargs: Any) -> Explorable[Any]:
+            def sync_wrapper(*args: Any, **kwargs: Any) -> str:
                 result = func(*args, **kwargs)
                 obj_id = object_store.put(result)
                 preview = explorer.explore(obj_id)
-                return Explorable(obj_id, result, preview)
+                return preview
 
             # Enhance docstring
             sync_wrapper.__doc__ = _enhance_docstring_for_explorable(func.__doc__ or "", func.__name__)
+            sync_wrapper.__annotations__["return"] = str
             return sync_wrapper  # type: ignore[return-value]
 
     return decorator

src/deepset_mcp/tools/tokonomics/explorer.py

@@ -91,7 +91,7 @@ def explore(self, obj_id: str, path: str = "") -> str:
         else:
             body = self._get_pretty_repr(obj)
 
-        return f"{header}\n\n{body}"
+        return f"{header}\n\n" + body
 
     def search(self, obj_id: str, pattern: str, path: str = "", case_sensitive: bool = False) -> str:
         """Search for a pattern within a string object.
@@ -162,21 +162,21 @@ def slice(self, obj_id: str, start: int = 0, end: int | None = None, path: str =
 
         # Handle string slicing
         if isinstance(obj, str):
-            sliced: str | list[Any] | tuple[Any] = obj[start:end]
+            sliced_str: str = obj[start:end]
             actual_end = end if end is not None else len(obj)
-            body = f"String slice [{start}:{actual_end}] of length {len(sliced)}:\n\n{sliced}"
-            return f"{header}\n\n{body}"
+            body = f"String slice [{start}:{actual_end}] of length {len(sliced_str)}:\n\n{sliced_str}"
+            return f"{header}\n\n" + body
 
         # Handle list/tuple slicing
         elif isinstance(obj, list | tuple):
-            sliced = obj[start:end]
+            sliced_list = obj[start:end]
             actual_end = end if end is not None else len(obj)
 
             # Use Pretty to render the sliced list with current settings
             with self.console.capture() as cap:
                 self.console.print(
                     Pretty(
-                        sliced,
+                        sliced_list,
                         max_depth=self.max_depth,
                         max_length=None,  # Show all items in the slice
                         max_string=self.max_string_length,
@@ -187,10 +187,10 @@ def slice(self, obj_id: str, start: int = 0, end: int | None = None, path: str =
             type_name = type(obj).__name__
             body = (
                 f"{type_name.capitalize()} slice [{start}:{actual_end}] "
-                f"(showing {len(sliced)} of {len(obj)} items):\n\n"
+                f"(showing {len(sliced_list)} of {len(obj)} items):\n\n"
                 f"{cap.get().rstrip()}"
             )
-            return f"{header}\n\n{body}"
+            return f"{header}\n\n" + body
 
         else:
             return f"{header}\n\nObject of type {type(obj).__name__} does not support slicing"

src/deepset_mcp/tools/tokonomics/object_store.py

@@ -2,86 +2,19 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-"""
-Tokonomics: Explorable and Referenceable Tools.
-
-===============================================
-
-A library that equips LLM‑agents with:
-
-* TTL‑based object storage
-* Rich object exploration & reference passing
-* Smart decorators for explorable outputs and referenceable inputs
-* Strict typing / signature preservation (incl. *async* callables)
-* ReST‑style docstring enhancement
-* Configurable preview truncation (`max_bytes`) and a user‑supplied
-  `preview_callback` for custom renderings (e.g. pandas.DataFrame)
-"""
-
 from __future__ import annotations
 
 import logging
 import time
 import uuid
 from typing import (
     Any,
-    Generic,
     Protocol,
-    TypeVar,
 )
 
 import orjson
 
 logger = logging.getLogger(__name__)
-# =============================================================================
-# 1 · Generic return‑value wrapper
-# =============================================================================
-
-_T = TypeVar("_T")
-
-
-class Explorable(Generic[_T]):
-    """
-    Wrapper returned by ``@explorable`` decorated tools.
-
-    Attributes
-    ----------
-    obj_id :
-        The internal identifier of the stored object.
-    value :
-        The original, *unmodified* object returned by the wrapped tool.
-    preview :
-        Rich‑rendered string generated by the explorer.
-    """
-
-    __slots__ = ("obj_id", "value", "_preview")
-
-    def __init__(self, obj_id: str, value: _T, preview: str) -> None:
-        """Initialize Explorable wrapper with object ID, value, and preview."""
-        self.obj_id = obj_id
-        self.value: _T = value
-        self._preview = preview
-
-    # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
-    # Representations
-    # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
-
-    def __str__(self) -> str:
-        """Return the preview string representation."""
-        return self._preview
-
-    __repr__ = __str__
-
-    # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
-    # Convenience for notebooks / REPLs
-    # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
-
-    _ipython_display_ = __str__  # Jupyter friendly
-
-
-# =============================================================================
-# 2 · ObjectStore Backend Protocol
-# =============================================================================
 
 
 class ObjectStoreBackend(Protocol):
@@ -178,11 +111,6 @@ def delete(self, key: str) -> bool:
         return bool(self._client.delete(key))
 
 
-# =============================================================================
-# 3 · Time‑to‑live based object store
-# =============================================================================
-
-
 class ObjectStore:
     """JSON-based object store with pluggable backends."""