MCP Traits Matcher

This MCP server provides personality analysis and matching capabilities. You can create persons and traits, describe individuals with trait-based descriptions, and find candidates that best fit a job description using computed matches. It exposes REST-like resource endpoints for listing entities and uses a local server to process personality data.

How to use

You interact with the MCP Traits Matcher server by running it locally and then querying its resources or invoking its tools through an MCP client. You can create persons, assign descriptions that update personality profiles, create traits with specific friendliness and dominance scores, and find matches for a given job description based on Euclidean distance between profiles.

Typical usage patterns include: creating a person, adding a description, creating traits, and requesting matches for a company and job description. You can list all persons and all traits to verify the current state of the data.

How to install

Prerequisites: you need Python 3.8 or newer and a Python environment management tool.

1. Create a virtual environment for isolation.

2. Activate the virtual environment.

3. Install dependencies in editable mode for development and testing.

4. Prepare environment variables for database paths and logging.

5. Start the server using the provided startup command.

Configuration and running the server

The server uses local SQLite databases and can be configured with environment variables. Create a .env file to set database paths and log level, then run the server from your development environment.

MCP_PERSONS_DB=mcp_persons.db
MCP_TRAITS_DB=mcp_traits.db
LOG_LEVEL=INFO

Starting the server locally

Run the server using the Python module entry point. The following command starts the MCP Traits Matcher server in your development environment.

.venv\Scripts\python.exe -m src.traits_matcher_server

Accessing resources and performing actions

After the server starts, you can access resources and perform actions via the MCP client or HTTP-like endpoints. Examples of resources you can query include all persons and all traits, and you can request a specific person by name.

Notes on usage and environment

The server reads configuration from environment variables and a .env file. Ensure the database files exist or can be created by the server. If you need to change database locations, update MCP_PERSONS_DB and MCP_TRAITS_DB accordingly, then restart the server.

Troubleshooting

Common issues include database access errors, import errors from missing dependencies, and port conflicts. Verify that the virtual environment is activated, all dependencies are installed, and there is no other process occupying the default port.

Enable debug logging to diagnose issues by setting LOG_LEVEL=DEBUG in your environment or .env file.

Tools and capabilities

The server exposes a set of tools to manage data and compute matches. You can create a person, add a description to influence personality traits, create a trait, and find matches for a given job description.

Examples

Create a person named John Doe, add a description describing friendliness and dominance, create a trait named friendly with specific scores, and search for matches for a given job description.

Security and access

Keep your development environment secure by using a private environment for your MCP server, never expose internal endpoints publicly without proper authentication, and manage database access with appropriate file permissions.

Available tools

create_person

Creates a new person with a default personality profile and stores it in the persons database.

add_description

Adds a textual description to a person and updates their personality profile based on the described traits.

create_trait

Creates a new personality trait with specified friendliness and dominance scores.

find_matches

Finds persons whose personality profiles best match a given job description by computing Euclidean distance.