Setup

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

1. Python 3.11+ installed on your system.
2. 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

3. Sign in to Langfuse

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).