MCPmed Python Package Template

A cookiecutter template for creating Python packages with a standardized structure, based on the STRING-MCP example. This template is specifically designed for MCPmed projects but can be used for any Python package.

Architecture Overview

This repository provides a generalized Python pattern for building a server that exposes functionalities of external APIs/services through the Model-Context-Protocol (MCP). It employs a Bridge component to abstract external interactions and separate Server/CLI components to handle different client interfaces.

Bridge: Encapsulates all logic for interacting with a specific external API. This is the core component that both MCP Server and CLI use.

Server: Handles the MCP protocol, dispatches requests to the Bridge, and manages tool discovery.

CLI: Provides command-line interface functionality, also using the Bridge for API interactions.

Error Handling: Integrated across all components for robust operation.

                            (Tool Management)        (Data Transformation)
+------------------+     +--------------------+     +-------------------+     +--------------------+
|  Client (MCP)    |<--->|   Server           |<--->|   Bridge          |<--->|   Client (CLI)    |
|                  |     | (MCP Protocol      |     | (API Adapter)     |     | (Command Line)    |
+------------------+     |   Handler)         |     |                   |     |                   |
  (JSON-RPC based)       +--------------------+     +-------------------+     +--------------------+
                            (Internal Logic,      (External API Calls,      (Internal Logic,
                            Tool Management)        Data Transformation)        Tool Management)

Features

• Standardized Structure: Follows Python packaging best practices
• Bridge Pattern: Centralized API logic in a reusable Bridge component
• Configurable Options: Choose whether to include CLI and MCP server functionality
• Complete Setup: Includes pyproject.toml, README, tests, and development tools
• Modern Python: Uses modern Python packaging standards with pyproject.toml
• Development Ready: Includes testing, linting, and formatting configuration
• MCP Integration: Optional Model Context Protocol server implementation
• CLI Interface: Optional command-line interface for direct API access

Usage

Prerequisites

Install cookiecutter:

pip install cookiecutter

Create a New Package

# Create a new package from this template
cookiecutter MCPmedtemplate

# Or specify the template path directly
cookiecutter /path/to/MCPmedtemplate/

Template Variables

The template will prompt you for the following variables:

• project_name: The display name of your project (e.g., "My Awesome Package")
• project_slug: Automatically generated from project_name (e.g., "my_awesome_package")
• package_name: The Python package name (lowercase, same as project_slug)
• project_description: A brief description of your package
• author_name: Your name
• author_email: Your email address
• github_username: Your GitHub username
• github_repo: The GitHub repository name
• python_version: Minimum Python version (default: 3.8)
• license: License type (default: MIT)
• use_cli: Whether to include CLI functionality (y/n)
• use_mcp: Whether to include MCP server functionality (y/n)

Generated Structure

your-package/
├── pyproject.toml          # Package configuration
├── README.md              # Package documentation
├── LICENSE                # License file
├── .gitignore            # Git ignore file
├── your_package/         # Main package directory
│   ├── __init__.py       # Package initialization
│   ├── bridge.py         # Core API bridge (shared by CLI and MCP)
│   ├── main.py           # CLI entry point (if use_cli=y)
│   ├── cli.py            # CLI interface (if use_cli=y)
│   ├── mcp_server.py     # MCP server (if use_mcp=y)
│   └── tests/            # Test files

Customization

Adding Dependencies

Edit the pyproject.toml file to add your package dependencies:

[project]
dependencies = [
    "requests>=2.25.0",
    "pandas>=1.3.0",
    "numpy>=1.21.0",
]

Extending the Bridge

The bridge.py file contains the core API logic. Add your methods here:

def your_api_method(self, param1: str) -> Dict[str, Any]:
    """Your custom API method."""
    # Implement your API call logic here
    return {"result": "your data"}

Adding CLI Commands

If you enabled CLI functionality, edit the cli.py file to add your commands.

Adding MCP Tools

If you enabled MCP functionality, edit the mcp_server.py file to add your tools. The MCP server uses the Bridge methods.

Development

After creating your package:

# Navigate to your new package
cd your-package

# Install in development mode
pip install -e .

License

This template is provided under the MIT License.