agentic-blocks 0.1.0__tar.gz

agentic_blocks-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Magnus Bjelkenhed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentic_blocks-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: agentic-blocks
+Version: 0.1.0
+Summary: Simple building blocks for agentic AI systems with MCP client and conversation management
+Author-email: Magnus Bjelkenhed <bjelkenhed@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/bjelkenhed/agentic-blocks
+Project-URL: Repository, https://github.com/bjelkenhed/agentic-blocks
+Project-URL: Issues, https://github.com/bjelkenhed/agentic-blocks/issues
+Keywords: ai,mcp,model-control-protocol,agent,llm,openai,conversation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp
+Requires-Dist: requests
+Requires-Dist: python-dotenv
+Requires-Dist: openai
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# Agentic Blocks
+
+Building blocks for agentic systems with a focus on simplicity and ease of use.
+
+## Overview
+
+Agentic Blocks provides clean, simple components for building AI agent systems, specifically focused on:
+
+- **MCP Client**: Connect to Model Control Protocol (MCP) endpoints with a sync-by-default API
+- **Messages**: Manage LLM conversation history with OpenAI-compatible format
+
+Both components follow principles of simplicity, maintainability, and ease of use.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+For development:
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### MCPClient - Connect to MCP Endpoints
+
+The MCPClient provides a unified interface for connecting to different types of MCP endpoints:
+
+```python
+from agentic_blocks import MCPClient
+
+# Connect to an SSE endpoint (sync by default)
+client = MCPClient("https://example.com/mcp/server/sse")
+
+# List available tools
+tools = client.list_tools()
+print(f"Available tools: {len(tools)}")
+
+# Call a tool
+result = client.call_tool("search", {"query": "What is MCP?"})
+print(result)
+```
+
+**Supported endpoint types:**
+- **SSE endpoints**: URLs with `/sse` in the path
+- **HTTP endpoints**: URLs with `/mcp` in the path  
+- **Local scripts**: File paths to Python MCP servers
+
+**Async support for advanced users:**
+```python
+# Async versions available
+tools = await client.list_tools_async()
+result = await client.call_tool_async("search", {"query": "async example"})
+```
+
+### Messages - Manage Conversation History
+
+The Messages class helps build and manage LLM conversations in OpenAI-compatible format:
+
+```python
+from agentic_blocks import Messages
+
+# Initialize with system prompt
+messages = Messages(
+    system_prompt="You are a helpful assistant.",
+    user_prompt="Hello, how can you help me?",
+    add_date_and_time=True
+)
+
+# Add assistant response
+messages.add_assistant_message("I can help you with various tasks!")
+
+# Add tool calls
+tool_call = {
+    "id": "call_123",
+    "type": "function", 
+    "function": {"name": "get_weather", "arguments": '{"location": "Paris"}'}
+}
+messages.add_tool_call(tool_call)
+
+# Add tool response
+messages.add_tool_response("call_123", "The weather in Paris is sunny, 22°C")
+
+# Get messages for LLM API
+conversation = messages.get_messages()
+
+# View readable format
+print(messages)
+```
+
+## Complete Example - Agent with MCP Tools
+
+```python
+from agentic_blocks import MCPClient, Messages
+
+def simple_agent():
+    # Initialize MCP client and conversation
+    client = MCPClient("https://example.com/mcp/server/sse")
+    messages = Messages(
+        system_prompt="You are a helpful research assistant.",
+        add_date_and_time=True
+    )
+    
+    # Get available tools
+    tools = client.list_tools()
+    print(f"Connected to MCP server with {len(tools)} tools")
+    
+    # Simulate user query
+    user_query = "What's the latest news about AI?"
+    messages.add_user_message(user_query)
+    
+    # Agent decides to use a search tool
+    if tools:
+        search_tool = next((t for t in tools if "search" in t["function"]["name"]), None)
+        if search_tool:
+            # Add tool call to messages
+            tool_call = {
+                "id": "search_001",
+                "type": "function",
+                "function": {
+                    "name": search_tool["function"]["name"],
+                    "arguments": '{"query": "latest AI news"}'
+                }
+            }
+            messages.add_tool_call(tool_call)
+            
+            # Execute the tool
+            result = client.call_tool(
+                search_tool["function"]["name"], 
+                {"query": "latest AI news"}
+            )
+            
+            # Add tool response
+            if result["content"]:
+                response_text = result["content"][0]["text"]
+                messages.add_tool_response("search_001", response_text)
+            
+            # Add final assistant response
+            messages.add_assistant_message(
+                "Based on my search, here's what I found about the latest AI news..."
+            )
+    
+    # Print conversation
+    print("\\nConversation:")
+    print(messages)
+    
+    return messages.get_messages()
+
+if __name__ == "__main__":
+    simple_agent()
+```
+
+## Development Principles
+
+This project follows these core principles:
+
+- **Simplicity First**: Keep code simple, readable, and focused on core functionality
+- **Sync-by-Default**: Primary methods are synchronous for ease of use, with optional async versions
+- **Minimal Dependencies**: Avoid over-engineering and complex error handling unless necessary  
+- **Clean APIs**: Prefer straightforward method names and clear parameter expectations
+- **Maintainable Code**: Favor fewer lines of clear code over comprehensive edge case handling
+
+## API Reference
+
+### MCPClient
+
+```python
+MCPClient(endpoint: str, timeout: int = 30)
+```
+
+**Methods:**
+- `list_tools() -> List[Dict]`: Get available tools (sync)
+- `call_tool(name: str, args: Dict) -> Dict`: Call a tool (sync)
+- `list_tools_async() -> List[Dict]`: Async version of list_tools
+- `call_tool_async(name: str, args: Dict) -> Dict`: Async version of call_tool
+
+### Messages
+
+```python
+Messages(system_prompt=None, user_prompt=None, add_date_and_time=False)
+```
+
+**Methods:**
+- `add_system_message(content: str)`: Add system message
+- `add_user_message(content: str)`: Add user message
+- `add_assistant_message(content: str)`: Add assistant message
+- `add_tool_call(tool_call: Dict)`: Add tool call to assistant message
+- `add_tool_response(call_id: str, content: str)`: Add tool response
+- `get_messages() -> List[Dict]`: Get all messages
+- `has_pending_tool_calls() -> bool`: Check for pending tool calls
+
+## Requirements
+
+- Python >= 3.11
+- Dependencies: `mcp`, `requests`, `python-dotenv`, `openai`
+
+## License
+
+MIT

agentic_blocks-0.1.0/README.md

@@ -0,0 +1,201 @@
+# Agentic Blocks
+
+Building blocks for agentic systems with a focus on simplicity and ease of use.
+
+## Overview
+
+Agentic Blocks provides clean, simple components for building AI agent systems, specifically focused on:
+
+- **MCP Client**: Connect to Model Control Protocol (MCP) endpoints with a sync-by-default API
+- **Messages**: Manage LLM conversation history with OpenAI-compatible format
+
+Both components follow principles of simplicity, maintainability, and ease of use.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+For development:
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### MCPClient - Connect to MCP Endpoints
+
+The MCPClient provides a unified interface for connecting to different types of MCP endpoints:
+
+```python
+from agentic_blocks import MCPClient
+
+# Connect to an SSE endpoint (sync by default)
+client = MCPClient("https://example.com/mcp/server/sse")
+
+# List available tools
+tools = client.list_tools()
+print(f"Available tools: {len(tools)}")
+
+# Call a tool
+result = client.call_tool("search", {"query": "What is MCP?"})
+print(result)
+```
+
+**Supported endpoint types:**
+- **SSE endpoints**: URLs with `/sse` in the path
+- **HTTP endpoints**: URLs with `/mcp` in the path  
+- **Local scripts**: File paths to Python MCP servers
+
+**Async support for advanced users:**
+```python
+# Async versions available
+tools = await client.list_tools_async()
+result = await client.call_tool_async("search", {"query": "async example"})
+```
+
+### Messages - Manage Conversation History
+
+The Messages class helps build and manage LLM conversations in OpenAI-compatible format:
+
+```python
+from agentic_blocks import Messages
+
+# Initialize with system prompt
+messages = Messages(
+    system_prompt="You are a helpful assistant.",
+    user_prompt="Hello, how can you help me?",
+    add_date_and_time=True
+)
+
+# Add assistant response
+messages.add_assistant_message("I can help you with various tasks!")
+
+# Add tool calls
+tool_call = {
+    "id": "call_123",
+    "type": "function", 
+    "function": {"name": "get_weather", "arguments": '{"location": "Paris"}'}
+}
+messages.add_tool_call(tool_call)
+
+# Add tool response
+messages.add_tool_response("call_123", "The weather in Paris is sunny, 22°C")
+
+# Get messages for LLM API
+conversation = messages.get_messages()
+
+# View readable format
+print(messages)
+```
+
+## Complete Example - Agent with MCP Tools
+
+```python
+from agentic_blocks import MCPClient, Messages
+
+def simple_agent():
+    # Initialize MCP client and conversation
+    client = MCPClient("https://example.com/mcp/server/sse")
+    messages = Messages(
+        system_prompt="You are a helpful research assistant.",
+        add_date_and_time=True
+    )
+    
+    # Get available tools
+    tools = client.list_tools()
+    print(f"Connected to MCP server with {len(tools)} tools")
+    
+    # Simulate user query
+    user_query = "What's the latest news about AI?"
+    messages.add_user_message(user_query)
+    
+    # Agent decides to use a search tool
+    if tools:
+        search_tool = next((t for t in tools if "search" in t["function"]["name"]), None)
+        if search_tool:
+            # Add tool call to messages
+            tool_call = {
+                "id": "search_001",
+                "type": "function",
+                "function": {
+                    "name": search_tool["function"]["name"],
+                    "arguments": '{"query": "latest AI news"}'
+                }
+            }
+            messages.add_tool_call(tool_call)
+            
+            # Execute the tool
+            result = client.call_tool(
+                search_tool["function"]["name"], 
+                {"query": "latest AI news"}
+            )
+            
+            # Add tool response
+            if result["content"]:
+                response_text = result["content"][0]["text"]
+                messages.add_tool_response("search_001", response_text)
+            
+            # Add final assistant response
+            messages.add_assistant_message(
+                "Based on my search, here's what I found about the latest AI news..."
+            )
+    
+    # Print conversation
+    print("\\nConversation:")
+    print(messages)
+    
+    return messages.get_messages()
+
+if __name__ == "__main__":
+    simple_agent()
+```
+
+## Development Principles
+
+This project follows these core principles:
+
+- **Simplicity First**: Keep code simple, readable, and focused on core functionality
+- **Sync-by-Default**: Primary methods are synchronous for ease of use, with optional async versions
+- **Minimal Dependencies**: Avoid over-engineering and complex error handling unless necessary  
+- **Clean APIs**: Prefer straightforward method names and clear parameter expectations
+- **Maintainable Code**: Favor fewer lines of clear code over comprehensive edge case handling
+
+## API Reference
+
+### MCPClient
+
+```python
+MCPClient(endpoint: str, timeout: int = 30)
+```
+
+**Methods:**
+- `list_tools() -> List[Dict]`: Get available tools (sync)
+- `call_tool(name: str, args: Dict) -> Dict`: Call a tool (sync)
+- `list_tools_async() -> List[Dict]`: Async version of list_tools
+- `call_tool_async(name: str, args: Dict) -> Dict`: Async version of call_tool
+
+### Messages
+
+```python
+Messages(system_prompt=None, user_prompt=None, add_date_and_time=False)
+```
+
+**Methods:**
+- `add_system_message(content: str)`: Add system message
+- `add_user_message(content: str)`: Add user message
+- `add_assistant_message(content: str)`: Add assistant message
+- `add_tool_call(tool_call: Dict)`: Add tool call to assistant message
+- `add_tool_response(call_id: str, content: str)`: Add tool response
+- `get_messages() -> List[Dict]`: Get all messages
+- `has_pending_tool_calls() -> bool`: Check for pending tool calls
+
+## Requirements
+
+- Python >= 3.11
+- Dependencies: `mcp`, `requests`, `python-dotenv`, `openai`
+
+## License
+
+MIT

agentic_blocks-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = [
+    "setuptools>=45",
+    "build",
+]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["agentic_blocks*"]
+
+[tool.setuptools.package-data]
+agentic_blocks = []
+
+[project]
+name = "agentic-blocks"
+version = "0.1.0"
+description = "Simple building blocks for agentic AI systems with MCP client and conversation management"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+keywords = ["ai", "mcp", "model-control-protocol", "agent", "llm", "openai", "conversation"]
+authors = [
+    { name = "Magnus Bjelkenhed", email = "bjelkenhed@gmail.com" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "mcp",
+    "requests",
+    "python-dotenv",
+    "openai",
+]
+
+[project.urls]
+Homepage = "https://github.com/bjelkenhed/agentic-blocks"
+Repository = "https://github.com/bjelkenhed/agentic-blocks"
+Issues = "https://github.com/bjelkenhed/agentic-blocks/issues"
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+]
+dev = [
+    "pytest",
+    "build",
+    "twine",
+]
+
+[dependency-groups]
+dev = [
+    "build>=1.3.0",
+    "twine>=6.1.0",
+]
+

agentic_blocks-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agentic_blocks-0.1.0/src/agentic_blocks/__init__.py

@@ -0,0 +1,8 @@
+"""Agentic Blocks - Building blocks for agentic systems."""
+
+from .mcp_client import MCPClient, MCPEndpointError
+from .messages import Messages
+
+__version__ = "0.1.0"
+
+__all__ = ["MCPClient", "MCPEndpointError", "Messages"]

agentic_blocks-0.1.0/src/agentic_blocks/mcp_client.py

@@ -0,0 +1,262 @@
+"""
+Simplified MCP Client for connecting to MCP endpoints with sync-by-default API.
+"""
+
+import asyncio
+import logging
+import os
+from typing import List, Dict, Any
+from urllib.parse import urlparse
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.sse import sse_client
+from mcp.client.stdio import stdio_client
+from mcp.client.streamable_http import streamablehttp_client
+
+logger = logging.getLogger(__name__)
+
+
+class MCPEndpointError(Exception):
+    """Exception raised when there's an error connecting to or using an MCP endpoint."""
+
+    pass
+
+
+class MCPClient:
+    """
+    A simplified MCP client that can connect to MCP endpoints with sync-by-default API.
+
+    Supports:
+    - SSE endpoints (e.g., 'https://example.com/mcp/server/sse')
+    - Streamable HTTP endpoints (e.g., 'https://example.com/mcp/server')
+    - Local StdioServer scripts (e.g., 'path/to/server.py')
+    """
+
+    def __init__(self, endpoint: str, timeout: int = 30):
+        """
+        Initialize the MCP client.
+
+        Args:
+            endpoint: Either a URL (for SSE/HTTP) or a file path (for StdioServer)
+            timeout: Connection timeout in seconds
+        """
+        self.endpoint = endpoint
+        self.timeout = timeout
+        self.transport_type = self._detect_transport_type(endpoint)
+
+    def _detect_transport_type(self, endpoint: str) -> str:
+        """
+        Detect the transport type based on the endpoint.
+
+        Args:
+            endpoint: The endpoint URL or file path
+
+        Returns:
+            Transport type: 'sse', 'streamable-http', or 'stdio'
+        """
+        if endpoint.startswith(("http://", "https://")):
+            parsed = urlparse(endpoint)
+            path = parsed.path.lower()
+
+            if "/sse" in path:
+                return "sse"
+            elif "/mcp" in path:
+                return "streamable-http"
+            else:
+                return "streamable-http"
+        else:
+            return "stdio"
+
+    def list_tools(self) -> List[Dict[str, Any]]:
+        """
+        List all available tools from the MCP endpoint in OpenAI standard format.
+
+        Returns:
+            List of tools in OpenAI function calling format
+
+        Raises:
+            MCPEndpointError: If connection or listing fails
+        """
+        return asyncio.run(self.list_tools_async())
+
+    async def list_tools_async(self) -> List[Dict[str, Any]]:
+        """
+        Async version of list_tools for advanced users.
+
+        Returns:
+            List of tools in OpenAI function calling format
+
+        Raises:
+            MCPEndpointError: If connection or listing fails
+        """
+        try:
+            if self.transport_type == "sse":
+                async with sse_client(url=self.endpoint, timeout=self.timeout) as (
+                    read_stream,
+                    write_stream,
+                ):
+                    return await self._get_tools_from_session(read_stream, write_stream)
+            elif self.transport_type == "streamable-http":
+                async with streamablehttp_client(
+                    url=self.endpoint, timeout=self.timeout
+                ) as (read_stream, write_stream, session_id_getter):
+                    return await self._get_tools_from_session(read_stream, write_stream)
+            elif self.transport_type == "stdio":
+                if not os.path.exists(self.endpoint):
+                    raise MCPEndpointError(
+                        f"StdioServer script not found: {self.endpoint}"
+                    )
+
+                server_params = StdioServerParameters(
+                    command="python", args=[self.endpoint]
+                )
+                async with stdio_client(server_params) as (read_stream, write_stream):
+                    return await self._get_tools_from_session(read_stream, write_stream)
+            else:
+                raise MCPEndpointError(
+                    f"Unsupported transport type: {self.transport_type}"
+                )
+        except Exception as e:
+            logger.error(f"Failed to list tools from {self.endpoint}: {e}")
+            raise MCPEndpointError(f"Failed to list tools: {e}")
+
+    async def _get_tools_from_session(
+        self, read_stream, write_stream
+    ) -> List[Dict[str, Any]]:
+        """Get tools from an MCP session in OpenAI standard format."""
+        async with ClientSession(read_stream, write_stream) as session:
+            await session.initialize()
+            tools_response = await session.list_tools()
+
+            tools = []
+            for tool in tools_response.tools:
+                function_dict = {
+                    "name": tool.name,
+                    "description": tool.description or "",
+                    "parameters": tool.inputSchema or {},
+                }
+
+                openai_tool = {
+                    "type": "function",
+                    "function": function_dict,
+                }
+                tools.append(openai_tool)
+
+            return tools
+
+    def call_tool(self, tool_name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Call a specific tool on the MCP endpoint.
+
+        Args:
+            tool_name: Name of the tool to call
+            arguments: Arguments to pass to the tool
+
+        Returns:
+            Tool call result dictionary
+
+        Raises:
+            MCPEndpointError: If connection or tool call fails
+        """
+        return asyncio.run(self.call_tool_async(tool_name, arguments))
+
+    async def call_tool_async(
+        self, tool_name: str, arguments: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Async version of call_tool for advanced users.
+
+        Args:
+            tool_name: Name of the tool to call
+            arguments: Arguments to pass to the tool
+
+        Returns:
+            Tool call result dictionary
+
+        Raises:
+            MCPEndpointError: If connection or tool call fails
+        """
+        try:
+            if self.transport_type == "sse":
+                async with sse_client(url=self.endpoint, timeout=self.timeout) as (
+                    read_stream,
+                    write_stream,
+                ):
+                    return await self._call_tool_from_session(
+                        read_stream, write_stream, tool_name, arguments
+                    )
+            elif self.transport_type == "streamable-http":
+                async with streamablehttp_client(
+                    url=self.endpoint, timeout=self.timeout
+                ) as (read_stream, write_stream, session_id_getter):
+                    return await self._call_tool_from_session(
+                        read_stream, write_stream, tool_name, arguments
+                    )
+            elif self.transport_type == "stdio":
+                if not os.path.exists(self.endpoint):
+                    raise MCPEndpointError(
+                        f"StdioServer script not found: {self.endpoint}"
+                    )
+
+                server_params = StdioServerParameters(
+                    command="python", args=[self.endpoint]
+                )
+                async with stdio_client(server_params) as (read_stream, write_stream):
+                    return await self._call_tool_from_session(
+                        read_stream, write_stream, tool_name, arguments
+                    )
+            else:
+                raise MCPEndpointError(
+                    f"Unsupported transport type: {self.transport_type}"
+                )
+        except Exception as e:
+            logger.error(f"Failed to call tool {tool_name} on {self.endpoint}: {e}")
+            raise MCPEndpointError(f"Failed to call tool {tool_name}: {e}")
+
+    async def _call_tool_from_session(
+        self, read_stream, write_stream, tool_name: str, arguments: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Call a tool from an MCP session."""
+        async with ClientSession(read_stream, write_stream) as session:
+            await session.initialize()
+            result = await session.call_tool(tool_name, arguments)
+
+            result_dict = {
+                "content": [],
+                "is_error": result.isError,
+            }
+
+            for content in result.content:
+                if hasattr(content, "type") and content.type == "text":
+                    result_dict["content"].append(
+                        {"type": "text", "text": content.text}
+                    )
+                else:
+                    result_dict["content"].append(str(content))
+
+            return result_dict
+
+
+# Example usage
+def example_usage():
+    """Example of how to use the simplified MCPClient."""
+    # Simple usage with sync API
+    client = MCPClient("https://ai-center.se/mcp/think-mcp-server/sse")
+
+    try:
+        # List available tools
+        tools = client.list_tools()
+        print(f"Found {len(tools)} tools")
+
+        # Call a tool if any are available
+        if tools:
+            result = client.call_tool(
+                tools[0]["function"]["name"], {"query": "What is MCP"}
+            )
+            print(f"Tool result: {result}")
+    except MCPEndpointError as e:
+        print(f"Error: {e}")
+
+
+if __name__ == "__main__":
+    example_usage()

agentic_blocks-0.1.0/src/agentic_blocks/messages.py

@@ -0,0 +1,225 @@
+"""
+Simplified Messages class for managing LLM conversation history.
+"""
+
+from typing import List, Dict, Any, Optional
+from datetime import datetime
+
+
+class Messages:
+    """A simplified class for managing LLM conversation messages."""
+
+    def __init__(
+        self,
+        system_prompt: Optional[str] = None,
+        user_prompt: Optional[str] = None,
+        add_date_and_time: bool = False,
+    ):
+        """
+        Initialize the Messages instance.
+
+        Args:
+            system_prompt: Optional system prompt to add to the messages list
+            user_prompt: Optional initial user prompt to add to the messages list
+            add_date_and_time: If True, adds a message with current date and time
+        """
+        self.messages: List[Dict[str, Any]] = []
+
+        if system_prompt:
+            self.add_system_message(system_prompt)
+
+        if add_date_and_time:
+            self._add_date_time_message()
+
+        if user_prompt:
+            self.add_user_message(user_prompt)
+
+    def _add_date_time_message(self):
+        """Add a message with the current date and time."""
+        now = datetime.now()
+        day = now.day
+        if 4 <= day <= 20 or 24 <= day <= 30:
+            suffix = "th"
+        else:
+            suffix = ["st", "nd", "rd"][day % 10 - 1]
+
+        date_str = now.strftime(f"%d{suffix} of %B %Y")
+        time_str = now.strftime("%H:%M")
+        date_time_message = f"Today is {date_str} and the current time is {time_str}."
+        self.messages.append({"role": "system", "content": date_time_message})
+
+    def add_system_message(self, content: str):
+        """Add a system message to the messages list."""
+        self.messages.append({"role": "system", "content": content})
+
+    def add_user_message(self, content: str):
+        """Add a user message to the messages list."""
+        self.messages.append({"role": "user", "content": content})
+
+    def add_assistant_message(self, content: str):
+        """Add an assistant message to the messages list."""
+        self.messages.append({"role": "assistant", "content": content})
+
+    def add_tool_call(self, tool_call: Dict[str, Any]):
+        """
+        Add a tool call to the latest assistant message or create a new one.
+
+        Args:
+            tool_call: The tool call dictionary with id, type, function, etc.
+        """
+        # Check if the latest message is an assistant message with tool_calls
+        if (self.messages 
+            and self.messages[-1].get("role") == "assistant" 
+            and "tool_calls" in self.messages[-1]):
+            # Append to existing assistant message
+            self.messages[-1]["tool_calls"].append(tool_call)
+        else:
+            # Create new assistant message with tool call
+            assistant_message = {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [tool_call],
+            }
+            self.messages.append(assistant_message)
+
+    def add_tool_response(self, tool_call_id: str, content: str):
+        """
+        Add a tool response message.
+
+        Args:
+            tool_call_id: The ID of the tool call this response belongs to
+            content: The response content
+        """
+        tool_message = {
+            "role": "tool",
+            "tool_call_id": tool_call_id,
+            "content": content,
+        }
+        self.messages.append(tool_message)
+
+    def add_tool_responses(self, tool_responses: List[Dict[str, Any]]):
+        """
+        Add multiple tool responses to the conversation history.
+
+        Args:
+            tool_responses: List of tool response dictionaries with tool_call_id,
+                           tool_response, and is_error fields
+        """
+        for response in tool_responses:
+            tool_call_id = response.get("tool_call_id", "unknown")
+            is_error = response.get("is_error", False)
+            
+            if is_error:
+                content = f"Error: {response.get('error', 'Unknown error')}"
+            else:
+                tool_response = response.get("tool_response", {})
+                # Simple content extraction
+                if isinstance(tool_response, dict) and "content" in tool_response:
+                    content_list = tool_response["content"]
+                    if content_list and isinstance(content_list[0], dict):
+                        content = content_list[0].get("text", str(tool_response))
+                    else:
+                        content = str(tool_response)
+                else:
+                    content = str(tool_response)
+
+            self.add_tool_response(tool_call_id, content)
+
+    def get_messages(self) -> List[Dict[str, Any]]:
+        """Get the current messages list."""
+        return self.messages
+
+    def has_pending_tool_calls(self) -> bool:
+        """
+        Check if the last message has tool calls that need execution.
+
+        Returns:
+            True if there are tool calls waiting for responses
+        """
+        if not self.messages:
+            return False
+
+        last_message = self.messages[-1]
+        
+        # Check if the last message is an assistant message with tool calls
+        if last_message.get("role") == "assistant" and "tool_calls" in last_message:
+            # Check if there are subsequent tool responses
+            tool_call_ids = {tc.get("id") for tc in last_message["tool_calls"]}
+            
+            # Look for tool responses after this message
+            for msg in reversed(self.messages):
+                if msg.get("role") == "tool" and msg.get("tool_call_id") in tool_call_ids:
+                    tool_call_ids.remove(msg.get("tool_call_id"))
+            
+            # If there are still unresponded tool call IDs, we have pending calls
+            return len(tool_call_ids) > 0
+
+        return False
+
+    def __str__(self) -> str:
+        """Return messages in a simple, readable format."""
+        if not self.messages:
+            return "No messages"
+
+        lines = []
+        for i, message in enumerate(self.messages, 1):
+            role = message.get("role", "unknown")
+            content = message.get("content", "")
+
+            # Handle tool calls in assistant messages
+            if role == "assistant" and message.get("tool_calls"):
+                lines.append(f"{i}. {role}: {content}")
+                for j, tool_call in enumerate(message["tool_calls"], 1):
+                    function_name = tool_call.get("function", {}).get("name", "unknown")
+                    lines.append(f"   └─ Tool Call {j}: {function_name}")
+            
+            # Handle tool messages
+            elif role == "tool":
+                tool_call_id = message.get("tool_call_id", "unknown")
+                # Truncate long content for readability
+                if len(content) > 200:
+                    content = content[:197] + "..."
+                lines.append(f"{i}. {role} [{tool_call_id[:8]}...]: {content}")
+            
+            # Handle other message types
+            else:
+                # Truncate long content for readability
+                if len(content) > 100:
+                    content = content[:97] + "..."
+                lines.append(f"{i}. {role}: {content}")
+
+        return "\n".join(lines)
+
+
+# Example usage
+def example_usage():
+    """Example of how to use the simplified Messages class."""
+    # Create messages with system prompt
+    messages = Messages(
+        system_prompt="You are a helpful assistant.",
+        user_prompt="Hello, how are you?",
+        add_date_and_time=True
+    )
+    
+    # Add assistant response
+    messages.add_assistant_message("I'm doing well, thank you!")
+    
+    # Add a tool call
+    tool_call = {
+        "id": "call_123",
+        "type": "function",
+        "function": {"name": "get_weather", "arguments": '{"location": "Paris"}'}
+    }
+    messages.add_tool_call(tool_call)
+    
+    # Add tool response
+    messages.add_tool_response("call_123", "The weather in Paris is sunny, 22°C")
+    
+    print("Conversation:")
+    print(messages)
+    
+    print(f"\nHas pending tool calls: {messages.has_pending_tool_calls()}")
+
+
+if __name__ == "__main__":
+    example_usage()

agentic_blocks-0.1.0/src/agentic_blocks.egg-info/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: agentic-blocks
+Version: 0.1.0
+Summary: Simple building blocks for agentic AI systems with MCP client and conversation management
+Author-email: Magnus Bjelkenhed <bjelkenhed@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/bjelkenhed/agentic-blocks
+Project-URL: Repository, https://github.com/bjelkenhed/agentic-blocks
+Project-URL: Issues, https://github.com/bjelkenhed/agentic-blocks/issues
+Keywords: ai,mcp,model-control-protocol,agent,llm,openai,conversation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp
+Requires-Dist: requests
+Requires-Dist: python-dotenv
+Requires-Dist: openai
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# Agentic Blocks
+
+Building blocks for agentic systems with a focus on simplicity and ease of use.
+
+## Overview
+
+Agentic Blocks provides clean, simple components for building AI agent systems, specifically focused on:
+
+- **MCP Client**: Connect to Model Control Protocol (MCP) endpoints with a sync-by-default API
+- **Messages**: Manage LLM conversation history with OpenAI-compatible format
+
+Both components follow principles of simplicity, maintainability, and ease of use.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+For development:
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### MCPClient - Connect to MCP Endpoints
+
+The MCPClient provides a unified interface for connecting to different types of MCP endpoints:
+
+```python
+from agentic_blocks import MCPClient
+
+# Connect to an SSE endpoint (sync by default)
+client = MCPClient("https://example.com/mcp/server/sse")
+
+# List available tools
+tools = client.list_tools()
+print(f"Available tools: {len(tools)}")
+
+# Call a tool
+result = client.call_tool("search", {"query": "What is MCP?"})
+print(result)
+```
+
+**Supported endpoint types:**
+- **SSE endpoints**: URLs with `/sse` in the path
+- **HTTP endpoints**: URLs with `/mcp` in the path  
+- **Local scripts**: File paths to Python MCP servers
+
+**Async support for advanced users:**
+```python
+# Async versions available
+tools = await client.list_tools_async()
+result = await client.call_tool_async("search", {"query": "async example"})
+```
+
+### Messages - Manage Conversation History
+
+The Messages class helps build and manage LLM conversations in OpenAI-compatible format:
+
+```python
+from agentic_blocks import Messages
+
+# Initialize with system prompt
+messages = Messages(
+    system_prompt="You are a helpful assistant.",
+    user_prompt="Hello, how can you help me?",
+    add_date_and_time=True
+)
+
+# Add assistant response
+messages.add_assistant_message("I can help you with various tasks!")
+
+# Add tool calls
+tool_call = {
+    "id": "call_123",
+    "type": "function", 
+    "function": {"name": "get_weather", "arguments": '{"location": "Paris"}'}
+}
+messages.add_tool_call(tool_call)
+
+# Add tool response
+messages.add_tool_response("call_123", "The weather in Paris is sunny, 22°C")
+
+# Get messages for LLM API
+conversation = messages.get_messages()
+
+# View readable format
+print(messages)
+```
+
+## Complete Example - Agent with MCP Tools
+
+```python
+from agentic_blocks import MCPClient, Messages
+
+def simple_agent():
+    # Initialize MCP client and conversation
+    client = MCPClient("https://example.com/mcp/server/sse")
+    messages = Messages(
+        system_prompt="You are a helpful research assistant.",
+        add_date_and_time=True
+    )
+    
+    # Get available tools
+    tools = client.list_tools()
+    print(f"Connected to MCP server with {len(tools)} tools")
+    
+    # Simulate user query
+    user_query = "What's the latest news about AI?"
+    messages.add_user_message(user_query)
+    
+    # Agent decides to use a search tool
+    if tools:
+        search_tool = next((t for t in tools if "search" in t["function"]["name"]), None)
+        if search_tool:
+            # Add tool call to messages
+            tool_call = {
+                "id": "search_001",
+                "type": "function",
+                "function": {
+                    "name": search_tool["function"]["name"],
+                    "arguments": '{"query": "latest AI news"}'
+                }
+            }
+            messages.add_tool_call(tool_call)
+            
+            # Execute the tool
+            result = client.call_tool(
+                search_tool["function"]["name"], 
+                {"query": "latest AI news"}
+            )
+            
+            # Add tool response
+            if result["content"]:
+                response_text = result["content"][0]["text"]
+                messages.add_tool_response("search_001", response_text)
+            
+            # Add final assistant response
+            messages.add_assistant_message(
+                "Based on my search, here's what I found about the latest AI news..."
+            )
+    
+    # Print conversation
+    print("\\nConversation:")
+    print(messages)
+    
+    return messages.get_messages()
+
+if __name__ == "__main__":
+    simple_agent()
+```
+
+## Development Principles
+
+This project follows these core principles:
+
+- **Simplicity First**: Keep code simple, readable, and focused on core functionality
+- **Sync-by-Default**: Primary methods are synchronous for ease of use, with optional async versions
+- **Minimal Dependencies**: Avoid over-engineering and complex error handling unless necessary  
+- **Clean APIs**: Prefer straightforward method names and clear parameter expectations
+- **Maintainable Code**: Favor fewer lines of clear code over comprehensive edge case handling
+
+## API Reference
+
+### MCPClient
+
+```python
+MCPClient(endpoint: str, timeout: int = 30)
+```
+
+**Methods:**
+- `list_tools() -> List[Dict]`: Get available tools (sync)
+- `call_tool(name: str, args: Dict) -> Dict`: Call a tool (sync)
+- `list_tools_async() -> List[Dict]`: Async version of list_tools
+- `call_tool_async(name: str, args: Dict) -> Dict`: Async version of call_tool
+
+### Messages
+
+```python
+Messages(system_prompt=None, user_prompt=None, add_date_and_time=False)
+```
+
+**Methods:**
+- `add_system_message(content: str)`: Add system message
+- `add_user_message(content: str)`: Add user message
+- `add_assistant_message(content: str)`: Add assistant message
+- `add_tool_call(tool_call: Dict)`: Add tool call to assistant message
+- `add_tool_response(call_id: str, content: str)`: Add tool response
+- `get_messages() -> List[Dict]`: Get all messages
+- `has_pending_tool_calls() -> bool`: Check for pending tool calls
+
+## Requirements
+
+- Python >= 3.11
+- Dependencies: `mcp`, `requests`, `python-dotenv`, `openai`
+
+## License
+
+MIT

agentic_blocks-0.1.0/src/agentic_blocks.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/agentic_blocks/__init__.py
+src/agentic_blocks/mcp_client.py
+src/agentic_blocks/messages.py
+src/agentic_blocks.egg-info/PKG-INFO
+src/agentic_blocks.egg-info/SOURCES.txt
+src/agentic_blocks.egg-info/dependency_links.txt
+src/agentic_blocks.egg-info/requires.txt
+src/agentic_blocks.egg-info/top_level.txt

agentic_blocks-0.1.0/src/agentic_blocks.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agentic_blocks-0.1.0/src/agentic_blocks.egg-info/requires.txt

@@ -0,0 +1,12 @@
+mcp
+requests
+python-dotenv
+openai
+
+[dev]
+pytest
+build
+twine
+
+[test]
+pytest

agentic_blocks-0.1.0/src/agentic_blocks.egg-info/top_level.txt

@@ -0,0 +1 @@
+agentic_blocks