Kubementat/sokrates-mcp

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.

Installation & Setup

Prerequisites

Ensure you have:

• Python 3.10+
• uv (fast package installer)

Install from PyPi

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:

git clone https://github.com/Kubementat/sokrates-mcp.git
cd sokrates-mcp

2. Install dependencies using pyproject.toml:

uv sync

Setup Server Configuration File

Via git installed version

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:

mkdir $HOME/.sokrates-mcp
vim $HOME/.sokrates-mcp/config.yml

Then use this as template and adjust it to your use case:

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

{
  "mcpServers": {
    "sokrates": {
      "command": "uv",
      "args": [
        "run",
        "sokrates-mcp"
      ],
      "cwd": "YOUR_PATH_TO_sokrates-mcp",
      "timeout": 600000
    }
  }
}

via uvx

{
  "mcpServers": {
    "sokrates": {
      "command": "uvx",
      "args": [
        "sokrates-mcp"
      ]
    }
  }
}

Usage Examples

Starting the Server

# from local git repo
uv run sokrates-mcp

# without checking out the git repo
uvx sokrates-mcp

Listing available command line options

# 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 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.3 (Sep 2025)

• bugfix in workflow class - fix refinement workflow

0.4.2 (Sep 2025)

• Update version to 0.4.2

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