tlcharchar/mcp_servers

MCP User Profile Server

A Model Context Protocol (MCP) server that provides user profile lookup functionality. This server allows you to retrieve complete user profiles using various identifiers such as user ID, CPF (Brazilian tax ID), or phone number.

Features

• Multiple Lookup Methods: Search users by:
  • User ID (UUID format)
  • ID Document Value (e.g., CPF)
  • Phone Number
• Complete Profile Data: Returns comprehensive user information including:
  • Personal details (name, ID document)
  • Multiple identities (email, phone, service IDs)
  • Service associations and roles
  • Group memberships
• CSV Data Source: Reads user profile data from a CSV file
• MCP Integration: Fully compatible with Model Context Protocol for AI assistant integration

Installation

Prerequisites

• Python 3.8 or higher
• pip package manager

Setup

1. Clone this repository:

git clone <repository-url>
cd mcp_servers

2. Create a virtual environment:

python -m venv devenv
source devenv/bin/activate  # On Windows: devenv\Scripts\activate

3. Install dependencies:

pip install mcp mcp[cli] pandas

Configuration

MCP Server Configuration

Add the following configuration to your MCP client (e.g., Cursor IDE):

{
  "mcpServers": {
    "mcp-user-profile": {
      "command": "python",
      "args": ["/path/to/your/mcp_servers/devenv/user_profile.py"],
      "cwd": "/path/to/your/mcp_servers/devenv"
    }
  }
}

Data Configuration

The server reads user profile data from devenv/data/UserProfile.csv. The CSV file should contain the following columns:

• user_id: Unique user identifier (UUID format)
• name: User's full name
• id_document_country: Country code (e.g., "BR")
• id_document_type: Document type (e.g., "CPF")
• id_document_value: Document value (e.g., CPF number)
• identity_id: Identity identifier (email, phone, service ID, etc.)
• services: Comma-separated list of services
• type: Identity type (email, phone_number, uid, etc.)
• role: User role (e.g., "owner")
• group_ids: Group identifiers (optional)
• frienly_name: Friendly name for the identity (optional)
• start_date: Start date timestamp
• last_mod_date: Last modification timestamp
• end_date: End date timestamp (optional)

Usage

Available Tools

1. Get User Profile by ID

get_user_profile_by_id(user_id: str) -> Dict

Retrieves a complete user profile using the user's UUID.

Example:

result = get_user_profile_by_id("b6db5432-3178-4fd6-b43e-f81bf949b4a3")

2. Get User Profile by ID Document Value

get_user_profile_by_id_document_value(id_document_value: str) -> Dict

Retrieves a user profile using their ID document value (e.g., CPF).

Example:

result = get_user_profile_by_id_document_value("21451589161")

3. Get User Profile by Phone Number

get_user_profile_by_phone_number(phone_number: str) -> Dict

Retrieves a user profile using their phone number.

Example:

result = get_user_profile_by_phone_number("+5589941883901")

Available Resources

User Profile Resource

user://profile/{key_type}/{key_value}

Parameters:

• key_type: One of "id", "id_document_value", or "phone_number"
• key_value: The corresponding value

Examples:

• user://profile/id/b6db5432-3178-4fd6-b43e-f81bf949b4a3
• user://profile/id_document_value/21451589161
• user://profile/phone_number/+5589941883901

Response Format

All tools return a JSON object with the following structure:

{
  "id": "b6db5432-3178-4fd6-b43e-f81bf949b4a3",
  "name": "João Silva",
  "id_document": {
    "value": "21451589161",
    "country": "BR",
    "type": "CPF"
  },
  "identities": [
    {
      "services": ["authentication"],
      "roles": ["owner"],
      "id": "21451589161",
      "type": "uid"
    },
    {
      "services": ["authentication"],
      "roles": ["owner"],
      "id": "joão.silva496@icloud.com",
      "type": "email"
    },
    {
      "services": ["authentication", "mobile_postpaid"],
      "roles": ["owner"],
      "id": "+5589941883901",
      "type": "phone_number"
    },
    {
      "services": ["iptv"],
      "roles": ["owner"],
      "id": "TV-SPO-V3299USI0Z-108",
      "type": "uid",
      "group_ids": ["NDN8746763507551"]
    }
  ]
}

Running the Server

Standalone Mode

cd devenv
python user_profile.py

With MCP Client

The server is designed to run with MCP-compatible clients like Cursor IDE. Configure your MCP client with the server details as shown in the Configuration section.

Error Handling

The server provides comprehensive error handling:

• File Not Found: Returns error if CSV file is missing
• User Not Found: Returns error if requested user doesn't exist
• Invalid Parameters: Returns error for invalid key types
• Data Processing Errors: Returns error with details for processing failures

Development

Project Structure

mcp_servers/
├── devenv/
│   ├── data/
│   │   └── UserProfile.csv    # User profile data
│   ├── user_profile.py        # Main MCP server
│   └── .cursor/
│       └── mcp.json          # MCP configuration
└── README.md                 # This file

Adding New Features

1. New Lookup Methods: Add new @mcp.tool() decorated functions
2. Data Processing: Modify the get_complete_user_profile() function
3. Resources: Add new @mcp.resource() decorated functions

Testing

Test the server by running it standalone and using the available tools:

# Test user profile lookup
result = get_user_profile_by_id("b6db5432-3178-4fd6-b43e-f81bf949b4a3")
print(json.dumps(result, indent=2))

Dependencies

• mcp: Model Context Protocol server framework
• pandas: Data manipulation and analysis
• json: JSON handling (built-in)
• os: Operating system interface (built-in)
• typing: Type hints (built-in)

Contributing

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