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
1 change: 1 addition & 0 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,7 @@ Audit is on by default. To opt out:
Semantics:

- Sourced at startup (if the file exists) and again on every `reload_credentials` call; only keys with non-empty values are set, nothing is ever unset.
- An absent file is created at startup as an empty commented dotenv file (`0600` on unix, parent directories included), so packaged installs (eg MCPB bundles in Claude Desktop) can pass the flag unconditionally; an existing file is never touched, so bundle updates cannot wipe populated credentials.
- The file may be created, updated or rotated at any time while the server runs.
- `reload_credentials` reports variable names and per-provider status (`ok`, `unresolved`, `not_checked`) only; secret values are never returned, logged or audited. Without `--env.file` it degrades to a pure status probe.
- Credential resolution failures carry a hint directing the agent to call `reload_credentials` and retry.
Expand Down
46 changes: 46 additions & 0 deletions internal/stackql/cmd/mcp.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,12 @@ package cmd
import (
"context"
"encoding/json"
"fmt"
"os"
"os/signal"
"runtime/debug"
"syscall"
"time"

"github.com/spf13/cobra"
"gopkg.in/yaml.v2"
Expand Down Expand Up @@ -105,7 +111,38 @@ var mcpSrvCmd = &cobra.Command{
},
}

// mcpDiagf writes lifecycle diagnostics straight to stderr, bypassing the
// configured log level: stdio MCP hosts (eg Claude Desktop) capture stderr,
// and these lines are the forensic trail for unexpected termination (issue
// #691). Never log secret values through this.
func mcpDiagf(format string, args ...any) {
timestamp := time.Now().UTC().Format(time.RFC3339Nano)
fmt.Fprintf(os.Stderr, "[stackql mcp] %s %s\n", timestamp, fmt.Sprintf(format, args...))
}

// logTerminationOnSignal distinguishes external termination from a crash in
// the host's captured stderr, then exits with the conventional signal status.
func logTerminationOnSignal() {
sigCh := make(chan os.Signal, 1)
signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)
go func() {
sig := <-sigCh
mcpDiagf("received signal %q; terminating", sig)
if sigNum, ok := sig.(syscall.Signal); ok {
os.Exit(128 + int(sigNum)) //nolint:mnd // conventional signal exit status
}
os.Exit(1)
}()
}

func runMCPServer(handlerCtx handler.HandlerContext) {
defer func() {
if r := recover(); r != nil {
mcpDiagf("panic: %v\n%s", r, debug.Stack())
os.Exit(1)
}
}()
logTerminationOnSignal()
var config mcp_server.Config
json.Unmarshal([]byte(mcpConfig), &config) //nolint:errcheck // TODO: investigate
if config.Server.Transport == "" {
Expand Down Expand Up @@ -169,6 +206,15 @@ func runMCPServer(handlerCtx handler.HandlerContext) {
iqlerror.PrintErrorAndExitOneIfError(serverErr)
// A transport/session failure must be loud: log it and exit non-zero
// rather than silently returning success (issue #668).
mcpDiagf(
"starting: version=%s platform=%s pid=%d transport=%s args=%q",
bi.GetSemVersion(), bi.GetPlatform(), os.Getpid(), transport, os.Args,
)
startErr := server.Start(context.Background())
if startErr != nil {
mcpDiagf("server terminated with error: %v", startErr)
} else {
mcpDiagf("server run ended cleanly (transport closed)")
}
iqlerror.PrintErrorAndExitOneIfError(startErr)
}
10 changes: 9 additions & 1 deletion internal/stackql/cmd/root.go
Original file line number Diff line number Diff line change
Expand Up @@ -223,7 +223,7 @@ func init() {

rootCmd.PersistentFlags().StringVar(&mcpConfig, "mcp.config", "{}", "MCP server config file path (YAML or JSON)")
rootCmd.PersistentFlags().StringVar(&mcpServerType, "mcp.server.type", "", "MCP server type (http or stdio for now)")
rootCmd.PersistentFlags().StringVar(&envFilePath, "env.file", "", "optional dotenv-style file sourced into the process environment at startup; the MCP reload_credentials tool re-sources it on demand")
rootCmd.PersistentFlags().StringVar(&envFilePath, "env.file", "", "optional dotenv-style file sourced into the process environment at startup, created empty if absent; the MCP reload_credentials tool re-sources it on demand")
}

func mergeConfigFromFile(runtimeCtx *dto.RuntimeCtx, flagSet pflag.FlagSet) {
Expand All @@ -242,6 +242,14 @@ func mergeConfigFromFile(runtimeCtx *dto.RuntimeCtx, flagSet pflag.FlagSet) {
func initConfig() {
mergeConfigFromFile(&runtimeCtx, *rootCmd.PersistentFlags())

// An absent --env.file is created empty (issue #691) so packaged installs
// have a credential store to populate; creation failure is non-fatal
// because a missing file is already tolerated by Source.
if created, err := envfile.EnsureExists(envFilePath); err != nil {
fmt.Fprintf(os.Stderr, "could not create default env file '%s': %v\n", envFilePath, err)
} else if created {
fmt.Fprintf(os.Stderr, "created default env file '%s'\n", envFilePath)
}
// Source --env.file before anything credential-bearing runs; a missing
// file is fine (it may be written later), a malformed one is fatal.
if _, _, err := envfile.Source(envFilePath); err != nil {
Expand Down
45 changes: 45 additions & 0 deletions internal/stackql/envfile/envfile.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,55 @@ package envfile

import (
"os"
"path/filepath"
"sort"
"strings"
)

const defaultContent = `# StackQL credential store, sourced at startup and on each reload_credentials call
# One KEY=VALUE per line, eg:
# AWS_ACCESS_KEY_ID=AKIA...
# AWS_SECRET_ACCESS_KEY=...
`

const (
dirPermissions os.FileMode = 0o700
filePermissions os.FileMode = 0o600
)

// EnsureExists creates path (parent directories included) as an empty
// commented dotenv file when absent, so packaged installs (eg MCP bundles)
// get a working credential store on first launch; an existing file is never
// touched, since bundle updates must not wipe populated credentials. Returns
// whether this call created the file. An empty path is a no-op.
func EnsureExists(path string) (bool, error) {
if path == "" {
return false, nil
}
if _, err := os.Stat(path); err == nil {
return false, nil
} else if !os.IsNotExist(err) {
return false, err
}
if dir := filepath.Dir(path); dir != "" {
if err := os.MkdirAll(dir, dirPermissions); err != nil {
return false, err
}
}
f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, filePermissions)
if err != nil {
if os.IsExist(err) {
return false, nil
}
return false, err
}
defer f.Close() //nolint:errcheck // write error is surfaced below
if _, writeErr := f.WriteString(defaultContent); writeErr != nil {
return false, writeErr
}
return true, nil
}

// parse reads a dotenv-style file: KEY=VALUE lines; `#` comments, blanks,
// `export ` prefixes, surrounding quotes and CRLF tolerated. Keys with
// empty values are dropped so a reload cannot blank out a working credential.
Expand Down
64 changes: 64 additions & 0 deletions internal/stackql/envfile/envfile_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package envfile //nolint:testpackage // exercise unexported parse
import (
"os"
"path/filepath"
"runtime"
"strings"
"testing"
)
Expand Down Expand Up @@ -52,6 +53,69 @@ func TestParse(t *testing.T) {
}
}

func TestEnsureExists_CreatesCommentedFileWithParentDirs(t *testing.T) {
path := filepath.Join(t.TempDir(), "nested", "dir", "creds.env")
created, err := EnsureExists(path)
if err != nil {
t.Fatalf("EnsureExists: %v", err)
}
if !created {
t.Errorf("expected created=true for absent file")
}
b, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read created file: %v", err)
}
if !strings.HasPrefix(string(b), "# StackQL credential store") {
t.Errorf("expected comment header, got %q", string(b))
}
vars, err := parse(path)
if err != nil {
t.Fatalf("parse created file: %v", err)
}
if len(vars) != 0 {
t.Errorf("created file must source no vars, got %v", vars)
}
if runtime.GOOS != "windows" {
info, statErr := os.Stat(path)
if statErr != nil {
t.Fatalf("stat created file: %v", statErr)
}
if info.Mode().Perm() != 0o600 {
t.Errorf("expected 0600 permissions, got %v", info.Mode().Perm())
}
}
}

func TestEnsureExists_NeverTouchesExistingFile(t *testing.T) {
path := filepath.Join(t.TempDir(), "creds.env")
const populated = "POPULATED_KEY=populated-value\n"
if err := os.WriteFile(path, []byte(populated), 0o600); err != nil {
t.Fatalf("write env file: %v", err)
}
created, err := EnsureExists(path)
if err != nil {
t.Fatalf("EnsureExists: %v", err)
}
if created {
t.Errorf("expected created=false for existing file")
}
b, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read file: %v", err)
}
if string(b) != populated {
t.Errorf("existing file must be untouched, got %q", string(b))
}
}

func TestEnsureExists_EmptyPathIsNoop(t *testing.T) {
created, err := EnsureExists("")
if err != nil || created {
t.Errorf("empty path must be a silent no-op, got created=%t err=%v", created, err)
}
}

func TestSource_MissingFileIsNotAnError(t *testing.T) {
keys, sourced, err := Source(filepath.Join(t.TempDir(), "absent.env"))
if err != nil {
Expand Down
36 changes: 36 additions & 0 deletions test/robot/functional/stackql_mocked_from_cmd_line.robot
Original file line number Diff line number Diff line change
Expand Up @@ -10247,3 +10247,39 @@ Env File Flag Sources Credentials For Exec Entrypoint
... ${SELECT_OKTA_APPS}
... ${SELECT_OKTA_APPS_ASC_EXPECTED}
... \-\-env.file\=${envFile}

Env File Flag Creates Default Empty File When Absent And Never Touches Existing
[Documentation] Issue #691: an absent --env.file path is created at startup as an
... empty commented dotenv file; an existing file is never touched.
Pass Execution If "${EXECUTION_PLATFORM}" == "docker" host env file path is not visible inside the container
${envFile} = Set Variable ${CURDIR}${/}tmp${/}created-if-absent-dotenv.env
Remove File ${envFile}
Should Stackql Exec Inline Equal
... ${STACKQL_EXE}
... ${OKTA_SECRET_STR}
... ${GITHUB_SECRET_STR}
... ${K8S_SECRET_STR}
... ${REGISTRY_NO_VERIFY_CFG_STR}
... ${AUTH_CFG_STR}
... ${SQL_BACKEND_CFG_STR_CANONICAL}
... ${SELECT_OKTA_APPS}
... ${SELECT_OKTA_APPS_ASC_EXPECTED}
... \-\-env.file\=${envFile}
${created} = Get File ${envFile}
Should Start With ${created} \# StackQL credential store
${populated} = Set Variable OKTA_SECRET_KEY_DOTENV=${OKTA_SECRET_STR}\n
Create File ${envFile} ${populated}
${authCfg} = Set Variable { "okta": { "credentialsenvvar": "OKTA_SECRET_KEY_DOTENV", "type": "api_key" } }
Should Stackql Exec Inline Equal
... ${STACKQL_EXE}
... ${OKTA_SECRET_STR}
... ${GITHUB_SECRET_STR}
... ${K8S_SECRET_STR}
... ${REGISTRY_NO_VERIFY_CFG_STR}
... ${authCfg}
... ${SQL_BACKEND_CFG_STR_CANONICAL}
... ${SELECT_OKTA_APPS}
... ${SELECT_OKTA_APPS_ASC_EXPECTED}
... \-\-env.file\=${envFile}
${after} = Get File ${envFile}
Should Be Equal ${after} ${populated}
Loading