Introducing a new way to review your PRs.

Read the announcement

koala73 / worldmonitor

Real-time global intelligence dashboard. AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface

View on GitHub

29 documents · Updated Nov 20, 2026

docs / sdk-client-libraries

SDK client libraries

WorldMonitor provides language-native clients for programmatic access to its global-intelligence data. The clients give applications one shared MCP tool surface and a small REST surface without requiring each consumer to build its own HTTP and JSON-RPC integration. This page belongs under desktop and external clients; related client surfaces include the CLI dashboard and the API platform.

SDK role

The SDKs let services, scripts, agents, and research tools query WorldMonitor through stable language-specific entry points. They are thin clients: the WorldMonitor MCP server remains the main documented data interface, while REST access supports health checks, host-relative endpoints, and self-hosted or alternate deployments.

Common client surface

Each client exposes a low-level operation for any MCP tool and a small set of convenience methods for common intelligence queries. This keeps new server tools available before every language receives a new helper.

The clients cover these shared use cases:

  • Discover public tools, prompt templates, and resources.
  • Call intelligence tools such as country risk, market data, conflict, cyber, news, disaster, sanctions, forecast, and maritime queries.
  • Apply optional server-side JMESPath projection to reduce response size.
  • Fetch a host-relative REST path or the API health result.
  • Return the server's JSON result so the consuming application can choose its own model layer.

References: sdk/…/__init__.py• L179-273 sdk/…/worldmonitor.go• L137-265 sdk/…/lib.rs• L132-243

Client interface styles

The interfaces are hand-authored wrappers, not generated model clients. Python, Ruby, and Go expose language-native methods that return decoded or raw JSON values. Rust uses a blocking client and returns serde_json::Value; the JavaScript package exposes the same request-planning and execution model through the worldmonitor npm package, which also provides the CLI.

The shared relationship between an application, an SDK, and the two service surfaces is:

flowchart LR
    A[Application or agent] --> B[Language SDK or npm client]
    B --> C[MCP endpoint]
    B --> D[REST endpoint]
    C --> E[WorldMonitor tools and intelligence data]
    D --> F[Health and host-relative API paths]

The SDK does not create a separate data model or cache. It translates the language-native call into the common wire request and passes the response or typed error back to the caller.

References: sdk/…/README.md• L1-5 sdk/…/README.md• L1-5 sdk/…/README.md• L1-5 cli/package.json• L24-32 cli/…/core.mjs• L1-10

Authentication and request conventions

The clients share one credential and request model so a consumer can move between languages without changing the service contract. Public discovery is separate from protected data access, and each client identifies itself on the wire.

Credential boundary

MCP tool discovery through tools/list, prompts/list, and resources/list is public. get_sources is the only data tool designed for anonymous use without daily quota consumption; anonymous source calls still have a separate 10-calls-per-minute-per-IP limit. Other data-bearing tool calls require a World Monitor subscription API key.

Clients accept a key directly or read WORLDMONITOR_API_KEY, with WM_API_KEY as a fallback in the supported clients. When present, the key travels in X-WorldMonitor-Key. Authentication errors remain visible as MCP JSON-RPC errors or REST API errors and include a hint about obtaining a key.

References: sdk/…/README.md• L18-27 sdk/…/README.md• L19-43 sdk/…/__init__.py• L40-50 sdk/…/worldmonitor.go• L48-60

MCP request contract

MCP calls use POST to the configured MCP endpoint with a JSON-RPC 2.0 envelope. A tool call names the tool and sends its named arguments as a JSON object. The clients accept normal JSON responses and finite Streamable HTTP responses delivered as server-sent events, then return the unwrapped result.

The result can contain MCP fields such as content, structuredContent, and isError. A JSON-RPC error takes priority over the HTTP status, because an authentication or tool error can arrive with an HTTP success status. Callers must therefore handle the SDK's MCP error type in addition to transport and HTTP errors.

References: sdk/…/__init__.py• L84-111 sdk/…/worldmonitor.go• L270-313 sdk/…/lib.rs• L245-286 sdk/…/README.md• L39-43

REST request contract

REST access uses GET against a host-relative path such as /api/health. Query values are passed separately and encoded by the client. The configured REST base defaults to https://api.worldmonitor.app, while the MCP endpoint defaults to https://worldmonitor.app/mcp.

Every request sends a versioned worldmonitor-<language>/<version> User-Agent. This identity is part of the edge request convention because generic library User-Agents can be challenged. Clients also apply a default request deadline of about 30 seconds, with language-specific configuration where supported. Redirects are not followed, which prevents an API key from being forwarded to another host.

References: sdk/…/__init__.py• L31-38 sdk/…/__init__.py• L114-150 sdk/…/__init__.py• L205-225 sdk/…/worldmonitor.go• L162-197 sdk/…/worldmonitor.go• L322-341 sdk/…/lib.rs• L207-237

Package and publication model

Each language package is released as an independent artifact with its own version and registry rules. Package metadata points back to the WorldMonitor product and source repository so consumers can distinguish official clients from similarly named projects.

Package distribution

The current package map is:

LanguagePackage or moduleDistribution pathClient shape
Pythonworldmonitor-sdkPyPIDependency-free synchronous client
RubyworldmonitorRubyGemsStandard-library synchronous client
Gogithub.com/koala73/worldmonitor/sdk/goGit tags, Go module proxy, and pkg.go.devStandard-library client with context-aware calls
Rustworldmonitorcrates.io and docs.rsBlocking client using Rustls and JSON values
JavaScriptworldmonitornpmImportable client logic and command-line client

Python, Ruby, and Go keep runtime dependencies minimal. Rust uses reqwest and serde_json; consumers do not need a desktop app or system OpenSSL installation. The Rust lockfile records the resolved dependency graph used for repeatable package builds. The JavaScript package requires Node 18.17 or newer.

References: sdk/…/pyproject.toml• L5-44 sdk/…/worldmonitor.gemspec• L5-29 sdk/…/go.mod• L1-3 sdk/…/Cargo.toml• L1-18 sdk/…/Cargo.lock• L1164-1170 cli/package.json• L1-48

Release channels

Publication is decoupled from desktop and CLI releases. The release workflows validate the package from its language directory, compare the package version with its SDK-specific tag, and then publish through the ecosystem's normal channel.

PackageRelease markerPublication behavior
Pythonpy-vX.Y.ZBuilds and checks the wheel and source archive, then uses PyPI trusted publishing.
Rubygem-vX.Y.ZBuilds the gem, then uses RubyGems trusted publishing.
Gosdk/go/vX.Y.ZThe repository tag is the release; the workflow validates it and warms the Go module proxy.
Rustrust-vX.Y.ZA manually dispatched workflow verifies the tag and commit, performs a dry run, and publishes the verified commit with crates.io OIDC after approval.

The package metadata and README files are part of the consumer contract. They carry the install name, product links, license, and registry-specific discovery information.

References: .github/…/publish-python.yml• L14-71 .github/…/publish-ruby.yml• L17-69 .github/…/publish-go.yml• L3-78 .github/…/publish-rust.yml• L3-88 sdk/…/RELEASING.md• L4-20

Compatibility checks

Compatibility depends on shared wire contracts rather than shared generated source. When the MCP server adds or changes a tool, each hand-authored wrapper must continue to pass the same tool name, argument names, response envelope, and error semantics.

Contract alignment

The main compatibility points are:

  • Tool names and named arguments match the MCP tool catalog.
  • Country helpers use ISO 3166-1 alpha-2 values and the server's country_code argument name.
  • JSON-RPC results are unwrapped without hiding MCP tool-level error fields.
  • SSE responses select the final usable data payload.
  • REST paths remain host-relative and query values remain separate from the path.
  • Authentication failures preserve the distinction between an MCP error and an HTTP error.
  • Redirect responses stop at the original host instead of carrying credentials to a new host.

The low-level call_tool operation is the forward-compatibility path. Curated helpers improve common calls, but they must not become the only way to reach new tools or optional arguments.

References: sdk/…/test_client.py• L91-185 sdk/…/test_client.py• L187-236 sdk/…/worldmonitor_test.go• L47-239 sdk/…/worldmonitor_test.go• L264-289 sdk/…/client.rs• L55-263 sdk/…/test_worldmonitor.rb• L71-169 sdk/…/test_worldmonitor.rb• L181-220

Version and package checks

The repository checks package identity, product-domain metadata, version declarations, User-Agent identity, and publication wiring. Native package tests use local transports or fixtures, so they can verify wire behavior without a live API key.

Version declarations must remain aligned with the release process:

  • Python stores the version in both pyproject.toml and the importable module.
  • Ruby stores it in the shared version file used by the gemspec and workflow.
  • Go stores it in the exported Version constant checked against the module tag.
  • Rust derives the public version from the Cargo manifest and checks the release tag against that manifest.
  • JavaScript keeps the package and client version aligned for npm publication and User-Agent identity.

References: tests/sdk-packages.test.mjs• L10-18 tests/sdk-packages.test.mjs• L19-80 sdk/…/pyproject.toml• L5-12 sdk/…/__init__.py• L31-35 sdk/…/version.rb• L1-5 sdk/…/worldmonitor.go• L39-46 .github/…/publish-python.yml• L44-62 .github/…/publish-go.yml• L40-54 .github/…/publish-rust.yml• L40-62

Change checklist

When these files or sections are changed, remember to consider these:

  • A new or renamed MCP tool must remain reachable through the generic client method even if no curated helper is added.
  • Changes to tool argument names, country code fields, JMESPath handling, or JSON-RPC envelopes must be checked in every language client and its wire-contract tests.
  • A package version change must update the language's source version declaration, manifest or gemspec, User-Agent, and release tag rule together.
  • A new package registry or install name must update package metadata, SDK discovery pages, and the matching publication workflow.
  • Changes to authentication headers, anonymous access, endpoint defaults, or redirect handling must be checked against all SDKs and the external client surfaces that share the MCP contract.
  • A Rust dependency change must keep the manifest and lockfile aligned before package publication.

Important failure modes

TriggerConsequenceGuard
A data tool call omits a subscription keyThe MCP server returns an authentication error, sometimes with HTTP status 200Handle the JSON-RPC error before the HTTP status and surface the key hint
A client sends a generic User-AgentThe API edge can challenge or reject the requestKeep the versioned worldmonitor-<language>/<version> User-Agent
A wrapper uses the wrong tool argument nameThe server receives a valid request with invalid semanticsTest the complete JSON-RPC params.arguments contract
A release tag and package version differPublication stops or points consumers at the wrong versionRun the language-specific version-to-tag checks before publication
A REST caller embeds a query or absolute URL in the pathThe request can target the wrong resource or fail validationRequire a host-relative path and pass query parameters separately
An MCP client treats a tool-level isError result as an HTTP failure onlyThe consuming program can accept an unsuccessful tool result as valid dataPreserve the MCP result fields and inspect tool-level error state
A client follows a redirect to another hostThe API key can be sent to the redirect targetStop on 3xx responses and return them as API errors
The Rust manifest and lockfile resolve different dependency setsA package build can differ from the checked release stateRefresh and review the lockfile with the manifest change

Key files

FileWhy to read it
sdk/…/__init__.pyComplete hand-authored Python client contract and error model
sdk/…/worldmonitor.goGo client interface, context-aware requests, and exported compatibility constants
sdk/…/lib.rsRust client configuration, blocking behavior, validation, and error variants
sdk/…/worldmonitor.rbRuby client interface and shared request behavior
cli/…/core.mjsJavaScript client request planning and the shared CLI-facing MCP conventions
tests/sdk-packages.test.mjsCross-package identity, metadata, version, and publication checks
.github/…/publish-python.ymlPython build, tag check, and PyPI publication path
.github/…/publish-ruby.ymlRuby build, tag check, and RubyGems publication path
.github/…/publish-go.ymlGo module tag validation and proxy publication path
.github/…/publish-rust.ymlRust release verification and crates.io publication path