Helping Geek MCP Server - Sample Project

A simplified Model Context Protocol (MCP) server created as a proof-of-concept for learning Python package publishing to PyPI. This project demonstrates the structure and components of an MCP server without containing production-level code.

🌟 Overview

This is a sample MCP server project that provides:

• Basic String Operations: Simple text manipulation utilities
• Data Transformation: Basic data format conversion (JSON, XML, YAML)
• Template Management: Simple template handling with variable substitution
• Configuration System: Basic configuration management
• MCP Protocol Support: Working MCP server implementation for AI assistants

🚀 Features

MCP Tools

1. `process_text` - Basic text processing (uppercase, lowercase, reverse, capitalize)
2. `transform_data` - Data format transformation (JSON, XML, YAML)
3. `get_template` - Template retrieval with variable substitution
4. `get_config` - Configuration value retrieval

Key Capabilities

• 🎓 Educational: Perfect for learning Python packaging and PyPI publishing
• 🔧 Simple Code: Easy-to-understand implementations
• 📦 Modern Packaging: Uses pyproject.toml and modern Python standards
• 🤖 MCP Compatible: Works with AI assistants (Cline, Claude Desktop)
• 🧪 Test Suite: Complete test coverage with pytest
• 📚 Documentation: Comprehensive guides and examples

📋 Requirements

• Python: 3.10 or higher
• Dependencies: mcp>=1.0.0, requests>=2.31.0

🔧 Installation

Option 1: Install from PyPI (When Published)

pip install helping-geek-mcp

Option 2: Install from Source

# Navigate to the package directory
cd python-server

# Install build tools
pip install build twine

# Build the package
python -m build

# Install from the wheel
pip install dist/helping_geek_mcp-*.whl --force-reinstall

Option 3: Editable Install (For Development)

# Navigate to the package directory
cd python-server

# Install in editable mode
pip install -e ".[dev]"

Verify Installation

# Check if the package is installed
pip show helping-geek-mcp

# Test the server
helping-geek-mcp start

🎯 Quick Start

Running the Server

# Start with default settings
helping-geek-mcp start

# Start with logging enabled
helping-geek-mcp start --enable-logging --log-level DEBUG

# Start with custom base directory
helping-geek-mcp start --base-dir /custom/path

Configuration for AI Assistants

#### Cline (VS Code Extension)

Add to your Cline MCP settings:

{
  "mcpServers": {
    "helping-geek-mcp": {
      "timeout": 60,
      "command": "helping-geek-mcp",
      "args": ["start"],
      "env": {}
    }
  }
}

#### Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "helping-geek-mcp": {
      "command": "helping-geek-mcp",
      "args": ["start"]
    }
  }
}

🛠️ Available Tools

1. process_text

Process text with basic string operations.

Parameters:

• text (required): Input text to process
• operation (optional): Operation type - "uppercase", "lowercase", "reverse", "capitalize"

Example:

# Via AI assistant
"Process 'hello world' to uppercase"
# Returns: "HELLO WORLD"

2. transform_data

Transform data between different formats.

Parameters:

• data (required): Input data dictionary
• format_type (optional): Output format - "json", "xml", "yaml"

Example:

# Via AI assistant
"Transform {'name': 'Alice', 'age': 30} to XML format"

3. get_template

Get a template and fill it with variables.

Parameters:

• template_name (required): Name of the template
• variables (optional): Variables to substitute

Example:

# Via AI assistant
"Get the greeting template with name=Bob and service=MCP"

4. get_config

Get configuration value by key.

Parameters:

• key (required): Configuration key

Example:

# Via AI assistant
"Get the version from configuration"

📁 Project Structure

python-server/
├── src/
│   └── helping_geek_mcp/
│       ├── server.py              # Main MCP server
│       ├── config/                # Configuration management
│       ├── utils/                 # Utility modules
│       │   ├── string_helper.py
│       │   ├── data_processor.py
│       │   ├── template_manager.py
│       │   └── constants.py
│       ├── services/              # Service layer
│       ├── tools/                 # Additional tools
│       ├── prompts/               # Error definitions
│       └── static/                # Static resources
│           └── templates/
├── tests/                         # Test suite
│   ├── test_string_helper.py
│   ├── test_data_processor.py
│   ├── test_template_manager.py
│   ├── test_config_manager.py
│   └── test_basic_service.py
├── docs/                          # Documentation
│   ├── API_DOCS.md
│   ├── USAGE_EXAMPLES.md
│   ├── PACKAGING_GUIDE.md
│   └── PROJECT_STRUCTURE.md
├── pyproject.toml                 # Package configuration
├── requirements.txt               # Dependencies
├── LICENSE                        # MIT License
├── CHANGELOG.md                   # Version history
└── README.md                      # Main documentation

🧪 Testing

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=helping_geek_mcp --cov-report=html

# Run specific test file
pytest tests/test_string_helper.py

# Run with verbose output
pytest -v

🔧 Development

Setting Up Development Environment

# Navigate to project
cd python-server

# Create virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Linux/Mac

# Install in development mode
pip install -e ".[dev]"

Code Quality

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

Building the Package

# Clean previous builds
Remove-Item -Recurse -Force dist, build, *.egg-info

# Build package
python -m build

# Check package
twine check dist/*

📦 Publishing to PyPI

Test PyPI (Recommended First)

# Upload to Test PyPI
twine upload --repository testpypi dist/*

# Test install
pip install --index-url https://test.pypi.org/simple/ helping-geek-mcp

Production PyPI

# Upload to PyPI
twine upload dist/*

# Verify
pip install helping-geek-mcp

📚 Documentation

• [GET_STARTED.md](python-server/GET_STARTED.md) - Quick start guide
• [API_DOCS.md](python-server/docs/API_DOCS.md) - API reference
• [USAGE_EXAMPLES.md](python-server/docs/USAGE_EXAMPLES.md) - Code examples
• [PACKAGING_GUIDE.md](python-server/docs/PACKAGING_GUIDE.md) - PyPI publishing guide
• [PROJECT_STRUCTURE.md](python-server/docs/PROJECT_STRUCTURE.md) - Architecture details
• [QUICK_REFERENCE.md](python-server/QUICK_REFERENCE.md) - Command reference

🐛 Troubleshooting

Import Errors

# Reinstall package
pip uninstall helping-geek-mcp
pip install helping-geek-mcp

Build Issues

# Clean and rebuild
Remove-Item -Recurse -Force dist, build, *.egg-info
python -m build

Version Already Exists

If uploading to PyPI fails with "file already exists":

1. Update version in pyproject.toml
2. Update CHANGELOG.md
3. Rebuild and upload

🤝 Contributing

This is a sample/educational project. Feel free to:

1. Fork the repository
2. Experiment with the code
3. Learn from the structure
4. Use as a template for your own projects

📄 License

MIT License - See LICENSE file for details.

🔗 Links

• Project: python-server/ directory
• Package Name: helping-geek-mcp
• Author: Helping Geek
• Email: [email protected]
• MCP Documentation: https://modelcontextprotocol.io

🎓 Purpose

This project serves as:

• POC for PyPI publishing process
• Learning Tool for Python packaging
• Template for MCP server projects
• Reference for project structure

⚠️ Important Notes

• This is a demonstration project
• Not for production use
• Contains simplified code only
• Perfect for testing PyPI workflow
• No proprietary or sensitive code included

🙏 Acknowledgments

• Built with FastMCP
• Powered by Model Context Protocol

Ready to publish! See python-server/GET_STARTED.md for step-by-step publishing instructions.