diff --git a/README.md b/README.md index 1ad9d66..54580f4 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,21 @@ See [Using kagent-tools as a kagent 1.x skills bundle](docs/kagent-skills.md). For a quickstart guide on how to run KAgent tools using AgentGateway, please refer to the [Quickstart Guide](docs/quickstart.md). +### Optional LLM-backed tools + +The server only advertises LLM-backed tools when their configuration is present at startup: + +- `prometheus_promql_tool` requires a non-empty `OPENAI_API_KEY` environment variable. + With the Helm chart, create a Secret named `-openai` in the release + namespace with an `OPENAI_API_KEY` key. The chart references this optional Secret but does + not create it. Restart the server after adding the key. +- `k8s_generate_resource` requires a non-nil `llms.Model` passed to `k8s.RegisterTools` by + Go callers. The CLI does not configure this model, so it does not advertise this tool, + even when `OPENAI_API_KEY` is set. + +Other Kubernetes and Prometheus tools do not require LLM configuration. These requirements +also apply in read-only mode; configuring an LLM does not enable write tools. + ## Architecture The Go tools are implemented as a single MCP server that exposes all available tools through the MCP protocol. diff --git a/cmd/tools_output_schema_test.go b/cmd/tools_output_schema_test.go index d0e5817..ae209d8 100644 --- a/cmd/tools_output_schema_test.go +++ b/cmd/tools_output_schema_test.go @@ -70,3 +70,24 @@ func TestEveryToolHasValidOutputSchema(t *testing.T) { } require.NotEmpty(t, checked, "expected the server to advertise tools") } + +func TestRegisterMCPWithOptionalLLMConfiguration(t *testing.T) { + for _, apiKey := range []string{"", "test-key"} { + name := "without OpenAI key" + if apiKey != "" { + name = "with OpenAI key" + } + t.Run(name, func(t *testing.T) { + t.Setenv("OPENAI_API_KEY", apiKey) + tools := registeredTools(t) + require.Contains(t, tools, "k8s_get_resources") + require.Contains(t, tools, "prometheus_query_tool") + require.NotContains(t, tools, "k8s_generate_resource", "the CLI does not configure a Kubernetes LLM") + if apiKey == "" { + require.NotContains(t, tools, "prometheus_promql_tool") + } else { + require.Contains(t, tools, "prometheus_promql_tool") + } + }) + } +} diff --git a/pkg/k8s/k8s.go b/pkg/k8s/k8s.go index 5ca121d..326c08f 100644 --- a/pkg/k8s/k8s.go +++ b/pkg/k8s/k8s.go @@ -920,10 +920,12 @@ func RegisterTools(s *sdkmcp.Server, llm llms.Model, kubeconfig string, readOnly Description: "Wait for a condition on Kubernetes resources (kubectl wait). Blocks until the condition is met or the timeout elapses.", }, k8sTool.handleKubectlWait) - mcp.AddTool(s, "k8s", &sdkmcp.Tool{ - Name: "k8s_generate_resource", - Description: fmt.Sprintf("Generate a Kubernetes resource YAML from a description. Supported resource_type values: %s", strings.Join(slices.Collect(resourceTypes), ", ")), - }, k8sTool.handleGenerateResource) + if llm != nil { + mcp.AddTool(s, "k8s", &sdkmcp.Tool{ + Name: "k8s_generate_resource", + Description: fmt.Sprintf("Generate a Kubernetes resource YAML from a description. Supported resource_type values: %s", strings.Join(slices.Collect(resourceTypes), ", ")), + }, k8sTool.handleGenerateResource) + } // Write tools - only registered when write operations are enabled if !readOnly { diff --git a/pkg/k8s/k8s_test.go b/pkg/k8s/k8s_test.go index 6d6eab6..b7cc672 100644 --- a/pkg/k8s/k8s_test.go +++ b/pkg/k8s/k8s_test.go @@ -3,7 +3,9 @@ package k8s import ( "context" "net/http" + "slices" "testing" + "time" "github.com/kagent-dev/tools/internal/cmd" sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp" @@ -13,14 +15,60 @@ import ( ) func TestRegisterTools(t *testing.T) { - t.Run("read-write", func(t *testing.T) { - s := sdkmcp.NewServer(&sdkmcp.Implementation{Name: "test", Version: "v0.0.1"}, nil) - RegisterTools(s, nil, "", false) - }) - t.Run("read-only", func(t *testing.T) { - s := sdkmcp.NewServer(&sdkmcp.Implementation{Name: "test", Version: "v0.0.1"}, nil) - RegisterTools(s, nil, "/tmp/kubeconfig", true) - }) + for _, testCase := range []struct { + name string + readOnly bool + withLLM bool + }{ + {name: "read-write without LLM"}, + {name: "read-only without LLM", readOnly: true}, + {name: "read-write with LLM", withLLM: true}, + {name: "read-only with LLM", readOnly: true, withLLM: true}, + } { + t.Run(testCase.name, func(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + server := sdkmcp.NewServer(&sdkmcp.Implementation{Name: "test", Version: "test"}, nil) + model := newMockLLM(&llms.ContentResponse{ + Choices: []*llms.ContentChoice{{Content: "generated resource"}}, + }, nil) + var configuredModel llms.Model + if testCase.withLLM { + configuredModel = model + } + RegisterTools(server, configuredModel, "/tmp/kubeconfig", testCase.readOnly) + serverTransport, clientTransport := sdkmcp.NewInMemoryTransports() + go func() { _ = server.Run(ctx, serverTransport) }() + client := sdkmcp.NewClient(&sdkmcp.Implementation{Name: "test-client", Version: "test"}, nil) + session, err := client.Connect(ctx, clientTransport, nil) + require.NoError(t, err) + defer func() { _ = session.Close() }() + + var toolNames []string + for tool, err := range session.Tools(ctx, nil) { + require.NoError(t, err) + toolNames = append(toolNames, tool.Name) + } + require.Contains(t, toolNames, "k8s_get_resources") + assert.Equal(t, !testCase.readOnly, slices.Contains(toolNames, "k8s_scale")) + assert.Equal(t, testCase.withLLM, slices.Contains(toolNames, "k8s_generate_resource")) + result, err := session.CallTool(ctx, &sdkmcp.CallToolParams{ + Name: "k8s_generate_resource", + Arguments: generateResourceInput{ + ResourceType: "istio_auth_policy", ResourceDescription: "strict mTLS", + }, + }) + if !testCase.withLLM { + require.Error(t, err, "unconfigured tool must not be callable") + assert.Zero(t, model.called) + return + } + require.NoError(t, err) + require.False(t, result.IsError) + assert.Equal(t, "generated resource", getResultText(result)) + assert.Equal(t, 1, model.called) + }) + } } func TestNewK8sToolWithConfig(t *testing.T) { diff --git a/pkg/prometheus/prometheus.go b/pkg/prometheus/prometheus.go index f025420..10e5570 100644 --- a/pkg/prometheus/prometheus.go +++ b/pkg/prometheus/prometheus.go @@ -350,8 +350,10 @@ func RegisterTools(s *sdkmcp.Server, readOnly bool) { Description: "Get all Prometheus targets and their status", }, handlePrometheusTargetsQueryTool) - mcp.AddTool(s, "prometheus", &sdkmcp.Tool{ - Name: "prometheus_promql_tool", - Description: "Generate a PromQL query", - }, handlePromql) + if os.Getenv("OPENAI_API_KEY") != "" { + mcp.AddTool(s, "prometheus", &sdkmcp.Tool{ + Name: "prometheus_promql_tool", + Description: "Generate a PromQL query", + }, handlePromql) + } } diff --git a/pkg/prometheus/prometheus_test.go b/pkg/prometheus/prometheus_test.go index 5447ab7..83f989e 100644 --- a/pkg/prometheus/prometheus_test.go +++ b/pkg/prometheus/prometheus_test.go @@ -4,8 +4,11 @@ import ( "context" "io" "net/http" + "net/http/httptest" + "os" "strings" "testing" + "time" sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp" "github.com/stretchr/testify/assert" @@ -13,14 +16,65 @@ import ( ) func TestRegisterTools(t *testing.T) { - t.Run("read-write", func(t *testing.T) { - s := sdkmcp.NewServer(&sdkmcp.Implementation{Name: "test", Version: "v0.0.1"}, nil) - RegisterTools(s, false) - }) - t.Run("read-only", func(t *testing.T) { - s := sdkmcp.NewServer(&sdkmcp.Implementation{Name: "test", Version: "v0.0.1"}, nil) - RegisterTools(s, true) - }) + for _, testCase := range []struct { + name string + apiKey *string + }{ + {name: "unset key"}, + {name: "empty key", apiKey: new("")}, + {name: "configured key", apiKey: new("test-key")}, + } { + t.Run(testCase.name, func(t *testing.T) { + t.Setenv("OPENAI_API_KEY", "") + if testCase.apiKey == nil { + require.NoError(t, os.Unsetenv("OPENAI_API_KEY")) + } else { + t.Setenv("OPENAI_API_KEY", *testCase.apiKey) + } + modelServer := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) { + assert.Equal(t, "/v1/chat/completions", request.URL.Path) + assert.Equal(t, "Bearer test-key", request.Header.Get("Authorization")) + writer.Header().Set("Content-Type", "application/json") + _, _ = io.WriteString(writer, `{"choices":[{"message":{"role":"assistant","content":"up"},"finish_reason":"stop"}]}`) + })) + defer modelServer.Close() + t.Setenv("OPENAI_BASE_URL", modelServer.URL+"/v1") + + for _, readOnly := range []bool{false, true} { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + server := sdkmcp.NewServer(&sdkmcp.Implementation{Name: "test", Version: "test"}, nil) + RegisterTools(server, readOnly) + serverTransport, clientTransport := sdkmcp.NewInMemoryTransports() + go func() { _ = server.Run(ctx, serverTransport) }() + client := sdkmcp.NewClient(&sdkmcp.Implementation{Name: "test-client", Version: "test"}, nil) + session, err := client.Connect(ctx, clientTransport, nil) + require.NoError(t, err) + defer func() { _ = session.Close() }() + var toolNames []string + for tool, err := range session.Tools(ctx, nil) { + require.NoError(t, err) + toolNames = append(toolNames, tool.Name) + } + expectedTools := []string{"prometheus_query_tool", "prometheus_query_range_tool", "prometheus_label_names_tool", "prometheus_targets_tool"} + configured := testCase.apiKey != nil && *testCase.apiKey != "" + if configured { + expectedTools = append(expectedTools, "prometheus_promql_tool") + } + assert.ElementsMatch(t, expectedTools, toolNames) + result, err := session.CallTool(ctx, &sdkmcp.CallToolParams{ + Name: "prometheus_promql_tool", Arguments: promqlInput{QueryDescription: "target availability"}, + }) + if !configured { + require.Error(t, err, "unconfigured tool must not be callable") + continue + } + require.NoError(t, err) + require.False(t, result.IsError, getResultText(result)) + assert.Equal(t, "up", getResultText(result)) + } + }) + } } func TestPrometheusInputValidation(t *testing.T) {