# Hello World MCP Server

A simple "Hello World" MCP (Model Context Protocol) server built with FastMCP. This server demonstrates basic MCP functionality with several example tools.

## Quick Start

### Using uvx with GitHub (Recommended)

You can run this MCP server directly from GitHub using `uvx`:

```bash
uvx --from git+https://github.com/macsymwang/hello-mcp-server.git hello-mcp-server
```

### MCP Client Configuration

Add this to your MCP client configuration:

```json
{
  "mcpServers": {
    "hello-world": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/macsymwang/hello-mcp-server.git", "hello-mcp-server"]
    }
  }
}
```

## Features

- **say_hello**: Greet someone with a personalized message
- **get_server_info**: Get information about the MCP server
- **echo_message**: Echo back any message you send
- **count_words**: Analyze text and count words/characters

## Installation

### Using uvx with GitHub (Recommended)

You can run this MCP server directly from GitHub using `uvx`:

```bash
uvx --from git+https://github.com/macsymwang/hello-mcp-server.git hello-mcp-server
```

### Using uvx from PyPI (if published)

```bash
uvx hello-mcp-server
```

### Local Installation

1. Clone or download this repository
2. Install the package:

```bash
pip install .
```

3. Run the server:

```bash
hello-mcp-server
```

### Development Installation

For development, install in editable mode:

```bash
pip install -e .
```

## Usage

### Registering as Stdio Protocol

This MCP server is designed to work with the **stdio transport protocol**, which is the standard way MCP servers communicate with clients. The server reads JSON-RPC messages from stdin and writes responses to stdout.

### MCP Client Configuration

#### Claude Desktop

Add this configuration to your Claude Desktop config file (usually located at `~/.config/claude/claude_desktop_config.json` on Linux/Mac or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "hello-world": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/macsymwang/hello-mcp-server.git", "hello-mcp-server"]
    }
  }
}
```

#### Cursor IDE

Add this to your Cursor MCP configuration:

```json
{
  "mcpServers": {
    "hello-world": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/macsymwang/hello-mcp-server.git", "hello-mcp-server"],
      "transport": {
        "type": "stdio"
      }
    }
  }
}
```

#### Generic MCP Client

For other MCP clients, use this configuration:

```json
{
  "mcpServers": {
    "hello-world": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/macsymwang/hello-mcp-server.git", "hello-mcp-server"],
      "env": {},
      "transport": {
        "type": "stdio"
      }
    }
  }
}
```

### Running the Server Manually

The server can also be started manually for testing:

1. **Using uvx** (recommended):
   ```bash
   uvx hello-mcp-server
   ```

2. **Using the installed command**:
   ```bash
   hello-mcp-server
   ```

3. **Using Python module**:
   ```bash
   python -m hello_mcp_server.server
   ```

4. **Direct execution**:
   ```bash
   python hello_mcp_server/server.py
   ```

When run manually, the server will wait for JSON-RPC messages on stdin. You can test it by sending MCP protocol messages, but it's typically used through MCP clients.

### Available Tools

#### say_hello
Greets someone with a personalized message.

**Parameters:**
- `name` (optional): Name of the person to greet (default: "World")

**Example:**
```json
{
  "name": "Alice"
}
```

#### get_server_info
Returns information about the MCP server.

**Parameters:** None

#### echo_message
Echoes back the provided message.

**Parameters:**
- `message` (required): The message to echo back

#### count_words
Analyzes text and provides word/character statistics.

**Parameters:**
- `text` (required): The text to analyze

## Configuration

### Stdio Protocol

This MCP server uses the **stdio transport protocol**, which means:

- **Input**: The server reads JSON-RPC messages from standard input (stdin)
- **Output**: The server writes JSON-RPC responses to standard output (stdout)
- **Logging**: Error messages and logs are written to standard error (stderr)

This is the standard protocol for MCP servers and ensures compatibility with all MCP clients.

### Transport Configuration

The server automatically configures itself for stdio transport when started. No additional configuration is needed for the transport layer.

For advanced FastMCP configuration options, refer to the FastMCP documentation.

## Requirements

- Python 3.8+
- fastmcp>=0.1.0

## Project Structure

```
hello-mcp-server/
├── hello_mcp_server/
│   ├── __init__.py
│   └── server.py
├── pyproject.toml
└── README.md
```

## Development

To contribute to this project:

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

## License

This project is open source. Please check the license file for details.

## Support

For issues and questions, please open an issue on the project repository.