docs: update QUICKSTART with full step-by-step install guide for all 4 MCPs
This commit is contained in:
Claude AI
@@ -1,269 +1,329 @@
|
||||
# Ollama MCP Quick Start Guide
|
||||
# MCP Stack — Installation Guide
|
||||
|
||||
## Быстрая установка (1 команда)
|
||||
> Covers: mcp-kubernetes · mcp-gitea · mcp-prometheus · mcp-loki
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Check |
|
||||
|---|---|
|
||||
| Docker + Docker Compose | `docker compose version` |
|
||||
| Git | `git --version` |
|
||||
| kubectl + kubeconfig | `kubectl get nodes` |
|
||||
| Access to the Gitea repo | https://git.thedevops.dev |
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Clone the repository
|
||||
|
||||
```bash
|
||||
curl -sSL https://git.thedevops.dev/admin/k3s-gitops/raw/branch/main/apps/ollama-mcp/install.sh | bash
|
||||
git clone https://git.thedevops.dev/admin/k3s-gitops.git
|
||||
cd k3s-gitops/apps/ollama-mcp
|
||||
```
|
||||
|
||||
## Что будет установлено:
|
||||
---
|
||||
|
||||
1. **MCP Kubernetes Server** - REST API для управления кластером
|
||||
2. **MCP Gitea Server** - REST API для работы с Git репозиториями
|
||||
3. **Docker Compose** - оркестрация сервисов
|
||||
4. **Health checks** - автоматический мониторинг состояния
|
||||
|
||||
## После установки:
|
||||
|
||||
### 1. Настроить Gitea токен
|
||||
## Step 2 — Configure environment
|
||||
|
||||
```bash
|
||||
cd ~/ollama-mcp
|
||||
cp .env.example .env
|
||||
nano .env
|
||||
```
|
||||
|
||||
Добавь свой токен:
|
||||
Fill in the required values:
|
||||
|
||||
```env
|
||||
GITEA_TOKEN=your_token_here
|
||||
# ── Gitea ────────────────────────────────────────────────────
|
||||
GITEA_URL=https://git.thedevops.dev
|
||||
GITEA_TOKEN=<your-token> # Settings → Applications → Generate Token
|
||||
GITEA_OWNER=admin # your Gitea username
|
||||
|
||||
# ── Kubernetes ───────────────────────────────────────────────
|
||||
K8S_CONTEXT= # leave empty for default context
|
||||
K8S_NAMESPACE=default
|
||||
|
||||
# ── Ports ────────────────────────────────────────────────────
|
||||
MCP_K8S_PORT=3001
|
||||
MCP_GITEA_PORT=3002
|
||||
MCP_PROMETHEUS_PORT=3003
|
||||
MCP_LOKI_PORT=3005
|
||||
|
||||
# ── Prometheus ───────────────────────────────────────────────
|
||||
# Find your NodePort: kubectl -n monitoring get svc kube-prometheus-stack-prometheus
|
||||
PROMETHEUS_URL=http://<node-ip>:<nodeport>
|
||||
GRAFANA_URL=http://<node-ip>:<grafana-nodeport>
|
||||
GRAFANA_TOKEN= # optional — Grafana API key
|
||||
|
||||
# ── Loki ─────────────────────────────────────────────────────
|
||||
# Find your NodePort: kubectl -n monitoring get svc loki
|
||||
LOKI_URL=http://<node-ip>:<nodeport>
|
||||
```
|
||||
|
||||
Получить токен:
|
||||
- https://git.thedevops.dev/user/settings/applications
|
||||
- Generate New Token
|
||||
- Права: `repo`, `admin:org`, `write:repository`
|
||||
|
||||
### 2. Перезапустить сервисы
|
||||
|
||||
**Get your Gitea token:**
|
||||
```bash
|
||||
docker-compose restart
|
||||
# Via browser:
|
||||
# https://git.thedevops.dev/user/settings/applications
|
||||
# → Generate New Token → select: repo, admin:org, write:repository
|
||||
|
||||
# Verify the token works:
|
||||
curl -H "Authorization: token <your-token>" \
|
||||
https://git.thedevops.dev/api/v1/user
|
||||
```
|
||||
|
||||
### 3. Проверить статус
|
||||
|
||||
**Find Prometheus and Loki NodePorts:**
|
||||
```bash
|
||||
docker-compose ps
|
||||
docker-compose logs -f
|
||||
# Get node IP
|
||||
kubectl get nodes -o wide
|
||||
|
||||
# Prometheus NodePort
|
||||
kubectl -n monitoring get svc kube-prometheus-stack-prometheus
|
||||
|
||||
# Loki NodePort
|
||||
kubectl -n monitoring get svc loki
|
||||
|
||||
# Grafana NodePort (optional)
|
||||
kubectl -n monitoring get svc kube-prometheus-stack-grafana
|
||||
```
|
||||
|
||||
## Интеграция с Ollama
|
||||
---
|
||||
|
||||
### Способ 1: Через Open WebUI
|
||||
|
||||
Если у тебя установлен Open WebUI:
|
||||
|
||||
1. Settings → Connections → Add Connection
|
||||
2. Name: `Kubernetes MCP`
|
||||
3. URL: `http://localhost:3001`
|
||||
4. Type: `REST API`
|
||||
|
||||
### Способ 2: Прямые запросы
|
||||
## Step 3 — Copy kubeconfig
|
||||
|
||||
```bash
|
||||
# Список подов
|
||||
curl -X POST http://localhost:3001/api/pods/list \
|
||||
mkdir -p config
|
||||
cp ~/.kube/config config/kubeconfig
|
||||
chmod 600 config/kubeconfig
|
||||
|
||||
# Verify it works
|
||||
kubectl --kubeconfig=config/kubeconfig get nodes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4 — Build images
|
||||
|
||||
```bash
|
||||
docker compose build
|
||||
```
|
||||
|
||||
Or build individually if you only want specific MCPs:
|
||||
|
||||
```bash
|
||||
docker compose build mcp-kubernetes
|
||||
docker compose build mcp-gitea
|
||||
docker compose build mcp-prometheus
|
||||
docker compose build mcp-loki
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — Start services
|
||||
|
||||
```bash
|
||||
# Start all
|
||||
docker compose up -d
|
||||
|
||||
# Or start only the monitoring MCPs
|
||||
docker compose up -d mcp-prometheus mcp-loki
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 6 — Verify everything is running
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
NAME STATUS PORTS
|
||||
ollama-mcp-kubernetes running 0.0.0.0:3001->3000/tcp
|
||||
ollama-mcp-gitea running 0.0.0.0:3002->3000/tcp
|
||||
ollama-mcp-prometheus running 0.0.0.0:3003->3000/tcp
|
||||
ollama-mcp-loki running 0.0.0.0:3005->3000/tcp
|
||||
```
|
||||
|
||||
Health check all endpoints:
|
||||
```bash
|
||||
curl -s http://localhost:3001/health | jq . # Kubernetes MCP
|
||||
curl -s http://localhost:3002/health | jq . # Gitea MCP
|
||||
curl -s http://localhost:3003/health | jq . # Prometheus MCP
|
||||
curl -s http://localhost:3005/health | jq . # Loki MCP
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7 — Test each MCP
|
||||
|
||||
### Kubernetes MCP
|
||||
```bash
|
||||
# List all namespaces
|
||||
curl -s -X POST http://localhost:3001/api/namespaces/list | jq .
|
||||
|
||||
# List pods in monitoring
|
||||
curl -s -X POST http://localhost:3001/api/pods/list \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"namespace": "argocd"}'
|
||||
|
||||
# Логи пода
|
||||
curl -X POST http://localhost:3001/api/pods/logs \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "argocd-server-xxx", "namespace": "argocd", "tailLines": 100}'
|
||||
|
||||
# Список репозиториев
|
||||
curl -X POST http://localhost:3002/api/repos/list \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"owner": "admin"}'
|
||||
-d '{"namespace": "monitoring"}' | jq .
|
||||
```
|
||||
|
||||
### Способ 3: Создать wrapper для Ollama
|
||||
### Gitea MCP
|
||||
```bash
|
||||
# List repositories
|
||||
curl -s -X POST http://localhost:3002/api/repos/list \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"owner": "admin"}' | jq .
|
||||
```
|
||||
|
||||
Создай файл `ollama-k8s.sh`:
|
||||
### Prometheus MCP
|
||||
```bash
|
||||
# Firing alerts
|
||||
curl -s -X POST http://localhost:3003/api/alerts \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"firingOnly": true}' | jq .
|
||||
|
||||
# Top pods by CPU
|
||||
curl -s -X POST http://localhost:3003/api/pod_cpu \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"namespace": "monitoring"}' | jq .
|
||||
|
||||
# Node resources
|
||||
curl -s -X POST http://localhost:3003/api/node_resources | jq .
|
||||
```
|
||||
|
||||
### Loki MCP
|
||||
```bash
|
||||
# List namespaces with logs
|
||||
curl -s -X POST http://localhost:3005/api/namespaces | jq .
|
||||
|
||||
# Errors in argocd last 30 min
|
||||
curl -s -X POST http://localhost:3005/api/errors \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"namespace": "argocd", "minutes": 30}' | jq .
|
||||
|
||||
# OOMKill events last 24h
|
||||
curl -s -X POST http://localhost:3005/api/oomkilled \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"hours": 24}' | jq .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Updating after a git pull
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
cd k3s-gitops
|
||||
git pull
|
||||
cd apps/ollama-mcp
|
||||
|
||||
PROMPT="$*"
|
||||
# Rebuild changed services
|
||||
docker compose build mcp-prometheus mcp-loki
|
||||
|
||||
# Отправить запрос к Ollama с контекстом MCP
|
||||
ollama run qwen2.5-coder:32b "
|
||||
Context: You have access to Kubernetes API at http://localhost:3001 and Gitea API at http://localhost:3002
|
||||
|
||||
Available Kubernetes endpoints:
|
||||
- POST /api/pods/list - list pods
|
||||
- POST /api/pods/logs - get pod logs
|
||||
- POST /api/deployments/list - list deployments
|
||||
- POST /api/services/list - list services
|
||||
- POST /api/namespaces/list - list namespaces
|
||||
|
||||
Available Gitea endpoints:
|
||||
- POST /api/repos/list - list repositories
|
||||
- POST /api/repos/file/get - get file content
|
||||
- POST /api/repos/tree/get - list directory
|
||||
- POST /api/repos/file/create - create file
|
||||
- POST /api/repos/branches/list - list branches
|
||||
|
||||
User request: $PROMPT
|
||||
|
||||
Generate curl commands to execute this request and show the results.
|
||||
"
|
||||
# Restart with new images
|
||||
docker compose up -d mcp-prometheus mcp-loki
|
||||
```
|
||||
|
||||
Использование:
|
||||
```bash
|
||||
chmod +x ollama-k8s.sh
|
||||
./ollama-k8s.sh "покажи все поды в namespace monitoring"
|
||||
./ollama-k8s.sh "получи логи grafana за последние 50 строк"
|
||||
```
|
||||
|
||||
## Примеры промптов для Ollama
|
||||
|
||||
### Kubernetes:
|
||||
|
||||
```
|
||||
"Покажи все поды в namespace argocd"
|
||||
"Получи логи пода prometheus-xxx за последние 100 строк"
|
||||
"Список всех deployments в namespace monitoring"
|
||||
"Покажи все сервисы в default namespace"
|
||||
"Какие namespaces есть в кластере?"
|
||||
```
|
||||
|
||||
### Gitea:
|
||||
|
||||
```
|
||||
"Покажи все репозитории пользователя admin"
|
||||
"Получи содержимое файла apps/loki/statefulset.yaml из репозитория k3s-gitops"
|
||||
"Покажи структуру директории apps/ в k3s-gitops"
|
||||
"Создай файл test.yaml в репозитории k3s-gitops"
|
||||
"Какие ветки есть в репозитории k3s-gitops?"
|
||||
```
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### MCP серверы не отвечают
|
||||
### Container won't start
|
||||
```bash
|
||||
docker compose logs mcp-prometheus
|
||||
docker compose logs mcp-loki
|
||||
```
|
||||
|
||||
### Prometheus MCP returns connection errors
|
||||
```bash
|
||||
# Check Prometheus is reachable from the Docker host
|
||||
curl http://<node-ip>:<nodeport>/api/v1/status/runtimeinfo
|
||||
|
||||
# If using cluster DNS (svc.cluster.local), it won't work from Docker.
|
||||
# Use the NodePort IP in PROMETHEUS_URL instead.
|
||||
```
|
||||
|
||||
### Loki returns empty results
|
||||
```bash
|
||||
# Confirm Loki has data
|
||||
curl "http://<loki-ip>:<port>/loki/api/v1/labels"
|
||||
|
||||
# Check Promtail is shipping logs
|
||||
kubectl -n monitoring logs -l app=promtail --tail=50
|
||||
```
|
||||
|
||||
### Port already in use
|
||||
```bash
|
||||
# Find what's using a port
|
||||
ss -tlnp | grep 3003
|
||||
|
||||
# Change the port in .env
|
||||
MCP_PROMETHEUS_PORT=3013
|
||||
docker compose up -d mcp-prometheus
|
||||
```
|
||||
|
||||
### Kubeconfig permission denied
|
||||
```bash
|
||||
chmod 600 config/kubeconfig
|
||||
docker compose restart mcp-kubernetes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Management commands
|
||||
|
||||
```bash
|
||||
cd ~/ollama-mcp
|
||||
cd k3s-gitops/apps/ollama-mcp
|
||||
|
||||
# Проверить логи
|
||||
docker-compose logs mcp-kubernetes
|
||||
docker-compose logs mcp-gitea
|
||||
# Status
|
||||
docker compose ps
|
||||
|
||||
# Перезапустить
|
||||
docker-compose restart
|
||||
# Live logs
|
||||
docker compose logs -f
|
||||
docker compose logs -f mcp-prometheus
|
||||
docker compose logs -f mcp-loki
|
||||
|
||||
# Пересобрать
|
||||
docker-compose down
|
||||
docker-compose build --no-cache
|
||||
docker-compose up -d
|
||||
# Restart a specific service
|
||||
docker compose restart mcp-prometheus
|
||||
|
||||
# Full rebuild
|
||||
docker compose down
|
||||
docker compose build --no-cache
|
||||
docker compose up -d
|
||||
|
||||
# Stop everything
|
||||
docker compose down
|
||||
```
|
||||
|
||||
### Ошибка подключения к Kubernetes
|
||||
---
|
||||
|
||||
```bash
|
||||
# Проверить kubeconfig
|
||||
kubectl --kubeconfig=~/ollama-mcp/config/kubeconfig get nodes
|
||||
## Available endpoints reference
|
||||
|
||||
# Если не работает, скопировать заново
|
||||
cp ~/.kube/config ~/ollama-mcp/config/kubeconfig
|
||||
docker-compose restart mcp-kubernetes
|
||||
```
|
||||
### Prometheus MCP (`localhost:3003`)
|
||||
| Endpoint | Description |
|
||||
|---|---|
|
||||
| `POST /api/alerts` | Firing alerts |
|
||||
| `POST /api/targets` | Scrape target health |
|
||||
| `POST /api/pod_cpu` | CPU usage by pod/namespace |
|
||||
| `POST /api/pod_memory` | Memory usage by pod/namespace |
|
||||
| `POST /api/pod_restarts` | Restart counts |
|
||||
| `POST /api/node_resources` | Node CPU/mem/disk % |
|
||||
| `POST /api/pvc_usage` | PVC disk usage % |
|
||||
| `POST /api/http_errors` | Nginx ingress 5xx rate |
|
||||
| `POST /api/query` | Raw PromQL instant query |
|
||||
| `POST /api/query_range` | Raw PromQL range query |
|
||||
| `POST /api/grafana_dashboards` | List Grafana dashboards |
|
||||
|
||||
### Ошибка подключения к Gitea
|
||||
|
||||
```bash
|
||||
# Проверить токен
|
||||
curl -H "Authorization: token YOUR_TOKEN" \
|
||||
https://git.thedevops.dev/api/v1/user
|
||||
|
||||
# Обновить токен в .env
|
||||
nano ~/ollama-mcp/.env
|
||||
docker-compose restart mcp-gitea
|
||||
```
|
||||
|
||||
### Порты заняты
|
||||
|
||||
Если порты 3001 или 3002 уже заняты:
|
||||
|
||||
```bash
|
||||
nano ~/ollama-mcp/.env
|
||||
```
|
||||
|
||||
Измени порты:
|
||||
```env
|
||||
MCP_K8S_PORT=4001
|
||||
MCP_GITEA_PORT=4002
|
||||
```
|
||||
|
||||
```bash
|
||||
docker-compose down
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Управление
|
||||
|
||||
```bash
|
||||
cd ~/ollama-mcp
|
||||
|
||||
# Запустить
|
||||
docker-compose up -d
|
||||
|
||||
# Остановить
|
||||
docker-compose down
|
||||
|
||||
# Перезапустить
|
||||
docker-compose restart
|
||||
|
||||
# Статус
|
||||
docker-compose ps
|
||||
|
||||
# Логи (следить в реальном времени)
|
||||
docker-compose logs -f
|
||||
|
||||
# Логи конкретного сервиса
|
||||
docker-compose logs -f mcp-kubernetes
|
||||
docker-compose logs -f mcp-gitea
|
||||
|
||||
# Обновить образы
|
||||
docker-compose pull
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Безопасность
|
||||
|
||||
- **Kubeconfig**: Защищен правами 600, доступен только внутри контейнера
|
||||
- **Gitea Token**: Хранится в .env (не коммитится в git)
|
||||
- **Network**: Изолированная Docker сеть
|
||||
- **Ports**: По умолчанию доступны на localhost (127.0.0.1)
|
||||
|
||||
Для публичного доступа (НЕ рекомендуется без SSL):
|
||||
```yaml
|
||||
ports:
|
||||
- "0.0.0.0:3001:3000" # Доступен извне
|
||||
```
|
||||
|
||||
## Дополнительно
|
||||
|
||||
### Мониторинг
|
||||
|
||||
Health checks доступны по:
|
||||
- http://localhost:3001/health
|
||||
- http://localhost:3002/health
|
||||
|
||||
### Логи в файл
|
||||
|
||||
```bash
|
||||
docker-compose logs > mcp-logs.txt
|
||||
```
|
||||
|
||||
### Автозапуск при перезагрузке
|
||||
|
||||
Сервисы уже настроены с `restart: unless-stopped`
|
||||
|
||||
Для проверки после перезагрузки:
|
||||
```bash
|
||||
docker ps | grep mcp
|
||||
```
|
||||
|
||||
## Полная документация
|
||||
|
||||
Смотри [README.md](./README.md) для подробной информации.
|
||||
### Loki MCP (`localhost:3005`)
|
||||
| Endpoint | Description |
|
||||
|---|---|
|
||||
| `POST /api/pod_logs` | Logs for a specific pod |
|
||||
| `POST /api/namespace_logs` | All logs in a namespace |
|
||||
| `POST /api/errors` | ERROR/WARN lines (namespace or cluster) |
|
||||
| `POST /api/search` | Full-text search across logs |
|
||||
| `POST /api/oomkilled` | OOMKilled events |
|
||||
| `POST /api/crash_loops` | CrashLoopBackOff events |
|
||||
| `POST /api/rate` | Log ingestion rate by namespace |
|
||||
| `POST /api/labels` | Available Loki label names |
|
||||
| `POST /api/namespaces` | Namespaces with logs |
|
||||
| `POST /api/query` | Raw LogQL query |
|
||||
|
||||
Reference in New Issue
Block a user