sokrates-mcp 0.2.0__tar.gz → 0.4.0__tar.gz

{sokrates_mcp-0.2.0/src/sokrates_mcp.egg-info → sokrates_mcp-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sokrates-mcp
-Version: 0.2.0
+Version: 0.4.0
 Summary: A templated MCP server for demonstration and quick start.
 Author-email: Julian Weber <julianweberdev@gmail.com>
 License: MIT License
@@ -158,12 +158,20 @@ providers:
 ### Starting the Server
 
 ```bash
+# from local git repo
 uv run sokrates-mcp
+
+# without checking out the git repo
+uvx sokrates-mcp
 ```
 
 ### Listing available command line options
 ```bash
+# from local git repo
 uv run sokrates-mcp --help
+
+# without checking out the git repo
+uvx sokrates-mcp --help
 ```
 
 ## Architecture & Technical Details
@@ -185,110 +193,37 @@ The server follows a modular design pattern:
 
 ## Available Tools
 
-### main.py
-
-- **refine_prompt**: Refines a given prompt by enriching it with additional context.
-  - Parameters:
-    - `prompt` (str): The input prompt to be refined
-    - `refinement_type` (str, optional): Type of refinement ('code' or 'default'). Default is 'default'
-    - `model` (str, optional): Model name for refinement. Default is 'default'
-
-- **refine_and_execute_external_prompt**: Refines a prompt and executes it with an external LLM.
-  - Parameters:
-    - `prompt` (str): The input prompt to be refined and executed
-    - `refinement_model` (str, optional): Model for refinement. Default is 'default'
-    - `execution_model` (str, optional): Model for execution. Default is 'default'
-    - `refinement_type` (str, optional): Type of refinement ('code' or 'default'). Default is 'default'
-
-- **handover_prompt**: Hands over a prompt to an external LLM for processing.
-  - Parameters:
-    - `prompt` (str): The prompt to be executed externally
-    - `model` (str, optional): Model name for execution. Default is 'default'
-
-- **breakdown_task**: Breaks down a task into sub-tasks with complexity ratings.
-  - Parameters:
-    - `task` (str): The full task description to break down
-    - `model` (str, optional): Model name for processing. Default is 'default'
-
-- **list_available_models**: Lists all available large language models accessible by the server.
-
-### mcp_config.py
-
-- **MCPConfig** class: Manages configuration settings for the MCP server.
-  - Parameters:
-    - `config_file_path` (str, optional): Path to YAML config file
-    - `api_endpoint` (str, optional): API endpoint URL
-    - `api_key` (str, optional): API key for authentication
-    - `model` (str, optional): Model name
-
-### workflow.py
-
-- **Workflow** class: Implements the business logic for prompt refinement and execution.
-  - Methods:
-    - `refine_prompt`: Refines a given prompt
-    - `refine_and_execute_external_prompt`: Refines and executes a prompt with an external LLM
-    - `handover_prompt`: Hands over a prompt to an external LLM for processing
-    - `breakdown_task`: Breaks down a task into sub-tasks
-    - `list_available_models`: Lists all available models
+See the [main.py](src/sokrates_mcp/main.py) file for a list of all mcp tools in the server
 
 ## Project Structure
 
 - `src/sokrates_mcp/main.py`: Sets up the MCP server and registers tools
 - `src/sokrates_mcp/mcp_config.py`: Configuration management
+- `src/sokrates_mcp/utils.py`: Helper and utility methods
 - `src/sokrates_mcp/workflow.py`: Business logic for prompt refinement and execution
 - `pyproject.toml`: Dependency management
 
 
-## Script List
-
-### `main.py`
-Sets up an MCP server using the FastMCP framework to provide tools for prompt refinement and execution workflows.
-#### Usage
-- `uv run python main.py` - Start the MCP server (default port: 8000)
-- `uv run fastmcp dev main.py` - Run in development mode with auto-reload
-
-### `mcp_config.py`
-Provides configuration management for the MCP server. Loads configuration from a YAML file and sets default values if needed.
-#### Usage
-- Import and use in other scripts:
-  ```python
-  from mcp_config import MCPConfig
-  config = MCPConfig(api_endpoint="https://api.example.com", model="my-model")
-  ```
-
-### `workflow.py`
-Implements the business logic for prompt refinement and execution workflows. Contains methods to refine prompts, execute them with external LLMs, break down tasks, etc.
-#### Usage
-- Import and use in other scripts:
-  ```python
-  from workflow import Workflow
-  from mcp_config import MCPConfig
-
-  config = MCPConfig()
-  workflow = Workflow(config)
-  result = await workflow.refine_prompt("Write a Python function to sort a list", refinement_type="code")
-  ```
-
-### `src/mcp_client_example.py`
-Demonstrates a basic Model Context Protocol (MCP) client using the fastmcp library. Defines a simple model and registers it with the client.
-
-#### Usage
-- Run as a standalone script:
-  ```bash
-  python src/mcp_client_example.py
-  ```
-- Or use with an ASGI server like Uvicorn:
-  ```bash
-  uvicorn src.mcp_client_example:main --factory
-  ```
-
 **Common Error:**
 If you see "ModuleNotFoundError: fastmcp", ensure:
-1. Dependencies are installed (`uv pip install .`)
+1. Dependencies are installed (`uv sync`)
 2. Python virtual environment is activated
 
 ## Changelog
 
+**0.4.0 (Aug 2025)**
+- adds new tools:
+  - read_files_from_directory
+  - directory_tree
+  - logging refactoring in workflow.py
+
+**0.3.0 (Aug 2025)**
+- adds new tools:
+    - roll_dice
+    - read_from_file
+    - store_to_file
+- refactorings - code quality - still ongoing
+
 **0.2.0 (Aug 2025)**
 - First published version
 - Update to latest sokrates library version

{sokrates_mcp-0.2.0 → sokrates_mcp-0.4.0}/README.md

@@ -120,12 +120,20 @@ providers:
 ### Starting the Server
 
 ```bash
+# from local git repo
 uv run sokrates-mcp
+
+# without checking out the git repo
+uvx sokrates-mcp
 ```
 
 ### Listing available command line options
 ```bash
+# from local git repo
 uv run sokrates-mcp --help
+
+# without checking out the git repo
+uvx sokrates-mcp --help
 ```
 
 ## Architecture & Technical Details
@@ -147,110 +155,37 @@ The server follows a modular design pattern:
 
 ## Available Tools
 
-### main.py
-
-- **refine_prompt**: Refines a given prompt by enriching it with additional context.
-  - Parameters:
-    - `prompt` (str): The input prompt to be refined
-    - `refinement_type` (str, optional): Type of refinement ('code' or 'default'). Default is 'default'
-    - `model` (str, optional): Model name for refinement. Default is 'default'
-
-- **refine_and_execute_external_prompt**: Refines a prompt and executes it with an external LLM.
-  - Parameters:
-    - `prompt` (str): The input prompt to be refined and executed
-    - `refinement_model` (str, optional): Model for refinement. Default is 'default'
-    - `execution_model` (str, optional): Model for execution. Default is 'default'
-    - `refinement_type` (str, optional): Type of refinement ('code' or 'default'). Default is 'default'
-
-- **handover_prompt**: Hands over a prompt to an external LLM for processing.
-  - Parameters:
-    - `prompt` (str): The prompt to be executed externally
-    - `model` (str, optional): Model name for execution. Default is 'default'
-
-- **breakdown_task**: Breaks down a task into sub-tasks with complexity ratings.
-  - Parameters:
-    - `task` (str): The full task description to break down
-    - `model` (str, optional): Model name for processing. Default is 'default'
-
-- **list_available_models**: Lists all available large language models accessible by the server.
-
-### mcp_config.py
-
-- **MCPConfig** class: Manages configuration settings for the MCP server.
-  - Parameters:
-    - `config_file_path` (str, optional): Path to YAML config file
-    - `api_endpoint` (str, optional): API endpoint URL
-    - `api_key` (str, optional): API key for authentication
-    - `model` (str, optional): Model name
-
-### workflow.py
-
-- **Workflow** class: Implements the business logic for prompt refinement and execution.
-  - Methods:
-    - `refine_prompt`: Refines a given prompt
-    - `refine_and_execute_external_prompt`: Refines and executes a prompt with an external LLM
-    - `handover_prompt`: Hands over a prompt to an external LLM for processing
-    - `breakdown_task`: Breaks down a task into sub-tasks
-    - `list_available_models`: Lists all available models
+See the [main.py](src/sokrates_mcp/main.py) file for a list of all mcp tools in the server
 
 ## Project Structure
 
 - `src/sokrates_mcp/main.py`: Sets up the MCP server and registers tools
 - `src/sokrates_mcp/mcp_config.py`: Configuration management
+- `src/sokrates_mcp/utils.py`: Helper and utility methods
 - `src/sokrates_mcp/workflow.py`: Business logic for prompt refinement and execution
 - `pyproject.toml`: Dependency management
 
 
-## Script List
-
-### `main.py`
-Sets up an MCP server using the FastMCP framework to provide tools for prompt refinement and execution workflows.
-#### Usage
-- `uv run python main.py` - Start the MCP server (default port: 8000)
-- `uv run fastmcp dev main.py` - Run in development mode with auto-reload
-
-### `mcp_config.py`
-Provides configuration management for the MCP server. Loads configuration from a YAML file and sets default values if needed.
-#### Usage
-- Import and use in other scripts:
-  ```python
-  from mcp_config import MCPConfig
-  config = MCPConfig(api_endpoint="https://api.example.com", model="my-model")
-  ```
-
-### `workflow.py`
-Implements the business logic for prompt refinement and execution workflows. Contains methods to refine prompts, execute them with external LLMs, break down tasks, etc.
-#### Usage
-- Import and use in other scripts:
-  ```python
-  from workflow import Workflow
-  from mcp_config import MCPConfig
-
-  config = MCPConfig()
-  workflow = Workflow(config)
-  result = await workflow.refine_prompt("Write a Python function to sort a list", refinement_type="code")
-  ```
-
-### `src/mcp_client_example.py`
-Demonstrates a basic Model Context Protocol (MCP) client using the fastmcp library. Defines a simple model and registers it with the client.
-
-#### Usage
-- Run as a standalone script:
-  ```bash
-  python src/mcp_client_example.py
-  ```
-- Or use with an ASGI server like Uvicorn:
-  ```bash
-  uvicorn src.mcp_client_example:main --factory
-  ```
-
 **Common Error:**
 If you see "ModuleNotFoundError: fastmcp", ensure:
-1. Dependencies are installed (`uv pip install .`)
+1. Dependencies are installed (`uv sync`)
 2. Python virtual environment is activated
 
 ## Changelog
 
+**0.4.0 (Aug 2025)**
+- adds new tools:
+  - read_files_from_directory
+  - directory_tree
+  - logging refactoring in workflow.py
+
+**0.3.0 (Aug 2025)**
+- adds new tools:
+    - roll_dice
+    - read_from_file
+    - store_to_file
+- refactorings - code quality - still ongoing
+
 **0.2.0 (Aug 2025)**
 - First published version
 - Update to latest sokrates library version

{sokrates_mcp-0.2.0 → sokrates_mcp-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sokrates-mcp"
-version = "0.2.0"
+version = "0.4.0"
 description = "A templated MCP server for demonstration and quick start."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -41,4 +41,4 @@ explicit = true
 name = "testpypi"
 url = "https://test.pypi.org/simple/"
 publish-url = "https://test.pypi.org/legacy/"
-explicit = true
+explicit = true

{sokrates_mcp-0.2.0 → sokrates_mcp-0.4.0}/src/sokrates_mcp/main.py

@@ -294,6 +294,67 @@ async def generate_code_review(
     ) -> str:
     return await workflow.generate_code_review(ctx=ctx, provider=provider, model=model, review_type=review_type, source_directory=source_directory, source_file_paths=source_file_paths, target_directory=target_directory)
 
+@mcp.tool(
+    name="read_from_file",
+    description="Read a file from the local disk at the given file path and return it's contents.",
+    tags={"file","read","load","local"}
+)
+async def read_from_file(
+    ctx: Context, 
+    file_path: Annotated[str, Field(description="The source file path to use for reading the file. This should be an absolute file path on the disk.")], 
+    ) -> str:
+    return await workflow.read_from_file(ctx=ctx, file_path=file_path)
+
+@mcp.tool(
+    name="read_files_from_directory",
+    description="Read files from the local disk from the given directory path and return the file contents. You can also provide a list of file extentsions to include optionally.",
+    tags={"directory","read","load","local"}
+)
+async def read_files_from_directory(
+    ctx: Context, 
+    directory_path: Annotated[str, Field(description="The source directory path to use for reading the files. This should be an absolute file path on the disk.")],
+    file_extensions: Annotated[list[str], Field(description="A list of file extensions to include when reading the files. For markdown files you could use ['.md']", default=None)],
+    ) -> str:
+    return await workflow.read_files_from_directory(ctx=ctx, directory_path=directory_path, file_extensions=file_extensions)
+
+@mcp.tool(
+    name="directory_tree",
+    description="Provides a recursive directory file listing for the given directory path.",
+    tags={"directory","list","local"}
+)
+async def directory_tree(
+    ctx: Context, 
+    directory_path: Annotated[str, Field(description="The source directory path to use for reading the files. This should be an absolute file path on the disk.")]
+    ) -> str:
+    return await workflow.directory_tree(ctx=ctx, directory_path=directory_path)
+
+
+@mcp.tool(
+    name="store_to_file",
+    description="Store a file with the provided content to the local drive at the provided file path.",
+    tags={"file","store","save","local"}
+)
+async def store_to_file(
+    ctx: Context, 
+    file_path: Annotated[str, Field(description="The target file path to use for storing the file. This should be an absolute file path on the disk.")],
+    file_content: Annotated[str, Field(description="The content that should be written to the target file.")],
+    ) -> str:
+    return await workflow.store_to_file(ctx=ctx, file_path=file_path, file_content=file_content)
+
+@mcp.tool(
+    name="roll_dice",
+    description="Rolls the given number of dice with the specified number of sides for the given number of times and returns the result. For example you can also instruct to throw a W12, which should then set the side_count to 12.",
+    tags={"dice","roll","random"}
+)
+async def roll_dice(
+    ctx: Context, 
+    number_of_dice: Annotated[int, Field(description="The number of dice to to use for rolling.", default=1)],
+    side_count: Annotated[int, Field(description="The number of sides of the dice to use for rolling.", default=6)],
+    number_of_rolls: Annotated[int, Field(description="The count of dice rolls to execute.", default=1)]
+    ) -> str:
+    return await workflow.roll_dice(ctx=ctx, number_of_dice=number_of_dice, side_count=side_count, number_of_rolls=number_of_rolls)
+
+
 @mcp.tool(
     name="list_available_models_for_provider",
     description="Lists all available large language models and the target api endpoint configured as provider for the sokrates-mcp server.",

{sokrates_mcp-0.2.0 → sokrates_mcp-0.4.0}/src/sokrates_mcp/mcp_config.py

@@ -18,6 +18,7 @@ import logging
 from urllib.parse import urlparse
 from pathlib import Path
 from sokrates import Config
+from typing import Dict, List, Optional, Any
 
 DEFAULT_API_ENDPOINT = "http://localhost:1234/v1"
 DEFAULT_API_KEY = "mykey"
@@ -53,7 +54,7 @@ class MCPConfig:
         "openai"
     ]
     
-    def __init__(self, config_file_path=CONFIG_FILE_PATH, api_endpoint = DEFAULT_API_ENDPOINT, api_key = DEFAULT_API_KEY, model= DEFAULT_MODEL, verbose=False):
+    def __init__(self, config_file_path: str = CONFIG_FILE_PATH, api_endpoint: str = DEFAULT_API_ENDPOINT, api_key: str = DEFAULT_API_KEY, model: str = DEFAULT_MODEL, verbose: bool = False):
         """Initialize MCP configuration.
 
         Args:
@@ -64,15 +65,15 @@ class MCPConfig:
             model (str): Model name to use. Defaults to DEFAULT_MODEL.
             verbose (bool): Enable verbose logging. Defaults to False.
 
-        Returns:
-            None
-
         Side Effects:
             Initializes instance attributes with values from config file or defaults
             Sets up logging based on verbose parameter
         """
         self.logger = logging.getLogger(__name__)
         self.config_file_path = config_file_path
+        # Validate config file path
+        if not self._validate_config_file_path(config_file_path):
+            raise ValueError(f"Invalid config file path: {config_file_path}")
         config_data = self._load_config_from_file(self.config_file_path)
 
         prompts_directory = config_data.get("prompts_directory", self.DEFAULT_PROMPTS_DIRECTORY)
@@ -80,14 +81,13 @@ class MCPConfig:
             raise ValueError(f"Invalid prompts directory: {prompts_directory}")
         self.prompts_directory = prompts_directory
 
+        # Validate prompt files using helper method
         refinement_prompt_filename = config_data.get("refinement_prompt_filename", self.DEFAULT_REFINEMENT_PROMPT_FILENAME)
-        if not os.path.exists(os.path.join(prompts_directory, refinement_prompt_filename)):
-            raise FileNotFoundError(f"Refinement prompt file not found: {refinement_prompt_filename}")
+        self._validate_prompt_file_exists(prompts_directory, refinement_prompt_filename)
         self.refinement_prompt_filename = refinement_prompt_filename
 
         refinement_coding_prompt_filename = config_data.get("refinement_coding_prompt_filename", self.DEFAULT_REFINEMENT_CODING_PROMPT_FILENAME)
-        if not os.path.exists(os.path.join(prompts_directory, refinement_coding_prompt_filename)):
-            raise FileNotFoundError(f"Refinement coding prompt file not found: {refinement_coding_prompt_filename}")
+        self._validate_prompt_file_exists(prompts_directory, refinement_coding_prompt_filename)
         self.refinement_coding_prompt_filename = refinement_coding_prompt_filename
     
 
@@ -98,25 +98,74 @@ class MCPConfig:
         self.logger.info(f"  Refinement Coding Prompt Filename: {self.refinement_coding_prompt_filename}")
         self.logger.info(f"  Default Provider: {self.default_provider}")
         for prov in self.providers:
-            self.logger.info(f"Configured provider name: {prov["name"]} , api_endpoint: {prov["api_endpoint"]} , default_model: {prov["default_model"]}")
+            self.logger.info(f"Configured provider name: {prov['name']} , api_endpoint: {prov['api_endpoint']} , default_model: {prov['default_model']}")
+
+    def _validate_prompt_file_exists(self, prompts_directory: str, filename: str) -> None:
+        """Validate that a prompt file exists in the specified directory.
+        
+        Args:
+            prompts_directory (str): Directory where prompt files are located
+            filename (str): Name of the prompt file to check
+            
+        Raises:
+            FileNotFoundError: If the prompt file does not exist
+        """
+        if not os.path.exists(os.path.join(prompts_directory, filename)):
+            raise FileNotFoundError(f"Prompt file not found: {filename}")
+
+    def _validate_config_file_path(self, config_file_path: str) -> bool:
+        """Validate that the configuration file path is valid and accessible.
+        
+        Args:
+            config_file_path (str): Path to the configuration file
+            
+        Returns:
+            bool: True if path is valid and accessible, False otherwise
+        """
+        try:
+            # Check if we can write to the directory
+            dir_path = os.path.dirname(config_file_path) or "."
+            if not os.path.exists(dir_path):
+                os.makedirs(dir_path, exist_ok=True)
+            # Test that we can actually access the file path
+            Path(config_file_path).touch(exist_ok=True)
+            return True
+        except (OSError, IOError):
+            return False
 
-    def available_providers(self):
-        return list(map(lambda prov: {'name': prov['name'], 'api_endpoint': prov['api_endpoint'], 'type': prov['type']}, self.providers))
+    def available_providers(self) -> List[Dict[str, Any]]:
+        return [{'name': p['name'], 'api_endpoint': p['api_endpoint'], 'type': p['type']} for p in self.providers]
 
-    def get_provider_by_name(self, provider_name):
-        providers = list(filter(lambda x: x['name'] == provider_name, self.providers))
-        return providers[0]
+    def get_provider_by_name(self, provider_name: str) -> Dict[str, Any]:
+        """Get a provider by its name.
+        
+        Args:
+            provider_name (str): Name of the provider to find
+            
+        Returns:
+            dict: Provider configuration dictionary
+            
+        Raises:
+            IndexError: If no provider with the given name is found
+        """
+        for provider in self.providers:
+            if provider['name'] == provider_name:
+                return provider
+        raise IndexError(f"Provider '{provider_name}' not found")
 
-    def get_default_provider(self):
+    def get_default_provider(self) -> Dict[str, Any]:
         return self.get_provider_by_name(self.default_provider)
 
-    def _configure_providers(self, config_data):
+    def _configure_providers(self, config_data: Dict[str, Any]) -> None:
         # configure defaults if not config_data could be loaded
-        self.providers = config_data.get("providers", {})
+        providers = config_data.get("providers", [])
+        if not isinstance(providers, list):
+            raise ValueError("'providers' must be a list in the configuration file")
+        self.providers = providers
         if len(self.providers) < 1:
-            self.providers = [
-                DEFAULT_PROVIDER_CONFIGURATION
-            ]
+            # Validate defaults before use
+            self._validate_provider(DEFAULT_PROVIDER_CONFIGURATION)
+            self.providers = [DEFAULT_PROVIDER_CONFIGURATION]
             self.default_provider = DEFAULT_PROVIDER_NAME
             return
         
@@ -127,41 +176,42 @@ class MCPConfig:
             self._validate_provider(provider)
             provider_names.append(provider['name'])
 
-        if not config_data['default_provider']:
+        if not config_data.get('default_provider'):
             raise ValueError(f"No default_provider was configured at the root level of the config file in {self.config_file_path}")
         self.default_provider = config_data['default_provider']
 
-    def _validate_provider(self, provider):
+    def _validate_provider(self, provider: Dict[str, Any]) -> None:
         self._validate_provider_name(provider.get("name", ""))
         self._validate_provider_type(provider.get("type", ""))
         self._validate_url(provider.get("api_endpoint", ""))
         self._validate_api_key(provider.get("api_key", ""))
         self._validate_model_name(provider.get("default_model", ""))
 
-    def _validate_provider_name(self, provider_name):
+    def _validate_provider_name(self, provider_name: str) -> None:
         if len(provider_name) < 1:
             raise ValueError(f"The provider name: {provider_name} is not a valid provider name")
 
-    def _validate_provider_type(self, provider_type):
+    def _validate_provider_type(self, provider_type: str) -> None:
         if not provider_type in self.PROVIDER_TYPES:
             raise ValueError(f"The provider type: {provider_type} is not supported by sokrates-mcp")
 
-    def _validate_url(self, url):
+    def _validate_url(self, url: str) -> None:
         """Validate URL format.
 
         Args:
             url (str): URL to validate
 
-        Returns:
-            bool: True if valid URL, False otherwise
+        Raises:
+            ValueError: If the URL is invalid
         """
         try:
             result = urlparse(url)
-            return all([result.scheme in ['http', 'https'], result.netloc])
-        except:
-            raise ValueError(f"The api_endpoint: {url} is not a valid llm API endpoint")
+            if not (result.scheme in ['http', 'https'] and result.netloc):
+                raise ValueError(f"Invalid API endpoint: {url}")
+        except Exception as e:
+            raise ValueError(f"Invalid API endpoint format: {url}") from e
 
-    def _validate_api_key(self, api_key):
+    def _validate_api_key(self, api_key: str) -> None:
         """Validate API key format.
 
         Args:
@@ -173,7 +223,7 @@ class MCPConfig:
         if len(api_key) < 1:
             raise ValueError("The api key is empty")
 
-    def _validate_model_name(self, model):
+    def _validate_model_name(self, model: str) -> None:
         """Validate model name format.
 
         Args:
@@ -185,7 +235,7 @@ class MCPConfig:
         if len(model) < 1:
             raise ValueError("The model is empty")
 
-    def _ensure_directory_exists(self, directory_path):
+    def _ensure_directory_exists(self, directory_path: str) -> bool:
         """Ensure directory exists and is valid.
 
         Args:
@@ -203,7 +253,7 @@ class MCPConfig:
             self.logger.error(f"Error ensuring directory exists: {e}")
             return False
 
-    def _load_config_from_file(self, config_file_path):
+    def _load_config_from_file(self, config_file_path: str) -> Dict[str, Any]:
         """Load configuration data from a YAML file.
 
         Args:
@@ -224,13 +274,12 @@ class MCPConfig:
                 with open(config_file_path, 'r') as f:
                     return yaml.safe_load(f) or {}
             else:
-                self.logger.warning(f"Config file not found at {config_file_path}. Using defaults.")
-                # Create empty config file
-                with open(config_file_path, 'w') as f:
-                    yaml.dump({}, f)
+                self.logger.warning(f"Config file not found at {config_file_path}. Using defaults (no config created).")
                 return {}
         except yaml.YAMLError as e:
             self.logger.error(f"Error parsing YAML config file {config_file_path}: {e}")
+        except OSError as e:
+            self.logger.error(f"OS error reading config file {config_file_path}: {e}")
         except Exception as e:
-            self.logger.error(f"Error reading config file {config_file_path}: {e}")
+            self.logger.error(f"Unexpected error reading config file {config_file_path}: {e}")
         return {}

sokrates_mcp-0.4.0/src/sokrates_mcp/utils.py

@@ -0,0 +1,28 @@
+import secrets
+
+class Utils:
+    
+    @staticmethod
+    def rand_int_inclusive(min_val: int, max_val: int) -> int:
+        """
+        Return a random integer N such that min_val <= N <= max_val.
+        Uses `secrets.randbelow` which is cryptographically secure.
+
+        Parameters
+        ----------
+        min_val : int
+            Lower bound (inclusive).
+        max_val : int
+            Upper bound (inclusive).
+
+        Returns
+        -------
+        int
+            Random integer in the specified range.
+        """
+        if min_val > max_val:
+            raise ValueError("min_val must be <= max_val")
+
+        # randbelow(n) returns 0 .. n-1.  We need a window of size (max-min+1)
+        range_size = max_val - min_val + 1
+        return secrets.randbelow(range_size) + min_val

{sokrates_mcp-0.2.0 → sokrates_mcp-0.4.0}/src/sokrates_mcp/workflow.py

@@ -1,9 +1,15 @@
+from pathlib import Path
+import logging
+from typing import List
+
 from fastmcp import Context
-from .mcp_config import MCPConfig
+
 from sokrates import FileHelper, RefinementWorkflow, LLMApi, PromptRefiner, IdeaGenerationWorkflow
 from sokrates.coding.code_review_workflow import run_code_review
-from pathlib import Path
-from typing import List
+
+from .mcp_config import MCPConfig
+from .utils import Utils
+
 class Workflow:
   
   WORKFLOW_COMPLETION_MESSAGE = "Workflow completed."
@@ -14,12 +20,8 @@ class Workflow:
     Args:
         config (MCPConfig): The MCP configuration object
     """
+    self.logger = logging.getLogger(f"{__name__}.{self.__class__.__name__}")
     self.config = config
-    default_provider = self.config.get_default_provider()
-    self.default_model = default_provider['default_model']
-    self.default_api_endpoint = default_provider['api_endpoint']
-    self.default_api_key = default_provider['api_key']
-
     self.prompt_refiner = PromptRefiner()
     
   def _get_model(self, provider, model=''):
@@ -76,7 +78,8 @@ class Workflow:
     """
     refinement_prompt = self.load_refinement_prompt(refinement_type)
     workflow = self._initialize_refinement_workflow(provider_name=provider, model=model)
-    
+    self.logger.info(f"Starting refinement workflow with provider: {provider} and model: {model}")
+
     await ctx.info(f"Prompt refinement and execution workflow started with refinement model: {workflow.model} . Waiting for the response from the LLM...")
     refined = workflow.refine_prompt(input_prompt=prompt, refinement_prompt=refinement_prompt)
     await ctx.info(self.WORKFLOW_COMPLETION_MESSAGE)
@@ -102,6 +105,8 @@ class Workflow:
     refinement_model = self._get_model(provider=prov, model=refinement_model)
     execution_model = self._get_model(provider=prov, model=execution_model)
 
+    self.logger.info(f"Starting refinement workflow with provider: {provider} with refinement model: {refinement_model} and execution model: {execution_model}")
+
     workflow = self._initialize_refinement_workflow(provider_name=provider, model=execution_model)
     await ctx.info(f"Prompt refinement and execution workflow started with refinement model: {refinement_model} and execution model {execution_model} . Waiting for the responses from the LLMs...")
     result = workflow.refine_and_send_prompt(input_prompt=prompt, refinement_prompt=refinement_prompt, refinement_model=refinement_model, execution_model=execution_model)
@@ -125,6 +130,7 @@ class Workflow:
     
     prov = self._get_provider(provider)
     model = self._get_model(provider=prov, model=model)
+    self.logger.info(f"Handing over prompt to provider: {provider} and model: {model}")
     llm_api = LLMApi(api_endpoint=prov['api_endpoint'], api_key=prov['api_key'])
 
     result = llm_api.send(prompt,model=model, temperature=temperature)
@@ -146,6 +152,7 @@ class Workflow:
     Returns:
         str: A JSON string containing the list of sub-tasks with complexity ratings.
     """
+    self.logger.info(f"Breaking down task with provider: {provider} and model: {model}")
     workflow = self._initialize_refinement_workflow(provider_name=provider, model=model)
     await ctx.info(f"Task break-down started with model: {workflow.model} . Waiting for the response from the LLM...")
     result = workflow.breakdown_task(task=task)
@@ -167,6 +174,8 @@ class Workflow:
     """
     prov = self._get_provider(provider)
     model = self._get_model(provider=prov, model=model)
+
+    self.logger.info(f"Generating random ideas with provider: {provider} and model: {model}")
     await ctx.info(f"Task `generate random ideas` started at provider: {prov['name']} with model: {model} , idea_count: {idea_count} and temperature: {temperature}. Waiting for the response from the LLM...")
 
     idea_generation_workflow = IdeaGenerationWorkflow(api_endpoint=prov['api_endpoint'],
@@ -200,6 +209,7 @@ class Workflow:
     prov = self._get_provider(provider)
     model = self._get_model(provider=prov, model=model)
 
+    self.logger.info(f"Generating ideas on topic with provider: {provider} and model: {model}")
     await ctx.info(f"Task `generate ideas on topic` started with topic: '{topic}' , model: {model} , idea_count: {idea_count} and temperature: {temperature}. Waiting for the response from the LLM...")
     idea_generation_workflow = IdeaGenerationWorkflow(api_endpoint=prov['api_endpoint'],
       api_key=prov['api_key'],
@@ -233,6 +243,7 @@ class Workflow:
     prov = self._get_provider(provider)
     model = self._get_model(provider=prov, model=model)
 
+    self.logger.info(f"Generating code review of type: {review_type} with provider: {provider} and model: {model}")
     await ctx.info(f"Generating code review of type: {review_type} - using model: {model} ...")
     run_code_review(file_paths=source_file_paths,
                     directory_path=source_directory,
@@ -256,6 +267,7 @@ class Workflow:
     Returns:
         str: Formatted list of configured providers.
     """
+    self.logger.info(f"Listing available providers")
     providers = self.config.available_providers()
     result = "# Configured providers"
     for prov in providers:
@@ -274,6 +286,7 @@ class Workflow:
     Returns:
         str: Formatted list of available models and API endpoint.
     """
+    self.logger.info(f"Listing models for provider: {provider_name}")
     await ctx.info(f"Retrieving endpoint information and list of available models for configured provider {provider_name} ...")
     if not provider_name:
       provider = self.config.get_default_provider()
@@ -290,4 +303,77 @@ class Workflow:
     model_list = "\n".join([f"- {model}" for model in models])
     result = f"{api_headline}\n# List of available models\n{model_list}"
     await ctx.info(self.WORKFLOW_COMPLETION_MESSAGE)
-    return result
+    return result
+  
+  async def store_to_file(self, ctx: Context, file_path: str, file_content: str) -> str:
+    """Store the provided content to a file on disk
+
+    """
+    await ctx.info(f"Storing file to: {file_path} ...")
+    self.logger.info(f"Storing content to file: {file_path}")
+    if not file_path:
+      raise ValueError("No file_path provided.")
+    if not file_content:
+      raise ValueError("No file_content provided.")
+    
+    FileHelper.write_to_file(file_path=file_path, content=file_content)
+
+    result = f"The file has been stored to {file_path}"
+    await ctx.info(self.WORKFLOW_COMPLETION_MESSAGE)
+    return result
+  
+  async def read_from_file(self, ctx: Context, file_path: str) -> str:
+    """Read content of the provided file path
+
+    """
+    await ctx.info(f"Reading file from: {file_path} ...")
+    templated_file = self._read_file_to_templated_format(file_path=file_path)
+    await ctx.info(self.WORKFLOW_COMPLETION_MESSAGE)
+    return templated_file
+  
+  async def read_files_from_directory(self, ctx: Context, directory_path: str, file_extensions: List[str]) -> str:
+    file_exts_str = '.*'
+    if file_extensions:
+      file_exts_str = ','.join(file_extensions)
+    self.logger.info(f"Reading content for directory: {directory_path}")
+    await ctx.info(f"Reading files from directory: {directory_path} with file extensions: {file_exts_str} ...")
+    all_files = FileHelper.directory_tree(directory=directory_path, file_extensions=file_extensions)
+    result = ""
+    for file_path in all_files:
+      file_content = self._read_file_to_templated_format(file_path)
+      result = "\n".join([result, file_content])
+    await ctx.info(self.WORKFLOW_COMPLETION_MESSAGE)
+    return result
+  
+  async def directory_tree(self, ctx: Context, directory_path: str) -> str:
+    self.logger.info(f"Listing directory tree for directory: {directory_path}")
+    await ctx.info(f"Listing files recursively for directory: {directory_path} ...")
+    all_file_paths = FileHelper.directory_tree(directory=directory_path)
+    result = f"Directory: {directory_path}\n{"\n- ".join(all_file_paths)}"
+    
+    await ctx.info(self.WORKFLOW_COMPLETION_MESSAGE)
+    return result
+  
+  async def roll_dice(self, ctx: Context, number_of_dice: int=1, side_count: int=6, number_of_rolls: int=1) -> str:
+    """Roll a dice with the provided number of sides and return the result
+
+    """
+    self.logger.info(f"Rolling {number_of_dice} dice with  {side_count} sides {number_of_rolls} times")
+    await ctx.info(f"Throwing {number_of_dice} dice with {side_count} sides {number_of_rolls} times ...")
+    result = ""
+    for throw_number in range(1,number_of_rolls):
+      result = f"{result}# Roll {throw_number}\n"
+      for dice_number in range(1, number_of_dice):
+        dice_result = Utils.rand_int_inclusive(1, side_count)
+        result = f"- Dice {dice_number} result: {dice_result}\n"
+    await ctx.info(self.WORKFLOW_COMPLETION_MESSAGE)
+    return result
+  
+  def _read_file_to_templated_format(self, file_path: str) -> str:
+    if not file_path:
+      raise ValueError("No file_path provided.")
+    if not Path(file_path).is_file():
+      raise ValueError("No file exists at the given file path.")
+
+    content = FileHelper.read_file(file_path=file_path)
+    return f"<file source_file_path='{file_path}'>\n{content}\n</file>"

{sokrates_mcp-0.2.0 → sokrates_mcp-0.4.0/src/sokrates_mcp.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sokrates-mcp
-Version: 0.2.0
+Version: 0.4.0
 Summary: A templated MCP server for demonstration and quick start.
 Author-email: Julian Weber <julianweberdev@gmail.com>
 License: MIT License
@@ -158,12 +158,20 @@ providers:
 ### Starting the Server
 
 ```bash
+# from local git repo
 uv run sokrates-mcp
+
+# without checking out the git repo
+uvx sokrates-mcp
 ```
 
 ### Listing available command line options
 ```bash
+# from local git repo
 uv run sokrates-mcp --help
+
+# without checking out the git repo
+uvx sokrates-mcp --help
 ```
 
 ## Architecture & Technical Details
@@ -185,110 +193,37 @@ The server follows a modular design pattern:
 
 ## Available Tools
 
-### main.py
-
-- **refine_prompt**: Refines a given prompt by enriching it with additional context.
-  - Parameters:
-    - `prompt` (str): The input prompt to be refined
-    - `refinement_type` (str, optional): Type of refinement ('code' or 'default'). Default is 'default'
-    - `model` (str, optional): Model name for refinement. Default is 'default'
-
-- **refine_and_execute_external_prompt**: Refines a prompt and executes it with an external LLM.
-  - Parameters:
-    - `prompt` (str): The input prompt to be refined and executed
-    - `refinement_model` (str, optional): Model for refinement. Default is 'default'
-    - `execution_model` (str, optional): Model for execution. Default is 'default'
-    - `refinement_type` (str, optional): Type of refinement ('code' or 'default'). Default is 'default'
-
-- **handover_prompt**: Hands over a prompt to an external LLM for processing.
-  - Parameters:
-    - `prompt` (str): The prompt to be executed externally
-    - `model` (str, optional): Model name for execution. Default is 'default'
-
-- **breakdown_task**: Breaks down a task into sub-tasks with complexity ratings.
-  - Parameters:
-    - `task` (str): The full task description to break down
-    - `model` (str, optional): Model name for processing. Default is 'default'
-
-- **list_available_models**: Lists all available large language models accessible by the server.
-
-### mcp_config.py
-
-- **MCPConfig** class: Manages configuration settings for the MCP server.
-  - Parameters:
-    - `config_file_path` (str, optional): Path to YAML config file
-    - `api_endpoint` (str, optional): API endpoint URL
-    - `api_key` (str, optional): API key for authentication
-    - `model` (str, optional): Model name
-
-### workflow.py
-
-- **Workflow** class: Implements the business logic for prompt refinement and execution.
-  - Methods:
-    - `refine_prompt`: Refines a given prompt
-    - `refine_and_execute_external_prompt`: Refines and executes a prompt with an external LLM
-    - `handover_prompt`: Hands over a prompt to an external LLM for processing
-    - `breakdown_task`: Breaks down a task into sub-tasks
-    - `list_available_models`: Lists all available models
+See the [main.py](src/sokrates_mcp/main.py) file for a list of all mcp tools in the server
 
 ## Project Structure
 
 - `src/sokrates_mcp/main.py`: Sets up the MCP server and registers tools
 - `src/sokrates_mcp/mcp_config.py`: Configuration management
+- `src/sokrates_mcp/utils.py`: Helper and utility methods
 - `src/sokrates_mcp/workflow.py`: Business logic for prompt refinement and execution
 - `pyproject.toml`: Dependency management
 
 
-## Script List
-
-### `main.py`
-Sets up an MCP server using the FastMCP framework to provide tools for prompt refinement and execution workflows.
-#### Usage
-- `uv run python main.py` - Start the MCP server (default port: 8000)
-- `uv run fastmcp dev main.py` - Run in development mode with auto-reload
-
-### `mcp_config.py`
-Provides configuration management for the MCP server. Loads configuration from a YAML file and sets default values if needed.
-#### Usage
-- Import and use in other scripts:
-  ```python
-  from mcp_config import MCPConfig
-  config = MCPConfig(api_endpoint="https://api.example.com", model="my-model")
-  ```
-
-### `workflow.py`
-Implements the business logic for prompt refinement and execution workflows. Contains methods to refine prompts, execute them with external LLMs, break down tasks, etc.
-#### Usage
-- Import and use in other scripts:
-  ```python
-  from workflow import Workflow
-  from mcp_config import MCPConfig
-
-  config = MCPConfig()
-  workflow = Workflow(config)
-  result = await workflow.refine_prompt("Write a Python function to sort a list", refinement_type="code")
-  ```
-
-### `src/mcp_client_example.py`
-Demonstrates a basic Model Context Protocol (MCP) client using the fastmcp library. Defines a simple model and registers it with the client.
-
-#### Usage
-- Run as a standalone script:
-  ```bash
-  python src/mcp_client_example.py
-  ```
-- Or use with an ASGI server like Uvicorn:
-  ```bash
-  uvicorn src.mcp_client_example:main --factory
-  ```
-
 **Common Error:**
 If you see "ModuleNotFoundError: fastmcp", ensure:
-1. Dependencies are installed (`uv pip install .`)
+1. Dependencies are installed (`uv sync`)
 2. Python virtual environment is activated
 
 ## Changelog
 
+**0.4.0 (Aug 2025)**
+- adds new tools:
+  - read_files_from_directory
+  - directory_tree
+  - logging refactoring in workflow.py
+
+**0.3.0 (Aug 2025)**
+- adds new tools:
+    - roll_dice
+    - read_from_file
+    - store_to_file
+- refactorings - code quality - still ongoing
+
 **0.2.0 (Aug 2025)**
 - First published version
 - Update to latest sokrates library version

{sokrates_mcp-0.2.0 → sokrates_mcp-0.4.0}/src/sokrates_mcp.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ pyproject.toml
 src/sokrates_mcp/__init__.py
 src/sokrates_mcp/main.py
 src/sokrates_mcp/mcp_config.py
+src/sokrates_mcp/utils.py
 src/sokrates_mcp/workflow.py
 src/sokrates_mcp.egg-info/PKG-INFO
 src/sokrates_mcp.egg-info/SOURCES.txt