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 changeLLM_BASE_URL,LLM_API_KEY,LLM_MODEL). - No SDK:
net/http,encoding/jsonand abufio.Scannerfor 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
EOFExpected:
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.txtExpected (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")
}
EOFThe 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/llmExpected (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
}
EOFcat > 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 -2Expected:
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 }
EOFThe 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")
}
EOFPlus 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.Commandwith 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-minilmcat > 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.
EOFcat > 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)
}
}
EOFThe 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"andLLM_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.