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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sokrates-mcp
-Version: 0.2.0
+Version: 0.3.0
 Summary: A templated MCP server for demonstration and quick start.
 Author-email: Julian Weber <julianweberdev@gmail.com>
 License: MIT License
@@ -224,7 +224,7 @@ The server follows a modular design pattern:
 ### workflow.py
 
 - **Workflow** class: Implements the business logic for prompt refinement and execution.
-  - Methods:
+  -  e.g.:
     - `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
@@ -289,6 +289,13 @@ If you see "ModuleNotFoundError: fastmcp", ensure:
 
 ## Changelog
 
+**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.3.0}/README.md

@@ -186,7 +186,7 @@ The server follows a modular design pattern:
 ### workflow.py
 
 - **Workflow** class: Implements the business logic for prompt refinement and execution.
-  - Methods:
+  -  e.g.:
     - `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
@@ -251,6 +251,13 @@ If you see "ModuleNotFoundError: fastmcp", ensure:
 
 ## Changelog
 
+**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.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sokrates-mcp"
-version = "0.2.0"
+version = "0.3.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.3.0}/src/sokrates_mcp/main.py

@@ -294,6 +294,43 @@ 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="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.3.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.3.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.3.0}/src/sokrates_mcp/workflow.py

@@ -1,9 +1,14 @@
+from pathlib import Path
+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."
@@ -290,4 +295,49 @@ 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
+  
+  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} ...")
+    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} ...")
+    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)
+    result = f"<file source_file_path='{file_path}'>\n{content}\n</file>"
+    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
+
+    """
+    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

{sokrates_mcp-0.2.0 → sokrates_mcp-0.3.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.3.0
 Summary: A templated MCP server for demonstration and quick start.
 Author-email: Julian Weber <julianweberdev@gmail.com>
 License: MIT License
@@ -224,7 +224,7 @@ The server follows a modular design pattern:
 ### workflow.py
 
 - **Workflow** class: Implements the business logic for prompt refinement and execution.
-  - Methods:
+  -  e.g.:
     - `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
@@ -289,6 +289,13 @@ If you see "ModuleNotFoundError: fastmcp", ensure:
 
 ## Changelog
 
+**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.3.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