Documentation
¶
Overview ¶
Package probe is the keyless MCP-server health engine. For a given server it runs only public, unauthenticated signals - repository liveness (GitHub API), package publication (npm, PyPI, Docker Hub anon), and remote reachability (a plain GET plus a capability-only MCP `initialize` handshake) - and classifies the server as healthy, degraded, dead, or unknown.
It never authenticates to a probed server and never executes a tool. Any GitHub token supplied is used solely against the public GitHub API as a higher-rate-limit measurement instrument, exactly as a human running `gh` would. Nothing here touches a user secret. This keeps the zero-key pledge true by construction.
Index ¶
Constants ¶
const DefaultUserAgent = "akashi (mcp health probe; keyless; +https://roninforge.org)"
DefaultUserAgent identifies akashi politely to every third party it probes.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Check ¶
type Check struct {
Name string `json:"name"`
Status Status `json:"status"`
Detail string `json:"detail,omitempty"`
}
Check is one line in the human-readable report.
type Engine ¶
type Engine struct {
HTTP *http.Client
// UserAgent is sent on every request.
UserAgent string
// GitHubToken, when set, is sent only to api.github.com to raise the rate
// limit. It is never sent to a probed server.
GitHubToken string
// Now supplies the clock; overridable in tests.
Now func() time.Time
// RemoteTimeout bounds each remote-endpoint request.
RemoteTimeout time.Duration
// RequestTimeout bounds each registry/repo/package request.
RequestTimeout time.Duration
// ProbeTools runs the go-sdk tools/list conformance probe on reachable,
// conformant remotes. Default true; a bulk scan can disable it for speed.
ProbeTools bool
// ValidateServerJSON validates a registry server's server.json against its
// declared JSON Schema. Default true.
ValidateServerJSON bool
// contains filtered or unexported fields
}
Engine runs keyless probes. The zero value is not usable; call NewEngine.
type PackageSignal ¶
type PackageSignal struct {
Type string `json:"type"` // npm|pypi|oci
ID string `json:"id"`
Status string `json:"status"` // published|missing|unpublished|unprobed|error
HTTPStatus int `json:"httpStatus,omitempty"`
Latest string `json:"latest,omitempty"`
Detail string `json:"detail,omitempty"`
}
PackageSignal is the raw package probe result for one entrypoint.
type RemoteSignal ¶
type RemoteSignal struct {
URL string `json:"url"`
Type string `json:"type,omitempty"`
Status string `json:"status"` // reachable|unreachable|server_error|not_found
HTTPStatus int `json:"httpStatus,omitempty"`
Conformance string `json:"conformance,omitempty"` // initialize_ok|auth_gated|reachable_nonconformant
Probe string `json:"probe,omitempty"` // get|initialize
IDEchoed *bool `json:"idEchoed,omitempty"` // did the initialize response echo the JSON-RPC id
Detail string `json:"detail,omitempty"`
// tools/list probe, run with the official MCP client after a conformant
// initialize. A completed session that lists tools is the strongest keyless
// proof that this is a real, working MCP server.
ToolsStatus string `json:"toolsStatus,omitempty"` // ok|empty|error|connect_failed
ToolCount int `json:"toolCount,omitempty"`
ToolNames []string `json:"toolNames,omitempty"`
}
RemoteSignal is the raw remote-endpoint probe result.
type RepoSignal ¶
type RepoSignal struct {
Kind string `json:"kind"` // github|other|none
Status string `json:"status"` // alive|archived|missing|error|unprobed|none
HTTPStatus int `json:"httpStatus,omitempty"`
Archived bool `json:"archived,omitempty"`
PushedAt string `json:"pushedAt,omitempty"`
AgeDays *int `json:"ageDays,omitempty"`
Stars *int `json:"stars,omitempty"`
License string `json:"license,omitempty"`
URL string `json:"url,omitempty"`
Detail string `json:"detail,omitempty"`
}
RepoSignal is the raw repository probe result.
type Result ¶
type Result struct {
Name string `json:"name"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
RegistryStatus string `json:"registryStatus,omitempty"`
Version string `json:"version,omitempty"`
Verdict Verdict `json:"verdict"`
Reasons []string `json:"reasons"`
Checks []Check `json:"checks"`
Signals Signals `json:"signals"`
AliveEntrypoints int `json:"aliveEntrypoints"`
ProbedEntrypoints int `json:"probedEntrypoints"`
CheckedAt string `json:"checkedAt"` // YYYY-MM-DD, UTC
}
Result is the per-server probe outcome: a verdict, the reasons behind it, a display-ready check list, and the raw signals for machine consumers. Title and Description are carried through unchanged from the registry (see registry.Server) so a downstream index page has a human title and a meta description without a second registry lookup; both are empty when the target was not resolved from the registry (a bare repo or remote URL) or when the registry itself has no title for that server.
type ServerJSONSignal ¶ added in v0.2.0
type ServerJSONSignal struct {
Status string `json:"status"` // valid|invalid|no_schema|absent|error
Schema string `json:"schema,omitempty"`
Errors []string `json:"errors,omitempty"`
}
ServerJSONSignal is the result of validating the server's published server.json against its declared JSON Schema.
type Signals ¶
type Signals struct {
Repo RepoSignal `json:"repo"`
Packages []PackageSignal `json:"packages"`
Remotes []RemoteSignal `json:"remotes"`
ServerJSON ServerJSONSignal `json:"serverJson"`
}
Signals is the full raw evidence behind a verdict.
type Verdict ¶
type Verdict string
Verdict is the overall health classification of a server.
const ( Healthy Verdict = "healthy" // at least one live entrypoint and nothing broken Degraded Verdict = "degraded" // usable, but something is broken Dead Verdict = "dead" // registry-deleted, or every probed entrypoint is broken Unknown Verdict = "unknown" // only un-probeable entrypoints declared )
Verdict values, from best to worst health.
Source Files