Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<kagent-tools-fullname>-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.
Expand Down
21 changes: 21 additions & 0 deletions cmd/tools_output_schema_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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")
}
})
}
}
10 changes: 6 additions & 4 deletions pkg/k8s/k8s.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
64 changes: 56 additions & 8 deletions pkg/k8s/k8s_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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) {
Expand Down
10 changes: 6 additions & 4 deletions pkg/prometheus/prometheus.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
}
70 changes: 62 additions & 8 deletions pkg/prometheus/prometheus_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,77 @@ import (
"context"
"io"
"net/http"
"net/http/httptest"
"os"
"strings"
"testing"
"time"

sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)

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) {
Expand Down