MCP Server: Trend Data Persister

This project implements a Model Context Protocol (MCP) server using Python (fastmcp) to persist trend data (upward or downward) into a PostgreSQL database.

The server exposes a single tool, persist-trend-data, which accepts:

1. datasource_url: The connection string for the target PostgreSQL database.

2. json_data: A JSON object representing the trend. It must match one of the following schemas:

   • Upward Trend:

     {
       "trend": "upward",
       "rockstars": [
         { "name": "string", "department": "string", "amount": integer },
         ...
       ]
     }
     

   • Downward Trend:

     {
       "trend": "downward",
       "culprits": [
         { "name": "string", "department": "string", "amount": integer },
         ...
       ]
     }
     

Functionality:

Based on the trend value in json_data:

• If trend is "upward", it ensures a table named upward_trend_rockstars exists (with columns id, name, department, amount). It then inserts the data from the rockstars array into this table.
• If trend is "downward", it ensures a table named downward_trend_culprits exists (with the same columns). It then inserts the data from the culprits array into this table.
• The tool uses Pydantic for input validation and psycopg2 to interact with the PostgreSQL database.

Prerequisites

• Python (>=3.10 recommended, as specified in pyproject.toml)
• make
• uv (Optional, Makefile will fallback to python -m venv and pip if uv is not found)
• Access to a running PostgreSQL database.

Setup and Running

A Makefile is provided for convenience.

1. Clone/Navigate: Go into the project directory:

   cd /path/to/mcp-server-trend-persister
   

2. Run the Server:

   make
   

   The setup will install dependencies, run the mcp server and inspect it. Also the mcp server will listen for requests via standard input/output.

Makefile Targets

The following targets are available in the Makefile:

• make install: Creates/updates the .venv virtual environment and installs dependencies using uv (preferred) or pip.
• make run: Runs the MCP server (persister.py) using the Python interpreter from .venv.
• make inspect: Inspects the tools defined in persister.py using the MCP inspector (npx @modelcontextprotocol/inspector uv run persister.py). Depends on install.
• make lint: Placeholder for running code linters (e.g., Ruff, Black).
• make clean: Removes the virtual environment, cache files, and other build artifacts.
• make help: Shows the list of available targets.

Integration with MCP Clients

Configure your MCP client (like the one mentioned in the context) to connect to this server. When using the Makefile, the command to launch the server simplifies.

Example configuration snippet:

{
    "mcpServers": {
        "trend-persister": {
            "command": "make",
            "args": [
                "run" // Target to execute
            ],
            "cwd": "/Users/julian/Documents/Code/Learning/MCP/mcp-server-trend-persister" // Important: Set the working directory
        },
        // ... other servers
    }
}

Ensure the cwd path points to the correct project directory where the Makefile resides.

Example Tool Request

An MCP client would send a request like:

{
  "toolName": "persist-trend-data",
  "arguments": {
    "datasource_url": "postgresql://your_user:your_password@your_host:5432/your_db",
    "json_data": {
      "trend": "upward",
      "rockstars": [
        { "name": "Alice", "department": "Sales", "amount": 50000 },
        { "name": "Bob", "department": "Engineering", "amount": 60000 }
      ]
    }
  }
}