# MCP Reverse Text Service

A Model Context Protocol (MCP) service that provides text manipulation tools including text reversal and analysis.

## Features

- **reverse_text**: Reverse the characters in a text string
- **text_info**: Get detailed information about a text string (length, word count, character analysis)

## Quick Start

### Local Development

```bash
# Clone the repository
git clone https://github.com/NimbleBrainInc/mcp-reverse-text.git
cd mcp-reverse-text

# Install dependencies with uv
uv sync

# Run the server
uv run python server.py

# Or install in editable mode
uv pip install -e .
python server.py
```

The server will start on `http://localhost:8000` with:
- Health check: `GET /health`
- MCP endpoint: `POST /mcp/` (note the trailing slash)

### Docker

```bash
# Build the image
docker build -t nimblebrain/mcp-reverse-text .

# Run the container
docker run -p 8000:8000 nimblebrain/mcp-reverse-text
```

## MCP Protocol Support

This server implements the full MCP (Model Context Protocol) specification:

- **Transport**: Streamable HTTP with Server-Sent Events (SSE)
- **Session Management**: Proper initialization handshake required
- **Protocol Version**: 2024-11-05
- **Framework**: FastMCP 2.11.2
- **Python Version**: 3.13+

### Session Management

The server requires proper MCP initialization:

1. **Initialize**: Send `initialize` request to establish session
2. **Initialized**: Send `notifications/initialized` notification 
3. **Tools**: Use session ID for all subsequent requests

## API Usage

### Complete MCP Example

```bash
# Step 1: Initialize session
INIT_RESPONSE=$(curl -s -i -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "example-client", "version": "1.0.0"}
    },
    "id": 1
  }')

# Extract session ID
SESSION_ID=$(echo "$INIT_RESPONSE" | grep -i "mcp-session-id" | cut -d' ' -f2 | tr -d '\r')

# Step 2: Send initialized notification
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

# Step 3: List available tools
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}'

# Step 4: Call reverse_text tool
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call", 
    "params": {
      "name": "reverse_text",
      "arguments": {"text": "Hello World"}
    },
    "id": 3
  }'
```

### Simple Health Check

```bash
curl http://localhost:8000/health
```

## Development

### Testing

```bash
# Install with dev dependencies
uv sync --group dev

# Run tests (includes async MCP client tests)
uv run python -m pytest

# Run with coverage
uv run python -m pytest --cov=server

# Run specific test
uv run python -m pytest tests/test_server.py::test_reverse_text_tool -v
```

### Building and Deployment

```bash
# Build Docker image
docker build -t mcp-reverse-text .

# Test the container
docker run -d --name mcp-test -p 8000:8000 mcp-reverse-text

# Check health
curl http://localhost:8000/health

# Clean up
docker stop mcp-test && docker rm mcp-test
```

### Contributing

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

## About

Part of the [NimbleTools](https://www.nimbletools.ai) ecosystem.
From the makers of [NimbleBrain](https://www.nimblebrain.ai). 

## License

MIT License - see LICENSE file for details.