Getting Started & Setup Guide

This page explains how to install dependencies, configure environment settings, and run the MCP Explorer locally or inside a Docker Compose environment.

💻 Method A: Running Locally (Bare Metal)

Running the application locally is ideal for debugging and editing components without container rebuilding.

Prerequisites

Python 3.11+ installed on your system.
Ollama installed and running on localhost:11434. Pull the default model using:
```
ollama pull gemma4:e4b
```

1. Execute Setup Script

We provide an interactive setup.sh script to automate your local virtual environment instantiation:

./setup.sh

This script will: * Create a virtual environment (venv). * Upgrade pip and install project packages declared in pyproject.toml (including automated test requirements). * Install Playwright browser binaries for e2e automation testing.

2. Configure Local Secrets

Create a local .env file in the project root based on our template:

cp .env.example .env

Open .env and fill in your values (e.g. your Langfuse credentials if using observability).

3. Run the Chat Application

Activate the virtual environment and start Chainlit:

source venv/bin/activate
chainlit run ui/app.py

The Chat UI will open automatically at: http://localhost:8000

🐳 Method B: Running via Docker Compose Stack

The Docker Compose setup launches a complete production-ready pipeline, including clickhouse backends, redis caches, minio media uploads, postgres stores, langfuse-server logs visualization, and the chat app.

1. Build and Run the Stack

We provide a helper launch script docker-run.sh that auto-generates your secure encryption keys and starts the build:

./docker-run.sh

This script: * Checks for the existence of .env. * Generates a safe SALT, ENCRYPTION_KEY, and NEXTAUTH_SECRET if not present. * Writes these configuration values to .env.docker. * Builds the application container and boots up the multi-container stack.

2. Access Dashboards

Once started, the services can be accessed at: - Chainlit Chat UI: http://localhost:8000 - Langfuse Dashboard: http://localhost:3000

Use the default administrator credentials generated by our compose file: * Email: admin@langfuse.local * Password: admin123

You will immediately see the "MCP Explorer" project populated with real-time logs and active spans!

🛠️ Local Serves of Documentation Site

To run this documentation website locally: 1. Activate your local virtual environment:

source venv/bin/activate

2. Install the documentation theme:

pip install mkdocs-material

3. Start the documentation server:

mkdocs serve

4. Access the site in your browser at http://localhost:8000 (or the port specified by mkdocs).