# MCP Multi-Tool Server

A comprehensive Model Context Protocol (MCP) server that provides calculator tools, documentation resources, and prompt templates. This server supports both stdio and SSE (Server-Sent Events) transports, making it compatible with various MCP clients including Claude Desktop.

## Features

### 🧮 Calculator Tools (8 Tools)
- **add** - Add two numbers
- **subtract** - Subtract two numbers
- **multiply** - Multiply two numbers
- **divide** - Divide two numbers
- **power** - Raise a number to a power
- **square_root** - Calculate square root
- **factorial** - Calculate factorial
- **calculate_percentage** - Calculate percentage

### 📚 Resources
- **TypeScript SDK Documentation** - Access the full TypeScript SDK MCP documentation via resource URI `typescript-sdk-mcp://documentation`

### 📝 Prompts
- **Meeting Summary** - Generate executive meeting summaries from transcripts using a customizable template

### 🔌 Transport Support
- **stdio** (default) - Standard input/output for local integrations
- **SSE** - Server-Sent Events for remote HTTP connections

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Installation](#installation)
3. [Quick Start](#quick-start)
4. [Usage](#usage)
5. [Transport Modes](#transport-modes)
6. [Connecting to Claude Desktop](#connecting-to-claude-desktop)
7. [API Reference](#api-reference)
8. [Project Structure](#project-structure)
9. [Troubleshooting](#troubleshooting)
10. [Contributing](#contributing)
11. [License](#license)

---

## Prerequisites

- **Python 3.10+** (Python 3.12 recommended)
- **uv** - Fast Python package installer
- **Administrative privileges** (for software installation)

---

## Installation

### Step 1: Install Python

#### Windows

1. Download Python from [python.org/downloads](https://www.python.org/downloads/)
2. Run the installer and **check "Add Python to PATH"**
3. Verify installation:
   ```powershell
   python --version
   pip --version
   ```

#### macOS

```bash
# Using Homebrew (recommended)
brew install python@3.12

# Or download from python.org
```

#### Linux (Ubuntu/Debian)

```bash
sudo apt update
sudo apt install python3 python3-pip python3-venv -y
```

### Step 2: Install uv

#### Windows

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Close and reopen PowerShell, then verify:
```powershell
uv --version
```

#### macOS/Linux

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Add to PATH if needed:
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```

Verify:
```bash
uv --version
```

### Step 3: Clone and Setup

```bash
# Clone the repository
git clone <your-repo-url>
cd mcp-multi-tool-server

# Initialize project
uv init --no-readme

# Create virtual environment
uv venv

# Activate virtual environment
# Windows PowerShell:
.\.venv\Scripts\Activate.ps1
# Windows CMD:
.venv\Scripts\activate.bat
# macOS/Linux:
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]"
```

---

## Quick Start

### Running with stdio (Default)

```bash
# Activate virtual environment first
source .venv/bin/activate  # or .\.venv\Scripts\Activate.ps1 on Windows

# Run the server
python server.py
```

The server will start in stdio mode, ready to accept connections from MCP clients.

### Running with SSE

```bash
# Set transport to SSE
TRANSPORT=sse python server.py

# Or with custom host/port
TRANSPORT=sse HOST=0.0.0.0 PORT=8000 python server.py
```

The server will start an HTTP server on the specified host and port, accessible via SSE.

---

## Usage

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `TRANSPORT` | Transport mode: `stdio` or `sse` | `stdio` |
| `HOST` | Host address for SSE transport | `0.0.0.0` |
| `PORT` | Port number for SSE transport | `8000` |

### Examples

#### stdio Mode (for Claude Desktop)
```bash
python server.py
```

#### SSE Mode (for HTTP clients)
```bash
TRANSPORT=sse PORT=8080 python server.py
```

---

## Transport Modes

### stdio Transport

**Use case:** Local integrations, Claude Desktop, command-line tools

**How it works:**
- Server communicates via standard input/output
- Spawned as a subprocess by the MCP client
- No network configuration needed

**Configuration example:**
```json
{
  "mcpServers": {
    "multi-tool-server": {
      "command": "uv",
      "args": ["--directory", "/path/to/project", "run", "server.py"],
      "env": {}
    }
  }
}
```

### SSE Transport

**Use case:** Remote servers, web applications, HTTP-based clients

**How it works:**
- Server runs as an HTTP server
- Uses Server-Sent Events for real-time communication
- Accessible via HTTP endpoints

**Access URL:**
```
http://localhost:8000/sse
```

**Configuration example:**
```json
{
  "mcpServers": {
    "multi-tool-server": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}
```

---

## Connecting to Claude Desktop

### Step 1: Locate Configuration File

**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```

**macOS:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Linux:**
```
~/.config/Claude/claude_desktop_config.json
```

### Step 2: Get Your Project Path

```bash
# Windows PowerShell
Get-Location

# macOS/Linux
pwd
```

### Step 3: Add Server Configuration

Open `claude_desktop_config.json` and add:

```json
{
  "mcpServers": {
    "multi-tool-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-multi-tool-server",
        "run",
        "server.py"
      ],
      "env": {
        "TRANSPORT": "stdio"
      }
    }
  }
}
```

**Important:**
- Use absolute paths (not relative)
- On Windows, use forward slashes `/` or escaped backslashes `\\`
- Replace `/absolute/path/to/mcp-multi-tool-server` with your actual project path

### Step 4: Restart Claude Desktop

Close and reopen Claude Desktop completely. All tools, resources, and prompts should now be available!

---

## API Reference

### Calculator Tools

#### `add(a: float, b: float) -> float`
Add two numbers together.

**Example:**
```python
add(2, 3)  # Returns: 5.0
```

#### `subtract(a: float, b: float) -> float`
Subtract the second number from the first.

**Example:**
```python
subtract(10, 4)  # Returns: 6.0
```

#### `multiply(a: float, b: float) -> float`
Multiply two numbers.

**Example:**
```python
multiply(5, 6)  # Returns: 30.0
```

#### `divide(a: float, b: float) -> float`
Divide the first number by the second.

**Example:**
```python
divide(20, 4)  # Returns: 5.0
```

**Error:** Raises `ValueError` if divisor is zero.

#### `power(base: float, exponent: float) -> float`
Raise a number to a power.

**Example:**
```python
power(2, 8)  # Returns: 256.0
```

#### `square_root(number: float) -> float`
Calculate the square root of a number.

**Example:**
```python
square_root(16)  # Returns: 4.0
```

**Error:** Raises `ValueError` if number is negative.

#### `factorial(n: int) -> int`
Calculate the factorial of a non-negative integer.

**Example:**
```python
factorial(5)  # Returns: 120 (5! = 5 × 4 × 3 × 2 × 1)
```

**Error:** Raises `ValueError` if n is negative.

#### `calculate_percentage(part: float, whole: float) -> float`
Calculate what percentage one number is of another.

**Example:**
```python
calculate_percentage(25, 100)  # Returns: 25.0 (25%)
```

**Error:** Raises `ValueError` if whole is zero.

### Resources

#### `typescript-sdk-mcp://documentation`
Returns the full content of the TypeScript SDK MCP documentation markdown file.

**Usage:**
Access this resource through your MCP client to retrieve the documentation.

### Prompts

#### `meeting_summary(meeting_date: str, meeting_title: str, transcript: str) -> list[dict]`
Generate an executive meeting summary from a transcript.

**Parameters:**
- `meeting_date`: Date of the meeting (e.g., "2025-01-15")
- `meeting_title`: Title of the meeting
- `transcript`: Full meeting transcript text

**Returns:**
A formatted prompt message ready to send to an LLM.

**Template:**
The prompt uses a template located at `templates/meeting_summary/template.md` with placeholders:
- `{{ meeting_date }}`
- `{{ meeting_title }}`
- `{{ transcript }}`

**Example Usage:**
```python
meeting_summary(
    meeting_date="2025-01-15",
    meeting_title="Q1 Planning Meeting",
    transcript="John: Let's discuss Q1 goals..."
)
```

---

## Project Structure

```
mcp-multi-tool-server/
├── .venv/                          # Virtual environment
├── templates/
│   └── meeting_summary/
│       └── template.md             # Meeting summary prompt template
├── __pycache__/                    # Python cache
├── server.py                       # Main server file
├── pyproject.toml                  # Project configuration
├── uv.lock                         # Dependency lock file
├── README.md                       # This file
├── Typerscript SDK MCP.md          # Documentation resource
├── claude_desktop_config.json.example  # Example Claude Desktop config
└── .gitignore                      # Git ignore rules
```

---

## Testing

### Test Calculator Tools

Create a test file `test_server.py`:

```python
from server import (
    add, subtract, multiply, divide,
    power, square_root, factorial, calculate_percentage
)

# Test all tools
assert add(2, 3) == 5.0
assert subtract(10, 4) == 6.0
assert multiply(5, 6) == 30.0
assert divide(20, 4) == 5.0
assert power(2, 8) == 256.0
assert square_root(16) == 4.0
assert factorial(5) == 120
assert calculate_percentage(25, 100) == 25.0

print("All tests passed!")
```

Run:
```bash
python test_server.py
```

### Test Resource

```python
from server import get_typescript_sdk_documentation

content = get_typescript_sdk_documentation()
print(content[:100])  # Print first 100 characters
```

### Test Prompt

```python
from server import meeting_summary

result = meeting_summary(
    meeting_date="2025-01-15",
    meeting_title="Test Meeting",
    transcript="This is a test transcript."
)
print(result)
```

---

## Troubleshooting

### Python Not Found

**Problem:** `python --version` returns "command not found"

**Solution:**
- Windows: Reinstall Python with "Add Python to PATH" checked
- macOS/Linux: Use `python3` instead of `python`

### uv Not Found

**Problem:** `uv --version` returns "command not found"

**Solution:**
- Make sure you opened a **new terminal** after installation
- Add `~/.cargo/bin` (or `%USERPROFILE%\.cargo\bin` on Windows) to PATH
- Restart terminal

### Virtual Environment Issues

**Problem:** Can't activate virtual environment

**Solution:**
- Windows PowerShell: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
- Verify `.venv` folder exists: `ls .venv` (or `dir .venv` on Windows)

### MCP Installation Fails

**Problem:** `uv add "mcp[cli]"` fails

**Solution:**
- Ensure virtual environment is activated (you should see `(.venv)` in prompt)
- Update uv: `uv self update`
- Check Python version: `python --version` (should be 3.10+)

### Server Won't Start

**Problem:** Server fails to start

**Solution:**
- Verify virtual environment is activated
- Check MCP is installed: `uv pip list | grep mcp`
- Ensure `server.py` exists in current directory

### Claude Desktop Connection Issues

**Problem:** Server doesn't appear in Claude Desktop

**Solution:**
- Verify configuration file path is correct
- Use absolute paths (not relative)
- Check JSON syntax is valid
- Ensure `uv` is in PATH or use full path
- Restart Claude Desktop completely
- Check Claude Desktop logs for errors

### SSE Transport Issues

**Problem:** SSE server won't start

**Solution:**
- Check if port is already in use: `lsof -i :8000` (macOS/Linux) or `netstat -ano | findstr :8000` (Windows)
- Try a different port: `PORT=8080 TRANSPORT=sse python server.py`
- Ensure firewall allows connections on the specified port

---

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

---

## License

This project is provided as-is for educational and personal use.

---

## Additional Resources

- [MCP Documentation](https://modelcontextprotocol.io/)
- [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [uv Documentation](https://github.com/astral-sh/uv)
- [Claude Desktop MCP Setup](https://docs.anthropic.com/claude/docs/desktop-mcp)

---

## Support

If you encounter any issues or have questions:

1. Check the [Troubleshooting](#troubleshooting) section
2. Search existing [GitHub Issues](https://github.com/yourusername/mcp-multi-tool-server/issues)
3. Create a new issue with:
   - Description of the problem
   - Steps to reproduce
   - Expected vs actual behavior
   - System information (OS, Python version, etc.)

---

**Made with ❤️ using FastMCP and the Model Context Protocol**