poespas/mcp-server-template

MCP Server Template

A clean Model Context Protocol (MCP) server template built with FastMCP 2.0, ready for you to build your own MCP server on top of it.

Features

• FastMCP 2.0: Modern MCP server implementation
• Multiple Transport Support: stdio, HTTP, and SSE (Server-Sent Events)
• Auto-tool Registration: Automatic discovery and registration of tools
• Base Tool Class: Common functionality for all tools
• Safe Command Execution: Utilities for secure command execution
• Hello World Tool: Example tool to get you started

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Run the server:

python server.py

The server will start with stdio transport for MCP clients.

Project Structure

├── server.py              # Main MCP server entry point
├── tools/                 # Directory containing all MCP tools
│   ├── __init__.py        # Auto-registration of tools
│   ├── generic.py         # Base tool class and registry
│   └── hello_world.py     # Example hello world tool
├── utils/                 # Shared utilities and helpers
│   ├── __init__.py
│   └── command_executor.py # Safe command execution utilities
├── tests/                 # Test files
├── requirements.txt       # Python dependencies
└── README.md             # This file

Available Tools

Hello World Tool

A simple example tool that returns a hello world message.

{
  "name": "hello_world",
  "description": "Simple hello world tool for testing"
}

Response:

{
  "message": "Hello World from MCP Server Template!",
  "status": "success"
}

Creating New Tools

1. Create a new tool file

Create a new Python file in the tools/ directory:

"""
My Custom Tool for MCP Server Template.
"""

from typing import Dict, Any
from .generic import BaseTool, tool_registry

class MyCustomTool(BaseTool):
    """My custom tool implementation."""
    
    async def tool_my_custom_function(self, param1: str, param2: int = 10) -> Dict[str, Any]:
        """
        My custom tool function.
        
        Args:
            param1: First parameter
            param2: Second parameter with default value
            
        Returns:
            Dict containing the result
        """
        # Your tool logic here
        result = f"Processed {param1} with value {param2}"
        
        return {
            "result": result,
            "status": "success",
            "param1": param1,
            "param2": param2
        }

# Create and register the tool instance automatically
my_custom_tool = MyCustomTool()
tool_registry.register_tool(my_custom_tool)

2. Tool Naming Convention

• Tool methods should start with tool_ prefix
• The actual tool name will be the method name without the tool_ prefix
• Example: tool_my_custom_function becomes my_custom_function

3. Using the Base Tool Class

The BaseTool class provides:

• Automatic MCP registration
• Logging setup
• Common functionality

4. Using Command Executor

For tools that need to execute shell commands:

from utils.command_executor import CommandExecutor

# Execute a command
result = await CommandExecutor.execute_command("ls -la", timeout=30)

if result.success:
    print(f"Output: {result.stdout}")
else:
    print(f"Error: {result.stderr}")

Usage Examples

Using with MCP Client

1. Start the server:

python server.py

2. Connect with an MCP client:

# Example with stdio transport
python server.py | mcp-client

Using with HTTP API

The server can be configured to expose an HTTP API:

# In server.py, change the transport
mcp.run(transport="http", host="0.0.0.0", port=8000)

Development

Running Tests

./runtests.sh

Code Standards

• Use type hints for all function parameters and return values
• Follow PEP 8 style guidelines
• Use descriptive variable and function names
• Add docstrings to all functions and classes
• Handle errors gracefully with proper error messages
• Use async/await for I/O operations

Security Standards

• Never execute dangerous commands without proper validation
• Sanitize all user inputs
• Use subprocess with proper security measures
• Log all command executions for audit purposes
• Implement rate limiting for resource-intensive operations

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

This template is provided as-is for building your own MCP servers.