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

casual_mcp/__init__.py

@@ -1,13 +1,24 @@
+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
-from .providers.provider_factory import ProviderFactory
+from .provider_factory import ProviderFactory
+from .tool_cache import ToolCache
 from .utils import load_config, load_mcp_client, render_system_prompt
 
 __all__ = [
+    "__version__",
     "McpToolChat",
     "ProviderFactory",
+    "ToolCache",
     "load_config",
     "load_mcp_client",
     "render_system_prompt",
     "models",
+    "ChatStats",
+    "TokenUsageStats",
+    "ToolCallStats",
 ]

casual_mcp/cli.py

@@ -1,6 +1,10 @@
 import asyncio
+from typing import Any
+
+import mcp
 import typer
 import uvicorn
+from fastmcp import Client
 from rich.console import Console
 from rich.table import Table
 
@@ -10,63 +14,58 @@ from casual_mcp.utils import load_config, load_mcp_client
 app = typer.Typer()
 console = Console()
 
+
 @app.command()
-def serve(host: str = "0.0.0.0", port: int = 8000, reload: bool = True):
+def serve(host: str = "0.0.0.0", port: int = 8000, reload: bool = True) -> None:
     """
     Start the Casual MCP API server.
     """
-    uvicorn.run(
-        "casual_mcp.main:app",
-        host=host,
-        port=port,
-        reload=reload,
-        app_dir="src"
-    )
+    uvicorn.run("casual_mcp.main:app", host=host, port=port, reload=reload, app_dir="src")
+
 
 @app.command()
-def servers():
+def servers() -> None:
     """
     Return a table of all configured servers
     """
-    config = load_config('casual_mcp_config.json')
+    config = load_config("casual_mcp_config.json")
     table = Table("Name", "Type", "Command / Url", "Env")
 
     for name, server in config.servers.items():
-        type = 'stdio'
+        server_type = "stdio"
         if isinstance(server, RemoteServerConfig):
-            type = 'remote'
+            server_type = "remote"
 
-        path = ''
+        path = ""
         if isinstance(server, RemoteServerConfig):
             path = server.url
         else:
             path = f"{server.command} {' '.join(server.args)}"
-        env = ''
+        env = ""
 
-        table.add_row(name, type, path, env)
+        table.add_row(name, server_type, path, env)
 
     console.print(table)
 
+
 @app.command()
-def models():
+def models() -> None:
     """
     Return a table of all configured models
     """
-    config = load_config('casual_mcp_config.json')
+    config = load_config("casual_mcp_config.json")
     table = Table("Name", "Provider", "Model", "Endpoint")
 
     for name, model in config.models.items():
-        endpoint = ''
-        if model.provider == 'openai':
-            endpoint = model.endpoint or ''
-
+        endpoint = model.endpoint or ""
         table.add_row(name, model.provider, model.model, str(endpoint))
 
     console.print(table)
 
+
 @app.command()
-def tools():
-    config = load_config('casual_mcp_config.json')
+def tools() -> None:
+    config = load_config("casual_mcp_config.json")
     mcp_client = load_mcp_client(config)
     table = Table("Name", "Description")
     # async with mcp_client:
@@ -76,9 +75,10 @@ def tools():
     console.print(table)
 
 
-async def get_tools(client):
+async def get_tools(client: Client[Any]) -> list[mcp.Tool]:
     async with client:
         return await client.list_tools()
 
+
 if __name__ == "__main__":
     app()

casual_mcp/convert_tools.py

@@ -0,0 +1,68 @@
+import mcp
+from casual_llm import Tool
+
+from casual_mcp.logging import get_logger
+
+logger = get_logger("convert_tools")
+
+
+# MCP format converters (for interop with MCP libraries)
+def tool_from_mcp(mcp_tool: mcp.Tool) -> Tool:
+    """
+    Convert an MCP Tool to casual-llm Tool format.
+
+    Args:
+        mcp_tool: MCP Tool object (from mcp library)
+
+    Returns:
+        casual-llm Tool instance
+
+    Raises:
+        ValueError: If MCP tool is missing required fields
+
+    Examples:
+        >>> # Assuming mcp_tool is an MCP Tool object
+        >>> # tool = tool_from_mcp(mcp_tool)
+        >>> # assert tool.name == mcp_tool.name
+        pass
+    """
+    if not mcp_tool.name or not mcp_tool.description:
+        raise ValueError(
+            f"MCP tool missing required fields: "
+            f"name={mcp_tool.name}, description={mcp_tool.description}"
+        )
+
+    input_schema = getattr(mcp_tool, "inputSchema", {})
+    if not isinstance(input_schema, dict):
+        input_schema = {}
+
+    return Tool.from_input_schema(
+        name=mcp_tool.name, description=mcp_tool.description, input_schema=input_schema
+    )
+
+
+def tools_from_mcp(mcp_tools: list[mcp.Tool]) -> list[Tool]:
+    """
+    Convert multiple MCP Tools to casual-llm format.
+
+    Args:
+        mcp_tools: List of MCP Tool objects
+
+    Returns:
+        List of casual-llm Tool instances
+
+    Examples:
+        >>> # tools = tools_from_mcp(mcp_tool_list)
+        >>> # assert len(tools) == len(mcp_tool_list)
+        pass
+    """
+    tools = []
+
+    for mcp_tool in mcp_tools:
+        try:
+            tool = tool_from_mcp(mcp_tool)
+            tools.append(tool)
+        except ValueError as e:
+            logger.warning(f"Skipping invalid MCP tool: {e}")
+
+    return tools

casual_mcp/logging.py

@@ -1,5 +1,4 @@
 import logging
-from typing import Literal
 
 from rich.console import Console
 from rich.logging import RichHandler
@@ -10,7 +9,7 @@ def get_logger(name: str) -> logging.Logger:
 
 
 def configure_logging(
-    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | int = "INFO",
+    level: str | int = "INFO",
     logger: logging.Logger | None = None,
 ) -> None:
     if logger is None:
@@ -27,4 +26,9 @@ def configure_logging(
         logger.removeHandler(hdlr)
 
     logger.addHandler(handler)
+
+    # Set logging level on FastMCP and MCP libraries
+    logging.getLogger("fastmcp").setLevel(level)
+    logging.getLogger("mcp").setLevel(level)
+
     logger.info("Logging Configured")

casual_mcp/main.py

@@ -1,26 +1,28 @@
 import os
-import sys
-from pathlib import Path
+from typing import Any
 
+from casual_llm import ChatMessage
 from dotenv import load_dotenv
 from fastapi import FastAPI, HTTPException
 from pydantic import BaseModel, Field
 
 from casual_mcp import McpToolChat
 from casual_mcp.logging import configure_logging, get_logger
-from casual_mcp.models.messages import ChatMessage
-from casual_mcp.providers.provider_factory import ProviderFactory
+from casual_mcp.provider_factory import ProviderFactory
+from casual_mcp.tool_cache import ToolCache
 from casual_mcp.utils import load_config, load_mcp_client, render_system_prompt
 
+# Load environment variables
 load_dotenv()
 
 # Configure logging
-configure_logging(os.getenv("LOG_LEVEL", 'INFO'))
+configure_logging(os.getenv("LOG_LEVEL", "INFO"))
 logger = get_logger("main")
 
 config = load_config("casual_mcp_config.json")
 mcp_client = load_mcp_client(config)
-provider_factory = ProviderFactory(mcp_client)
+tool_cache = ToolCache(mcp_client)
+provider_factory = ProviderFactory()
 
 app = FastAPI()
 
@@ -39,63 +41,62 @@ Always present information as current and factual.
 
 
 class GenerateRequest(BaseModel):
-    session_id: str | None = Field(
-        default=None, title="Session to use"
-    )
-    model: str = Field(
-        title="Model to user"
-    )
-    system_prompt: str | None = Field(
-        default=None, title="System Prompt to use"
-    )
-    prompt: str = Field(
-        title="User Prompt"
-    )
+    session_id: str | None = Field(default=None, title="Session to use")
+    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 user"
-    )
-    system_prompt: str | None = Field(
-        default=None, title="System Prompt to use"
-    )
-    messages: list[ChatMessage] = Field(
-        title="Previous messages to supply to the LLM"
-    )
-
-sys.path.append(str(Path(__file__).parent.resolve()))
-
-
+    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):
-    chat = await get_chat(req.model, req.system_prompt)
-    messages = await chat.chat(req.messages)
+async def chat(req: ChatRequest) -> dict[str, Any]:
+    chat_instance = await get_chat(req.model, req.system_prompt)
+    messages = await chat_instance.chat(req.messages)
 
-    return {
-        "messages": messages,
-        "response": messages[len(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):
-    chat = await get_chat(req.model, req.system_prompt)
-    messages = await chat.generate(
-        req.prompt,
-        req.session_id
-    )
+async def generate(req: GenerateRequest) -> dict[str, Any]:
+    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},
+        )
 
-    return {
-        "messages": messages,
-        "response": messages[len(messages) - 1].content
-    }
+    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}")
-async def get_generate_session(session_id):
+async def get_generate_session(session_id: str) -> list[ChatMessage]:
     session = McpToolChat.get_session(session_id)
     if not session:
         raise HTTPException(status_code=404, detail="Session not found")
@@ -106,17 +107,14 @@ async def get_generate_session(session_id):
 async def get_chat(model: str, system: str | None = None) -> McpToolChat:
     # Get Provider from Model Config
     model_config = config.models[model]
-    provider = await provider_factory.get_provider(model, model_config)
+    provider = provider_factory.get_provider(model, model_config)
 
     # Get the system prompt
     if not system:
-        if (model_config.template):
-            async with mcp_client:
-                system = render_system_prompt(
-                    f"{model_config.template}.j2",
-                    await mcp_client.list_tools()
-                )
+        if model_config.template:
+            tools = await tool_cache.get_tools()
+            system = render_system_prompt(f"{model_config.template}.j2", tools)
         else:
             system = default_system_prompt
 
-    return McpToolChat(mcp_client, provider, system)
+    return McpToolChat(mcp_client, provider, system, tool_cache=tool_cache)

casual_mcp/mcp_tool_chat.py

@@ -1,62 +1,92 @@
 import json
 import os
+from typing import Any
 
-from fastmcp import Client
-
-from casual_mcp.logging import get_logger
-from casual_mcp.models.messages import (
+from casual_llm import (
+    AssistantToolCall,
     ChatMessage,
+    LLMProvider,
     SystemMessage,
     ToolResultMessage,
     UserMessage,
 )
-from casual_mcp.models.tool_call import AssistantToolCall
-from casual_mcp.providers.provider_factory import LLMProvider
+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
 
 logger = get_logger("mcp_tool_chat")
 sessions: dict[str, list[ChatMessage]] = {}
 
 
-def get_session_messages(session_id: str | None):
+def get_session_messages(session_id: str) -> list[ChatMessage]:
     global sessions
 
-    if not sessions.get(session_id):
+    if session_id not in sessions:
         logger.info(f"Starting new session {session_id}")
         sessions[session_id] = []
     else:
-        logger.info(
-            f"Retrieving session {session_id} of length {len(sessions[session_id])}"
-        )
+        logger.info(f"Retrieving session {session_id} of length {len(sessions[session_id])}")
     return sessions[session_id].copy()
 
 
-def add_messages_to_session(session_id: str, messages: list[ChatMessage]):
+def add_messages_to_session(session_id: str, messages: list[ChatMessage]) -> None:
     global sessions
     sessions[session_id].extend(messages.copy())
 
 
 class McpToolChat:
-    def __init__(self, mcp_client: Client, provider: LLMProvider, system: str = None):
+    def __init__(
+        self,
+        mcp_client: Client[Any],
+        provider: LLMProvider,
+        system: str | None = None,
+        tool_cache: ToolCache | None = None,
+    ):
         self.provider = provider
         self.mcp_client = mcp_client
         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) -> list[ChatMessage] | None:
+    def get_session(session_id: str) -> list[ChatMessage] | None:
         global sessions
         return sessions.get(session_id)
 
-    async def generate(
-        self,
-        prompt: str,
-        session_id: str | None = None
-    ) -> list[ChatMessage]:
+    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]
         if session_id:
             messages = get_session_messages(session_id)
         else:
-            messages: list[ChatMessage] = []
+            messages = []
 
         # Add the prompt as a user message
         user_message = UserMessage(content=prompt)
@@ -75,56 +105,75 @@ class McpToolChat:
 
         return response
 
+    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()
 
-    async def chat(
-        self,
-        messages: list[ChatMessage]
-    ) -> list[ChatMessage]:
         # Add a system message if required
-        has_system_message = any(message.role == 'system' for message in messages)
+        has_system_message = any(message.role == "system" for message in messages)
         if self.system and not has_system_message:
             # Insert the system message at the start of the messages
-            logger.debug(f"Adding System Message")
+            logger.debug("Adding System Message")
             messages.insert(0, SystemMessage(content=self.system))
 
         logger.info("Start Chat")
-        async with self.mcp_client:
-            tools = await self.mcp_client.list_tools()
-
         response_messages: list[ChatMessage] = []
         while True:
             logger.info("Calling the LLM")
-            ai_message = await self.provider.generate(messages, tools)
+            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)
 
+            logger.debug(f"Assistant: {ai_message}")
             if not ai_message.tool_calls:
                 break
 
-            if ai_message.tool_calls and len(ai_message.tool_calls) > 0:
-                logger.info(f"Executing {len(ai_message.tool_calls)} tool calls")
-                result_count = 0
-                for tool_call in ai_message.tool_calls:
-                    try:
-                        result = await self.execute(tool_call)
-                    except Exception as e:
-                        logger.error(e)
-                        return messages
-                    if result:
-                        messages.append(result)
-                        response_messages.append(result)
-                        result_count = result_count + 1
-
-                logger.info(f"Added {result_count} tool results")
+            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:
+                    logger.error(
+                        f"Failed to execute tool '{tool_call.function.name}' "
+                        f"(id={tool_call.id}): {e}"
+                    )
+                    continue
+                if result:
+                    messages.append(result)
+                    response_messages.append(result)
+                    result_count = result_count + 1
+
+            logger.info(f"Added {result_count} tool results")
 
         logger.debug(f"Final Response: {response_messages[-1].content}")
 
         return response_messages
 
-
-    async def execute(self, tool_call: AssistantToolCall):
+    async def execute(self, tool_call: AssistantToolCall) -> ToolResultMessage:
         tool_name = tool_call.function.name
         tool_args = json.loads(tool_call.function.arguments)
         try:
@@ -144,8 +193,37 @@ class McpToolChat:
 
         logger.debug(f"Tool Call Result: {result}")
 
-        result_format = os.getenv('TOOL_RESULT_FORMAT', 'result')
-        content = format_tool_call_result(tool_call, result.content[0].text, style=result_format)
+        result_format = os.getenv("TOOL_RESULT_FORMAT", "result")
+
+        # 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:
+            # 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(
             name=tool_call.function.name,