probe

package

v0.1.0-beta.9 Latest Latest Go to latest Published: May 9, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/gridctl/gridctl

Links

Open Source Insights

Documentation ¶

Overview ¶

Package probe implements the ephemeral MCP server probe used by the wizard to enumerate a server's tool list before it has been deployed.

The cache keeps successful probe results for 5 minutes keyed by a canonicalized hash of the server config so repeated "Discover tools" clicks on the same config short-circuit the spawn.

Index ¶

Constants
func Key(cfg config.MCPServer) string
type Cache
- func NewCache(ttl time.Duration) *Cache
type ClientFactory
type Entry
type Error
- func (e *Error) Error() string
type Prober
- func NewProber(cache *Cache) *Prober
type Result

Constants ¶

View Source

const (
	CodeProbeTimeout         = "probe_timeout"
	CodeInitializeFailed     = "initialize_failed"
	CodeToolsListFailed      = "tools_list_failed"
	CodeUnsupportedTransport = "unsupported_transport"
	CodeInvalidConfig        = "invalid_config"
	CodeRateLimited          = "rate_limited"
	CodeInternal             = "internal_error"
)

Error codes surfaced to clients. Kept as constants so the frontend can map them to user-facing copy deterministically.

View Source

const DefaultTTL = 5 * time.Minute

DefaultTTL is how long a successful probe result is cached.

Variables ¶

This section is empty.

Functions ¶

func Key ¶

func Key(cfg config.MCPServer) string

Key produces a stable sha256 hash of the subset of the server config that actually identifies the target being probed. Volatile / identity-only fields (name, network) are excluded so two identical servers with different names share a cache entry.

Types ¶

type Cache ¶

type Cache struct {
	// contains filtered or unexported fields
}

Cache is a concurrency-safe TTL cache for probe results. The zero value is not usable — call NewCache.

func NewCache ¶

func NewCache(ttl time.Duration) *Cache

NewCache constructs a probe cache with the given TTL. Zero or negative TTLs fall back to DefaultTTL so callers can't accidentally disable caching.

func (*Cache) Get ¶

func (c *Cache) Get(key string) (Entry, bool)

Get returns the entry for key if present and not expired. Expired entries are removed on access (lazy eviction).

func (*Cache) Len ¶

func (c *Cache) Len() int

Len returns the number of entries currently in the cache (including ones that are expired but not yet evicted). Intended for tests.

func (*Cache) Put ¶

func (c *Cache) Put(key string, tools []mcp.Tool)

Put stores an entry under the given key. Only callers that have a successful probe result should Put — failure paths must not populate the cache.

type ClientFactory ¶

type ClientFactory interface {
	NewHTTP(name, endpoint string) mcp.AgentClient
}

ClientFactory builds an MCP client for a given transport. The default implementation defers to the standard pkg/mcp constructors; tests override it to inject stubs.

type Entry ¶

type Entry struct {
	Tools    []mcp.Tool
	ProbedAt time.Time
}

Entry is a cached probe result.

type Error ¶

type Error struct {
	Code    string
	Message string
	Hint    string
}

Error is a structured probe failure. Unlike a plain error, it carries a stable code for the UI and an optional hint. Secrets in Message / Hint are scrubbed by the handler before the response is serialized.

func (*Error) Error ¶

func (e *Error) Error() string

type Prober ¶

type Prober struct {
	// contains filtered or unexported fields
}

Prober enumerates an MCP server's tools without registering it with the gateway. Scope: external URL transport only.

For every other transport (container HTTP/SSE, container stdio, local process, SSH, OpenAPI) the probe returns CodeUnsupportedTransport with a hint pointing users at the post-deploy tool editor. Running a server ephemerally before deploy is a niche workflow compared to the common deploy-then-curate flow that the topology editor supports.

func NewProber ¶

func NewProber(cache *Cache) *Prober

NewProber wires up a prober. A nil cache becomes a new one with DefaultTTL.

func (*Prober) Probe ¶

func (p *Prober) Probe(ctx context.Context, cfg config.MCPServer) (Result, *Error)

Probe validates the config, short-circuits on cache hits, and otherwise connects to the external URL long enough to run initialize + tools/list. It is safe to call concurrently; the caller is responsible for enforcing concurrency caps.

func (*Prober) SetClientFactory ¶

func (p *Prober) SetClientFactory(f ClientFactory)

SetClientFactory overrides the MCP client constructor. Primarily for tests.

func (*Prober) SetLogger ¶

func (p *Prober) SetLogger(logger *slog.Logger)

SetLogger installs a structured logger. Nil is ignored.

type Result ¶

type Result struct {
	Tools  []mcp.Tool
	Cached bool
}

Result is what a probe returns on success.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL