| Name | sokrates-mcp JSON |
| Version |
0.4.1
JSON |
| download |
| home_page | None |
| Summary | A templated MCP server for demonstration and quick start. |
| upload_time | 2025-09-01 19:53:00 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License Copyright (c) 2025 Julian Weber 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. |
| keywords |
mcp
llm
tools
system-monitoring
ai
prompt refinement
idea generation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sokrates-mcp
[](https://opensource.org/licenses/MIT)
[](https://github.com/Kubementat/sokrates-mcp)
A MCP server offering tools for prompt refinement and execution workflows using the FastMCP framework and the `sokrates` python library.
## Features
- Multiple provider/APU support
- Available Model/Provider listing
- Prompt refinement with different types (code/default)
- External LLM processing
- Task breakdown into sub-tasks
- Create code reviews for Python source files
- Generate random ideas
- Generate ideas to a topic
Have a look at the [sokrates library](https://github.com/Kubementat/sokrates).
## Installation & Setup
### Prerequisites
Ensure you have:
* Python 3.10+
* uv (fast package installer)
### Install from PyPi
```bash
pip install sokrates-mcp
# or using uv (recommended)
## basic version:
uv pip install sokrates-mcp
```
### Alternative - Local Configuration from git
1. Clone the repository if hosted:
```bash
git clone https://github.com/Kubementat/sokrates-mcp.git
cd sokrates-mcp
```
2. Install dependencies using pyproject.toml:
```bash
uv sync
```
### Setup Server Configuration File
#### Via git installed version
```bash
mkdir $HOME/.sokrates-mcp
cp config.yml.example $HOME/.sokrates-mcp/config.yml
# edit the according endpoints to your use case
vim $HOME/.sokrates-mcp/config.yml
```
#### From scratch
Create the configuration file:
```bash
mkdir $HOME/.sokrates-mcp
vim $HOME/.sokrates-mcp/config.yml
```
Then use this as template and adjust it to your use case:
```yaml
refinement_prompt_filename: refine-prompt.md
refinement_coding_prompt_filename: refine-coding-v3.md
# providers
default_provider: local
providers:
- name: local
type: openai
api_endpoint: http://localhost:1234/v1
api_key: "not-required"
default_model: "qwen/qwen3-4b-2507"
- name: external
type: openai
api_endpoint: http://CHANGEME/v1
api_key: CHANGEME
default_model: CHANGEME
```
### Setup as mcp server in other tools (Example for LM Studio)
#### For local Git installed version
```yaml
{
"mcpServers": {
"sokrates": {
"command": "uv",
"args": [
"run",
"sokrates-mcp"
],
"cwd": "YOUR_PATH_TO_sokrates-mcp",
"timeout": 600000
}
}
}
```
#### via uvx
```yaml
{
"mcpServers": {
"sokrates": {
"command": "uvx",
"args": [
"sokrates-mcp"
]
}
}
}
```
## Usage Examples
### 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
The server follows a modular design pattern:
1. Tools are registered in `main.py` using FastMCP decorators
2. Dependency management via pyproject.toml
3. Configuration files stored in `$HOME/.sokrates-mcp/` directory
## Contributing Guidelines
1. Fork the repository and create feature branches
2. Follow PEP8 style guide with 4-space indentation
3. Submit pull requests with:
- Clear description of changes
- Updated tests (see Testing section)
- Documentation updates
## Available Tools
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
**Common Error:**
If you see "ModuleNotFoundError: fastmcp", ensure:
1. Dependencies are installed (`uv sync`)
2. Python virtual environment is activated
## Changelog
**0.4.1 (Sep 2025)**
- fix roll_dice tool
**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
- bugfixes and cleanup
- multi provider/API support in the configuration file
**0.1.5 (July 2025)**
- Updated README with comprehensive documentation
- Added tool descriptions and usage examples
- Improved project structure overview
**0.1.0 (March 7, 2025)**
- Initial release with refinement tools
- Basic FastMCP integration
Bug reports and feature requests: [GitHub Issues](https://github.com/Kubementat/sokrates-mcp/issues)
Raw data
{
"_id": null,
"home_page": null,
"name": "sokrates-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, llm, tools, system-monitoring, ai, prompt refinement, idea generation",
"author": null,
"author_email": "Julian Weber <julianweberdev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f9/0a/695c21e83092d97bc860934301a5c5faac4da6a361f31ab5af18a424c325/sokrates_mcp-0.4.1.tar.gz",
"platform": null,
"description": "# sokrates-mcp\n\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/Kubementat/sokrates-mcp)\n\nA MCP server offering tools for prompt refinement and execution workflows using the FastMCP framework and the `sokrates` python library.\n\n## Features\n\n- Multiple provider/APU support\n- Available Model/Provider listing\n- Prompt refinement with different types (code/default)\n- External LLM processing\n- Task breakdown into sub-tasks\n- Create code reviews for Python source files\n- Generate random ideas\n- Generate ideas to a topic\n\nHave a look at the [sokrates library](https://github.com/Kubementat/sokrates).\n\n## Installation & Setup\n\n### Prerequisites\n\nEnsure you have:\n* Python 3.10+\n* uv (fast package installer)\n\n### Install from PyPi\n```bash\npip install sokrates-mcp\n\n# or using uv (recommended)\n## basic version: \nuv pip install sokrates-mcp\n```\n\n### Alternative - Local Configuration from git\n\n1. Clone the repository if hosted:\n```bash\ngit clone https://github.com/Kubementat/sokrates-mcp.git\ncd sokrates-mcp\n```\n\n2. Install dependencies using pyproject.toml:\n```bash\nuv sync\n```\n\n### Setup Server Configuration File\n\n#### Via git installed version\n```bash\nmkdir $HOME/.sokrates-mcp\ncp config.yml.example $HOME/.sokrates-mcp/config.yml\n# edit the according endpoints to your use case\nvim $HOME/.sokrates-mcp/config.yml\n```\n\n#### From scratch\nCreate the configuration file:\n```bash\nmkdir $HOME/.sokrates-mcp\nvim $HOME/.sokrates-mcp/config.yml\n```\n\nThen use this as template and adjust it to your use case:\n```yaml\nrefinement_prompt_filename: refine-prompt.md\nrefinement_coding_prompt_filename: refine-coding-v3.md\n\n# providers\ndefault_provider: local\nproviders:\n - name: local\n type: openai\n api_endpoint: http://localhost:1234/v1\n api_key: \"not-required\"\n default_model: \"qwen/qwen3-4b-2507\"\n - name: external\n type: openai\n api_endpoint: http://CHANGEME/v1\n api_key: CHANGEME\n default_model: CHANGEME\n```\n\n### Setup as mcp server in other tools (Example for LM Studio)\n\n#### For local Git installed version\n```yaml\n{\n \"mcpServers\": {\n \"sokrates\": {\n \"command\": \"uv\",\n \"args\": [\n \"run\",\n \"sokrates-mcp\"\n ],\n \"cwd\": \"YOUR_PATH_TO_sokrates-mcp\",\n \"timeout\": 600000\n }\n }\n}\n```\n\n#### via uvx\n```yaml\n{\n \"mcpServers\": {\n \"sokrates\": {\n \"command\": \"uvx\",\n \"args\": [\n \"sokrates-mcp\"\n ]\n }\n }\n}\n```\n\n## Usage Examples\n\n### Starting the Server\n\n```bash\n# from local git repo\nuv run sokrates-mcp\n\n# without checking out the git repo\nuvx sokrates-mcp\n```\n\n### Listing available command line options\n```bash\n# from local git repo\nuv run sokrates-mcp --help\n\n# without checking out the git repo\nuvx sokrates-mcp --help\n```\n\n## Architecture & Technical Details\n\nThe server follows a modular design pattern:\n1. Tools are registered in `main.py` using FastMCP decorators\n2. Dependency management via pyproject.toml\n3. Configuration files stored in `$HOME/.sokrates-mcp/` directory\n\n\n## Contributing Guidelines\n\n1. Fork the repository and create feature branches\n2. Follow PEP8 style guide with 4-space indentation\n3. Submit pull requests with:\n - Clear description of changes\n - Updated tests (see Testing section)\n - Documentation updates\n\n## Available Tools\n\nSee the [main.py](src/sokrates_mcp/main.py) file for a list of all mcp tools in the server\n\n## Project Structure\n\n- `src/sokrates_mcp/main.py`: Sets up the MCP server and registers tools\n- `src/sokrates_mcp/mcp_config.py`: Configuration management\n- `src/sokrates_mcp/utils.py`: Helper and utility methods\n- `src/sokrates_mcp/workflow.py`: Business logic for prompt refinement and execution\n- `pyproject.toml`: Dependency management\n\n\n**Common Error:**\nIf you see \"ModuleNotFoundError: fastmcp\", ensure:\n1. Dependencies are installed (`uv sync`)\n2. Python virtual environment is activated\n\n## Changelog\n\n**0.4.1 (Sep 2025)**\n- fix roll_dice tool\n\n**0.4.0 (Aug 2025)**\n- adds new tools:\n - read_files_from_directory\n - directory_tree\n - logging refactoring in workflow.py\n\n**0.3.0 (Aug 2025)**\n- adds new tools:\n - roll_dice\n - read_from_file\n - store_to_file\n- refactorings - code quality - still ongoing\n\n**0.2.0 (Aug 2025)**\n- First published version\n- Update to latest sokrates library version\n- bugfixes and cleanup\n- multi provider/API support in the configuration file \n\n**0.1.5 (July 2025)**\n- Updated README with comprehensive documentation\n- Added tool descriptions and usage examples\n- Improved project structure overview\n\n**0.1.0 (March 7, 2025)**\n- Initial release with refinement tools\n- Basic FastMCP integration\n\nBug reports and feature requests: [GitHub Issues](https://github.com/Kubementat/sokrates-mcp/issues)\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2025 Julian Weber 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.",
"summary": "A templated MCP server for demonstration and quick start.",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/Kubementat/sokrates-mcp",
"Repository": "https://github.com/Kubementat/sokrates-mcp"
},
"split_keywords": [
"mcp",
" llm",
" tools",
" system-monitoring",
" ai",
" prompt refinement",
" idea generation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "438bb2a00784d7a70de33ffc8c33a8ba46601a379376b1246ac1e1a2e98b7099",
"md5": "39819ee9d92c15eb38169133ef3311ed",
"sha256": "562e1a8668930703b16434121301a38ab1329505cfe5295850f29f7875d8d5c9"
},
"downloads": -1,
"filename": "sokrates_mcp-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "39819ee9d92c15eb38169133ef3311ed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19210,
"upload_time": "2025-09-01T19:52:59",
"upload_time_iso_8601": "2025-09-01T19:52:59.178498Z",
"url": "https://files.pythonhosted.org/packages/43/8b/b2a00784d7a70de33ffc8c33a8ba46601a379376b1246ac1e1a2e98b7099/sokrates_mcp-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f90a695c21e83092d97bc860934301a5c5faac4da6a361f31ab5af18a424c325",
"md5": "9d2867894a26f913d2a40e9445515424",
"sha256": "e33488e6051e26e4338a50e90bf432199af381e6a6b5a7574eb31ab747e4c422"
},
"downloads": -1,
"filename": "sokrates_mcp-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "9d2867894a26f913d2a40e9445515424",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19753,
"upload_time": "2025-09-01T19:53:00",
"upload_time_iso_8601": "2025-09-01T19:53:00.525381Z",
"url": "https://files.pythonhosted.org/packages/f9/0a/695c21e83092d97bc860934301a5c5faac4da6a361f31ab5af18a424c325/sokrates_mcp-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 19:53:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Kubementat",
"github_project": "sokrates-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sokrates-mcp"
}
