User Data Service MCP

A Model Context Protocol (MCP) server that provides tools for querying and analyzing user data from a JSON database.

Overview

This MCP server exposes a set of tools to interact with user data stored in sample.json. It provides functionality for retrieving, searching, filtering, and analyzing user records through the FastMCP framework.

Features

• User Retrieval: Get all users with pagination support
• User Lookup: Find users by ID or index
• Search: Search users by name, email, company, or address
• Filtering: Filter users by active status, gender, age, eye color, favorite fruit, or tags
• Statistics: Get comprehensive statistics about the user database

Prerequisites

• Python 3.7+
• pip (Python package manager)

Installation

1. Clone or download this repository

2. Install the required dependencies:

pip install fastmcp python-dotenv

3. Ensure you have a sample.json file in the same directory with user data

Configuration

Create a .env file in the project root if you need to configure environment variables (optional).

Usage

Starting the Server

Run the server using:

python server.py

The server will start and log output to both the console and mcp_server.log.

Available Tools

1. get_all_users

Get all users from the database with optional pagination.

Parameters:

• limit (optional): Maximum number of users to return
• offset (default: 0): Number of users to skip

Returns: List of user records

2. get_user_by_id

Get a specific user by their unique ID.

Parameters:

• user_id: The _id of the user to retrieve

Returns: User record if found, None otherwise

3. get_user_by_index

Get a specific user by their index.

Parameters:

• index: The index of the user to retrieve

Returns: User record if found, None otherwise

4. search_users

Search users using case-insensitive partial matches.

Parameters:

• name (optional): Search by name
• email (optional): Search by email
• company (optional): Search by company
• address (optional): Search by address

Returns: List of matching user records

5. filter_users

Filter users by various criteria.

Parameters:

• is_active (optional): Filter by active status (true/false)
• gender (optional): Filter by gender (male/female)
• min_age (optional): Minimum age
• max_age (optional): Maximum age
• eye_color (optional): Filter by eye color
• favorite_fruit (optional): Filter by favorite fruit
• has_tag (optional): Filter users who have a specific tag

Returns: List of matching user records

6. get_user_stats

Get comprehensive statistics about the user database.

Parameters: None

Returns: Dictionary containing:

• Total users count
• Active/inactive users count
• Gender distribution
• Eye color distribution
• Favorite fruit distribution
• Age statistics (min, max, average)

Data Format

The server expects sample.json to contain an array of user objects with the following structure:

[
  {
    "_id": "unique-id",
    "index": 0,
    "name": "User Name",
    "email": "user@example.com",
    "company": "Company Name",
    "address": "User Address",
    "isActive": true,
    "gender": "male",
    "age": 30,
    "eyeColor": "brown",
    "favoriteFruit": "apple",
    "tags": ["tag1", "tag2"]
  }
]

Logging

The server logs all operations to:

• Console output
• mcp_server.log file

Log entries include timestamps, log levels, and detailed messages about server operations.

Error Handling

The server includes error handling for:

• Missing data file
• Invalid JSON format
• Out-of-range queries

Errors are logged with appropriate error messages.

License

This project is provided as-is for demonstration purposes.