tools

Documentation

Overview

Package tools wires Spur-backed MCP tools onto an mcp.Server.

Index

• func Register(s *mcp.Server, c *spur.Client, dict *enumdict.Dict)
• type ExplainEnumInput
• type ExplainEnumOutput
• type ExportInput
• type ExportOutput
• type FeedDownloadInput
• type FeedDownloadOutput
• type FeedStatusInput
• type FeedStatusOutput
• type FormatAssessmentInput
• type FormatAssessmentOutput
• type GetAPIStatusInput
• type GetAPIStatusOutput
• type GetIPContextInput
• type GetIPContextOutput
• type GetTagMetadataInput
• type GetTagMetadataOutput
• type IPContextResult
• type ListFeedsInput
• type ListFeedsOutput

Functions

func Register

func Register(s *mcp.Server, c *spur.Client, dict *enumdict.Dict)

Register adds every Spur tool to s, wired to the provided client and enum dictionary.

Types

type ExplainEnumInput

type ExplainEnumInput struct {
	Value string `` /* 143-byte string literal not displayed */
}

ExplainEnumInput is the argument for explain_enum.

type ExplainEnumOutput

type ExplainEnumOutput struct {
	Matches []enumdict.Entry `json:"matches" jsonschema:"Entries that matched the value. Empty when no match."`
}

ExplainEnumOutput is the list of matching entries (one value can occur in multiple fields; each occurrence is reported).

type ExportInput

type ExportInput struct {
	Feed            string   `json:"feed" jsonschema:"Export feed: anonymous, anonymous-residential, ztna, dch, or ipgeo."`
	IPv6            bool     `json:"ipv6,omitempty" jsonschema:"Select the feed's IPv6 variant (anonymous, anonymous-residential, ztna)."`
	Format          string   `json:"format,omitempty" jsonschema:"Sample format: csv (default) or json. mmdb is binary and not returned over MCP."`
	Fields          []string `json:"fields,omitempty" jsonschema:"Columns to include and their order (feed-specific; default is the feed's full set)."`
	Tags            []string `json:"tags,omitempty" jsonschema:"Filter to IPs carrying any of these service tags (not accepted by dch/ipgeo)."`
	Ccs             []string `json:"ccs,omitempty" jsonschema:"Filter to these ISO country codes (not accepted by dch)."`
	Asns            []int    `json:"asns,omitempty" jsonschema:"Filter to these autonomous-system numbers."`
	CallbackProxies []string `json:"callback_proxies,omitempty" jsonschema:"Filter to these callback-proxy providers (anonymous-residential only)."`
	Attributed      *bool    `` /* 154-byte string literal not displayed */
	Diff            bool     `json:"diff,omitempty" jsonschema:"Return only changes versus the previous day (anonymous, ztna)."`
	DiffDate        string   `json:"diff_date,omitempty" jsonschema:"Return the diff against this date (YYYY-MM-DD; implies diff)."`
	CSVHeader       bool     `json:"csv_header,omitempty" jsonschema:"Prepend a header row to CSV output."`
	MaxRows         int      `json:"max_rows,omitempty" jsonschema:"Maximum rows to return in the sample (default 50, hard cap 1000)."`
}

ExportInput is the argument object for the export tool. It surfaces the same filters as `spur export`; which ones a given feed accepts is enforced by spur.BuildExportQuery, exactly as the command does.

type ExportOutput

type ExportOutput struct {
	Feed      string   `json:"feed" jsonschema:"The resolved export feed family."`
	Slug      string   `json:"slug" jsonschema:"The concrete feed slug queried (includes any -ipv6 suffix)."`
	Format    string   `json:"format" jsonschema:"The sample format: csv or json."`
	Rows      []string `json:"rows" jsonschema:"A bounded sample of raw export rows (CSV lines, or one JSON object per line), capped at max_rows."`
	RowCount  int      `json:"row_count" jsonschema:"Number of rows in this sample."`
	Truncated bool     `json:"truncated" jsonschema:"True when the export had more rows than the sample cap; run the command for the full result."`
	Command   string   `json:"command" jsonschema:"The spur CLI command that streams the full, unbounded export."`
}

ExportOutput is a bounded sample of an export plus enough context to fetch the full stream out-of-band.

type FeedDownloadInput

type FeedDownloadInput struct {
	Type   string `json:"type" jsonschema:"Feed type identifier from list_feeds, e.g. anonymous or anonymous-residential/realtime."`
	Format string `` /* 159-byte string literal not displayed */
	Date   string `json:"date,omitempty" jsonschema:"Optional historical release date (YYYYMMDD). Omit for the latest release."`
}

FeedDownloadInput is the argument object for feed_download.

type FeedDownloadOutput

type FeedDownloadOutput struct {
	Type        string              `json:"type" jsonschema:"The feed type this pointer describes."`
	Format      string              `json:"format" jsonschema:"The artifact format described: json or mmdb."`
	File        *spur.FeedFile      `` /* 257-byte string literal not displayed */
	DownloadURL string              `` /* 177-byte string literal not displayed */
	Command     string              `json:"command" jsonschema:"The spur CLI command that downloads this artifact."`
	Note        string              `json:"note" jsonschema:"Why the bytes are not returned inline."`
	Integrity   *spur.FeedIntegrity `` /* 237-byte string literal not displayed */
}

FeedDownloadOutput is a download pointer for a feed's data artifact: enough metadata to decide whether to fetch it, plus the URL and command that do.

type FeedStatusInput

type FeedStatusInput struct {
	Type string `json:"type" jsonschema:"Feed type identifier from list_feeds, e.g. anonymous or anonymous-residential/realtime."`
}

FeedStatusInput is the argument object for feed_status.

type FeedStatusOutput

type FeedStatusOutput struct {
	Metadata  spur.FeedMetadata   `` /* 181-byte string literal not displayed */
	Integrity *spur.FeedIntegrity `` /* 181-byte string literal not displayed */
}

FeedStatusOutput wraps the feed's metadata document.

type FormatAssessmentInput

type FormatAssessmentInput struct {
	Context    spur.IPContext              `json:"context" jsonschema:"The complete get_ip_context result for the IP being assessed."`
	Tags       map[string]spur.TagMetadata `` /* 275-byte string literal not displayed */
	BottomLine string                      `` /* 392-byte string literal not displayed */
	Assessment string                      `` /* 289-byte string literal not displayed */
}

FormatAssessmentInput is the argument object for format_assessment. The caller (LLM) passes the raw Spur responses alongside two short prose blocks it authors itself. The tool validates select fidelity rules around risk citations and density formatting, then renders the final customer-facing markdown deterministically.

type FormatAssessmentOutput

type FormatAssessmentOutput struct {
	Markdown string `` /* 173-byte string literal not displayed */
}

FormatAssessmentOutput wraps the rendered markdown. We return the final customer-facing text in a single field so clients can forward it without reassembly.

type GetAPIStatusInput

type GetAPIStatusInput struct{}

GetAPIStatusInput is intentionally empty — the endpoint takes no arguments.

type GetAPIStatusOutput

type GetAPIStatusOutput struct {
	Status spur.Status `json:"status" jsonschema:"Status of the configured SPUR_TOKEN."`
}

GetAPIStatusOutput is the API token status.

type GetIPContextInput

type GetIPContextInput struct {
	IP  string   `json:"ip,omitempty" jsonschema:"A single IPv4 or IPv6 address to look up. Provide this, ips, or both."`
	IPs []string `json:"ips,omitempty" jsonschema:"Several IPv4/IPv6 addresses to look up in one call. Provide this, ip, or both."`
	DT  string   `` /* 137-byte string literal not displayed */
}

GetIPContextInput is the argument object for get_ip_context. Supply either a single ip or a batch of ips (or both — they are concatenated in order).

type GetIPContextOutput

type GetIPContextOutput struct {
	Results []IPContextResult `json:"results" jsonschema:"One entry per requested IP, in request order. For a single IP this is a one-element list."`
}

GetIPContextOutput holds one result per requested IP, in request order.

type GetTagMetadataInput

type GetTagMetadataInput struct {
	Tag string `json:"tag" jsonschema:"Service tag to look up, e.g. OXYLABS_PROXY, PROTON_VPN, TOR_PROXY."`
}

GetTagMetadataInput is the argument object for get_tag_metadata.

type GetTagMetadataOutput

type GetTagMetadataOutput struct {
	Tag spur.TagMetadata `json:"tag" jsonschema:"Tag Metadata object. See resource spur://schemas/tag-metadata for the full field reference."`
}

GetTagMetadataOutput wraps the parsed tag metadata body.

type IPContextResult

type IPContextResult struct {
	IP      string          `json:"ip" jsonschema:"The IP address this result is for."`
	Context *spur.IPContext `` /* 158-byte string literal not displayed */
	Meta    *spur.Meta      `json:"meta,omitempty" jsonschema:"Response metadata derived from Spur response headers, omitted when this IP failed."`
	Error   string          `` /* 132-byte string literal not displayed */
}

IPContextResult is one IP's outcome in a get_ip_context batch: either the context (with response metadata) or a per-IP error. One failed IP does not fail the others.

type ListFeedsInput

type ListFeedsInput struct{}

ListFeedsInput is intentionally empty — the catalog takes no arguments.

type ListFeedsOutput

type ListFeedsOutput struct {
	Feeds []spur.FeedType `` /* 160-byte string literal not displayed */
}

ListFeedsOutput is the static Spur data-feed catalog.