Vibe Light MCP

🧠 TechStack Local MCP Server

Biến AI của bạn thành một developer thực thụ — tự nhận diện project, nhớ context, và học hỏi qua từng workspace.

TechStack Local MCP Server là một MCP server chạy local, giúp các AI coding assistants (Antigravity, Claude, Cursor, Windsurf...) trở nên thông minh hơn bằng cách:

• 🔍 Tự nhận diện dự án — Quét project, trả về coding rules + skills phù hợp
• 🧠 Nhớ context 2 tầng — L1 (tạm, per-project) + L2 (vĩnh viễn, global)
• 🔄 Auto-recall — Tự nhớ lại ngữ cảnh từ các cuộc hội thoại trước
• 🛡️ Chạy lệnh an toàn — Allowlist + Defense-in-Depth (4 lớp bảo vệ)
• 🌐 Multi-transport — stdio, SSE (streaming), Streamable HTTP
• 🖥️ Cross-platform — macOS, Linux, Windows

📖 Mục lục

• 🚀 Quick Start (Khuyến nghị)
• 🌐 SSE Hybrid — Multi-Client Architecture
• 🤖 Tích hợp AI Agent
• 🛠 Tools
• 📥 Import Skills — Mở rộng Knowledge Base
• 🛡️ Security Model
• 🔄 Multi-Instance Behavior

🚀 Quick Start (Khuyến nghị)

Kiến trúc khuyến nghị: ChromaDB chạy Docker + MCP Server chạy trực tiếp (stdio).

AI Client (Antigravity/Claude/Cursor)
    │  stdio
    ▼
  main.py (MCP Server)
    │  HTTP :9000
    ▼
  ChromaDB (Docker Container)

💡 Tại sao? Kiến trúc này đơn giản, ổn định, không phụ thuộc vào HTTP streaming library, và AI client kết nối trực tiếp qua stdio (nhanh nhất).

Bước 1: Clone & cài đặt

git clone https://github.com/PhanHug93/vibe-light-mcp.git
cd vibe-light-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Bước 2: Chạy ChromaDB bằng Docker

# Cài Docker: https://www.docker.com/products/docker-desktop/

docker run -d --name mcp-chromadb \
  -p 9000:8000 \
  -v chroma_data:/chroma/chroma \
  -e IS_PERSISTENT=TRUE \
  -e ANONYMIZED_TELEMETRY=FALSE \
  --restart unless-stopped \
  chromadb/chroma:latest

Kiểm tra ChromaDB:

curl http://localhost:9000/api/v2/heartbeat
# → {"nanosecond heartbeat": ...}

Bước 3: Cấu hình AI Client

Thay `` bằng username trên máy.

Antigravity — ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "tech-stack-expert": {
      "command": "/Users//projects/vibe-light-mcp/.venv/bin/python",
      "args": ["/Users//projects/vibe-light-mcp/main.py"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "MCP_CHROMA_HOST": "127.0.0.1",
        "MCP_CHROMA_PORT": "9000"
      }
    }
  }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "tech-stack-expert": {
      "command": "/Users//projects/vibe-light-mcp/.venv/bin/python",
      "args": ["/Users//projects/vibe-light-mcp/main.py"],
      "env": {
        "MCP_CHROMA_HOST": "127.0.0.1",
        "MCP_CHROMA_PORT": "9000"
      }
    }
  }
}

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "tech-stack-expert": {
      "command": "/Users//projects/vibe-light-mcp/.venv/bin/python",
      "args": ["/Users//projects/vibe-light-mcp/main.py"],
      "env": {
        "MCP_CHROMA_HOST": "127.0.0.1",
        "MCP_CHROMA_PORT": "9000"
      }
    }
  }
}

Windsurf / Cascade — ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "tech-stack-expert": {
      "command": "/Users//projects/vibe-light-mcp/.venv/bin/python",
      "args": ["/Users//projects/vibe-light-mcp/main.py"],
      "env": {
        "MCP_CHROMA_HOST": "127.0.0.1",
        "MCP_CHROMA_PORT": "9000"
      }
    }
  }
}

Bước 4: Restart AI Client

Restart IDE/app → MCP sẽ tự kết nối. Verify bằng cách yêu cầu AI gọi tool server_health.

Quản lý ChromaDB Docker

docker logs mcp-chromadb --tail 20   # Xem logs
docker stop mcp-chromadb             # Dừng
docker start mcp-chromadb            # Khởi động lại
docker stats mcp-chromadb            # Xem RAM/CPU

⚡ Cài đặt thủ công (không Docker)

Dùng khi bạn không muốn dùng Docker — chạy ChromaDB trực tiếp trên máy.

Bước 1: Clone & cài đặt

git clone https://github.com/PhanHug93/vibe-light-mcp.git
cd vibe-light-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Bước 2: Khởi động ChromaDB

./scripts/start_chroma.sh

Auto-start mỗi khi bật máy (macOS)

cp deploy/launchd/com.mcp.chromadb.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.mcp.chromadb.plist

Auto-start mỗi khi bật máy (Linux — Systemd)

sudo cp deploy/systemd/chromadb.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable chromadb
sudo systemctl start chromadb

Bước 3: Cấu hình AI Client

Giống Quick Start Bước 3, nhưng không cần env vars (sử dụng port mặc định 8888):

{
  "mcpServers": {
    "tech-stack-expert": {
      "command": "/Users//projects/vibe-light-mcp/.venv/bin/python",
      "args": ["/Users//projects/vibe-light-mcp/main.py"]
    }
  }
}

Biến môi trường

🌐 SSE Hybrid — Multi-Client Architecture

💡 Khi nào dùng? Khi bạn muốn nhiều AI IDE cùng kết nối 1 MCP server (Windsurf + Cursor + Claude...) hoặc chia sẻ MCP cho team qua mạng LAN.

Kiến trúc hybrid: ChromaDB chạy Docker, MCP Server chạy SSE trên host, các client kết nối qua cascade_bridge.py.

 AI Client 1 (Windsurf)     AI Client 2 (Cursor)     AI Client 3 (Claude)
     │  stdio                    │  stdio                    │  stdio
     ▼                           ▼                           ▼
 cascade_bridge.py          cascade_bridge.py          cascade_bridge.py
     │  HTTP POST + SSE          │  HTTP POST + SSE          │  HTTP POST + SSE
     └───────────────────────────┼───────────────────────────┘
                                 ▼
                        main.py (MCP Server)
                        SSE mode — port 8000
                                 │  HTTP :9000
                                 ▼
                     ChromaDB (Docker Container)

Bước 1: Khởi động MCP Server ở chế độ SSE

cd /path/to/vibe-light-mcp
source .venv/bin/activate

# Start ChromaDB (nếu chưa chạy)
docker start mcp-chromadb

# Start MCP Server — SSE mode
python main.py --transport sse --port 8000

Server sẽ chạy foreground, log ra terminal. Dùng tmux hoặc nohup nếu muốn chạy nền.

Bước 2: Cấu hình AI Client với Bridge

cascade_bridge.py là proxy stdio ↔ SSE — nhận JSON-RPC từ stdin, POST lên MCP server, và stream kết quả về stdout real-time.

Windsurf / Cascade — ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "tech-stack-expert": {
      "command": "/Users//projects/vibe-light-mcp/.venv/bin/python",
      "args": ["/Users//projects/vibe-light-mcp/cascade_bridge.py"],
      "env": {
        "MCP_BRIDGE_URL": "http://127.0.0.1:8000",
        "MCP_BRIDGE_MODE": "sse"
      }
    }
  }
}

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "tech-stack-expert": {
      "command": "/Users//projects/vibe-light-mcp/.venv/bin/python",
      "args": ["/Users//projects/vibe-light-mcp/cascade_bridge.py"],
      "env": {
        "MCP_BRIDGE_URL": "http://127.0.0.1:8000",
        "MCP_BRIDGE_MODE": "sse"
      }
    }
  }
}

Antigravity / Claude / Cline — cấu hình tương tự

Thay path file config cho phù hợp:

• Antigravity: ~/.gemini/antigravity/mcp_config.json
• Claude: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cline: .vscode/mcp.json trong project

Nội dung mcpServers giống Windsurf ở trên — chỉ đổi path tới cascade_bridge.py.

Bước 3: Kết nối nhiều client

# Terminal 1: MCP Server (SSE mode)
python main.py --transport sse --port 8000

# Terminal 2+: Mỗi client tự động chạy cascade_bridge.py qua config.
# Hoặc test thủ công:
MCP_BRIDGE_URL=http://127.0.0.1:8000 python cascade_bridge.py

Biến môi trường Bridge

Troubleshooting SSE

🐳 Deploy Full Docker (Production Server)

⚠️ Dành cho deploy 24/7 trên server (Ubuntu, không có GUI). Dev local nên dùng Quick Start.

Full Docker Compose chạy cả ChromaDB + MCP Server trong container, expose MCP qua SSE/HTTP.

Yêu cầu

• Docker Engine ≥ 20.10, Docker Compose ≥ 2.0
• RAM tối thiểu: 4GB (khuyến nghị 8GB)

Khởi động

cp deploy/compose/.env.example deploy/compose/.env
# Sửa .env nếu cần (transport, port...)
docker compose -f deploy/compose/docker-compose.yml up -d --build

Kết nối AI Client (qua Bridge)

Khi MCP chạy SSE/HTTP mode trong Docker, dùng cascade_bridge.py:

{
  "mcpServers": {
    "tech-stack-expert": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/cascade_bridge.py"],
      "env": {
        "MCP_BRIDGE_URL": "http://127.0.0.1:8000",
        "MCP_BRIDGE_MODE": "http"
      }
    }
  }
}

🏗 Kiến trúc Docker (chi tiết)

┌───────────────────────────────────────────────────────┐
│  mcp_internal (internal: true)                        │
│  ┌──────────────┐        ┌──────────────┐             │
│  │   chromadb   │◄──────►│  mcp_server  │             │
│  │   :8000      │        └──────┬───────┘             │
│  │ (NO exposed  │               │                     │
│  │  ports)      │               │                     │
│  └──────────────┘               │                     │
└─────────────────────────────────┼─────────────────────┘
┌─────────────────────────────────┼─────────────────────┐
│  mcp_exposed (bridge)           │                     │
│                      ┌──────────┴───────┐             │
│                      │  mcp_server      │──► :8000    │
│                      └──────────────────┘             │
└───────────────────────────────────────────────────────┘

📂 Cấu trúc thư mục Deploy

deploy/
├── docker/
│   └── Dockerfile              # Multi-stage build (python:3.10-slim)
├── compose/
│   ├── docker-compose.yml      # 2 services: chromadb + mcp_server
│   └── .env.example            # Template biến môi trường
├── launchd/
│   └── com.mcp.chromadb.plist  # macOS auto-start
└── systemd/
    └── chromadb.service        # Linux auto-start

🤖 Tích hợp AI Agent — Kích hoạt đầy đủ sức mạnh MCP

Để AI agent tận dụng 100% khả năng của MCP (auto-recall, memory, tech detection), copy System Prompt vào rules file của project:

# Antigravity (Gemini)
cp /path/to/vibe-light-mcp/docs/mcp_system_prompt.md /your-project/.gemini/rules.md

# Cursor
cp /path/to/vibe-light-mcp/docs/mcp_system_prompt.md /your-project/.cursorrules

# Windsurf / Cascade
cp /path/to/vibe-light-mcp/docs/mcp_system_prompt.md /your-project/.windsurfrules

# Cline / Roo Code
cp /path/to/vibe-light-mcp/docs/mcp_system_prompt.md /your-project/.clinerules

# GitHub Copilot
mkdir -p /your-project/.github
cp /path/to/vibe-light-mcp/docs/mcp_system_prompt.md /your-project/.github/copilot-instructions.md

# Claude Desktop → Dán nội dung vào Project → Custom Instructions

AI Agent sẽ tự động làm gì sau khi tích hợp?

📖 Xem chi tiết đầy đủ: docs/mcp_system_prompt.md — System Prompt + Tool Reference Card 📋 Phiên bản rút gọn (chỉ memory rules): docs/mcp_rules.md

🛠 Tools

🧠 Memory

🔍 Workspace & Knowledge

⚙️ System

📥 Import Skills — Mở rộng Knowledge Base

Import hàng trăm coding skills từ GitHub repo vào ChromaDB L2 — giúp AI agent có thêm knowledge để hỗ trợ bạn tốt hơn.

Quick Start

# Interactive — nhập repo URL rồi bấm Enter
./scripts/import_skills.sh

# Non-interactive — truyền args trực tiếp
./scripts/import_skills.sh https://github.com/HoangNguyen0403/agent-skills-standard develop

Cách hoạt động

import_skills.sh
  │
  ├── 1. Nhập repo URL + branch
  ├── 2. git clone --depth 1
  ├── 3. Detect skills/ directory
  ├── 4. Gọi seed_skills.py
  │       └── ThreadPoolExecutor(5 threads)
  │           ├── Parse SKILL.md (YAML + Markdown)
  │           ├── Group by category → tech_stack
  │           ├── Chunk (recursive_text_split)
  │           └── Upsert → ChromaDB L2
  ├── 5. In summary report
  └── 6. Cleanup /tmp

Tùy chọn nâng cao

# Preview không ghi dữ liệu
./scripts/import_skills.sh --dry-run https://github.com/.../repo develop

# Tùy chỉnh số threads
./scripts/import_skills.sh --workers 8 https://github.com/.../repo develop

# Gọi Python script trực tiếp
python3 scripts/seed_skills.py /path/to/skills --workers 5 --dry-run

Cấu trúc repo yêu cầu

Repo cần có thư mục skills/ với cấu trúc:

skills/
├── android/
│   ├── clean-architecture/
│   │   └── SKILL.md          ← YAML frontmatter + markdown
│   └── navigation/
│       └── SKILL.md
├── flutter/
│   ├── bloc-pattern/
│   │   └── SKILL.md
│   └── ...
└── ...

Mỗi SKILL.md có format:

---
name: Clean Architecture
description: Hướng dẫn triển khai Clean Architecture cho Android
---

## Nội dung skill...

Category Mapping

Folder name tự động map sang tech_stack key:

💡 Idempotent: Chạy lại bao nhiêu lần cũng không tạo duplicate — nhờ content-hash ID.

🛡️ Security Model

Hệ thống bảo mật sử dụng Defense-in-Depth (4 lớp bảo vệ):

Bổ sung:

• Process Group Kill — Timeout sẽ kill cả process tree (không để zombie)
• Cross-Platform — Windows dùng taskkill /F /T /PID, Unix dùng os.killpg
• Path Traversal Protection — read_reference, update_tech_stack chặn ../../
• URL Validation — sync_knowledge chặn shell injection qua repo URL
• Thread-safe LRU Cache — L1 collection cache có giới hạn (max 50) + thread lock

💡 Đặt MCP_EXEC_MODE=unrestricted nếu bạn tin tưởng hoàn toàn AI client (chỉ nên dùng khi dev local).

🔄 Multi-Instance Behavior

SSE/HTTP server dùng lock file (~/.mcp_server.lock) để ngăn conflict:

• Phát hiện server đang chạy → exit gracefully + gợi ý kết nối
• Phát hiện server đã chết (stale lock) → tự dọn lock cũ + start mới

# Kết nối nhiều client vào 1 SSE server
python main.py --transport sse --port 8000  # Terminal 1
MCP_BRIDGE_URL=http://127.0.0.1:8000 python cascade_bridge.py  # Terminal 2+

# Troubleshooting
cat ~/.mcp_server.lock    # Xem lock
rm ~/.mcp_server.lock     # Xoá nếu crash bất thường

📦 Backup & Recovery

# Backup qua MCP tool (AI gọi tự động)
# → backup_memory_database

# Backup thủ công
bash scripts/backup_chroma.sh

# Backup tự động (cron — weekly 3AM)
crontab -e
# Thêm dòng: 0 3 * * 0 /path/to/vibe-light-mcp/scripts/backup_chroma.sh

# Restore
tar xzf ~/.mcp_global_db/backups/chromadb_backup_YYYYMMDD_HHMMSS.tar.gz -C ~/.mcp_global_db

📚 Tech Stacks hỗ trợ

Built-in: Android/Kotlin · KMP · Flutter/Dart · iOS/Swift · Python · React Native · Vue.js 3

Importable (via import_skills.sh): Angular · React · NestJS · Next.js · Laravel · Go · PHP · TypeScript · JavaScript · Java · Spring Boot · Database · Quality Engineering · và hơn nữa...

💡 Thêm stack mới? Chỉ cần sửa tech_stacks/registry.yaml — không cần sửa code.

📄 License

MIT