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:
| Language | Package or module | Distribution path | Client shape |
|---|---|---|---|
| Python | worldmonitor-sdk | PyPI | Dependency-free synchronous client |
| Ruby | worldmonitor | RubyGems | Standard-library synchronous client |
| Go | github.com/koala73/worldmonitor/sdk/go | Git tags, Go module proxy, and pkg.go.dev | Standard-library client with context-aware calls |
| Rust | worldmonitor | crates.io and docs.rs | Blocking client using Rustls and JSON values |
| JavaScript | worldmonitor | npm | Importable 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.
| Package | Release marker | Publication behavior |
|---|---|---|
| Python | py-vX.Y.Z | Builds and checks the wheel and source archive, then uses PyPI trusted publishing. |
| Ruby | gem-vX.Y.Z | Builds the gem, then uses RubyGems trusted publishing. |
| Go | sdk/go/vX.Y.Z | The repository tag is the release; the workflow validates it and warms the Go module proxy. |
| Rust | rust-vX.Y.Z | A 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_codeargument 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
Versionconstant 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
| Trigger | Consequence | Guard |
|---|---|---|
| A data tool call omits a subscription key | The MCP server returns an authentication error, sometimes with HTTP status 200 | Handle the JSON-RPC error before the HTTP status and surface the key hint |
| A client sends a generic User-Agent | The API edge can challenge or reject the request | Keep the versioned worldmonitor-<language>/<version> User-Agent |
| A wrapper uses the wrong tool argument name | The server receives a valid request with invalid semantics | Test the complete JSON-RPC params.arguments contract |
| A release tag and package version differ | Publication stops or points consumers at the wrong version | Run the language-specific version-to-tag checks before publication |
| A REST caller embeds a query or absolute URL in the path | The request can target the wrong resource or fail validation | Require a host-relative path and pass query parameters separately |
An MCP client treats a tool-level isError result as an HTTP failure only | The consuming program can accept an unsuccessful tool result as valid data | Preserve the MCP result fields and inspect tool-level error state |
| A client follows a redirect to another host | The API key can be sent to the redirect target | Stop on 3xx responses and return them as API errors |
| The Rust manifest and lockfile resolve different dependency sets | A package build can differ from the checked release state | Refresh and review the lockfile with the manifest change |
Key files
| File | Why to read it |
|---|---|
| sdk/…/__init__.py | Complete hand-authored Python client contract and error model |
| sdk/…/worldmonitor.go | Go client interface, context-aware requests, and exported compatibility constants |
| sdk/…/lib.rs | Rust client configuration, blocking behavior, validation, and error variants |
| sdk/…/worldmonitor.rb | Ruby client interface and shared request behavior |
| cli/…/core.mjs | JavaScript client request planning and the shared CLI-facing MCP conventions |
| tests/sdk-packages.test.mjs | Cross-package identity, metadata, version, and publication checks |
| .github/…/publish-python.yml | Python build, tag check, and PyPI publication path |
| .github/…/publish-ruby.yml | Ruby build, tag check, and RubyGems publication path |
| .github/…/publish-go.yml | Go module tag validation and proxy publication path |
| .github/…/publish-rust.yml | Rust release verification and crates.io publication path |