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
2 changes: 1 addition & 1 deletion .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ on:
- '.github/workflows/contributors.yml'
env:
# Override this repository variable when the stable trunk changes.
LIVE_BRANCH: ${{ vars.LIVE_BRANCH || 'stable/v0.13' }}
LIVE_BRANCH: ${{ vars.LIVE_BRANCH || 'main' }}
BUILD_SOURCE_BRANCH: ${{ github.head_ref || github.ref_name }}
DOCKER_PYTHON_VERSION: '3.13'
GOTESTCMD: "go test -timeout 1200s -v ./..."
Expand Down
2 changes: 1 addition & 1 deletion docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ Then, assuming you have a `stackql` MCP server serving streamable HTTP on port `

The server publishes 15 tools. Each returns both rendered text (for the LLM) and a typed structured payload (for programmatic clients). Rendering is fixed per tool: a markdown table for uniform multi-row results, a markdown KV block for sparse / single-record / mixed-shape results.

Tools also carry MCP behavioural annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`), derived from the same policy-gate classification that enforces the server [mode](#server-modes): statically read-only tools claim `readOnlyHint`, mutation/lifecycle tools claim `destructiveHint`, and SQL-carrying tools make no read-only claim because their effect depends on the submitted statement. Annotations are advisory hints for client UX; enforcement always remains with the policy gate.
Tools also carry a `title` and every MCP behavioural hint as an explicit boolean (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), derived from the same policy-gate classification that enforces the server [mode](#server-modes): statically read-only tools claim `readOnlyHint`, mutation/lifecycle tools claim `destructiveHint`, and SQL-carrying tools make no read-only claim because their effect depends on the submitted statement. `run_select_query` claims `destructiveHint: false` because it refuses INSERT, UPDATE, DELETE and EXEC in every mode. `openWorldHint` is true for tools that reach provider or registry endpoints (`run_*`, `list_registry`, `pull_provider`) and false for tools that read only local state. Titles and `openWorldHint` are mastered in the frontmatter of `pkg/mcp_server/content/tools/*.md`. Annotations are advisory hints for client UX; enforcement always remains with the policy gate.

| Tool | Renderer | Description |
|---|---|---|
Expand Down
5 changes: 4 additions & 1 deletion internal/stackql/handler/handler.go
Original file line number Diff line number Diff line change
Expand Up @@ -806,7 +806,10 @@ func transformOpenapiStackqlAuthToLocal(auth *omnisdk.ProviderAuth) *dto.AuthCtx
if auth == nil {
return nil
}
return &dto.AuthCtx{AuthConfig: auth.AuthConfig, Successor: transformOpenapiStackqlAuthToLocal(auth.Successor)}
cfg := auth.AuthConfig
// A runtime token URL bypasses the document's token URL variables; omnisdk overlays the document's own.
cfg.TokenURL = ""
return &dto.AuthCtx{AuthConfig: cfg, Successor: transformOpenapiStackqlAuthToLocal(auth.Successor)}
}

func (hc *standardHandlerContext) GetExecutionContext() context.Context {
Expand Down
2 changes: 2 additions & 0 deletions pkg/mcp_server/content/tools/describe_method.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
---
name: describe_method
title: Describe Method
open_world: false
---
Full I/O contract for one method: every input with its param_type (input_required params become exact-match WHERE predicates; input_optional ones may be added) and every output field, which are the columns a SELECT or RETURNING can reference. Call it after list_methods and before the first query against a method; there is no resource-level equivalent because each method returns its own shape. Requires provider, service, resource, method.
4 changes: 3 additions & 1 deletion pkg/mcp_server/content/tools/list_methods.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
---
name: list_methods
title: List Methods
open_world: false
---
Access methods (HTTP operations) for a resource with their SQL verb and required params. Pick the method whose verb matches the intent and whose required params you can supply, then describe_method it. Call when composing SQL from scratch against an unfamiliar resource; not needed when executing a vetted query library template. Requires provider, service, resource.
Access methods for a resource with their SQL verb and required params. Pick the method whose verb matches the intent and whose required params you can supply, then describe_method it. Call when composing SQL from scratch against an unfamiliar resource; not needed when executing a vetted query library template. Requires provider, service, resource.
2 changes: 2 additions & 0 deletions pkg/mcp_server/content/tools/list_providers.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
---
name: list_providers
title: List Providers
open_world: false
---
Available cloud/SaaS providers (top of the hierarchy). No inputs.
2 changes: 2 additions & 0 deletions pkg/mcp_server/content/tools/list_registry.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
---
name: list_registry
title: List Registry Providers
open_world: true
---
Providers (and their versions) available in the configured registry. Distinct from list_providers, which lists only providers already pulled. Optional provider arg lists versions for that provider.
2 changes: 2 additions & 0 deletions pkg/mcp_server/content/tools/list_resources.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
---
name: list_resources
title: List Resources
open_world: false
---
Resources under a provider.service. Requires provider and service.
2 changes: 2 additions & 0 deletions pkg/mcp_server/content/tools/list_services.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
---
name: list_services
title: List Services
open_world: false
---
Services under a provider. Requires provider.
2 changes: 2 additions & 0 deletions pkg/mcp_server/content/tools/pull_provider.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
---
name: pull_provider
title: Pull Provider
open_world: true
---
Install a single provider from the registry into the local approot cache. Requires provider; version is optional (latest published is pulled when empty).
Writes only local cache state; no cloud control/data plane effect.
2 changes: 2 additions & 0 deletions pkg/mcp_server/content/tools/query_library_get.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
---
name: query_library_get
title: Get Query Library Entry
open_world: false
---
Retrieve a query library entry by id. Without params: returns the raw template, param declarations and notes (adapt from it when no exact match exists). With
params: the server validates values and returns rendered SQL plus which tool to execute it with (run_select_query or run_mutation_query). Read-only, no credentials.
2 changes: 2 additions & 0 deletions pkg/mcp_server/content/tools/query_library_search.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
---
name: query_library_search
title: Search Query Library
open_world: false
---
Search the curated StackQL query library by natural-language intent. Returns ranked template ids. Consult before composing SQL from scratch; follow with query_library_get, which validates params and surfaces any the index omits. Read-only, no credentials.
2 changes: 2 additions & 0 deletions pkg/mcp_server/content/tools/reload_credentials.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
---
name: reload_credentials
title: Reload Credentials
open_world: false
---
Live-reload provider credentials: re-sources the server's configured env file into the process environment, invalidates cached auth contexts, and reports resolution status for every installed provider (optional provider arg filters the report; changed field flags values that differ from before). Never returns secret values. Credentials resolve automatically at query time - never call this at session start or before queries. Call only after a query fails with a credential resolution error (fix the env file first, then reload, then retry) or when the user says credentials have been rotated or changed. If the report shows changed: false after a failure, the file was not updated - ask the user rather than retrying.
2 changes: 2 additions & 0 deletions pkg/mcp_server/content/tools/run_lifecycle_operation.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
---
name: run_lifecycle_operation
title: Run Lifecycle Operation
open_world: true
---
Execute a stackql EXEC lifecycle operation (eg EXEC
aws.ec2.instances.start_instances ...). Real cloud side effects. Discover available operations and required params via list_methods and describe_method. Returns {messages, timestamp}. Gated by server mode.
2 changes: 2 additions & 0 deletions pkg/mcp_server/content/tools/run_mutation_query.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
---
name: run_mutation_query
title: Run Mutation Query
open_world: true
---
Execute INSERT/UPDATE/REPLACE/DELETE against the provider. Real side effects. Returns {messages, timestamp}. Gated by server 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.
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
@@ -1,5 +1,8 @@
---
name: run_select_query
title: Run SELECT Query
open_world: true
---
Execute a SELECT. Returns {rows}. Reads only. Consult query_library_search for a vetted template before composing SQL from scratch; when the SQL came from a
Execute a SELECT. Returns {rows}. 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.
2 changes: 2 additions & 0 deletions pkg/mcp_server/content/tools/server_info.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
---
name: server_info
title: Server Info
open_world: false
---
Get server identity and runtime: stackql version, backing SQL engine, provider registry location, mode, read-only flag. Call on demand - eg to diagnose a refused/gated operation or check version-specific behavior. Not needed at session start or before queries.
2 changes: 2 additions & 0 deletions pkg/mcp_server/content/tools/validate_select_query.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
---
name: validate_select_query
title: Validate SELECT Query
open_world: false
---
Parse and plan a SELECT without executing; the provider's credentials must still resolve, as for execution. Returns {valid, errors}. Use when iterating on syntax or plan errors, or pre-flighting complex/expensive queries - don't validate routinely; run_select_query surfaces the same errors.
32 changes: 25 additions & 7 deletions pkg/mcp_server/embedded_content.go
Original file line number Diff line number Diff line change
Expand Up @@ -209,29 +209,43 @@ type resourceFrontmatter struct {
// toolFrontmatter is the YAML wire form of a tool description file header;
// the body is the description prose.
type toolFrontmatter struct {
Name string `yaml:"name"`
Name string `yaml:"name"`
Title string `yaml:"title"`
OpenWorld *bool `yaml:"open_world"`
}

// toolDescriptions carries the tool descriptions mastered under
// content/tools, one file per tool, keyed by tool name.
type toolDescriptions interface {
describe(name string) (string, bool)
title(name string) string
openWorld(name string) bool
names() []string
}

type toolDoc struct {
description string
title string
openWorld bool
}

type standardToolDescriptions struct {
byName map[string]string
byName map[string]toolDoc
}

func newToolDescriptions(byName map[string]string) toolDescriptions {
func newToolDescriptions(byName map[string]toolDoc) toolDescriptions {
return &standardToolDescriptions{byName: byName}
}

func (d *standardToolDescriptions) describe(name string) (string, bool) {
rv, ok := d.byName[name]
return rv, ok
return rv.description, ok
}

func (d *standardToolDescriptions) title(name string) string { return d.byName[name].title }

func (d *standardToolDescriptions) openWorld(name string) bool { return d.byName[name].openWorld }

func (d *standardToolDescriptions) names() []string {
rv := make([]string, 0, len(d.byName))
for name := range d.byName {
Expand Down Expand Up @@ -356,13 +370,14 @@ func loadResourcesFrom(fsys fs.FS, dir string) ([]embeddedResource, error) {
}

// loadToolDescriptionsFrom parses every tool description file; the
// frontmatter name must match the file stem and the body must be non-empty.
// frontmatter name must match the file stem, title and open_world are
// required and the body must be non-empty.
func loadToolDescriptionsFrom(fsys fs.FS, dir string) (toolDescriptions, error) {
names, err := listMarkdownFiles(fsys, dir)
if err != nil {
return nil, err
}
byName := make(map[string]string, len(names))
byName := make(map[string]toolDoc, len(names))
for _, name := range names {
raw, readErr := fs.ReadFile(fsys, dir+"/"+name)
if readErr != nil {
Expand All @@ -379,11 +394,14 @@ func loadToolDescriptionsFrom(fsys fs.FS, dir string) (toolDescriptions, error)
if fm.Name != strings.TrimSuffix(name, ".md") {
return nil, fmt.Errorf("tool file %s: name %q must match the file stem", name, fm.Name)
}
if fm.Title == "" || fm.OpenWorld == nil {
return nil, fmt.Errorf("tool file %s: title and open_world are required", name)
}
description := collapseProse(body)
if description == "" {
return nil, fmt.Errorf("tool file %s: description body is empty", name)
}
byName[fm.Name] = description
byName[fm.Name] = toolDoc{description: description, title: fm.Title, openWorld: *fm.OpenWorld}
}
return newToolDescriptions(byName), nil
}
Expand Down
15 changes: 12 additions & 3 deletions pkg/mcp_server/embedded_content_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ func TestToolDescriptions_MarkdownProseIsPublished(t *testing.T) {

func TestLoadToolDescriptionsFrom_ValidatesAndCollapsesProse(t *testing.T) {
fsys := fstest.MapFS{
"tools/alpha.md": {Data: []byte("---\nname: alpha\n---\nFirst line\nsecond line.\n\nSecond paragraph.\n")},
"tools/alpha.md": {Data: []byte("---\nname: alpha\ntitle: Alpha\nopen_world: false\n---\nFirst line\nsecond line.\n\nSecond paragraph.\n")},
}
descriptions, err := loadToolDescriptionsFrom(fsys, "tools")
if err != nil {
Expand All @@ -125,14 +125,23 @@ func TestLoadToolDescriptionsFrom_ValidatesAndCollapsesProse(t *testing.T) {
if !ok || got != "First line second line.\n\nSecond paragraph." {
t.Errorf("unexpected description %q (ok=%v)", got, ok)
}
if descriptions.title("alpha") != "Alpha" {
t.Errorf("unexpected title %q", descriptions.title("alpha"))
}
missing := fstest.MapFS{
"tools/alpha.md": {Data: []byte("---\nname: alpha\ntitle: Alpha\n---\nbody\n")},
}
if _, err := loadToolDescriptionsFrom(missing, "tools"); err == nil || !strings.Contains(err.Error(), "open_world") {
t.Errorf("expected missing open_world error, got %v", err)
}
mismatch := fstest.MapFS{
"tools/alpha.md": {Data: []byte("---\nname: beta\n---\nbody\n")},
"tools/alpha.md": {Data: []byte("---\nname: beta\ntitle: Beta\nopen_world: false\n---\nbody\n")},
}
if _, err := loadToolDescriptionsFrom(mismatch, "tools"); err == nil || !strings.Contains(err.Error(), "file stem") {
t.Errorf("expected file stem mismatch error, got %v", err)
}
empty := fstest.MapFS{
"tools/alpha.md": {Data: []byte("---\nname: alpha\n---\n \n")},
"tools/alpha.md": {Data: []byte("---\nname: alpha\ntitle: Alpha\nopen_world: false\n---\n \n")},
}
if _, err := loadToolDescriptionsFrom(empty, "tools"); err == nil || !strings.Contains(err.Error(), "empty") {
t.Errorf("expected empty body error, got %v", err)
Expand Down
57 changes: 48 additions & 9 deletions pkg/mcp_server/gate.go
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ type toolGate struct {
// audit event. For hierarchy tools this carries the hierarchy fields;
// for query tools it carries SQL + row_limit.
extractArgs func(any) map[string]any
// readsOnly refuses mutation, delete and lifecycle statements in every mode.
readsOnly bool
}

// extractSQLFromQueryInput returns args.SQL for the dto.QueryJSONInput shape.
Expand Down Expand Up @@ -115,11 +117,53 @@ func boolPtr(v bool) *bool { return &v }
// explicit Annotations value on the tool always wins.
func deriveToolAnnotations(gate toolGate) *mcp.ToolAnnotations {
if gate.defaultClass == policy.QueryClassSelect && gate.extractSQL == nil {
return &mcp.ToolAnnotations{ReadOnlyHint: true}
return &mcp.ToolAnnotations{ReadOnlyHint: true, DestructiveHint: boolPtr(false)}
}
return nil
}

func isWriteClass(class policy.QueryClass) bool {
return class == policy.QueryClassMutationCreate || class == policy.QueryClassMutationDelete ||
class == policy.QueryClassLifecycle
}

type refusedPolicy struct {
policy.Policy
reason string
}

func (p refusedPolicy) Decision() policy.Decision { return policy.DecisionRefuseImmediate }
func (p refusedPolicy) Reason() string { return p.reason }

// gatePolicy applies the mode policy, then refuses write-class SQL on read-only tools in every mode.
func gatePolicy(gate toolGate, mode, sql string) policy.Policy {
p := policy.NewPolicy(mode, sql, gate.defaultClass)
if gate.readsOnly && isWriteClass(p.Class()) && p.Decision() != policy.DecisionRefuseImmediate {
return refusedPolicy{Policy: p, reason: p.Class().String() +
" statements run through run_mutation_query or run_lifecycle_operation"}
}
return p
}

// applyToolMetadata attaches the description, title and the full hint set mastered under content/tools.
func applyToolMetadata(t *mcp.Tool, descriptions toolDescriptions, gate toolGate) error {
description, hasDescription := descriptions.describe(t.Name)
if !hasDescription {
return fmt.Errorf("tool %q has no description under %s", t.Name, embeddedToolsDir)
}
t.Description = description
t.Title = descriptions.title(t.Name)
if t.Annotations == nil {
t.Annotations = deriveToolAnnotations(gate)
}
// Directory validators require every hint as an explicit boolean.
if t.Annotations == nil || t.Annotations.DestructiveHint == nil {
return fmt.Errorf("tool %q must declare destructiveHint", t.Name)
}
t.Annotations.OpenWorldHint = boolPtr(descriptions.openWorld(t.Name))
return nil
}

// addToolWithGate wraps mcp.AddTool with the policy gate + audit middleware.
// It is the single chokepoint at which mode enforcement and audit recording
// are applied, and where the tool description mastered under content/tools
Expand All @@ -137,13 +181,8 @@ func addToolWithGate[In, Out any](
if !cfg.IsToolEnabled(t.Name) {
return nil
}
description, hasDescription := descriptions.describe(t.Name)
if !hasDescription {
return fmt.Errorf("tool %q has no description under %s", t.Name, embeddedToolsDir)
}
t.Description = description
if t.Annotations == nil {
t.Annotations = deriveToolAnnotations(gate)
if err := applyToolMetadata(t, descriptions, gate); err != nil {
return err
}
wrapped := func(ctx context.Context, req *mcp.CallToolRequest, args In) (*mcp.CallToolResult, Out, error) {
var zero Out
Expand All @@ -155,7 +194,7 @@ func addToolWithGate[In, Out any](
if gate.extractSQL != nil {
sql = gate.extractSQL(args)
}
p := policy.NewPolicy(mode, sql, gate.defaultClass)
p := gatePolicy(gate, mode, sql)
auditDecision := audit.DecisionAllow

switch p.Decision() {
Expand Down
10 changes: 8 additions & 2 deletions pkg/mcp_server/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -521,9 +521,15 @@ func registerTools(
},
))

runSelectGate := queryGate("run_select_query")
runSelectGate.readsOnly = true
errs = append(errs, addToolWithGate(
server, cfg, auditSink, approvals, descriptions, queryGate("run_select_query"),
&mcp.Tool{Name: "run_select_query"},
server, cfg, auditSink, approvals, descriptions, runSelectGate,
&mcp.Tool{
Name: "run_select_query",
// SQL-carrying tools never claim read-only; the gate refuses write-class statements.
Annotations: &mcp.ToolAnnotations{DestructiveHint: boolPtr(false)},
},
func(ctx context.Context, _ *mcp.CallToolRequest, args dto.QueryJSONInput) (*mcp.CallToolResult, dto.QueryResultDTO, error) {
logger.Debugf("run_select_query: %s", args.SQL)
format, formatErr := resolveRenderFormat(cfg, args.Format)
Expand Down
Loading
Loading