Company Logo
MCIP

Menu

Setup Server

Get MCIP running locally in under 5 minutes with Docker.

Prerequisites

Before we dive in, make sure you have:

RequirementVersionCheck Command
Docker20+docker --version
Docker Compose2.xdocker compose version
OpenAI API Key—Get one here

Don't have Docker? Install it here — it takes about 5 minutes.

Quick Setup (5 minutes)

Ready? Let's get MCIP running.

Step 1: Clone the Repository

git clone https://github.com/CloverDynamics/mcip.git
cd mcip

Step 2: Configure Your Environment

Create your environment file:

cp .env.example .env

Now open .env and add your OpenAI API key:

# Required — this powers the semantic search
OPENAI_API_KEY=sk-proj-your-api-key-here

# Data source (we'll use the demo store for now)
SOURCE_URL=https://demo.vendure.io/shop-api
STORE_PROVIDER=VENDURE

# Security — change this in production!
ADMIN_API_KEY=your-secret-admin-key

That's the minimum configuration. MCIP will use sensible defaults for everything else.

Step 3: Start the Services

docker compose up -d

This spins up three containers:

ServicePortPurpose
mcip8080The MCIP server
qdrant6333Vector database for semantic search
redis6379Queue backend for async processing

First startup takes 30-60 seconds while containers initialize.

Step 4: Verify It's Running

Check the health endpoint:

curl http://localhost:8080/health

You should see:

{"status":"ok"}

🎉 Congratulations! MCIP is running. But we're not done yet — we need products to search.

Sync Your First Products

MCIP doesn't store products itself. It fetches them from your e-commerce platform, transforms them, and indexes them for semantic search. Let's trigger that sync:

curl -X POST http://localhost:8080/admin/sync \
  -H "x-admin-api-key: your-secret-admin-key"

You'll see:

{
  "status": "success",
  "message": "Queued 150 products from URL",
  "count": 150
}

What just happened?

  1. MCIP fetched products from the demo Vendure store
  2. Each product was queued for processing (via BullMQ)
  3. Products are being transformed to a unified schema
  4. OpenAI generates embeddings for semantic understanding
  5. Everything gets stored in Qdrant for fast vector search

This runs asynchronously. Give it 30-60 seconds for the demo store's ~150 products.

Test Your First Search

Now the fun part — let's search:

curl "http://localhost:8080/search?q=laptop"

You'll get results like:

{
  "meta": {
    "count": 5,
    "take": 10,
    "skip": 0,
    "q": "laptop"
  },
  "items": [
    {
      "externalId": "prod_123",
      "title": "Gaming Laptop Pro",
      "price": { "amount": 1299.99, "currency": "USD" },
      "score": 0.892
    }
  ]
}

Notice the score field? That's semantic similarity — how well each product matches your intent, not just keywords.

What's Included

Your Docker Compose setup includes everything you need:

┌─────────────────────────────────────────────────────────┐
│                     Your Machine                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────┐    ┌──────────┐    ┌──────────────────┐  │
│  │   MCIP   │───▶│  Qdrant  │    │      Redis       │  │
│  │  :8080   │    │  :6333   │◀───│      :6379       │  │
│  └────┬─────┘    └──────────┘    └──────────────────┘  │
│       │                                                 │
│       ▼                                                 │
│   OpenAI API (external)                                 │
│                                                         │
└─────────────────────────────────────────────────────────┘

Troubleshooting

"Connection refused" on health check

Problem: MCIP hasn't finished starting.

Solution: Wait 30-40 seconds and try again. Check logs:

docker compose logs mcip

"Cannot connect to Qdrant"

Problem: Qdrant is still initializing.

Solution: MCIP retries Qdrant connection 10 times on startup. Check Qdrant status:

docker compose logs qdrant

"OpenAI API error" during sync

Problem: Invalid or rate-limited API key.

Solution: Verify your key works:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

If you're on a free tier, you may hit rate limits. Wait a minute and retry.

"No products found" after sync

Problem: Products are still processing.

Solution:

  1. Wait 30-60 seconds for async processing
  2. Check the logs: docker compose logs mcip
  3. Verify the GraphQL query returns products

Docker containers keep restarting

Problem: Missing environment variables.

Solution: Ensure .env has at least OPENAI_API_KEY set.

Alternative: Build from Source

Prefer to run without Docker? Here's how:

# Install dependencies
npm install

# Start infrastructure only
docker compose up redis qdrant -d

# Create local environment
cat > .env << EOF
OPENAI_API_KEY=sk-proj-your-key
REDIS_HOST=localhost
QDRANT_URL=http://localhost:6333
ADMIN_API_KEY=dev-admin-key
EOF

# Run in development mode (with hot reload)
npm run start:dev

Environment Variables Reference

Here's what you can configure:

VariableRequiredDefaultDescription
OPENAI_API_KEYYes—Powers embeddings and AI features
SOURCE_URLNoVendure demoWhere to fetch products
STORE_PROVIDERNoVENDUREAdapter to use
GRAPHQL_QUERYNo—Custom query for GraphQL sources
ADMIN_API_KEYNosecret-admin-keyProtects admin endpoints
PORTNo8080Server port
REDIS_HOSTNoredisRedis hostname
QDRANT_URLNohttp://qdrant:6333Vector database URL

For the complete list, see the Configuration Guide.