@communitywolf/sia

The Safety Intelligence API toolkit — TypeScript SDK, CLI, and MCP server in one package.

@communitywolf/sia is the official client for the Community Wolf Safety Intelligence API. One install gives you three surfaces against the same API, plus four agent skills that teach AI tools how to use them.

• TypeScript SDK — import { Client, hexLookup } from "@communitywolf/sia"
• CLI — sia health, sia hex lookup …, sia intents, …
• MCP server — sia mcp (stdio, drop into Cursor / Claude / VS Code)
• Agent skills — npx skills add Community-Wolf-Limited/sia-toolkit --skill sia (Markdown, teach the agent how to use the tools)

All four share the same auth, the same input schemas, and the same response types. Adding a new capability means writing one tool function — the SDK, CLI, MCP, and skills pick it up together.

Install

# Global install (recommended for the CLI + MCP)
npm install -g @communitywolf/sia

# Or per-project as an SDK
npm install @communitywolf/sia

Requires Node ≥ 18.

Authenticate

Issue a partner API key from the SIA developer portal and set two environment variables:

export SIA_API_KEY="cw_<id>_<secret>"
export SIA_API_URL="https://sia.communitywolf.com"   # optional, this is the default

Verify it works:

sia health
# ✓ health ok
# {
#   "hexCount": 3829928,
#   "precinctCount": 5970,
#   "success": true,
#   ...
# }

CLI

The CLI groups tools by domain. Run sia --help or any subcommand --help for usage.

sia --help
sia health
sia intents

# Hex queries — pre-computed, 5-source breakdown
sia hex get --h3 8828308281fffff
sia hex get --h3 8828308281fffff --details         # forensic per-source data
sia hex lookup --lat -33.92 --lng 18.42 --ring 1   # ring of hexes from coords
sia hex details --h3 8828308281fffff               # verbose per-layer breakdown

# Infrastructure (POIs / OSM with names, brand, taxonomy, risk class)
sia infrastructure lookup --lat -33.92 --lng 18.42 --ring 1
sia infra lookup --lat -33.92 --lng 18.42 --ring 0   # short alias

# MCP server (stdio)
sia mcp

Output formatting

Every subcommand respects three global flags on the root program:

| Flag | Behaviour | |---|---| | (default) | Pretty-printed JSON to stdout, green tick to stderr | | --json | Compact one-line JSON to stdout, no tick, no colour. Pipe-friendly. | | --pretty | Explicit pretty-print (same as default). | | --no-color | Strip ANSI colour from stderr only. |

sia hex lookup --lat -33.92 --lng 18.42 --ring 1 --json | jq '.results[0].safetyScore'

The CLI exits 0 on success, 1 on any HTTP or validation error, and writes errors in red to stderr (or as { "ok": false, "error": "..." } in --json mode).

MCP server

Add to your Cursor / Claude / VS Code MCP config:

{
  "mcpServers": {
    "sia": {
      "command": "npx",
      "args": ["-y", "@communitywolf/sia", "mcp"],
      "env": {
        "SIA_API_KEY": "cw_<id>_<secret>"
      }
    }
  }
}

The server registers six tools:

| Tool | Wraps | Use for | | --------------------------- | ---------------------------------------------- | ------------------------------------------------------ | | sia_health | GET /health | Connectivity + key check. | | sia_intents | GET /api/intents | Discover valid intent values before scoring queries. | | sia_hex_get | GET /v3/hex/{h3} | Single hex with 5-source breakdown. | | sia_hex_lookup | POST /v3/hex/lookup | Lat/lng + ring → array of hexes with breakdown. Flagship. | | sia_hex_details | GET /v3/hex/{h3}/details | Verbose per-layer breakdown — for "why" / "explain". | | sia_infrastructure_lookup | POST /api/infrastructure-ontology/lookup | POI / OSM rollups with names, brand, taxonomy, risk class. |

More tools land as the SIA API grows — see CHANGELOG.md.

Agent skills

The toolkit ships four agent skills that teach AI agents (Cursor, Claude, VS Code, …) how to use SIA correctly — concept orientation, tool ordering, payload trade-offs, gotchas. Tool descriptions tell the agent that a tool exists; skills make it good at composing them.

| Skill | When it loads | |---|---| | sia | Concepts overview — H3, intents, 5-source breakdown, country scoping, auth | | sia-cli | Terminal usage — install, commands, output flags, piping | | sia-mcp | Agents calling SIA MCP tools — selection, ordering, common workflows | | sia-sdk | Building features in TypeScript — Next.js, edge, error handling |

Install with the standard skills CLI:

# One skill (most common — load only what's relevant)
npx skills add Community-Wolf-Limited/sia-toolkit --skill sia

# All four
for s in sia sia-cli sia-mcp sia-sdk; do
  npx skills add Community-Wolf-Limited/sia-toolkit --skill "$s"
done

Or copy directly from the bundled npm package (node_modules/@communitywolf/sia/skills/) or GitHub raw URLs.

See skills/README.md for the full install guide and per-skill summaries.

SDK

import { Client, hexLookup, intents } from "@communitywolf/sia";

const client = new Client();

// Discover the available scoring intents
const intentList = await intents(client);
console.log(Object.keys(intentList.data));
// → ['business', 'holiday', 'invest', 'live', 'night', 'none', 'overall', 'travel', 'walk']

// Resolve a coordinate into an array of pre-computed hexes
const out = await hexLookup(client, {
  lat: -33.92,
  lng: 18.42,
  ring: 1,
});

console.log(out.count, out.results[0].safetyScore);

Or use the lower-level HTTP client directly:

import { Client } from "@communitywolf/sia";

const client = new Client();
const breakdown = await client.get(`/v3/hex/8828308281fffff?include=details`);

Errors are thrown as SiaError with an HTTP status and decoded body:

import { Client, SiaError } from "@communitywolf/sia";

try {
  await new Client().get("/health");
} catch (err) {
  if (err instanceof SiaError && err.status === 401) {
    // handle bad key
  }
  throw err;
}

Development

git clone https://github.com/Community-Wolf-Limited/sia-toolkit.git
cd sia-toolkit
npm install
npm run build
npm test
npm run smoke:cli   # `sia --help`
npm run smoke:mcp   # JSON-RPC stdio handshake + tools/list

The package layout:

src/
├── auth.ts          # env → credentials
├── client.ts        # HTTP client (X-API-Key, JSON, error mapping, get/post/delete)
├── errors.ts        # SiaError class
├── types.ts         # API request/response types
├── cli-utils.ts     # runTool helper + output formatting
├── tools/           # one file per capability — used by CLI + MCP + SDK
│   ├── health.ts
│   ├── hex-get.ts
│   ├── hex-lookup.ts
│   ├── hex-details.ts
│   ├── infrastructure-lookup.ts
│   └── intents.ts
├── cli.ts           # `sia` binary (commander)
├── mcp.ts           # MCP server on stdio
└── index.ts         # public SDK exports

skills/              # agent skill markdown — bundled in npm and installable via `npx skills add`
├── README.md
├── sia/SKILL.md
├── sia-cli/SKILL.md
├── sia-mcp/SKILL.md
└── sia-sdk/SKILL.md

Adding a new tool:

1. Write src/tools/<name>.ts with a Zod schema, types, and an async function.
2. Register a CLI subcommand in src/cli.ts via runTool(program, ..., async () => ...).
3. Register an MCP tool in src/mcp.ts via server.registerTool(...).
4. Re-export from src/index.ts.

That's it — same source of truth across all three surfaces.

Licence

MIT © Community Wolf