Documentation
¶
Overview ¶
Package embed runs an embedded StackQL MCP server from a binary carried inside the calling program.
The calling program embeds the platform's signed stackql binary (see cmd/stackql-mcp-fetch, which downloads it from the release bundle, verifies the published sha256 pin, and generates the go:embed glue). StartServer extracts the binary to the shared on-disk cache, spawns it as an MCP stdio server with the canonical launch arguments, and returns a connected client backed by github.com/modelcontextprotocol/go-sdk.
Because the package is named embed, import it with an alias when the file also blank-imports the standard library embed package:
import ( _ "embed" stackqlmcp "github.com/stackql/stackql-mcp-go/embed" )
Index ¶
- Constants
- Variables
- func BuildArgs(mode Mode, appRoot string, auth map[string]any) ([]string, error)
- func CommandLine(opts Options) (path string, args []string, err error)
- func CurrentPlatformKey() (string, error)
- func DefaultAppRoot() (string, error)
- func DefaultCacheDir() (string, error)
- func EnsureExtracted(cacheDir string, b Binary) (string, error)
- func PlatformKey(goos, goarch string) (string, error)
- type Binary
- type Client
- type Mode
- type Options
Constants ¶
const ( PlatformLinuxX64 = "linux-x64" PlatformLinuxARM64 = "linux-arm64" PlatformWindowsX64 = "windows-x64" PlatformDarwinUniversal = "darwin-universal" )
Platform keys match the stackql-mcpb-packaging release asset names and the shared binary cache layout used by the npm and pypi wrappers.
const DefaultVersion = "0.10.500"
DefaultVersion is the stackql release this module version was developed and conformance-tested against. cmd/stackql-mcp-fetch defaults to it.
Variables ¶
var BundlePins = map[string]string{
PlatformLinuxX64: "6615737747156b1a8413a976afb23af2e7eec29ebc98a6f0a0f65d1b153c44be",
PlatformLinuxARM64: "594bedbabc3096dc3563c907724e845ce0b61a67de4b3fed4158b40c0363786c",
PlatformWindowsX64: "d2ce895e88f9c6b557df07073158629808f56d75598f3a701164d65506b791b0",
PlatformDarwinUniversal: "4eed70af5cfa67295ae0b42fa3a6dca71ac9acabd0d67914fd96ad1247a9b4cc",
}
BundlePins maps platform key to the published sha256 of the release .mcpb bundle for DefaultVersion, copied from the release's .sha256 assets. The fetch tool verifies downloads against these before extracting the binary; for other versions it fetches the pin from the release at download time.
Functions ¶
func BuildArgs ¶
BuildArgs returns the canonical stackql MCP launch arguments:
mcp --mcp.server.type=stdio --approot <approot>
--mcp.config {"server":{"mode":"<mode>","audit":{"disabled":true}}}
[--auth=<json>]
Every path is absolute so the server is independent of the working directory: MCP hosts may launch with cwd "/", which is read-only on macOS. mode defaults to ModeReadOnly; appRoot defaults to ~/.stackql. auth, if non-nil, is marshalled into a --auth flag (for example the github null_auth fixture used by the conformance tests).
func CommandLine ¶
CommandLine resolves the exact command this package would run for the given options, extracting the binary to the cache first. It exists so external conformance harnesses (the packaging repo's smoke-test.py --cmd mode) can exercise the launcher without going through StartServer.
func CurrentPlatformKey ¶
CurrentPlatformKey returns the platform key for the running program.
func DefaultAppRoot ¶
DefaultAppRoot returns ~/.stackql, the conventional stackql application root shared with every other stackql distribution on the machine.
func DefaultCacheDir ¶
DefaultCacheDir returns the shared binary cache root, ~/.stackql/mcp-server-bin, the same location the npm and pypi wrappers use, so multiple embedders on one machine share a single extraction.
func EnsureExtracted ¶
EnsureExtracted writes the embedded binary to the shared cache and returns its absolute path. If a file with the expected sha256 is already present (extracted earlier by this module or by the npm/pypi wrappers) it is reused. Extraction is atomic: the binary is written to a temp file in the target directory and renamed into place, so concurrent extractors are safe. If cacheDir is empty, DefaultCacheDir is used.
func PlatformKey ¶
PlatformKey returns the packaging platform key for the given GOOS/GOARCH pair. Both darwin architectures map to the universal binary.
Types ¶
type Binary ¶
type Binary struct {
// Data is the raw server binary for the target platform.
Data []byte
// Version is the stackql release version, without the leading v
// (for example "0.10.500"). It namespaces the shared cache.
Version string
// PlatformKey is one of the packaging platform keys
// (linux-x64, linux-arm64, windows-x64, darwin-universal).
PlatformKey string
// SHA256 is the lowercase hex sha256 of Data, recorded at generate
// time from the pin-verified bundle. Extraction re-verifies it.
SHA256 string
}
Binary describes a stackql server binary carried inside the calling program, typically via go:embed. The fetch tool (cmd/stackql-mcp-fetch) downloads the signed release bundle, verifies it against the published sha256 pin, and generates a file that returns a populated Binary.
type Client ¶
type Client struct {
// Session is the initialized MCP session. Use it directly for
// ListTools, CallTool, and the rest of the protocol surface.
Session *mcp.ClientSession
// BinaryPath is where the server binary was extracted.
BinaryPath string
// Mode is the safety mode the server was started with.
Mode Mode
}
Client is a running embedded server and the MCP session connected to it.
func StartServer ¶
StartServer extracts the embedded binary, spawns it as an MCP stdio server, performs the MCP handshake, and returns a connected Client. ctx bounds the startup (extraction and handshake) only; the returned Client outlives it and runs until Close.
type Mode ¶
type Mode string
Mode is the stackql MCP server safety mode. It bounds which tools the server exposes and what SQL they may run.
const ( // ModeReadOnly exposes metadata and SELECT tools only. The default. ModeReadOnly Mode = "read_only" // ModeSafe additionally allows non-destructive mutations. ModeSafe Mode = "safe" // ModeDeleteSafe additionally allows deletes. ModeDeleteSafe Mode = "delete_safe" // ModeFullAccess removes mode restrictions. ModeFullAccess Mode = "full_access" )
type Options ¶
type Options struct {
// Binary is the embedded server binary. Required.
Binary Binary
// Mode is the server safety mode. Defaults to ModeReadOnly; anything
// more permissive is an explicit caller decision.
Mode Mode
// AppRoot is the stackql application root (provider registry cache,
// auth state). Defaults to ~/.stackql. Must be absolute if set.
AppRoot string
// CacheDir overrides the binary extraction cache root. Defaults to
// ~/.stackql/mcp-server-bin (shared with the npm/pypi wrappers).
CacheDir string
// Auth, if non-nil, is marshalled into the --auth flag, overriding
// provider auth from the environment. Example:
// map[string]any{"github": map[string]any{"type": "null_auth"}}.
Auth map[string]any
// Stderr receives the server's diagnostics. Defaults to os.Stderr.
// stdout belongs to the MCP protocol and is not configurable.
Stderr io.Writer
// ExtraArgs are appended verbatim after the canonical arguments.
ExtraArgs []string
// ClientInfo overrides the MCP client identity sent in initialize.
ClientInfo *mcp.Implementation
}
Options configures StartServer.
Source Files