worldmonitor

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 5, 2026 License: MIT Imports: 10 Imported by: 0

README

worldmonitor (Go)

Official Go SDK for the World Monitor global-intelligence API — country briefs, risk scores, conflict / cyber / market / news feeds, and every MCP tool, without writing an HTTP integration.

Stdlib-only (zero dependencies), MCP-first: the same design as the official worldmonitor npm CLI. The MCP server is the live, documented agent surface; a small REST escape hatch rounds it out.

Install

go get github.com/koala73/worldmonitor/sdk/go

Quickstart

package main

import (
	"context"
	"fmt"

	worldmonitor "github.com/koala73/worldmonitor/sdk/go"
)

func main() {
	ctx := context.Background()
	client := worldmonitor.New("wm_...") // or "" to read WORLDMONITOR_API_KEY

	tools, _ := client.ListTools(ctx) // public — no key needed
	fmt.Println(string(tools))

	risk, err := client.CountryRisk(ctx, "IR", nil) // curated helper
	if err != nil {
		panic(err)
	}
	fmt.Println(string(risk))

	// Any MCP tool:
	quotes, _ := client.CallTool(ctx, "get_market_data", worldmonitor.Args{"asset_class": "crypto"})
	fmt.Println(string(quotes))

	// Raw REST GET:
	health, _ := client.Get(ctx, "/api/health", nil)
	fmt.Println(string(health))
}

Data calls (tools/call) need a user API key — get one at worldmonitor.app/pro. Listing tools, prompts, and resources is public.

Server-side projection

Every tool accepts an optional jmespath argument that projects the response server-side (typically an 80–95% size cut):

brief, _ := client.WorldBrief(ctx, worldmonitor.Args{"jmespath": "hotspots[].name"})

See the JMESPath guide for worked examples.

Errors

  • *worldmonitor.MCPError — the MCP server returned a JSON-RPC error (.Code, auth failures carry a key hint).
  • *worldmonitor.APIError — a REST/transport failure (.Status, .Body).

Use errors.As to branch on them.

Configuration

Field Environment variable Default
APIKey WORLDMONITOR_API_KEY (or WM_API_KEY) —
BaseURL WORLDMONITOR_BASE_URL https://api.worldmonitor.app
MCPURL WORLDMONITOR_MCP_URL https://worldmonitor.app/mcp
HTTPClient — http.Client with a 30s timeout

The source lives in sdk/go/ in the main repository and is versioned with sdk/go/vX.Y.Z tags. Docs: worldmonitor.app/docs/sdks. License: MIT (thin client; the World Monitor platform itself remains AGPL-3.0).

Documentation

Overview

Package worldmonitor is the official Go SDK for the World Monitor global-intelligence API (https://worldmonitor.app) — country briefs, risk scores, conflict/cyber/market/news feeds, and MCP tools without writing an HTTP integration.

Stdlib-only (zero dependencies), MCP-first — the same design as the worldmonitor npm CLI this mirrors (cli/ in the main repository). The MCP server (https://worldmonitor.app/mcp) is the live, documented agent surface: tools/list is public, and tools/call (used by the curated helpers) authenticates with a user API key. A small REST escape hatch (Get/Health) rounds it out for host-relative and self-hosted use. 

client := worldmonitor.New("wm_...") // or "" to read WORLDMONITOR_API_KEY
risk, err := client.CountryRisk(ctx, "IR", nil)
quotes, err := client.CallTool(ctx, "get_market_data", worldmonitor.Args{"asset_class": "crypto"})
health, err := client.Get(ctx, "/api/health", nil)

Every tool accepts an optional "jmespath" argument for server-side projection (typically an 80-95% response-size cut), e.g. Args{"jmespath": "hotspots[].name"}.

Index

Constants

View Source 
const (
	DefaultBaseURL = "https://api.worldmonitor.app"
	DefaultMCPURL  = "https://worldmonitor.app/mcp"

	// APIKeyHeader is the header the API accepts for a user-issued key
	// (alias: X-Api-Key).
	APIKeyHeader = "X-WorldMonitor-Key"

	// MCPAuthErrorCode is the JSON-RPC error code the MCP server returns
	// when a call needs authentication.
	MCPAuthErrorCode = -32001
)
View Source 
const UserAgent = "worldmonitor-go/" + Version + " (+https://worldmonitor.app)"

UserAgent identifies the SDK on every request. Cloudflare's WAF challenges generic library User-Agents (Go-http-client, curl, empty) on the API edge, so we always identify ourselves.

View Source 
const Version = "0.1.1"

Version of this SDK. The release workflow checks it against the sdk/go/vX.Y.Z tag before warming the module proxy.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	Status int
	Body   json.RawMessage
}

APIError is a REST or transport-level failure (non-2xx HTTP response).

func (*APIError) Error 

func (e *APIError) Error() string

type Args 

type Args map[string]any

Args holds the named arguments of an MCP tool call or REST query.

type Client 

type Client struct {
	// APIKey is the user API key sent as X-WorldMonitor-Key.
	APIKey string
	// BaseURL is the REST base (default https://api.worldmonitor.app).
	BaseURL string
	// MCPURL is the MCP endpoint (default https://worldmonitor.app/mcp).
	MCPURL string
	// HTTPClient performs requests; override its Transport in tests.
	HTTPClient *http.Client
}

Client is a thin client for the World Monitor MCP server and REST API. The zero value is not usable; construct it with New.

func New 

func New(apiKey string) *Client

New returns a Client. An empty apiKey falls back to the WORLDMONITOR_API_KEY (or WM_API_KEY) environment variable; the REST and MCP endpoints honour WORLDMONITOR_BASE_URL and WORLDMONITOR_MCP_URL.

func (*Client) CallTool 

func (c *Client) CallTool(ctx context.Context, name string, args Args) (json.RawMessage, error)

CallTool calls an MCP tool by name and returns the unwrapped JSON-RPC result. A nil args map is allowed.

func (*Client) ConflictEvents 

func (c *Client) ConflictEvents(ctx context.Context, args Args) (json.RawMessage, error)

ConflictEvents returns recent conflict events (country, min_fatalities, limit, ...).

func (*Client) CountryBrief 

func (c *Client) CountryBrief(ctx context.Context, countryCode string, args Args) (json.RawMessage, error)

CountryBrief returns the AI strategic brief for a country (ISO 3166-1 alpha-2 code).

func (*Client) CountryRisk 

func (c *Client) CountryRisk(ctx context.Context, countryCode string, args Args) (json.RawMessage, error)

CountryRisk returns country risk / resilience scores (ISO 3166-1 alpha-2 code).

func (*Client) CyberThreats 

func (c *Client) CyberThreats(ctx context.Context, args Args) (json.RawMessage, error)

CyberThreats returns cyber-threat indicators (min_severity, threat_type, country, ...).

func (*Client) ForecastPredictions 

func (c *Client) ForecastPredictions(ctx context.Context, args Args) (json.RawMessage, error)

ForecastPredictions returns scenario forecasts (domain, region, ...).

func (*Client) Get 

func (c *Client) Get(ctx context.Context, path string, params Args) (json.RawMessage, error)

Get performs a GET against a raw REST path (host-relative, e.g. "/api/health") with optional query parameters.

func (*Client) Health 

func (c *Client) Health(ctx context.Context) (json.RawMessage, error)

Health fetches the API status / health check.

func (*Client) ListPrompts 

func (c *Client) ListPrompts(ctx context.Context) (json.RawMessage, error)

ListPrompts lists MCP prompt templates (public).

func (*Client) ListResources 

func (c *Client) ListResources(ctx context.Context) (json.RawMessage, error)

ListResources lists MCP resources (public).

func (*Client) ListTools 

func (c *Client) ListTools(ctx context.Context) (json.RawMessage, error)

ListTools lists every MCP tool (public - no key needed).

func (*Client) MaritimeActivity 

func (c *Client) MaritimeActivity(ctx context.Context, countryCode string, args Args) (json.RawMessage, error)

MaritimeActivity returns maritime / port activity for a country (ISO 3166-1 alpha-2 code).

func (*Client) MarketData 

func (c *Client) MarketData(ctx context.Context, args Args) (json.RawMessage, error)

MarketData returns equities, commodities, crypto and FX quotes.

func (*Client) NaturalDisasters 

func (c *Client) NaturalDisasters(ctx context.Context, args Args) (json.RawMessage, error)

NaturalDisasters returns earthquakes, fires and storms (dataset, active_only, min_magnitude, ...).

func (*Client) NewsIntelligence 

func (c *Client) NewsIntelligence(ctx context.Context, args Args) (json.RawMessage, error)

NewsIntelligence returns classified news intelligence (topic, country, alerts_only, ...).

func (*Client) SanctionsData 

func (c *Client) SanctionsData(ctx context.Context, args Args) (json.RawMessage, error)

SanctionsData returns sanctions designations (country, entity_type, query, ...).

func (*Client) WorldBrief 

func (c *Client) WorldBrief(ctx context.Context, args Args) (json.RawMessage, error)

WorldBrief returns the live global situation brief.

type MCPError 

type MCPError struct {
	Code    int
	Message string
	Data    json.RawMessage
}

MCPError is a JSON-RPC error returned by the MCP server.

func (*MCPError) Error 

func (e *MCPError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.