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
|
```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 для управления кластером
|
## Step 2 — Configure environment
|
||||||
2. **MCP Gitea Server** - REST API для работы с Git репозиториями
|
|
||||||
3. **Docker Compose** - оркестрация сервисов
|
|
||||||
4. **Health checks** - автоматический мониторинг состояния
|
|
||||||
|
|
||||||
## После установки:
|
|
||||||
|
|
||||||
### 1. Настроить Gitea токен
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd ~/ollama-mcp
|
cp .env.example .env
|
||||||
nano .env
|
nano .env
|
||||||
```
|
```
|
||||||
|
|
||||||
Добавь свой токен:
|
Fill in the required values:
|
||||||
|
|
||||||
```env
|
```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>
|
||||||
```
|
```
|
||||||
|
|
||||||
Получить токен:
|
**Get your Gitea token:**
|
||||||
- https://git.thedevops.dev/user/settings/applications
|
|
||||||
- Generate New Token
|
|
||||||
- Права: `repo`, `admin:org`, `write:repository`
|
|
||||||
|
|
||||||
### 2. Перезапустить сервисы
|
|
||||||
|
|
||||||
```bash
|
```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
|
```bash
|
||||||
docker-compose ps
|
# Get node IP
|
||||||
docker-compose logs -f
|
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
|
## Step 3 — Copy kubeconfig
|
||||||
|
|
||||||
Если у тебя установлен Open WebUI:
|
|
||||||
|
|
||||||
1. Settings → Connections → Add Connection
|
|
||||||
2. Name: `Kubernetes MCP`
|
|
||||||
3. URL: `http://localhost:3001`
|
|
||||||
4. Type: `REST API`
|
|
||||||
|
|
||||||
### Способ 2: Прямые запросы
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Список подов
|
mkdir -p config
|
||||||
curl -X POST http://localhost:3001/api/pods/list \
|
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" \
|
-H "Content-Type: application/json" \
|
||||||
-d '{"namespace": "argocd"}'
|
-d '{"namespace": "monitoring"}' | jq .
|
||||||
|
|
||||||
# Логи пода
|
|
||||||
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"}'
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Способ 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
|
```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
|
# Restart with new images
|
||||||
ollama run qwen2.5-coder:32b "
|
docker compose up -d mcp-prometheus mcp-loki
|
||||||
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.
|
|
||||||
"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Использование:
|
---
|
||||||
```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
|
## 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
|
```bash
|
||||||
cd ~/ollama-mcp
|
cd k3s-gitops/apps/ollama-mcp
|
||||||
|
|
||||||
# Проверить логи
|
# Status
|
||||||
docker-compose logs mcp-kubernetes
|
docker compose ps
|
||||||
docker-compose logs mcp-gitea
|
|
||||||
|
|
||||||
# Перезапустить
|
# Live logs
|
||||||
docker-compose restart
|
docker compose logs -f
|
||||||
|
docker compose logs -f mcp-prometheus
|
||||||
|
docker compose logs -f mcp-loki
|
||||||
|
|
||||||
# Пересобрать
|
# Restart a specific service
|
||||||
docker-compose down
|
docker compose restart mcp-prometheus
|
||||||
docker-compose build --no-cache
|
|
||||||
docker-compose up -d
|
# Full rebuild
|
||||||
|
docker compose down
|
||||||
|
docker compose build --no-cache
|
||||||
|
docker compose up -d
|
||||||
|
|
||||||
|
# Stop everything
|
||||||
|
docker compose down
|
||||||
```
|
```
|
||||||
|
|
||||||
### Ошибка подключения к Kubernetes
|
---
|
||||||
|
|
||||||
```bash
|
## Available endpoints reference
|
||||||
# Проверить kubeconfig
|
|
||||||
kubectl --kubeconfig=~/ollama-mcp/config/kubeconfig get nodes
|
|
||||||
|
|
||||||
# Если не работает, скопировать заново
|
### Prometheus MCP (`localhost:3003`)
|
||||||
cp ~/.kube/config ~/ollama-mcp/config/kubeconfig
|
| Endpoint | Description |
|
||||||
docker-compose restart mcp-kubernetes
|
|---|---|
|
||||||
```
|
| `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
|
### Loki MCP (`localhost:3005`)
|
||||||
|
| Endpoint | Description |
|
||||||
```bash
|
|---|---|
|
||||||
# Проверить токен
|
| `POST /api/pod_logs` | Logs for a specific pod |
|
||||||
curl -H "Authorization: token YOUR_TOKEN" \
|
| `POST /api/namespace_logs` | All logs in a namespace |
|
||||||
https://git.thedevops.dev/api/v1/user
|
| `POST /api/errors` | ERROR/WARN lines (namespace or cluster) |
|
||||||
|
| `POST /api/search` | Full-text search across logs |
|
||||||
# Обновить токен в .env
|
| `POST /api/oomkilled` | OOMKilled events |
|
||||||
nano ~/ollama-mcp/.env
|
| `POST /api/crash_loops` | CrashLoopBackOff events |
|
||||||
docker-compose restart mcp-gitea
|
| `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 |
|
||||||
|
|
||||||
Если порты 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) для подробной информации.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user