README.md

---
title: Text Counting MCP Server
emoji: 🔢
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: "4.44.1"
app_file: mcp_server.py  
pinned: false
---

# Text Counting MCP Server

A comprehensive text analysis and counting operations server built with Gradio, featuring both a web interface and MCP (Model Context Protocol) server capabilities.

## Features

This application provides 13 different text counting and analysis functions:

- **Letter Counter**: Count alphabetic characters in text
- **Word Counter**: Count words in sentences or paragraphs  
- **Sentence Counter**: Count sentences using multiple punctuation marks (., !, ?)
- **Paragraph Counter**: Count paragraphs separated by double line breaks
- **Vowel Counter**: Count vowel characters (a, e, i, o, u)
- **Consonant Counter**: Count consonant characters
- **Special Character Counter**: Count special symbols and punctuation
- **Digit Counter**: Count numeric digits (0-9)
- **Whitespace Counter**: Count spaces, tabs, and line breaks
- **Uppercase Letter Counter**: Count capital letters
- **Lowercase Letter Counter**: Count lowercase letters
- **Unique Word Counter**: Count distinct words in text
- **Syllable Counter**: Estimate syllables with enhanced algorithm

## Quick Start

### Prerequisites

- Python 3.8+
- pip package manager

### Installation

1. **Clone or download the project**
   ```bash
   git clone <repository-url>
   cd hugging-face
   ```

2. **Create and activate virtual environment** (recommended)
   ```bash
   python -m venv .venv
   
   # On Windows:
   .venv\Scripts\activate
   
   # On macOS/Linux:
   source .venv/bin/activate
   ```

3. **Install dependencies**
   ```bash
   pip install gradio
   ```

### Running the Application

**Web Interface Mode:**
```bash
python mcp_server.py
```

The application will launch at `http://localhost:7860` with a tabbed interface for each counting function.

**MCP Server Mode:**
```bash
# Enable MCP server functionality by setting mcp_server=True in the code
python mcp_server.py
```

## Usage Examples

### Web Interface
1. Navigate to the launched URL (typically `http://localhost:7860`)
2. Select the desired counting function from the tabs
3. Enter your text in the input field
4. View the results instantly

### Python API
```python
from mcp_server import count_letters, count_words, count_syllables

# Count letters
result = count_letters("Hello World!")  # Returns: 10

# Count words  
result = count_words("This is a test sentence.")  # Returns: 5

# Count syllables
result = count_syllables("beautiful")  # Returns: 3
```

## Project Structure

```
hugging-face/
├── mcp_server.py          # Main application with Gradio interface
├── mcp.json              # MCP server configuration
├── agent.json            # Agent configuration
├── README.md             # This file
├── .gitignore           # Git ignore rules
└── .venv/               # Virtual environment (created after setup)
```

## Configuration

### MCP Server Configuration
The `mcp.json` file defines the MCP server capabilities and tool definitions. It includes:
- Server metadata (name, version, description)
- Tool definitions with parameter schemas
- Capability declarations

### Environment Setup
- Python virtual environment in `.venv/`
- Gradio for web interface
- MCP server capabilities built into Python application

## Function Details

### Enhanced Features

1. **Robust Input Handling**: All functions accept any input type and convert to string
2. **Improved Algorithms**: 
   - Sentence counting uses regex for multiple punctuation marks
   - Syllable counting handles silent 'e' and edge cases
3. **Error Handling**: Functions gracefully handle empty inputs and special cases
4. **Type Safety**: Full type hints and comprehensive docstrings

### Algorithm Highlights

- **Syllable Counter**: Uses vowel grouping with silent 'e' detection
- **Sentence Counter**: Regex-based splitting on `.!?` patterns
- **Letter Counter**: Only counts alphabetic characters (excludes numbers/symbols)

## Development

### Code Quality Features
- Complete type hints for all functions
- Comprehensive docstrings with Args: blocks  
- Input validation and type conversion
- Error handling for edge cases
- Consistent code formatting

### Adding New Functions
1. Define the function with proper type hints
2. Add comprehensive docstring with Args: and Returns: sections
3. Include input validation (`str(input)` conversion)
4. Add the function to the Gradio interface
5. Update MCP configuration if needed

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/new-counter`)
3. Make your changes following the code quality standards
4. Add tests if applicable
5. Submit a pull request

## License

This project is licensed under the ISC License - see the LICENSE file for details.

## Troubleshooting

### Common Issues

**"ModuleNotFoundError: No module named 'gradio'"**
```bash
pip install gradio
```

**"JSON-RPC error: Not Acceptable: Client must accept text/event-stream"**
- This occurs when `mcp_server=True` is enabled but the client doesn't support event streams
- For web interface only, ensure `mcp_server=False` or remove the parameter

**Virtual Environment Issues**
```bash
# Recreate virtual environment
rm -rf .venv
python -m venv .venv
.venv\Scripts\activate  # Windows
pip install gradio
```

## Performance

- Lightweight algorithms optimized for text processing
- Efficient character iteration using generator expressions
- Memory-efficient for large text inputs
- Real-time processing suitable for interactive use

---

**Built using Python, Gradio, and MCP**