Skip to content
Hands-on IT IT Drills

Day 12: Go for AI – ask, docsearch and ops-mcp

Goal: Talk to a local LLM via net/http – streamed, as validated JSON and with tool calling –, search runbooks semantically and expose ops tools as an MCP server · Duration: approx. 180 min · Prerequisite: Day 11

Briefing

  • Under /v1, Ollama speaks the OpenAI API; the same code runs against vLLM or Mistral (just change LLM_BASE_URL, LLM_API_KEY, LLM_MODEL).
  • No SDK: net/http, encoding/json and a bufio.Scanner for server-sent events are enough.
  • Structured output via JSON Schema – and you still validate it yourself.
  • Tool calling: the model requests a call; your code decides and executes.
  • MCP with the official Go SDK makes the same tools usable for any AI client.
ask ---------> /v1/chat/completions (stream | json_schema | tools) --> ministral-3:3b
docsearch ---> /v1/embeddings --> cosine search over docs/*.md       --> all-minilm
AI client <--stdio JSON-RPC--> ops-mcp --> internal/tools.DiskFree

Drill 1: Module and HTTP client

First check whether Ollama is running and the model is there:

curl -s http://127.0.0.1:11434/v1/models | jq -r '.data[].id' | grep ministral
mkdir -p ~/go-lab/tag12-ask/{cmd/ask,cmd/docsearch,cmd/ops-mcp,docs}
mkdir -p ~/go-lab/tag12-ask/internal/{llm,search,tools}
cd ~/go-lab/tag12-ask
go mod init example.com/ask
cat > .golangci.yml <<'EOF'
version: "2"
linters:
  exclusions:
    presets: [std-error-handling] # fmt.Fprint*, Close & Co. nicht anmahnen
EOF

Expected:

ministral-3:3b
go: creating new go.mod: module example.com/ask
go: to add module requirements and sums:
    go mod tidy

Ignore the hint about go mod tidy for now – until Drill 6 you only need the standard library. You know the .golangci.yml from Day 5.

The types map only the fields of the OpenAI API that you need. post encapsulates JSON, the auth header and the status check.

cat > internal/llm/llm.go <<'EOF'
// Package llm talks to the OpenAI-compatible API (Ollama, vLLM, Mistral).
package llm

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

type Message struct {
    Role       string     `json:"role"`
    Content    string     `json:"content"`
    ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
    ToolCallID string     `json:"tool_call_id,omitempty"`
}

type ToolCall struct {
    ID       string `json:"id"`
    Type     string `json:"type"`
    Function struct {
        Name      string `json:"name"`
        Arguments string `json:"arguments"` // JSON als String
    } `json:"function"`
}

type Request struct {
    Model          string    `json:"model"`
    Messages       []Message `json:"messages"`
    Stream         bool      `json:"stream,omitempty"`
    Tools          []any     `json:"tools,omitempty"`
    ResponseFormat any       `json:"response_format,omitempty"`
}

type Client struct {
    BaseURL, Key, Model string
    HTTP                *http.Client
}

// FromEnv reads LLM_BASE_URL, LLM_API_KEY and LLM_MODEL (defaults: Ollama).
func FromEnv() *Client {
    return &Client{
        BaseURL: env("LLM_BASE_URL", "http://127.0.0.1:11434/v1"),
        Key:     os.Getenv("LLM_API_KEY"),
        Model:   env("LLM_MODEL", "ministral-3:3b"),
        HTTP:    &http.Client{Timeout: 5 * time.Minute},
    }
}

func env(k, def string) string {
    if v := os.Getenv(k); v != "" {
        return v
    }
    return def
}

// post sends JSON and returns the response only on status 200.
func (c *Client) post(ctx context.Context, path string, body any) (
    *http.Response, error) {
    b, err := json.Marshal(body)
    if err != nil {
        return nil, err
    }
    req, err := http.NewRequestWithContext(ctx, http.MethodPost,
        c.BaseURL+path, bytes.NewReader(b))
    if err != nil {
        return nil, err
    }
    req.Header.Set("Content-Type", "application/json")
    if c.Key != "" {
        req.Header.Set("Authorization", "Bearer "+c.Key)
    }
    resp, err := c.HTTP.Do(req)
    if err != nil {
        return nil, err
    }
    if resp.StatusCode != http.StatusOK {
        defer resp.Body.Close()
        msg, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
        return nil, fmt.Errorf("%s: %s: %s", path, resp.Status,
            strings.TrimSpace(string(msg)))
    }
    return resp, nil
}
EOF
go vet ./...

Expected: no output.

Why? Without a key, the Authorization header is left out – Ollama needs none, cloud APIs do. Error bodies are limited to 512 bytes so that no HTML error document floods your terminal.

Save your progress? Sign up for free

Drill 2: Streaming with server-sent events

With "stream": true the response arrives as lines of data: {...}. Take one look at the raw format:

curl -sN http://127.0.0.1:11434/v1/chat/completions -d '{"model":"ministral-3:3b",
  "stream":true,"messages":[{"role":"user","content":"Sag Hallo"}]}' > sse.txt
grep -o '"delta":{[^}]*}' sse.txt | head -3; grep DONE sse.txt; rm sse.txt

Expected (text varies):

"delta":{"role":"assistant","content":"**"}
"delta":{"content":"H"}
"delta":{"content":"allo"}
data: [DONE]

That is exactly what Stream parses: cut off the prefix, read the JSON, pass on delta.content, stop at [DONE].

cat > internal/llm/chat.go <<'EOF'
package llm

import (
    "bufio"
    "context"
    "encoding/json"
    "errors"
    "fmt"
    "strings"
)

// Chat sends a request without streaming and returns the answer.
func (c *Client) Chat(ctx context.Context, r Request) (Message, error) {
    r.Model, r.Stream = c.Model, false
    resp, err := c.post(ctx, "/chat/completions", r)
    if err != nil {
        return Message{}, err
    }
    defer resp.Body.Close()
    var out struct {
        Choices []struct{ Message Message } `json:"choices"`
    }
    if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
        return Message{}, fmt.Errorf("antwort lesen: %w", err)
    }
    if len(out.Choices) == 0 {
        return Message{}, errors.New("antwort ohne choices")
    }
    return out.Choices[0].Message, nil
}

// Stream calls onDelta for every piece of text from the SSE stream.
func (c *Client) Stream(ctx context.Context, msgs []Message,
    onDelta func(string)) error {
    resp, err := c.post(ctx, "/chat/completions",
        Request{Model: c.Model, Messages: msgs, Stream: true})
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    sc := bufio.NewScanner(resp.Body)
    for sc.Scan() {
        data, ok := strings.CutPrefix(sc.Text(), "data: ")
        if !ok {
            continue // Leerzeilen und Kommentare
        }
        if data == "[DONE]" {
            return nil
        }
        var chunk struct {
            Choices []struct {
                Delta struct{ Content string } `json:"delta"`
            } `json:"choices"`
        }
        if err := json.Unmarshal([]byte(data), &chunk); err != nil {
            return fmt.Errorf("sse-chunk: %w", err)
        }
        if len(chunk.Choices) > 0 {
            onDelta(chunk.Choices[0].Delta.Content)
        }
    }
    if err := sc.Err(); err != nil {
        return err
    }
    return errors.New("stream ohne [DONE] beendet")
}
EOF

The test simulates the server with httptest – no model needed:

cat > internal/llm/llm_test.go <<'EOF'
package llm

import (
    "context"
    "fmt"
    "net/http"
    "net/http/httptest"
    "strings"
    "testing"
)

// fake checks the key and streams three pieces of text via SSE.
func fake(t *testing.T) *Client {
    srv := httptest.NewServer(http.HandlerFunc(
        func(w http.ResponseWriter, r *http.Request) {
            if r.Header.Get("Authorization") != "Bearer sk-lab-1234" {
                http.Error(w, "kein key", http.StatusUnauthorized)
                return
            }
            w.Header().Set("Content-Type", "text/event-stream")
            for _, s := range []string{"Hal", "lo", " Welt"} {
                fmt.Fprintf(w, "data: {\"choices\":[{\"delta\":"+
                    "{\"content\":%q}}]}\n\n", s)
            }
            fmt.Fprint(w, "data: [DONE]\n\n")
        }))
    t.Cleanup(srv.Close)
    return &Client{BaseURL: srv.URL, Key: "sk-lab-1234", HTTP: srv.Client()}
}

func TestStream(t *testing.T) {
    var got strings.Builder
    err := fake(t).Stream(context.Background(), nil,
        func(s string) { got.WriteString(s) })
    if err != nil || got.String() != "Hallo Welt" {
        t.Fatalf("got %q, err %v", got.String(), err)
    }
}

func TestStatusError(t *testing.T) {
    c := fake(t)
    c.Key = "falsch"
    _, err := c.Chat(context.Background(), Request{})
    if err == nil || !strings.Contains(err.Error(), "401") {
        t.Fatalf("erwartet 401, got %v", err)
    }
}
EOF
go test -v ./internal/llm

Expected (abbreviated):

--- PASS: TestStream (0.00s)
--- PASS: TestStatusError (0.00s)
ok      example.com/ask/internal/llm    0.164s

Why? bufio.Scanner reads line by line; the code skips blank lines and comments without data:. A stream without [DONE] was cut off – you report that as an error instead of passing off half an answer as a whole one.

Save your progress? Sign up for free

Drill 3: Structured output with JSON Schema

response_format with json_schema forces the model into a fixed shape. Small models stick to it most of the time – “most of the time” is not enough, so you check for yourself.

cat > cmd/ask/triage.go <<'EOF'
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "os"
    "slices"

    "example.com/ask/internal/llm"
)

type Triage struct {
    Severity string `json:"severity"`
    Summary  string `json:"summary"`
    Action   string `json:"action"`
}

// triageSchema forces the model into exactly this JSON shape.
var triageSchema = json.RawMessage(`{"type": "json_schema", "json_schema": {
  "name": "triage", "schema": {"type": "object",
    "properties": {
      "severity": {"type": "string", "enum": ["low", "medium", "high"]},
      "summary": {"type": "string"}, "action": {"type": "string"}},
    "required": ["severity", "summary", "action"]}}}`)

func runTriage(ctx context.Context, c *llm.Client, q string) error {
    m, err := c.Chat(ctx, llm.Request{
        Messages: []llm.Message{
            {Role: "system", Content: "Du bist SRE. Bewerte die Meldung knapp."},
            {Role: "user", Content: q},
        },
        ResponseFormat: triageSchema,
    })
    if err != nil {
        return err
    }
    t, err := parseTriage(m.Content)
    if err != nil {
        return err
    }
    enc := json.NewEncoder(os.Stdout)
    enc.SetIndent("", "  ")
    return enc.Encode(t)
}

// parseTriage does not trust the model: the schema is a wish, checking is a must.
func parseTriage(s string) (Triage, error) {
    var t Triage
    if err := json.Unmarshal([]byte(s), &t); err != nil {
        return t, fmt.Errorf("kein gültiges JSON: %w", err)
    }
    if !slices.Contains([]string{"low", "medium", "high"}, t.Severity) {
        return t, fmt.Errorf("ungültige severity %q", t.Severity)
    }
    return t, nil
}
EOF
cat > cmd/ask/triage_test.go <<'EOF'
package main

import "testing"

func TestParseTriage(t *testing.T) {
    tests := []struct {
        in      string
        wantErr bool
    }{
        {`{"severity":"high","summary":"Disk voll","action":"aufräumen"}`, false},
        {`{"severity":"kritisch","summary":"x","action":"y"}`, true},
        {"Klar, hier ist dein JSON: {", true},
    }
    for _, tt := range tests {
        if _, err := parseTriage(tt.in); (err != nil) != tt.wantErr {
            t.Errorf("%q: err=%v, wantErr=%v", tt.in, err, tt.wantErr)
        }
    }
}
EOF
go test -run TestParseTriage -v ./cmd/ask 2>&1 | tail -2

Expected:

PASS
ok      example.com/ask/cmd/ask 0.153s

Why? json.RawMessage ends up in the request unchanged – that way you write schemas readably as JSON instead of nested map[string]any. An enum in the schema plus slices.Contains in the code: belt and braces.

Save your progress? Sign up for free

Drill 4: Tool calling

The model receives a tool description and answers with tool_calls instead of text. Your code runs the tool and sends the result back in the role tool. The tool itself is ordinary Go:

cat > internal/tools/disk.go <<'EOF'
// Package tools contains local functions that a model may call.
package tools

import (
    "fmt"
    "math"
    "syscall"
)

// Disk is the result of DiskFree.
type Disk struct {
    Path    string  `json:"path"`
    FreeGiB float64 `json:"free_gib"`
    FreePct float64 `json:"free_pct"`
}

// DiskFree measures the free space of the file system under path (Unix).
func DiskFree(path string) (Disk, error) {
    var st syscall.Statfs_t
    if err := syscall.Statfs(path, &st); err != nil {
        return Disk{}, fmt.Errorf("statfs %s: %w", path, err)
    }
    free := float64(st.Bavail) * float64(st.Bsize)
    total := float64(st.Blocks) * float64(st.Bsize)
    return Disk{path, round(free / (1 << 30)), round(100 * free / total)}, nil
}

func round(f float64) float64 { return math.Round(f*10) / 10 }
EOF

The loop: ask, run tools, append results, ask again – at most five rounds.

cat > cmd/ask/tools.go <<'EOF'
package main

import (
    "context"
    "encoding/json"
    "errors"
    "fmt"
    "os"

    "example.com/ask/internal/llm"
    "example.com/ask/internal/tools"
)

var toolDefs = []any{json.RawMessage(`{"type": "function", "function": {
  "name": "disk_free",
  "description": "Freier Speicherplatz eines Pfads auf diesem Rechner",
  "parameters": {"type": "object",
    "properties": {"path": {"type": "string"}}, "required": ["path"]}}}`)}

// callTool runs only known tools; the arguments come from the model.
func callTool(name, args string) string {
    if name != "disk_free" {
        return `{"error":"unbekanntes tool"}`
    }
    var in struct{ Path string }
    if err := json.Unmarshal([]byte(args), &in); err != nil || in.Path == "" {
        return `{"error":"argument path fehlt"}`
    }
    d, err := tools.DiskFree(in.Path)
    if err != nil {
        return fmt.Sprintf(`{"error":%q}`, err.Error())
    }
    b, _ := json.Marshal(d)
    return string(b)
}

func runTools(ctx context.Context, c *llm.Client, q string) error {
    msgs := []llm.Message{
        {Role: "system", Content: "Nutze Tools für Fakten über diesen Rechner."},
        {Role: "user", Content: q},
    }
    for range 5 { // Obergrenze gegen Endlosschleifen
        m, err := c.Chat(ctx, llm.Request{Messages: msgs, Tools: toolDefs})
        if err != nil {
            return err
        }
        if len(m.ToolCalls) == 0 {
            fmt.Println(m.Content)
            return nil
        }
        msgs = append(msgs, m)
        for _, tc := range m.ToolCalls {
            out := callTool(tc.Function.Name, tc.Function.Arguments)
            fmt.Fprintf(os.Stderr, "-> %s(%s) = %s\n",
                tc.Function.Name, tc.Function.Arguments, out)
            msgs = append(msgs, llm.Message{Role: "tool",
                ToolCallID: tc.ID, Content: out})
        }
    }
    return errors.New("zu viele tool-runden")
}
EOF

Plus main.go with three modes: streaming (default), -triage and -tools.

cat > cmd/ask/main.go <<'EOF'
// ask: questions to a local LLM – streamed, as JSON or with tools.
package main

import (
    "context"
    "flag"
    "fmt"
    "os"
    "os/signal"
    "strings"

    "example.com/ask/internal/llm"
)

func main() {
    triage := flag.Bool("triage", false, "Antwort als JSON (severity, summary, action)")
    agent := flag.Bool("tools", false, "Modell darf lokale Tools aufrufen")
    flag.Parse()
    q := strings.Join(flag.Args(), " ")
    if q == "" {
        fmt.Fprintln(os.Stderr, "usage: ask [-triage|-tools] <frage>")
        os.Exit(2)
    }
    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
    defer stop()
    c := llm.FromEnv()

    var err error
    switch {
    case *triage:
        err = runTriage(ctx, c, q)
    case *agent:
        err = runTools(ctx, c, q)
    default:
        msgs := []llm.Message{{Role: "user", Content: q}}
        err = c.Stream(ctx, msgs, func(s string) { fmt.Print(s) })
        fmt.Println() // Zeilenende nach dem Stream
    }
    if err != nil {
        fmt.Fprintln(os.Stderr, "ask:", err)
        os.Exit(1)
    }
}
EOF
go vet ./... && go build -o ask ./cmd/ask
./ask "Was ist ein Kubernetes-Pod? Antworte in einem Satz."
./ask -triage "kubelet: eviction manager: disk pressure on node worker-3, 97% used"
./ask -tools "Wie viel Speicher ist unter / frei?"

Expected (text varies, values depend on your Mac):

Ein **Kubernetes-Pod** ist die kleinste, ausgeführte Einheit eines Kontainers,
die statisch oder dynamisch aus mehreren Containern besteht, ...
{
  "severity": "high",
  "summary": "Disk Pressure - Node Disk Full Risk",
  "action": "• Check root and tmpfs utilization on **worker-3** (~97% used). ..."
}
-> disk_free({"path":"/"}) = {"path":"/","free_gib":17.8,"free_pct":7.8}
Unter dem Pfad `/` sind etwa **17,8 Gigabyte** Speicherplatz frei. Das entspricht
rund **7,8 %** des genutzten Speicherplatzes.

Why? With streaming, the words appear one after another instead of all at once after several seconds. The line with -> goes to stderr: you see what the model calls, while the actual answer stays pipeable on stdout.

Security: Tool call arguments are second-hand user input (prompt injection). Only tools from a fixed list, read-only, validate parameters – never exec.Command with model arguments.

Save your progress? Sign up for free

Drill 5: Embeddings and cosine search

An embedding is a vector that encodes the meaning of a text. Similar texts point in similar directions. Pull the small embedding model (about 45 MB):

ollama pull all-minilm
cat > internal/llm/embed.go <<'EOF'
package llm

import (
    "context"
    "encoding/json"
    "fmt"
)

// Embed returns one vector per input text (same order as input).
func (c *Client) Embed(ctx context.Context, model string, input []string) (
    [][]float64, error) {
    resp, err := c.post(ctx, "/embeddings",
        map[string]any{"model": model, "input": input})
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    var out struct {
        Data []struct {
            Index     int       `json:"index"`
            Embedding []float64 `json:"embedding"`
        } `json:"data"`
    }
    if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
        return nil, fmt.Errorf("embeddings lesen: %w", err)
    }
    if len(out.Data) != len(input) {
        return nil, fmt.Errorf("%d vektoren für %d texte", len(out.Data), len(input))
    }
    vecs := make([][]float64, len(input))
    for _, d := range out.Data {
        vecs[d.Index] = d.Embedding
    }
    return vecs, nil
}
EOF
cat > internal/search/search.go <<'EOF'
// Package search finds the most similar texts via cosine similarity.
package search

import (
    "math"
    "sort"
)

type Doc struct {
    Source, Text string
    Vec          []float64
}

type Hit struct {
    Doc
    Score float64
}

// Cosine returns 1 for the same direction, 0 for orthogonal vectors.
func Cosine(a, b []float64) float64 {
    var dot, na, nb float64
    for i := range a {
        dot += a[i] * b[i]
        na += a[i] * a[i]
        nb += b[i] * b[i]
    }
    if na == 0 || nb == 0 {
        return 0
    }
    return dot / (math.Sqrt(na) * math.Sqrt(nb))
}

// TopK returns the k documents with the highest similarity to q.
func TopK(docs []Doc, q []float64, k int) []Hit {
    hits := make([]Hit, 0, len(docs))
    for _, d := range docs {
        hits = append(hits, Hit{d, Cosine(d.Vec, q)})
    }
    sort.Slice(hits, func(i, j int) bool { return hits[i].Score > hits[j].Score })
    return hits[:min(k, len(hits))]
}
EOF
cat > internal/search/search_test.go <<'EOF'
package search

import (
    "math"
    "testing"
)

func TestTopK(t *testing.T) {
    docs := []Doc{{Source: "a", Vec: []float64{1, 0}},
        {Source: "b", Vec: []float64{0.7, 0.7}}, {Source: "c", Vec: []float64{0, 1}}}
    got := TopK(docs, []float64{0, 2}, 2)
    if len(got) != 2 || got[0].Source != "c" || got[1].Source != "b" {
        t.Fatalf("got %+v", got)
    }
    if math.Abs(got[0].Score-1) > 1e-9 {
        t.Errorf("gleiche Richtung: Score %v, want 1", got[0].Score)
    }
    if Cosine([]float64{0, 0}, []float64{1, 1}) != 0 {
        t.Error("Nullvektor muss 0 liefern")
    }
}
EOF
go test ./internal/...

Expected:

ok      example.com/ask/internal/llm    0.208s
ok      example.com/ask/internal/search 0.142s
?       example.com/ask/internal/tools  [no test files]

Four mini runbooks as the search corpus:

cat > docs/disk-voll.md <<'EOF'
# Runbook: Disk voll
Wenn ein Node DiskPressure meldet, zuerst ungenutzte Images löschen:
crictl rmi --prune. Danach Logs unter /var/log prüfen und rotieren.
EOF
cat > docs/crashloop.md <<'EOF'
# Runbook: CrashLoopBackOff
Startet ein Container immer wieder neu, die Logs des vorherigen Laufs lesen:
kubectl logs <pod> --previous. Häufige Ursachen: fehlende Env-Variable,
falsches Secret, Liveness-Probe zu streng.
EOF
cat > docs/zertifikat.md <<'EOF'
# Runbook: Zertifikat abgelaufen
Bei TLS-Fehlern "certificate has expired" das Ablaufdatum prüfen:
openssl x509 -enddate -noout -in tls.crt. cert-manager erneuert per
kubectl annotate certificate <name> cert-manager.io/issue-temporary-certificate.
EOF
cat > docs/vault-sealed.md <<'EOF'
# Runbook: OpenBao/Vault sealed
Nach einem Neustart ist der Server versiegelt. Status mit bao status prüfen,
dann mit den Unseal-Keys entsiegeln oder Auto-Unseal (KMS/Transit) einrichten.
EOF
cat > cmd/docsearch/main.go <<'EOF'
// docsearch: semantic search over Markdown runbooks with embeddings.
package main

import (
    "context"
    "flag"
    "fmt"
    "os"
    "path/filepath"
    "strings"

    "example.com/ask/internal/llm"
    "example.com/ask/internal/search"
)

func main() {
    dir := flag.String("dir", "docs", "Verzeichnis mit *.md")
    model := flag.String("model", "all-minilm", "Embedding-Modell")
    k := flag.Int("k", 2, "Anzahl Treffer")
    flag.Parse()
    q := strings.Join(flag.Args(), " ")
    if q == "" {
        fmt.Fprintln(os.Stderr, "usage: docsearch [-dir docs] [-k 2] <frage>")
        os.Exit(2)
    }
    ctx, c := context.Background(), llm.FromEnv()
    hits, err := find(ctx, c, *dir, *model, q, *k)
    if err != nil {
        fmt.Fprintln(os.Stderr, "docsearch:", err)
        os.Exit(1)
    }
    for _, h := range hits {
        title, _, _ := strings.Cut(h.Text, "\n")
        fmt.Printf("%.3f  %-16s %s\n", h.Score, h.Source, title)
    }
}

// find embeds the question and the documents and returns the k best hits.
func find(ctx context.Context, c *llm.Client, dir, model, q string, k int) (
    []search.Hit, error) {
    files, err := filepath.Glob(filepath.Join(dir, "*.md"))
    if err != nil || len(files) == 0 {
        return nil, fmt.Errorf("keine *.md in %s", dir)
    }
    var docs []search.Doc
    texts := []string{q} // Frage zuerst: ein einziger Embedding-Aufruf
    for _, f := range files {
        b, err := os.ReadFile(f)
        if err != nil {
            return nil, err
        }
        docs = append(docs, search.Doc{Source: filepath.Base(f), Text: string(b)})
        texts = append(texts, string(b))
    }
    vecs, err := c.Embed(ctx, model, texts)
    if err != nil {
        return nil, err
    }
    for i := range docs {
        docs[i].Vec = vecs[i+1]
    }
    return search.TopK(docs, vecs[0], k), nil
}
EOF
go build -o docsearch ./cmd/docsearch
./docsearch "pod startet ständig neu"
./docsearch -k 1 "TLS certificate expired"

Expected (scores vary slightly):

0.499  crashloop.md     # Runbook: CrashLoopBackOff
0.316  vault-sealed.md  # Runbook: OpenBao/Vault sealed
0.738  zertifikat.md    # Runbook: Zertifikat abgelaufen

Why? Not a single word of “pod startet ständig neu” (“pod keeps restarting”) appears verbatim in the runbook – the search finds it by meaning. all-minilm is trained on English; for German texts a multilingual model pays off (e.g. bge-m3). From a few thousand documents on, the vectors belong in a database (e.g. PostgreSQL with pgvector).

Save your progress? Sign up for free

Drill 6: MCP server with the Go SDK

MCP (Model Context Protocol) is JSON-RPC over stdio or HTTP. The SDK generates the JSON Schema from your Go structs.

go get github.com/modelcontextprotocol/[email protected]
cat > cmd/ops-mcp/main.go <<'EOF'
// ops-mcp: MCP server (stdio) with ops tools for AI assistants.
package main

import (
    "context"
    "log"
    "os"

    "example.com/ask/internal/tools"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

type diskIn struct {
    Path string `json:"path" jsonschema:"Pfad, z. B. / oder /var"`
}

func diskFree(_ context.Context, _ *mcp.CallToolRequest, in diskIn) (
    *mcp.CallToolResult, tools.Disk, error) {
    d, err := tools.DiskFree(in.Path)
    return nil, d, err // Fehler landen als isError beim Client
}

func newServer() *mcp.Server {
    s := mcp.NewServer(&mcp.Implementation{Name: "ops-mcp", Version: "v0.1.0"}, nil)
    mcp.AddTool(s, &mcp.Tool{
        Name:        "disk_free",
        Description: "Freier Speicherplatz eines Pfads auf diesem Rechner",
    }, diskFree)
    return s
}

func main() {
    log.SetOutput(os.Stderr) // stdout gehört dem JSON-RPC-Protokoll
    if err := newServer().Run(context.Background(), &mcp.StdioTransport{}); err != nil {
        log.Fatal(err)
    }
}
EOF

The test connects client and server in memory – no process, no pipes:

cat > cmd/ops-mcp/main_test.go <<'EOF'
package main

import (
    "context"
    "testing"

    "github.com/modelcontextprotocol/go-sdk/mcp"
)

func TestDiskFreeTool(t *testing.T) {
    ctx := context.Background()
    st, ct := mcp.NewInMemoryTransports()
    if _, err := newServer().Connect(ctx, st, nil); err != nil {
        t.Fatal(err)
    }
    c := mcp.NewClient(&mcp.Implementation{Name: "test", Version: "v0"}, nil)
    cs, err := c.Connect(ctx, ct, nil)
    if err != nil {
        t.Fatal(err)
    }
    defer cs.Close()

    tests := []struct {
        path    string
        wantErr bool
    }{{"/", false}, {"/gibt/es/nicht", true}}
    for _, tt := range tests {
        res, err := cs.CallTool(ctx, &mcp.CallToolParams{
            Name: "disk_free", Arguments: map[string]any{"path": tt.path}})
        if err != nil {
            t.Fatal(err)
        }
        if res.IsError != tt.wantErr {
            t.Errorf("%s: IsError=%v", tt.path, res.IsError)
        }
        t.Logf("%s -> %v", tt.path, res.Content[0].(*mcp.TextContent).Text)
    }
}
EOF
go mod tidy
go test -v ./cmd/ops-mcp 2>&1 | grep -E 'main_test|ok'

Expected (values depend on your Mac):

    main_test.go:36: / -> {"free_gib":17.3,"free_pct":7.6,"path":"/"}
    main_test.go:36: /gibt/es/nicht -> statfs /gibt/es/nicht: no such file or directory
ok      example.com/ask/cmd/ops-mcp 0.163s

And live over stdio, the way an AI client starts the server:

go build -o ops-mcp ./cmd/ops-mcp
rpc() { jq -nc --argjson id "$1" --arg m "$2" --argjson p "$3" \
  '{jsonrpc:"2.0", id:$id, method:$m, params:$p}'; }
{
  rpc 1 initialize '{"protocolVersion":"2025-06-18","capabilities":{},
    "clientInfo":{"name":"bash","version":"0"}}'
  echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
  rpc 2 tools/list '{}'
  rpc 3 tools/call '{"name":"disk_free","arguments":{"path":"/"}}'
  sleep 1
} | ./ops-mcp | jq -c '.result.serverInfo
  // .result.tools[0].inputSchema.properties // .result.structuredContent'

Expected:

{"name":"ops-mcp","version":"v0.1.0"}
{"path":{"type":"string","description":"Pfad, z. B. / oder /var"}}
{"free_gib":17.8,"free_pct":7.8,"path":"/"}

Why? Only JSON-RPC may appear on stdout – that is why the server logs to stderr. The sleep 1 keeps stdin open until the responses are in; when stdin closes, the server shuts down cleanly.

Save your progress? Sign up for free

Drill 7: The tools are done

go build -o bin/ ./cmd/...
ls bin
./bin/ask "Nenne drei kubectl-Befehle zur Fehlersuche als nummerierte Liste, \
ohne Erklärung, ohne Markdown."
LLM_MODEL=gibtsnicht ./bin/ask hallo; echo "exit=$?"

Expected (text varies, long line wrapped):

ask
docsearch
ops-mcp
1. kubectl logs <pod-identifikator> --previous
2. kubectl describe pod <pod-identifikator>
3. kubectl get events --sort-by='.metadata.creationTimestamp'

ask: /chat/completions: 404 Not Found: {"error":{"message":"model 'gibtsnicht'
  not found","type":"not_found_error","param":null,"code":null}}
exit=1

Why? go build -o bin/ ./cmd/... builds all three binaries at once. post passes the server’s error message through unchanged – so you see immediately that the model is missing. Answers from a 3B model are suggestions, not commands: sometimes it writes Kontainer, sometimes it invents flags.

You register the MCP server in your AI client; most clients use this format (adjust the path):

{
  "mcpServers": {
    "ops-mcp": { "command": "/Users/DU/go-lab/tag12-ask/bin/ops-mcp" }
  }
}

Tip: To use a cloud API, you only change the environment, e.g. LLM_BASE_URL=https://api.mistral.ai/v1, LLM_API_KEY="$MISTRAL_API_KEY" and LLM_MODEL=mistral-small-latest – the key comes from your shell, never from the code.

Save your progress? Sign up for free

Checkpoint

#!/usr/bin/env bash
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
cd ~/go-lab/tag12-ask
check "gofmt sauber" "test -z \"\$(gofmt -l .)\""
check "go vet" "go vet ./..."
check "golangci-lint" "~/go-lab/bin/lint run ./..."
check "Tests mit -race" "go test -race -count=1 ./..."
check "drei Binaries" "test -x bin/ask -a -x bin/docsearch -a -x bin/ops-mcp"
check "Streaming live" "./bin/ask 'Antworte nur mit OK' | grep -qi ok"
check "Triage ist JSON" "./bin/ask -triage 'disk 99% voll' | jq -e .severity"
check "docsearch findet Runbook" \
  "./bin/docsearch -k 1 'certificate expired' | grep -q zertifikat"
check "kein Key im Code" "! grep -rn 'sk-[A-Za-z0-9]\{20,\}' --include=*.go ."

Expected:

✔ gofmt sauber
✔ go vet
✔ golangci-lint
✔ Tests mit -race
✔ drei Binaries
✔ Streaming live
✔ Triage ist JSON
✔ docsearch findet Runbook
✔ kein Key im Code

Challenge

Turn docsearch into a small RAG: with -answer, the chat model should answer the question – using only the runbooks it found as context.

Hint: find already returns the hits; send their texts along as a system message via c.Chat.

Solution

In cmd/docsearch/main.go, add after the flag k:

    answer := flag.Bool("answer", false, "Antwort aus den Treffern erzeugen")

At the end of main, after the output loop:

    if *answer {
        if err := rag(ctx, c, q, hits); err != nil {
            fmt.Fprintln(os.Stderr, "docsearch:", err)
            os.Exit(1)
        }
    }

And the new function:

// rag lets the model answer only with the runbooks it found.
func rag(ctx context.Context, c *llm.Client, q string, hits []search.Hit) error {
    var sb strings.Builder
    for _, h := range hits {
        sb.WriteString(h.Text + "\n")
    }
    m, err := c.Chat(ctx, llm.Request{Messages: []llm.Message{
        {Role: "system", Content: "Antworte knapp in 2 Sätzen, nur mit " +
            "diesen Runbooks:\n" + sb.String()},
        {Role: "user", Content: q},
    }})
    if err != nil {
        return err
    }
    fmt.Println("\n" + m.Content)
    return nil
}
go build -o bin/ ./cmd/... && ./bin/docsearch -k 1 -answer \
  "pod startet ständig neu, was tun?"

Expected (text varies):

0.409  crashloop.md     # Runbook: CrashLoopBackOff

Prüfe zuerst die fehlenden oder falschen **Env-Variablen/Secrets** im Pod oder
Container (z. B. mit `kubectl describe pod`). Lies die Logs des **vorherigen
Laufs** mit: `kubectl logs <pod> --previous`.

Clean up when you no longer need the embeddings: ollama rm all-minilm.

Save your progress? Sign up for free

Enterprise Note

  • Keys come from a secret store or OpenBao, never from env files in the repo; route outgoing traffic to cloud LLMs through a gateway with tenants, rate limiting and an audit log.
  • Streaming needs per-read timeouts and cancellation via context; proxies (nginx, Ingress) must not buffer SSE.
  • Always validate structured output and count failed attempts (metric); for critical workflows, keep a human in the loop.
  • MCP servers run with the client’s privileges: read-only tools only, allowlists, no shell; over HTTP only with auth (OAuth) and TLS.
  • RAG in production: persist vectors (e.g. pgvector), version documents, carry the source’s access rights over to the search.