Skip to content
Merged
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
19 changes: 17 additions & 2 deletions internal/stackql/mcpbackend/mcp_reverse_proxy_backend_service.go
Original file line number Diff line number Diff line change
Expand Up @@ -184,8 +184,23 @@ func (b *stackqlMCPReverseProxyService) query(ctx context.Context, query string,
return finalRows, nil
}

func (b *stackqlMCPReverseProxyService) RunQueryJSON(ctx context.Context, input dto.QueryJSONInput) ([]map[string]interface{}, error) {
return b.query(ctx, input.SQL, input.RowLimit)
// RunQueryJSON returns rows only: this backend reaches the engine over the
// PostgreSQL wire protocol via database/sql, which carries no channel for the
// engine's per-statement messages (they surface on the backing server's
// notice/stderr streams). See content/instructions/06-errors.md.
func (b *stackqlMCPReverseProxyService) RunQueryJSON(
ctx context.Context,
input dto.QueryJSONInput,
) (dto.QueryResultDTO, error) {
rows, err := b.query(ctx, input.SQL, input.RowLimit)
if err != nil {
return dto.QueryResultDTO{}, err
}
if rows == nil {
// SDK schema validation on QueryResultDTO.Rows rejects null.
rows = []map[string]any{}
}
return dto.QueryResultDTO{Rows: rows}, nil
}

func (b *stackqlMCPReverseProxyService) DescribeMethod(ctx context.Context, hI dto.HierarchyInput) ([]map[string]interface{}, error) {
Expand Down
64 changes: 45 additions & 19 deletions internal/stackql/mcpbackend/mcp_service_stackql.go
Original file line number Diff line number Diff line change
Expand Up @@ -345,16 +345,22 @@ func (b *stackqlMCPService) ServerInfo(_ context.Context, _ any) (dto.ServerInfo
}, nil
}

func (b *stackqlMCPService) RunQueryJSON(ctx context.Context, input dto.QueryJSONInput) ([]map[string]interface{}, error) {
func (b *stackqlMCPService) RunQueryJSON(ctx context.Context, input dto.QueryJSONInput) (dto.QueryResultDTO, error) {
q, qErr := b.interrogator.GetQueryJSON(input)
if qErr != nil {
return nil, qErr
return dto.QueryResultDTO{}, qErr
}
rows, messages, extractErr := b.withContext(ctx).extractQueryResults(q, input.RowLimit)
if extractErr != nil {
return dto.QueryResultDTO{}, extractErr
}
return b.runPreprocessedQueryJSON(ctx, q, input.RowLimit)
return dto.QueryResultDTO{Rows: rows, Messages: messages}, nil
}

func (b *stackqlMCPService) runPreprocessedQueryJSON(ctx context.Context, query string, rowLimit int) ([]map[string]interface{}, error) {
results, extractErr := b.withContext(ctx).extractQueryResults(query, rowLimit)
// Metadata tools (SHOW / DESCRIBE / EXPLAIN) keep their rows-only shape;
// per-statement messages surface only through RunQueryJSON.
results, _, extractErr := b.withContext(ctx).extractQueryResults(query, rowLimit)
if extractErr != nil {
return nil, extractErr
}
Expand Down Expand Up @@ -456,7 +462,7 @@ func (b *stackqlMCPService) ValidateQuery(ctx context.Context, query string) ([]

func (b *stackqlMCPService) execQuery(query string) (map[string]any, error) {
rv := map[string]any{}
r, ok := b.applyQuery(query)
r, _, ok := b.applyQuery(query)
if !ok {
return rv, fmt.Errorf("failed to extract query results")
}
Expand Down Expand Up @@ -488,39 +494,59 @@ func (h strictHandlerContext) NewClientContext() handler.HandlerContext {
return strictHandlerContext{h.HandlerContext.NewClientContext()}
}

func (b *stackqlMCPService) getUpdatedHandlerCtx(query string) (handler.HandlerContext, error) {
func (b *stackqlMCPService) getUpdatedHandlerCtx(
query string,
) (handler.HandlerContext, *statementMessageCapture, error) {
clonedCtx := b.handlerCtx.Clone()
clonedCtx.SetRawQuery(query)
return strictHandlerContext{clonedCtx}, nil
}

func (b *stackqlMCPService) applyQuery(query string) ([]internaldto.ExecutorOutput, bool) {
updatedCtx, ctxErr := b.getUpdatedHandlerCtx(query)
// The engine writes per-statement diagnostics (eg upstream 404 bodies for
// reads presented as empty tables) to the context's OutErrFile. Tee the
// clone's writer through a bounded capture so those diagnostics can be
// attributed to exactly this statement; the operator-visible stream is
// unchanged. Clone() copies the writer field by value, so this never
// leaks to the parent context or to concurrent statements.
capture := newStatementMessageCapture()
if existing := clonedCtx.GetOutErrFile(); existing != nil {
clonedCtx.SetOutErrFile(io.MultiWriter(existing, capture))
} else {
clonedCtx.SetOutErrFile(capture)
}
return strictHandlerContext{clonedCtx}, capture, nil
}

func (b *stackqlMCPService) applyQuery(query string) ([]internaldto.ExecutorOutput, *statementMessageCapture, bool) {
updatedCtx, capture, ctxErr := b.getUpdatedHandlerCtx(query)
if ctxErr != nil {
return nil, false
return nil, nil, false
}
r, ok := b.txnOrchestrator.ProcessQueryOrQueries(updatedCtx)
return r, ok
return r, capture, ok
}

func (b *stackqlMCPService) extractQueryResults(query string, rowLimit int) ([]map[string]interface{}, error) {
r, ok := b.applyQuery(query)
//nolint:gocognit // single bounded drain loop plus error classification
func (b *stackqlMCPService) extractQueryResults(
query string,
rowLimit int,
) ([]map[string]interface{}, []string, error) {
r, capture, ok := b.applyQuery(query)
if !ok {
return nil, fmt.Errorf("failed to extract query results")
return nil, nil, fmt.Errorf("failed to extract query results")
}
// Initialise as empty (not nil) so a zero-row result survives downstream
// JSON-array schema validation on QueryResultDTO.Rows. This pairs with
// fix 1 (returning ok regardless of len(rv)) so empty results render as
// "**no results**" rather than failing extraction.
rv := []map[string]interface{}{}
rowCount := 0
var respMessages []string
for _, resp := range r {
if respErr := resp.GetError(); respErr != nil {
// Propagate the statement error (with upstream HTTP status
// classification where available) rather than collapsing it
// into an indistinct empty result (issue #670).
return nil, classifyBackendError(respErr, queryProviderName(query))
return nil, nil, classifyBackendError(respErr, queryProviderName(query))
}
respMessages = append(respMessages, resp.GetMessages()...)
// PrepareResultSet emits a nil SQLResult when RowMap is empty (eg
// REGISTRY LIST against an empty registry). That's a zero-row
// result, not an extraction failure: skip the stream and continue.
Expand All @@ -531,10 +557,10 @@ func (b *stackqlMCPService) extractQueryResults(query string, rowLimit int) ([]m
var drainOK bool
rv, rowCount, drainOK = drainSQLRowStream(sqlRowStream, rv, rowCount, rowLimit)
if !drainOK {
return nil, fmt.Errorf("failed to extract query results")
return nil, nil, fmt.Errorf("failed to extract query results")
}
}
return rv, nil
return rv, capture.drain(respMessages), nil
}

// drainSQLRowStream reads `stream` to EOF (or until rowLimit is reached),
Expand Down
110 changes: 110 additions & 0 deletions internal/stackql/mcpbackend/statement_message_capture.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
package mcpbackend

import (
"fmt"
"strings"
"sync"
)

// Bounds on per-statement engine message capture: an upstream response body
// can be arbitrarily large (eg a whole HTML page), so each message is
// truncated and the number of retained messages is capped, with a marker
// reporting anything cut.
const (
maxCapturedMessages = 24
maxCapturedMessageLen = 2048
)

const messageTruncationMarker = " ... [message truncated]"

// statementMessageCapture is a bounded io.Writer installed as the OutErrFile
// of a per-statement handler context clone, so that engine-emitted
// diagnostics (eg "http response status code: 404, response body is nil")
// are attributed to exactly one statement rather than interleaved on a
// process-wide stream. Writes are line-split: each newline-terminated line
// becomes one message.
type statementMessageCapture struct {
mu sync.Mutex
residual string
residualTruncated bool
messages []string
suppressed int
}

func newStatementMessageCapture() *statementMessageCapture {
return &statementMessageCapture{}
}

// Write never fails: diagnostics must not alter statement execution.
func (c *statementMessageCapture) Write(p []byte) (int, error) {
c.mu.Lock()
defer c.mu.Unlock()
data := c.residual + string(p)
for {
idx := strings.IndexByte(data, '\n')
if idx < 0 {
break
}
c.append(data[:idx], c.residualTruncated)
c.residualTruncated = false
data = data[idx+1:]
}
// Bound the partial line so an unterminated giant write cannot grow
// without limit; only the retained prefix can ever become a message.
if len(data) > maxCapturedMessageLen {
data = data[:maxCapturedMessageLen]
c.residualTruncated = true
}
c.residual = data
return len(p), nil
}

// append records one line as a message, applying the length and count caps.
// alreadyTruncated marks lines whose tail was dropped while buffered.
func (c *statementMessageCapture) append(line string, alreadyTruncated bool) {
line = strings.TrimRight(line, "\r")
if strings.TrimSpace(line) == "" {
return
}
if len(c.messages) >= maxCapturedMessages {
c.suppressed++
return
}
if len(line) > maxCapturedMessageLen {
line = line[:maxCapturedMessageLen]
alreadyTruncated = true
}
if alreadyTruncated {
line += messageTruncationMarker
}
c.messages = append(c.messages, line)
}

// drain flushes any unterminated partial line, folds in the supplied extra
// messages (eg ExecutorOutput.GetMessages()) under the same caps, and returns
// the bounded message list, ending with a suppression marker when the count
// cap was hit. nil is returned when nothing was captured, so a statement
// with no messages produces exactly the output it does today.
func (c *statementMessageCapture) drain(extra []string) []string {
c.mu.Lock()
defer c.mu.Unlock()
if c.residual != "" {
c.append(c.residual, c.residualTruncated)
c.residual = ""
c.residualTruncated = false
}
for _, msg := range extra {
c.append(msg, false)
}
if c.suppressed > 0 {
c.messages = append(
c.messages,
fmt.Sprintf("[%d further engine message(s) suppressed]", c.suppressed),
)
c.suppressed = 0
}
if len(c.messages) == 0 {
return nil
}
return c.messages
}
73 changes: 73 additions & 0 deletions internal/stackql/mcpbackend/statement_message_capture_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
package mcpbackend //nolint:testpackage // exercise unexported capture

import (
"fmt"
"strings"
"testing"
)

func TestStatementMessageCapture_SplitsLinesAndSkipsBlanks(t *testing.T) {
c := newStatementMessageCapture()
fmt.Fprintf(c, "first message\n\nsecond message\r\n")
got := c.drain(nil)
if len(got) != 2 || got[0] != "first message" || got[1] != "second message" {
t.Fatalf("unexpected messages: %#v", got)
}
}

func TestStatementMessageCapture_PartialWritesJoinIntoOneMessage(t *testing.T) {
c := newStatementMessageCapture()
// Two Write calls carrying one logical line, as a diagnostic writer might.
c.Write([]byte("http response status code: 404, ")) //nolint:errcheck // never fails
c.Write([]byte("response body is nil\nand a second one")) //nolint:errcheck // never fails
got := c.drain(nil)
if len(got) != 2 || got[0] != "http response status code: 404, response body is nil" ||
got[1] != "and a second one" {
t.Fatalf("unexpected messages: %#v", got)
}
}

func TestStatementMessageCapture_TruncatesLongMessages(t *testing.T) {
c := newStatementMessageCapture()
long := strings.Repeat("x", maxCapturedMessageLen+100)
fmt.Fprintf(c, "%s\n", long)
got := c.drain(nil)
if len(got) != 1 {
t.Fatalf("expected one message, got %#v", got)
}
if len(got[0]) > maxCapturedMessageLen+len(messageTruncationMarker) ||
!strings.HasSuffix(got[0], messageTruncationMarker) {
t.Fatalf("expected bounded message with truncation marker, got %d bytes: %q...", len(got[0]), got[0][:40])
}
}

func TestStatementMessageCapture_CapsMessageCountWithMarker(t *testing.T) {
c := newStatementMessageCapture()
total := maxCapturedMessages + 5
for i := 0; i < total; i++ {
fmt.Fprintf(c, "message %d\n", i)
}
got := c.drain(nil)
if len(got) != maxCapturedMessages+1 {
t.Fatalf("expected %d messages plus suppression marker, got %d", maxCapturedMessages, len(got))
}
if !strings.Contains(got[len(got)-1], "5 further engine message(s) suppressed") {
t.Fatalf("expected suppression marker, got %q", got[len(got)-1])
}
}

func TestStatementMessageCapture_DrainFoldsInExtraMessages(t *testing.T) {
c := newStatementMessageCapture()
fmt.Fprintf(c, "captured diagnostic\n")
got := c.drain([]string{"executor message"})
if len(got) != 2 || got[0] != "captured diagnostic" || got[1] != "executor message" {
t.Fatalf("unexpected messages: %#v", got)
}
}

func TestStatementMessageCapture_EmptyDrainsNil(t *testing.T) {
c := newStatementMessageCapture()
if got := c.drain(nil); got != nil {
t.Fatalf("expected nil for no messages, got %#v", got)
}
}
6 changes: 4 additions & 2 deletions pkg/mcp_server/backend.go
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,10 @@ type Backend interface {
// ValidateQuery parses and plans a SELECT without executing it.
ValidateQuery(ctx context.Context, query string) ([]map[string]any, error)

// RunQueryJSON executes a SELECT and returns the rows.
RunQueryJSON(ctx context.Context, input dto.QueryJSONInput) ([]map[string]interface{}, error)
// RunQueryJSON executes a SELECT and returns the rows plus any
// per-statement engine messages (eg upstream provider diagnostics).
// Backends that have no channel for messages return rows only.
RunQueryJSON(ctx context.Context, input dto.QueryJSONInput) (dto.QueryResultDTO, error)

// ListProviders lists available providers.
ListProviders(ctx context.Context) ([]map[string]any, error)
Expand Down
2 changes: 1 addition & 1 deletion pkg/mcp_server/content/instructions/06-errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

How errors surface:

- Provider HTTP errors are reported as messages (eg `http response status code: 404, response body is nil`), not SQL exceptions. A query can partially succeed: in a multi-member acquisition (eg per-identifier detail reads), members that 404 contribute zero rows and the message is reported alongside the rows that resolved. A hard failure in an `IN` fan-out, by contrast, fails the whole query (see routing).
- Provider HTTP errors are reported as messages (eg `http response status code: 404, response body is nil`), not SQL exceptions. For `run_select_query` against the native backend they arrive in the tool result itself: a `messages` array beside `rows` in the structured payload, and a labelled `**messages**` block after the rendered rows. Messages are bounded: long messages are truncated and the list is capped, with a marker reporting anything cut. A statement with no messages carries no `messages` field at all. Over the `reverse_proxy` backend the engine's messages are not available to the client; an empty result there simply means "not found". A query can partially succeed: in a multi-member acquisition (eg per-identifier detail reads), members that 404 contribute zero rows and their messages are reported alongside the rows that resolved. A hard failure in an `IN` fan-out, by contrast, fails the whole query (see routing).
- An empty result set accompanied by a 404 message is the normal outcome of querying an object that may or may not exist. Treat it as "not found" - a valid answer - not as a failure to be retried.
- Parser and planner errors (unknown table, `no such column`, syntax) are returned immediately; no provider call is made.

Expand Down
5 changes: 4 additions & 1 deletion pkg/mcp_server/content/tools/run_select_query.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@ name: run_select_query
title: Run SELECT Query
open_world: true
---
Execute a SELECT. Returns {rows}. Reads only; INSERT, UPDATE, DELETE and EXEC
Execute a SELECT. Returns {rows}, plus {messages} when the engine emitted
per-statement messages (eg upstream provider diagnostics such as a 404 for a
lookup of an object that does not exist; see the error handling instructions).
Reads only; INSERT, UPDATE, DELETE and EXEC
are refused in every mode. Consult query_library_search for a vetted template before composing SQL from scratch; when the SQL came from a
library entry, pass its id as source.
7 changes: 6 additions & 1 deletion pkg/mcp_server/dto/dto.go
Original file line number Diff line number Diff line change
Expand Up @@ -187,8 +187,13 @@ type CredentialsReloadDTO struct {
}

// QueryResultDTO is the typed structured payload returned alongside the rendered text.
// Messages carries the engine's per-statement messages (eg upstream provider
// diagnostics such as `http response status code: 404, response body is nil`)
// verbatim as the engine emitted them; it is absent when the statement
// produced none.
type QueryResultDTO struct {
Rows []map[string]any `json:"rows"`
Rows []map[string]any `json:"rows"`
Messages []string `json:"messages,omitempty" jsonschema:"engine messages for this statement, eg upstream provider diagnostics; absent when none"` //nolint:lll // schema doc
}

// ValidationResultDTO is the result of validate_select_query.
Expand Down
4 changes: 2 additions & 2 deletions pkg/mcp_server/example_backend.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ func (b *ExampleBackend) ServerInfo(ctx context.Context, _ any) (dto.ServerInfoO
return dto.ServerInfoOutput{}, nil
}

func (b *ExampleBackend) RunQueryJSON(ctx context.Context, input dto.QueryJSONInput) ([]map[string]interface{}, error) {
return []map[string]interface{}{}, nil
func (b *ExampleBackend) RunQueryJSON(ctx context.Context, input dto.QueryJSONInput) (dto.QueryResultDTO, error) {
return dto.QueryResultDTO{Rows: []map[string]any{}}, nil
}

func (b *ExampleBackend) ValidateQuery(ctx context.Context, query string) ([]map[string]any, error) {
Expand Down
Loading
Loading