YST KPI

You run a FastMCP-based service that automates KPI daily report collection and outputs structured Markdown. It logs in automatically via Google OAuth, persists session data for quick re-runs, supports collecting multiple months at once, detects login status smartly, and generates ready-to-use Markdown reports for easy sharing and archiving.

How to use

To use this MCP server, run the core tool to collect KPI daily reports across a range of months. The system will handle automatic login, persist your session, perform the data collection, and produce Markdown output for the specified period. You can reuse the same session for multiple collections and verify login status before running a new fetch.

How to install

Prerequisites you need before installing and running the MCP server:

• Python 3.10 or newer

• uv as the package manager

• Chromium browser (Playwright will install it automatically)

• Network access to https://kpi.drojian.dev

Steps to set up the project locally:

cd /Users/admin/go/empty/python/yst_mcp

# Install dependencies synchronously
uv sync

# Activate the virtual environment
source .venv/bin/activate

# Install Playwright browsers (Chromium)
playwright install chromium

MCP configuration for client (stdio server)

Configure the MCP client to run the local server through UV in stdio mode. Use the following MCP config snippet exactly as shown to enable the local process.

{
  "mcpServers": {
    "yst_mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/Users/admin/go/empty/python/yst_mcp",
        "run",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

Additional configuration and usage notes

Place the MCP configuration in the client’s configuration area for fast and reliable startup. After saving the configuration, restart the MCP client to apply changes.

The server is designed to automatically start a browser session for login if cookies are not present or have expired. It stores cookies and browser sessions locally for persistent authentication.

Security considerations

Cookies and browser session data are stored locally to enable seamless login in subsequent runs. Do not share or commit these files to version control.

The main sensitive artifacts are data/cookies.json and data/browser_profile/. Treat them as secrets and protect access to them accordingly.

Troubleshooting and tips

If you encounter login/connection issues, verify the following: you can access https://kpi.drojian.dev, the Playwright chromium browser is installed, and the session data directory exists. The system will retry failed fetches and continue collecting where possible.

If you need to completely reset login data, remove both cookies and the browser profile directory.

You can collect multiple, separate month ranges in multiple runs. For example, run 2025-01 to 2025-03 in one pass, then 2025-04 to 2025-06 in another pass, saving outputs to distinct files.

Tools available in this MCP server

• collect_reports: Collect daily KPI reports with automatic login and Markdown output (core tool)

• browser_login: Manually open the browser to login (optional) and initialize credentials

• check_login_status: Verify current login status and cookie validity

• clear_saved_cookies: Remove stored cookies and reset login state

• save_cookies_from_browser: Deprecated manual cookie saving helper

Example usage scenarios

Basic collection scenario: gather reports for 2025-07 to 2025-09 and output to a file.

Custom output path: collect 2025-07 reports and save to a specified output path.

Check login status: verify your cookies are still valid before running a collection.

Local debugging and development

Test login flow with the provided test script to ensure the browser login automation works as expected.

Development mode can be run via the FastMCP framework to enable hot-reloading during development.

Available tools

collect_reports

Collect KPI daily reports for a specified month range with automatic login and Markdown output (core tool)

browser_login

Manually open a browser to complete login (optional)

check_login_status

Check whether the current login cookies are valid and active

clear_saved_cookies

Clear stored login cookies and reset session state

save_cookies_from_browser

Deprecated manual cookie saving helper