# 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