casual-mcp 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

casual_mcp/__init__.py

@@ -1,6 +1,7 @@
 from importlib.metadata import version
 
 from . import models
+from .models.chat_stats import ChatStats, TokenUsageStats, ToolCallStats
 
 __version__ = version("casual-mcp")
 from .mcp_tool_chat import McpToolChat
@@ -17,4 +18,7 @@ __all__ = [
     "load_mcp_client",
     "render_system_prompt",
     "models",
+    "ChatStats",
+    "TokenUsageStats",
+    "ToolCallStats",
 ]

casual_mcp/main.py

@@ -45,28 +45,54 @@ class GenerateRequest(BaseModel):
     model: str = Field(title="Model to use")
     system_prompt: str | None = Field(default=None, title="System Prompt to use")
     prompt: str = Field(title="User Prompt")
+    include_stats: bool = Field(default=False, title="Include usage statistics in response")
 
 
 class ChatRequest(BaseModel):
     model: str = Field(title="Model to use")
     system_prompt: str | None = Field(default=None, title="System Prompt to use")
     messages: list[ChatMessage] = Field(title="Previous messages to supply to the LLM")
+    include_stats: bool = Field(default=False, title="Include usage statistics in response")
 
 
 @app.post("/chat")
 async def chat(req: ChatRequest) -> dict[str, Any]:
-    chat = await get_chat(req.model, req.system_prompt)
-    messages = await chat.chat(req.messages)
+    chat_instance = await get_chat(req.model, req.system_prompt)
+    messages = await chat_instance.chat(req.messages)
 
-    return {"messages": messages, "response": messages[-1].content}
+    if not messages:
+        error_result: dict[str, Any] = {"messages": [], "response": ""}
+        if req.include_stats:
+            error_result["stats"] = chat_instance.get_stats()
+        raise HTTPException(
+            status_code=500,
+            detail={"error": "No response generated", **error_result},
+        )
+
+    result: dict[str, Any] = {"messages": messages, "response": messages[-1].content}
+    if req.include_stats:
+        result["stats"] = chat_instance.get_stats()
+    return result
 
 
 @app.post("/generate")
 async def generate(req: GenerateRequest) -> dict[str, Any]:
-    chat = await get_chat(req.model, req.system_prompt)
-    messages = await chat.generate(req.prompt, req.session_id)
-
-    return {"messages": messages, "response": messages[-1].content}
+    chat_instance = await get_chat(req.model, req.system_prompt)
+    messages = await chat_instance.generate(req.prompt, req.session_id)
+
+    if not messages:
+        error_result: dict[str, Any] = {"messages": [], "response": ""}
+        if req.include_stats:
+            error_result["stats"] = chat_instance.get_stats()
+        raise HTTPException(
+            status_code=500,
+            detail={"error": "No response generated", **error_result},
+        )
+
+    result: dict[str, Any] = {"messages": messages, "response": messages[-1].content}
+    if req.include_stats:
+        result["stats"] = chat_instance.get_stats()
+    return result
 
 
 @app.get("/generate/session/{session_id}")

casual_mcp/mcp_tool_chat.py

@@ -14,6 +14,7 @@ from fastmcp import Client
 
 from casual_mcp.convert_tools import tools_from_mcp
 from casual_mcp.logging import get_logger
+from casual_mcp.models.chat_stats import ChatStats
 from casual_mcp.tool_cache import ToolCache
 from casual_mcp.utils import format_tool_call_result
 
@@ -50,12 +51,35 @@ class McpToolChat:
         self.system = system
         self.tool_cache = tool_cache or ToolCache(mcp_client)
         self._tool_cache_version = -1
+        self._last_stats: ChatStats | None = None
 
     @staticmethod
     def get_session(session_id: str) -> list[ChatMessage] | None:
         global sessions
         return sessions.get(session_id)
 
+    def get_stats(self) -> ChatStats | None:
+        """
+        Get usage statistics from the last chat() or generate() call.
+
+        Returns None if no calls have been made yet.
+        Stats are reset at the start of each new chat()/generate() call.
+        """
+        return self._last_stats
+
+    def _extract_server_from_tool_name(self, tool_name: str) -> str:
+        """
+        Extract server name from a tool name.
+
+        With multiple servers, fastmcp prefixes tools as "serverName_toolName".
+        With a single server, tools are not prefixed.
+
+        Returns the server name or "default" if it cannot be determined.
+        """
+        if "_" in tool_name:
+            return tool_name.split("_", 1)[0]
+        return "default"
+
     async def generate(self, prompt: str, session_id: str | None = None) -> list[ChatMessage]:
         # Fetch the session if we have a session ID
         messages: list[ChatMessage]
@@ -84,6 +108,9 @@ class McpToolChat:
     async def chat(self, messages: list[ChatMessage]) -> list[ChatMessage]:
         tools = await self.tool_cache.get_tools()
 
+        # Reset stats at the start of each chat
+        self._last_stats = ChatStats()
+
         # Add a system message if required
         has_system_message = any(message.role == "system" for message in messages)
         if self.system and not has_system_message:
@@ -97,6 +124,15 @@ class McpToolChat:
             logger.info("Calling the LLM")
             ai_message = await self.provider.chat(messages=messages, tools=tools_from_mcp(tools))
 
+            # Accumulate token usage stats
+            self._last_stats.llm_calls += 1
+            usage = self.provider.get_usage()
+            if usage:
+                prompt_tokens = getattr(usage, "prompt_tokens", 0) or 0
+                completion_tokens = getattr(usage, "completion_tokens", 0) or 0
+                self._last_stats.tokens.prompt_tokens += prompt_tokens
+                self._last_stats.tokens.completion_tokens += completion_tokens
+
             # Add the assistant's message
             response_messages.append(ai_message)
             messages.append(ai_message)
@@ -108,6 +144,16 @@ class McpToolChat:
             logger.info(f"Executing {len(ai_message.tool_calls)} tool calls")
             result_count = 0
             for tool_call in ai_message.tool_calls:
+                # Track tool call stats
+                tool_name = tool_call.function.name
+                self._last_stats.tool_calls.by_tool[tool_name] = (
+                    self._last_stats.tool_calls.by_tool.get(tool_name, 0) + 1
+                )
+                server_name = self._extract_server_from_tool_name(tool_name)
+                self._last_stats.tool_calls.by_server[server_name] = (
+                    self._last_stats.tool_calls.by_server.get(server_name, 0) + 1
+                )
+
                 try:
                     result = await self.execute(tool_call)
                 except Exception as e:
@@ -148,16 +194,35 @@ class McpToolChat:
         logger.debug(f"Tool Call Result: {result}")
 
         result_format = os.getenv("TOOL_RESULT_FORMAT", "result")
-        # Extract text content from result (handle both TextContent and other content types)
-        if not result.content:
+
+        # Prefer structuredContent when available (machine-readable format)
+        # Note: MCP types use camelCase (structuredContent), mypy stubs may differ
+        structured = getattr(result, "structuredContent", None)
+        if structured is not None:
+            try:
+                content_text = json.dumps(structured)
+            except (TypeError, ValueError):
+                content_text = str(structured)
+        elif not result.content:
             content_text = "[No content returned]"
         else:
-            content_item = result.content[0]
-            if hasattr(content_item, "text"):
-                content_text = content_item.text
-            else:
-                # Handle non-text content (e.g., ImageContent)
-                content_text = f"[Non-text content: {type(content_item).__name__}]"
+            # Fall back to processing content items
+            content_parts: list[Any] = []
+            for content_item in result.content:
+                if content_item.type == "text":
+                    try:
+                        parsed = json.loads(content_item.text)
+                        content_parts.append(parsed)
+                    except json.JSONDecodeError:
+                        content_parts.append(content_item.text)
+                elif hasattr(content_item, "mimeType"):
+                    # Image or audio content
+                    content_parts.append(f"[{content_item.type}: {content_item.mimeType}]")
+                else:
+                    content_parts.append(str(content_item))
+
+            content_text = json.dumps(content_parts)
+
         content = format_tool_call_result(tool_call, content_text, style=result_format)
 
         return ToolResultMessage(

casual_mcp/models/__init__.py

@@ -7,6 +7,11 @@ from casual_llm import (
     UserMessage,
 )
 
+from .chat_stats import (
+    ChatStats,
+    TokenUsageStats,
+    ToolCallStats,
+)
 from .mcp_server_config import (
     McpServerConfig,
     RemoteServerConfig,
@@ -25,6 +30,9 @@ __all__ = [
     "ToolResultMessage",
     "SystemMessage",
     "ChatMessage",
+    "ChatStats",
+    "TokenUsageStats",
+    "ToolCallStats",
     "McpModelConfig",
     "OllamaModelConfig",
     "OpenAIModelConfig",

casual_mcp/models/chat_stats.py

@@ -0,0 +1,37 @@
+"""Usage statistics models for chat sessions."""
+
+from pydantic import BaseModel, Field, computed_field
+
+
+class TokenUsageStats(BaseModel):
+    """Token usage statistics accumulated across all LLM calls."""
+
+    prompt_tokens: int = Field(default=0, ge=0)
+    completion_tokens: int = Field(default=0, ge=0)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def total_tokens(self) -> int:
+        """Total tokens (prompt + completion)."""
+        return self.prompt_tokens + self.completion_tokens
+
+
+class ToolCallStats(BaseModel):
+    """Statistics about tool calls during a chat session."""
+
+    by_tool: dict[str, int] = Field(default_factory=dict)
+    by_server: dict[str, int] = Field(default_factory=dict)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def total(self) -> int:
+        """Total number of tool calls made."""
+        return sum(self.by_tool.values())
+
+
+class ChatStats(BaseModel):
+    """Combined statistics from a chat session."""
+
+    tokens: TokenUsageStats = Field(default_factory=TokenUsageStats)
+    tool_calls: ToolCallStats = Field(default_factory=ToolCallStats)
+    llm_calls: int = Field(default=0, ge=0, description="Number of LLM calls made")

{casual_mcp-0.5.0.dist-info → casual_mcp-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: casual-mcp
-Version: 0.5.0
+Version: 0.6.0
 Summary: Multi-server MCP client for LLM tool orchestration
 Author: Alex Stansfield
 License: MIT
@@ -10,7 +10,7 @@ Project-URL: Issue Tracker, https://github.com/casualgenius/casual-mcp/issues
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: casual-llm[openai]>=0.4.2
+Requires-Dist: casual-llm[openai]>=0.4.3
 Requires-Dist: dateparser>=1.2.1
 Requires-Dist: fastapi>=0.115.12
 Requires-Dist: fastmcp>=2.12.4
@@ -33,6 +33,7 @@ It includes:
 - ✅ A multi-server MCP client using [FastMCP](https://github.com/jlowin/fastmcp)
 - ✅ Provider support for OpenAI and Ollama (powered by [casual-llm](https://github.com/AlexStansfield/casual-llm))
 - ✅ A recursive tool-calling chat loop
+- ✅ Usage statistics tracking (tokens, tool calls, LLM calls)
 - ✅ System prompt templating with Jinja2
 - ✅ A basic API exposing a chat endpoint
 
@@ -40,6 +41,7 @@ It includes:
 
 - Plug-and-play multi-server tool orchestration
 - OpenAI and Ollama LLM providers (via casual-llm)
+- Usage statistics tracking (tokens, tool calls, LLM calls)
 - Prompt templating with Jinja2
 - Configurable via JSON
 - CLI and API access
@@ -253,8 +255,39 @@ messages = [
   UserMessage(content="What time is it in London?")
 ]
 response = await chat.chat(messages)
+
+# Get usage statistics from the last call
+stats = chat.get_stats()
+if stats:
+    print(f"Tokens used: {stats.tokens.total_tokens}")
+    print(f"Tool calls: {stats.tool_calls.total}")
+    print(f"LLM calls: {stats.llm_calls}")
 ```
 
+#### Usage Statistics
+
+After calling `chat()` or `generate()`, you can retrieve usage statistics via `get_stats()`:
+
+```python
+response = await chat.chat(messages)
+stats = chat.get_stats()
+
+# Token usage (accumulated across all LLM calls in the agentic loop)
+stats.tokens.prompt_tokens      # Input tokens
+stats.tokens.completion_tokens  # Output tokens
+stats.tokens.total_tokens       # Total (computed)
+
+# Tool call stats
+stats.tool_calls.by_tool   # Dict of tool name -> call count, e.g. {"math_add": 2}
+stats.tool_calls.by_server # Dict of server name -> call count, e.g. {"math": 2}
+stats.tool_calls.total     # Total tool calls (computed)
+
+# LLM call count
+stats.llm_calls  # Number of LLM calls made (1 = no tools, 2+ = tool loop)
+```
+
+Stats are reset at the start of each new `chat()` or `generate()` call. Returns `None` if no calls have been made yet.
+
 #### `ProviderFactory`
 Instantiates LLM providers (from casual-llm) based on the selected model config.
 
@@ -294,6 +327,9 @@ Exported from `casual_mcp.models`:
 - `RemoteServerConfig`
 - `OpenAIModelConfig`
 - `OllamaModelConfig`
+- `ChatStats`
+- `TokenUsageStats`
+- `ToolCallStats`
 
 Use these types to build valid configs:
 
@@ -582,9 +618,10 @@ casual-mcp serve --host 0.0.0.0 --port 8000
 #### Request Body:
 - `model`: the LLM model to use
 - `messages`: list of chat messages (system, assistant, user, etc) that you can pass to the api, allowing you to keep your own chat session in the client calling the api
+- `include_stats`: (optional, default: `false`) include usage statistics in the response
 
 #### Example:
-```
+```json
 {
     "model": "gpt-4.1-nano",
     "messages": [
@@ -592,13 +629,35 @@ casual-mcp serve --host 0.0.0.0 --port 8000
             "role": "user",
             "content": "can you explain what the word consistent means?"
         }
-    ]
+    ],
+    "include_stats": true
+}
+```
+
+#### Response with stats:
+```json
+{
+    "messages": [...],
+    "response": "Consistent means...",
+    "stats": {
+        "tokens": {
+            "prompt_tokens": 150,
+            "completion_tokens": 75,
+            "total_tokens": 225
+        },
+        "tool_calls": {
+            "by_tool": {"words_define": 1},
+            "by_server": {"words": 1},
+            "total": 1
+        },
+        "llm_calls": 2
+    }
 }
 ```
 
 ### Generate
 
-The generate endpoint allows you to send a user prompt as a string. 
+The generate endpoint allows you to send a user prompt as a string.
 
 It also support sessions that keep a record of all messages in the session and feeds them back into the LLM for context. Sessions are stored in memory so are cleared when the server is restarted
 
@@ -606,15 +665,17 @@ It also support sessions that keep a record of all messages in the session and f
 
 ####  Request Body:
 - `model`: the LLM model to use
-- `prompt`: the user prompt 
+- `prompt`: the user prompt
 - `session_id`: an optional ID that stores all the messages from the session and provides them back to the LLM for context
+- `include_stats`: (optional, default: `false`) include usage statistics in the response
 
 #### Example:
-```
+```json
 {
     "session_id": "my-session",
     "model": "gpt-4o-mini",
-    "prompt": "can you explain what the word consistent means?"
+    "prompt": "can you explain what the word consistent means?",
+    "include_stats": true
 }
 ```
 

{casual_mcp-0.5.0.dist-info → casual_mcp-0.6.0.dist-info}/RECORD

@@ -1,20 +1,21 @@
-casual_mcp/__init__.py,sha256=X7xE1PVtbzkPo_2ad6gEPuDLWGLPkQ1WQjSRVgVuIZc,464
+casual_mcp/__init__.py,sha256=eeI1TIj8Cu-H4OMV64LaNqVqo4wSFaGu7215hJeN_HM,598
 casual_mcp/cli.py,sha256=2-0sTxfNfQSukBtg0Xs9P6VrAMZ89SqJ9VJzOM68d-o,2129
 casual_mcp/convert_tools.py,sha256=mlH18DTGGeWb0Vxfj1cUSMhTGRE9z8q_xWrVXvpg3mE,1742
 casual_mcp/logging.py,sha256=S2XpLIKHHDtmru_YBFLdMamdmYRm16Yw3tshE3g3Wqg,932
-casual_mcp/main.py,sha256=UQJN5D0WGdimTrwNzVqc_FaTANWar8enBobIULp6EqE,3199
-casual_mcp/mcp_tool_chat.py,sha256=FIEgK8629AIgT9X6zTsLgKC3u3R00v_St-QF76WC0JY,5703
+casual_mcp/main.py,sha256=aI3isW0Wzny_iubx8HlNgBVvYEeBe-Jrrdbp80oYmk4,4299
+casual_mcp/mcp_tool_chat.py,sha256=Evc5LMfUYicl7jlix42QURYaq0cI2CIUg0q-344cjUg,8401
 casual_mcp/provider_factory.py,sha256=Jp2HQOJdlDDed-hfZf1drEVbw0kpZSE0TN9G0Dcp4w8,1260
 casual_mcp/tool_cache.py,sha256=VE599sF7vHH6megcueqVxCZavvTcoFDoZu2QuZM3cYA,3161
 casual_mcp/utils.py,sha256=XxzPxQ3j97edeCRXtoO8lJS9R0JYOa25p2MJNwGapJA,3201
-casual_mcp/models/__init__.py,sha256=yAYtRqA_cJqdOELYFqAXLxmyt3ld6LIWgezceu0PE1U,642
+casual_mcp/models/__init__.py,sha256=byhteS6fueIdtoaQYL2w5hcBJmJhXF7X7YhGslvscco,786
+casual_mcp/models/chat_stats.py,sha256=ZjeZ_ckx-SfioYs39NAaQxK6qPG9SlFlrB7j7jHZ40w,1221
 casual_mcp/models/config.py,sha256=LcqtfW3w7iqrT3FnW50L1mgqAvD_OsYk4ySBZZVV-GI,300
 casual_mcp/models/generation_error.py,sha256=abDAahS2fhYkS-ARng1Tk7oudoAO4imkoKYcC9PHT2U,272
 casual_mcp/models/mcp_server_config.py,sha256=0OHsHUEKxRoCl21lsye4E5GoCNmdZWIZCOOthcTpdsE,539
 casual_mcp/models/model_config.py,sha256=59Y7MvcboPKdAilSwUyeC7lfRm4aYkFhZ5c8EVRP5ys,425
-casual_mcp-0.5.0.dist-info/licenses/LICENSE,sha256=U3Zu2tkrh5vXdy7gIdE8WJGM9D4gGp3hohAAWdre-yo,1058
-casual_mcp-0.5.0.dist-info/METADATA,sha256=9e4sknE7ksYxSeoNs_R8-ftYzjBuqqVCZjmY_C6fY3s,20290
-casual_mcp-0.5.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-casual_mcp-0.5.0.dist-info/entry_points.txt,sha256=X48Np2cwl-SlRQdV26y2vPZ-2tJaODgZeVtfpHho-zg,50
-casual_mcp-0.5.0.dist-info/top_level.txt,sha256=K4CiI0Jf8PHICjuQVm32HuNMB44kp8Lb02bbbdiH5bo,11
-casual_mcp-0.5.0.dist-info/RECORD,,
+casual_mcp-0.6.0.dist-info/licenses/LICENSE,sha256=U3Zu2tkrh5vXdy7gIdE8WJGM9D4gGp3hohAAWdre-yo,1058
+casual_mcp-0.6.0.dist-info/METADATA,sha256=GQLuEXfducugyuUHjB3qklz8FAOZ7go3PQ0d7Pqb2ZI,22218
+casual_mcp-0.6.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+casual_mcp-0.6.0.dist-info/entry_points.txt,sha256=X48Np2cwl-SlRQdV26y2vPZ-2tJaODgZeVtfpHho-zg,50
+casual_mcp-0.6.0.dist-info/top_level.txt,sha256=K4CiI0Jf8PHICjuQVm32HuNMB44kp8Lb02bbbdiH5bo,11
+casual_mcp-0.6.0.dist-info/RECORD,,