Name Origin Predictor

🚀 Name Origin Prediction Server

A Python server based on the MCP (Model Context Protocol) for predicting the origin of names via the Nationalize.io API.

🚀 Quick Start

This is a Python server based on the MCP protocol that leverages the Nationalize.io API to predict the origin of names. It offers seamless integration and real - time data retrieval.

✨ Features

• Predict the origin of a single name.
• Batch predict the origins of multiple names.
• Integrate with the Nationalize.io API in real - time.
• Support the MCP protocol for seamless integration.

📦 Installation

Prerequisites

• Python 3.x
• Virtual environment (recommended)
• Required libraries:
  • httpx
  • mcp - server

Steps

1. Clone the repository:

git clone https://github.com/allglenn/mcp-name-origin-server.git
cd mcp-name-origin-server

2. Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Unix/macOS systems
# Or
.\venv\Scripts\activate  # On Windows systems

3. Install dependencies:

pip install httpx

📚 Documentation

Configuration

1. Create a claude_desktop_config.json file:

{
    "mcpServers": {
        "origin": {
            "command": "source",
            "args": [
                "venv/bin/activate",
                "&&",
                "python3",
                "-u",
                "mcp-server.py"
            ],
            "shell": true,
            "env": {
                "PYTHONPATH": ".",
                "PYTHONUNBUFFERED": "1"
            }
        }
    },
    "defaultServer": "origin",
    "version": "0.1.0"
}

Usage

Start the server

python mcp-server.py

Available methods

1. predict_origin(name: str): Predict the origin of a single name.

   • Input: A string containing the name.
   • Output: A JSON object containing country predictions and probabilities.

2. batch_predict(names: list[str]): Predict the origins of multiple names.

   • Input: A list of names.
   • Output: A JSON object with prediction results for each name.

Example response

{
    "name": "glenn",
    "country": [
        {
            "country_id": "US",
            "probability": 0.421
        },
        {
            "country_id": "AU",
            "probability": 0.044
        }
    ]
}

API Reference

This project uses the Nationalize.io API for name origin prediction. The API is free for basic use but has rate limits.

Error Handling

The server handles various error conditions:

• Invalid name format
• API connection issues
• Rate limits
• Server errors

Development

To contribute to this project:

1. Fork the repository.
2. Create a feature branch.
3. Make modifications.
4. Submit a pull request.

📄 License

This project is released under the MIT License. See the LICENSE file for details.

Acknowledgments

• Nationalize.io for providing the name origin prediction API.
• The MCP protocol for the server implementation framework.