MCP Boilerplate Server

# MCP Server A Model Context Protocol (MCP) server built with FastMCP that provides tools, resources, and prompts for greeting, math operations, user management, and system monitoring. ## Features - **Tools**: Greeting, math operations (add/multiply), user information lookup - **Resources**: Server info, user data, configuration settings - **Prompts**: User analysis, report generation, system health checks, troubleshooting ## Quick Start ### Prerequisites - Python 3.12 or higher - [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended) or pip ## Installation Options ### Option 1: Install from PyPI (Recommended) ```bash # Install with uv (recommended) uv add mcp-server-boilerplate # Or install with pip pip install mcp-server-boilerplate # not published , this is boilerplate ``` After installation, you can run the server directly: ```bash mcp-server-boilerplate ``` ### Option 2: Install from GitHub (Development) 1. **Clone the repository**: ```bash git clone <YOUR_GITHUB_REPO_URL> cd mcp_server ``` 2. **Install uv** (if not already installed): ```bash # On macOS and Linux curl -LsSf https://astral.sh/uv/install.sh | sh # On Windows powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` 3. **Install dependencies**: ```bash uv sync ``` **Alternative with pip**: ```bash pip install fastmcp>=2.11.3 ``` 4. **Test the server**: ```bash uv run python main.py ``` You should see the FastMCP banner and server startup message. Press `Ctrl+C` to stop. ## Available Tools - `greet(name: str)` - Greet a person by name - `add(a: int, b: int)` - Add two numbers together - `multiply(a: int, b: int)` - Multiply two numbers together - `get_user_info(user_id: int)` - Get user information by ID ## Connecting to Claude Desktop To use this MCP server with Claude Desktop, you need to add it to your configuration file. ### Step 1: Find Your Config File - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%/Claude/claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` ### Step 2: Find Your Paths First, find the required paths for your system: ```bash # Find uv installation path which uv # Get your current directory pwd ``` ### Step 3: Add Server Configuration #### If Installed from PyPI Add this to your `claude_desktop_config.json` (create the file if it doesn't exist): ```json { "mcpServers": { "mcp-server-boilerplate": { "command": "mcp-server-boilerplate" } } } ``` #### If Installed from GitHub (Development) ```json { "mcpServers": { "mcp-server-boilerplate": { "command": "/path/to/uv", "args": [ "run", "python", "main.py" ], "cwd": "/path/to/your/mcp_server" } } } ``` **Important**: Replace the paths with your actual values: - Replace `/path/to/uv` with the output from `which uv` - Replace `/path/to/your/mcp_server` with your project directory path After adding the configuration, restart Claude Desktop to load the MCP server. ## Testing with MCP Inspector To test your server with MCP Inspector: 1. Start the server in one terminal: ```bash uv run python main.py ``` 2. In MCP Inspector, use these connection settings: - **Connection Type**: Local Command - **Command**: `/home/shaza/.local/bin/uv` (use `which uv` to find your path) - **Arguments**: `run python main.py` - **Working Directory**: `/home/shaza/shaza/mcp_server` Or alternatively, if using direct python: - **Command**: `python3` - **Arguments**: `main.py` - **Working Directory**: `/home/shaza/shaza/mcp_server` ## Troubleshooting ### Common Issues **1. "ModuleNotFoundError: No module named 'fastmcp'"** ```bash # Install dependencies uv sync # or pip install fastmcp>=2.11.3 ``` **2. "python: command not found"** - Use `python3` instead of `python` - Make sure Python 3.12+ is installed **3. "uv: command not found"** - Install uv following the installation instructions above - Or use the direct Python configuration in Claude Desktop **4. Claude Desktop connection issues** - Verify all paths in your config are absolute (not relative) - Restart Claude Desktop after config changes - Check that the config file is valid JSON (no trailing commas) - Test the server runs manually first: `uv run python main.py` **5. MCP Inspector connection errors** - Make sure the server isn't already running in another terminal - Use absolute paths for command and working directory - Verify uv is in your PATH ### Getting Help 1. Test the server manually: `uv run python main.py` 2. Check your paths with `which uv` and `pwd` 3. Validate your JSON config at [jsonlint.com](https://jsonlint.com/) 4. Check Claude Desktop logs for error messages ## Development ### Project Structure - `main.py` - Entry point that starts the MCP server - `server.py` - Main server code with tools, resources, and prompts - `pyproject.toml` - Python project configuration and dependencies ### Adding New Features - **Tools**: Add functions decorated with `@mcp.tool` in `server.py` - **Resources**: Add functions decorated with `@mcp.resource("uri")` - **Prompts**: Add functions decorated with `@mcp.prompt` All functions should include proper type hints and docstrings for the best experience. ## Publishing to PyPI (For Maintainers) ### First Time Setup 1. **Install build tools**: ```bash uv add --dev build twine ``` 2. **Create PyPI account** at [pypi.org](https://pypi.org/account/register/) 3. **Configure authentication**: ```bash # Create API token at https://pypi.org/manage/account/token/ # Store it securely - you'll use it as password with username '__token__' ``` ### Publishing Process 1. **Update version** in `pyproject.toml` and `mcp_server_boilerplate/__init__.py` 2. **Build the package**: ```bash uv run python -m build ``` 3. **Test upload to TestPyPI** (recommended first time): ```bash uv run twine upload --repository testpypi dist/* ``` 4. **Upload to PyPI**: ```bash uv run twine upload dist/* ``` ### Updating the Package 1. **Update version numbers** in: - `pyproject.toml` - `mcp_server_boilerplate/__init__.py` 2. **Clean previous builds**: ```bash rm -rf dist/ build/ *.egg-info/ ``` 3. **Build and upload**: ```bash uv run python -m build uv run twine upload dist/* ``` ### Before You Publish - [ ] Update GitHub URLs in `pyproject.toml` - [ ] Test the package locally: `uv run mcp-server-boilerplate` - [ ] Add your email to `pyproject.toml` authors section - [ ] Ensure all sensitive information is removed