Snippets and results

Snippets

A snippet is a file in any package except main that declares exactly this function:

func run(ctx context.Context) (any, error)

kode-gopher adds the main function. It calls run, encodes the returned value as JSON, and turns a returned error or a panic into a structured result. The snippet never writes main, and doesn’t print its answer: it returns it.

package snippet

import (
  "context"
  "os"

  container "cloud.google.com/go/container/apiv1"
  "cloud.google.com/go/container/apiv1/containerpb"
)

func run(ctx context.Context) (any, error) {
  c, err := container.NewClusterManagerClient(ctx)
  if err != nil {
    return nil, err
  }
  defer c.Close()
  resp, err := c.ListClusters(ctx, &containerpb.ListClustersRequest{
    Parent: "projects/" + os.Getenv("GOOGLE_CLOUD_PROJECT") + "/locations/-",
  })
  if err != nil {
    return nil, err
  }
  var names []string
  for _, cl := range resp.Clusters {
    names = append(names, cl.Name)
  }
  return names, nil
}

Full programs

A file in package main with its own func main() runs as is. The program owns stdout and stderr. For a structured result, it writes the same JSON shape the wrapper writes to /app/.kode-gopher/result.json:

{"kind": "ok", "value": ...}

Several files

The files argument takes a map from path to source, instead of code:

• Files at the root form the entry package. For a snippet, exactly one of them declares run.
• Files in subdirectories are helper packages. The module is named kode_gopher_user, so helper/format.go is imported as kode_gopher_user/helper.
• A go.mod in the map replaces the image’s lockfile. The snippet then chooses its own versions, and pays for any recompilation.

Imports

Packages in the precompiled set build in seconds. Any other pure-Go package works too: the build runs go mod tidy first, and the result reports tidied: true.

extra_imports adds blank imports through a generated file. It’s rarely needed, as a hint for go mod tidy.

Results

Every call returns:

Field	Meaning
phase	build if compilation failed, with the compiler’s errors in stderr. run if it compiled and ran.
mode	wrapped for a snippet, verbatim for a full program.
exit_code	The compiler’s exit code (build) or the program’s (run).
stdout, stderr	Output of the phase that ran last. Snippets can log to stdout freely, since the answer travels separately.
build_ms, duration_ms	Build time, and build plus run time.
tidied	Whether the build needed go mod tidy.
result	The structured result, below.
attachments	Metadata (name, mime_type, bytes) for any images written under /app/.kode-gopher/attachments/, returned alongside ImageContent blocks.

The result.kind is one of:

Kind	When	Other fields
ok	run returned a value	value: the value, as JSON
error	run returned an error	message
panic	run panicked	message, stack
marshal_error	the value couldn’t be encoded as JSON (a channel or a func, for example)	message, type

A result can be up to 256 KiB of JSON. A larger one is dropped, and so is a result.json that isn’t valid JSON. In both cases warnings says why, so return less data: filter, summarize, or page through it in the program, project responses into small structs or slices rather than returning raw *pb structs or full Kubernetes list objects (whose metadata.managedFields and last-applied-configuration annotations quickly fill 256 KiB), or stash raw datasets under /app/persist for follow-up calls in the same session. stdout and stderr are different: each is cut to its first and last 8 KiB, so the model sees the start and the end of long output.

The MCP response is flagged as an error (isError) when the build failed, the program exited non-zero, the result kind isn’t ok, or the result was dropped. The model can tell what to fix from phase and kind: compile errors mean changing the code, and error results usually mean a permission or API problem.

Image attachments

When a snippet renders a chart or downloads an image from Cloud Storage, write regular image/png, image/jpeg, or image/webp files under /app/.kode-gopher/attachments/ instead of base64-encoding bytes into result.value. Each run accepts up to 8 images and 2 MiB of combined raw image bytes, verified by file header signature rather than file extension. execute_go_code appends each image to the MCP tool result as a native ImageContent block and lists its metadata in attachments; symlinks, subdirectories, unsupported formats, or oversized files are skipped and reported in warnings.

The full schema is on the MCP tools page.