Emeritus MCP Server

This project is a Model Context Protocol (MCP) server implementation for the Emeritus API. It provides a standardized interface for AI models to interact with Emeritus services, including user management, tag operations, order management, and leads import.

About Model Context Protocol (MCP)

The Model Context Protocol (MCP) is an open standard introduced by Anthropic that enables seamless integration between LLM applications and external data sources and tools. Think of MCP as a "USB-C for AI applications" - it provides a standardized way to connect AI models with external systems.

MCP uses a client-server architecture where:

• MCP Servers expose capabilities (tools, resources, prompts) in a standardized way
• MCP Clients (within AI applications) connect to these servers
• JSON-RPC 2.0 is used for communication between clients and servers

Features

This MCP server provides:

• Tools: Functions that AI models can execute to interact with Emeritus services
• User management (create, fetch, update users)
• Tag operations (create groups, assign tags)
• Order management (fetch orders and financial records)
• Leads import functionality
• Resources: Access to Emeritus data sources
• Secure Authentication: Token-based authentication with the Emeritus API
• Error Handling: Comprehensive error reporting and validation

Requirements

• Python 3.10 or higher
• Access to Emeritus API credentials
• An MCP-compatible client (like Claude Desktop, or any application using MCP SDKs)

Installation

1. Clone the repository:

git clone <repository-url>
cd emeritus-mcp

1. Create a virtual environment and install dependencies:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

1. Create a .env file based on the provided .env.example:

cp .env.example .env

1. Edit the .env file with your Emeritus API credentials.

Configuration

Set the following environment variables in the .env file:

• EMERITUS_API_HOST: The Emeritus API host URL
• EMERITUS_USER_ID: Your Emeritus User ID
• EMERITUS_API_SECRET: Your Emeritus API Secret
• DEBUG: Set to True for development, False for production

Usage

Running the MCP Server

Start the server using the MCP standard way:

python -m emeritus_mcp

Or run directly:

python src/emeritus_mcp/server.py

Connecting to the Server

This MCP server can be used with any MCP-compatible client. For example:

#### Claude Desktop

Add the server to your Claude Desktop configuration:

{
  "mcpServers": {
    "emeritus": {
      "command": "python",
      "args": ["-m", "emeritus_mcp"],
      "env": {
        "EMERITUS_API_HOST": "your-api-host",
        "EMERITUS_USER_ID": "your-user-id",
        "EMERITUS_API_SECRET": "your-secret"
      }
    }
  }
}

#### Other MCP Clients

Use the standard MCP connection protocols (stdio, SSE) supported by your client.

Available Tools

The server exposes the following tools that AI models can use:

User Management

• create_user: Create a user by mobile number or email
• fetch_user_profile: Get a user's profile information
• update_user_owner: Update a user's owner
• update_user_pool: Update a user's pool
• update_user_email: Update a user's email
• fetch_user_contact: Fetch a user's contact information

Tag Management

• create_tag_group: Create a tag group
• list_tag_groups: Get a list of tag groups
• update_tag_group: Update a tag group
• deactivate_tag_group: Deactivate a tag group
• activate_tag_group: Activate a tag group
• assign_user_tag: Assign a tag to a user
• list_user_tags: List tags assigned to a user

Order Management

• fetch_order: Get details for a specific order
• list_orders: Get a list of orders
• list_order_financials: Get a list of order financial records

Leads Management

• import_leads: Import leads from raw data

Project Structure

emeritus-mcp/
├── pyproject.toml           # Project dependencies and configuration
├── README.md                # Project documentation
├── .env.example             # Example environment variables
├── src/
│   └── emeritus_mcp/        # Main package
│       ├── __init__.py      # Package initialization
│       ├── __main__.py      # CLI entry point
│       ├── server.py        # MCP server implementation
│       ├── tools/           # MCP tools implementation
│       │   ├── __init__.py
│       │   ├── user.py      # User management tools
│       │   ├── tag.py       # Tag management tools
│       │   ├── order.py     # Order management tools
│       │   └── leads.py     # Leads management tools
│       ├── services/        # Emeritus API integration
│       │   ├── __init__.py
│       │   └── emeritus_client.py
│       └── config/          # Configuration management
│           ├── __init__.py
│           └── settings.py

Development

Testing

Run tests with pytest:

pytest

Code Formatting

Format code with Black and isort:

black src tests
isort src tests

Type Checking

Run type checking with mypy:

mypy src

Contributing

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

License

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

More About MCP

To learn more about the Model Context Protocol:

• Official MCP Documentation
• MCP Specification
• Anthropic's MCP Introduction