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
23 changes: 22 additions & 1 deletion docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ Tools also carry a `title` and every MCP behavioural hint as an explicit boolean
| `list_services` | Table | Services under a provider. Requires `provider`. |
| `list_resources` | Table | Resources under a `provider`.`service`. Requires `provider` and `service`. |
| `list_methods` | Table | Access methods (HTTP operations) for a resource with their SQL verb and required params. **Call before writing any query.** Requires `provider`, `service`, `resource`. |
| `describe_method` | KV | Full I/O contract for one method (always EXTENDED): inputs with `param_type` and the `output` fields a SELECT can reference. Requires `provider`, `service`, `resource`, `method`. |
| `describe_method` | KV | Typed, shallow I/O contract for one method: inputs with `param_type` and selected response-row fields. Requires `provider`, `service`, `resource`, `method`. Optional `depth` (default 1, maximum 32), `path`, `descriptions` (default false), `param_type` and `include_global` control expansion. |
| `validate_select_query` | KV | Parse and plan a SELECT without executing. Returns `{valid, errors}`. SELECT only. |
| `run_select_query` | Table | Execute a SELECT. Returns `{rows}`. Reads only. |
| `run_mutation_query` | KV | Execute INSERT/UPDATE/REPLACE/DELETE. **Real side effects.** Returns `{messages, timestamp}`. Gated by the server [mode](#server-modes). |
Expand All @@ -167,6 +167,27 @@ Tools also carry a `title` and every MCP behavioural hint as an explicit boolean
| `query_library_search` | Table | Search the curated query library by natural-language `intent` (optional `provider` / `service` / `tags` filters). Consult before composing SQL from scratch. Read-only, no credentials. |
| `query_library_get` | KV | Retrieve one library entry by `id`; with `params` the server validates them and returns rendered SQL plus the tool to execute it with. Read-only, no credentials. |

Method discovery resolves recursive schemas but expands only the requested depth (maximum 4096
nodes). `shape` contains JSON schema properties/items, enums, wire names, child counts and truncation
markers. Drill down with paths such as `data__networkInterfaces.accessConfigs`; array items are
traversed implicitly. Descriptions and document-global optional query controls are opt-in.
`param_type` accepts `input`, `output`, `input_required` or `input_optional`.

The same controls are available over SQL and both MCP backends:

```sql
SELECT * FROM stackql_preview.metadata.method_fields
WHERE provider = 'google' AND service = 'compute'
AND resource = 'instances' AND method = 'insert'
AND path = 'data__networkInterfaces.accessConfigs'
AND depth = 2 AND descriptions = 'true' AND param_type = 'input';
```

Plain `DESCRIBE METHOD` uses the same typed shallow view; `EXTENDED` opts into descriptions.
Discovery verifies provider documents and makes no provider API calls. Malformed source schemas
produce explicit errors rather than invented row fields; the self-referencing S3 GET lifecycle
schema requires a registry correction. Request-only discovery remains available.

## Canonical agent prompts, resources and instructions

Instructions, prompts, resources and tool descriptions are authored as markdown under `pkg/mcp_server/content/` and embedded into the binary at build time; adding or changing published content is a markdown-only edit. Tool descriptions live one file per tool under `content/tools/`; the tool table above paraphrases them.
Expand Down
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ require (
github.com/spf13/cobra v1.10.2
github.com/spf13/pflag v1.0.10
github.com/spf13/viper v1.10.1
github.com/stackql-labs/omnisdk v0.1.11-alpha10
github.com/stackql-labs/omnisdk v0.1.11-beta1
github.com/stackql/go-suffix-map v0.0.1-alpha02
github.com/stackql/psql-wire v0.1.2-beta02
github.com/stackql/stackql-parser v0.0.17-alpha05
Expand Down
4 changes: 2 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -328,8 +328,8 @@ github.com/spf13/viper v1.10.1 h1:nuJZuYpG7gTj/XqiUwg8bA0cp1+M2mC3J4g5luUYBKk=
github.com/spf13/viper v1.10.1/go.mod h1:IGlFPqhNAPKRxohIzWpI5QEy4kuI7tcl5WvR+8qy1rU=
github.com/spiffe/go-spiffe/v2 v2.7.0 h1:uXe1MflJoHw58wAUvxVlcM7WpKtijWG7I1UidcGh6g4=
github.com/spiffe/go-spiffe/v2 v2.7.0/go.mod h1:47Q0Q9/AqGha8QLHp+kxpH4Wca7X7EnOtlIJy3mxZ3U=
github.com/stackql-labs/omnisdk v0.1.11-alpha10 h1:H9b11TzvfwjoCYossZsoMW4DtxtRqdntCmFf9+/q9b4=
github.com/stackql-labs/omnisdk v0.1.11-alpha10/go.mod h1:G6qZy+6Vbuy9sSfws6erzpbbuThI+cD/uXDQPgQkRBI=
github.com/stackql-labs/omnisdk v0.1.11-beta1 h1:qqbh6H9JQa8agwRa3t8gV7jvS5BqWjWxp3tyS2NXwgs=
github.com/stackql-labs/omnisdk v0.1.11-beta1/go.mod h1:G6qZy+6Vbuy9sSfws6erzpbbuThI+cD/uXDQPgQkRBI=
github.com/stackql/go-suffix-map v0.0.1-alpha02 h1:JI4aiq/OfHW4a/BiNqK31NbyaR94zlUOhGZof3G/OUo=
github.com/stackql/go-suffix-map v0.0.1-alpha02/go.mod h1:6BSMz4K/gIYfqdVRb7V8xL165wiPYyCjD9Kx7hLMd9Y=
github.com/stackql/psql-wire v0.1.2-beta02 h1:7DfliBpyyCaUHVJ1Jxk37q3zVwVLyh6+FCHeM0/gbAQ=
Expand Down
2 changes: 1 addition & 1 deletion internal/stackql/intrinsic/doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ func describeDocument(
columns = append(columns, column{name: name, dataType: types[name].Type})
}
if method != "" {
return describeDocumentMethod(ctx, signature, columns, extended)
return describeDocumentMethod(ctx, signature, extended)
}
return describeDocumentColumns(ctx, columns, extended)
}
Expand Down
34 changes: 2 additions & 32 deletions internal/stackql/intrinsic/doc_metadata.go
Original file line number Diff line number Diff line change
Expand Up @@ -82,37 +82,7 @@ func prepareDocMetadata(
}

func describeDocumentMethod(
ctx queryContext, signature omnisdk.MethodSignature, columns []column, extended bool,
ctx queryContext, signature omnisdk.MethodSignature, extended bool,
) internaldto.ExecutorOutput {
order := []string{"name", "type", "param_type", "shape"}
if extended {
order = append(order, "description")
}
rows := make(map[string]map[string]interface{})
appendRow := func(name, kind, parameterType string) {
row := map[string]interface{}{"name": name, "type": kind, "param_type": parameterType, "shape": kind}
if extended {
row["description"] = ""
}
rows[fmt.Sprintf("%06d", len(rows))] = row
}
for _, parameter := range signature.Params() {
name := parameter.Name()
if parameter.In() == "body" {
name = "data__" + name
}
kind := "string"
if typed, ok := parameter.(interface{ Type() string }); ok && typed.Type() != "" {
kind = typed.Type()
}
parameterType := "input_optional"
if parameter.Required() {
parameterType = "input_required"
}
appendRow(name, kind, parameterType)
}
for _, col := range columns {
appendRow(col.name, col.dataType, "output")
}
return prepare(ctx, order, rows, util.DefaultRowSort)
return describeSchema(ctx, signature, omnisdk.MethodSchemaOptions{Descriptions: extended}, extended)
}
Loading
Loading