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"`
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.
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