feat: add a tool catalog and local MCP server

Define tools that answer questions from the app's data once, independent of the surface that exposes them. A tool declares its arguments and the services it reads; applications compose tools with their own services and optional call interceptors. Queries reuse the layers' portable source factories, so they run wherever an application routes /api requests. The first queries are get_earthquakes, get_active_fires and get_recent_launches, with a shared area argument (place name, bounding box, or point and radius) and capped lists. gods-eye-view/tools/mcp adapts a catalog to the Model Context Protocol with a small JSON-RPC handler and a stateless HTTP transport, adding no dependencies. npm run mcp serves Core's tools over stdio to local clients such as Claude Code, reading from a running app. Both exports are portable and checked by check:boundaries; the app does not import them.
2026-11-05 10:53:59 +00:00 · 2026-10-01 11:51:59 -07:00
1 parent e7707d9a0f
commit c3dfa8e853
@@ -0,0 +1,98 @@
+/** Natural hazard queries: earthquakes and active fires. */
+
+import { defineTool, ToolError } from '../catalog.js';
+import { AREA_SCHEMA, areaContains, resolveArea } from '../area.js';
+import { LIMIT_SCHEMA, capRows, countNoun, isoTime } from '../results.js';
+
+export const getEarthquakes = defineTool({
+  name: 'get_earthquakes',
+  title: 'Recent earthquakes',
+  description:
+    'Earthquakes of magnitude 2.5 or more from the USGS feed for the last 24 ' +
+    'hours, strongest first. Optionally limited to an area and a minimum magnitude.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      area: AREA_SCHEMA,
+      min_magnitude: { type: 'number', minimum: 2.5, maximum: 10 },
+      limit: LIMIT_SCHEMA,
+    },
+    additionalProperties: false,
+  },
+  requires: ['earthquakes'],
+  async run(args, { services, signal }) {
+    const area = args.area
+      ? await resolveArea(args.area, { services, signal })
+      : null;
+    const minimum = args.min_magnitude ?? 2.5;
+    const events = (await services.earthquakes.getSnapshot({ signal }))
+      .filter(
+        (event) => event.mag >= minimum && (!area || areaContains(area, event)),
+      )
+      .sort((a, b) => b.mag - a.mag || (b.time ?? 0) - (a.time ?? 0));
+    const result = capRows(events, args.limit);
+    const where = area ? ` in ${area.label}` : ' worldwide';
+    const strongest = events[0]
+      ? `; strongest M${events[0].mag.toFixed(1)}${events[0].place ? ` ${events[0].place}` : ''}`
+      : '';
+    return {
+      summary: `${countNoun(events.length, 'earthquake')} of M${minimum}+ in the last 24 hours${where}${strongest}.`,
+      data: {
+        ...result,
+        rows: result.rows.map((event) => ({
+          id: event.usgsId ?? event.stableId,
+          magnitude: event.mag,
+          place: event.place,
+          time: isoTime(event.time),
+          lat: event.lat,
+          lon: event.lon,
+          depth_km: event.depthKm,
+        })),
+      },
+    };
+  },
+});
+
+export const getActiveFires = defineTool({
+  name: 'get_active_fires',
+  title: 'Active fires',
+  description:
+    'Satellite fire detections from NASA FIRMS in the last 24 hours within an ' +
+    'area, most intense (fire radiative power) first.',
+  inputSchema: {
+    type: 'object',
+    properties: { area: AREA_SCHEMA, limit: LIMIT_SCHEMA },
+    required: ['area'],
+    additionalProperties: false,
+  },
+  requires: ['fires'],
+  async run(args, { services, signal }) {
+    const area = await resolveArea(args.area, { services, signal });
+    const snapshot = await services.fires.getSnapshot({ signal });
+    if (snapshot.keyRequired)
+      throw new ToolError(
+        'unavailable',
+        'Fire detections need a NASA FIRMS key configured for this server',
+      );
+    const fires = snapshot.fires
+      .filter((fire) => areaContains(area, fire))
+      .sort((a, b) => (b.frp ?? 0) - (a.frp ?? 0));
+    const result = capRows(fires, args.limit);
+    return {
+      summary: `${countNoun(fires.length, 'fire detection')} in ${area.label} in the last 24 hours.`,
+      data: {
+        ...result,
+        rows: result.rows.map((fire) => ({
+          lat: fire.lat,
+          lon: fire.lon,
+          frp_mw: fire.frp ?? null,
+          confidence: fire.confidence ?? null,
+          acquired:
+            [fire.acqDate, fire.acqTime].filter(Boolean).join(' ') || null,
+          satellite: fire.satellite ?? null,
+          day_night: fire.daynight ?? null,
+        })),
+      },
+    };
+  },
+});
@@ -0,0 +1,202 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { composeCatalog, coreTools } from '../index.js';
+
+const earthquakes = {
+  getSnapshot: async () => [
+    {
+      stableId: 'a',
+      usgsId: 'us1',
+      lon: 121.5,
+      lat: 24,
+      depthKm: 10,
+      mag: 5.1,
+      place: 'near Hualien',
+      time: Date.UTC(2026, 0, 1, 1),
+    },
+    {
+      stableId: 'b',
+      usgsId: 'us2',
+      lon: -120,
+      lat: 36,
+      depthKm: 5,
+      mag: 3.2,
+      place: 'Central California',
+      time: Date.UTC(2026, 0, 1, 2),
+    },
+    {
+      stableId: 'c',
+      usgsId: null,
+      lon: 122,
+      lat: 23.5,
+      depthKm: null,
+      mag: 2.6,
+      place: null,
+      time: null,
+    },
+  ],
+};
+const fires = (snapshot) => ({ getSnapshot: async () => snapshot });
+const launches = (payload) => ({ getLaunches: async () => payload });
+const taiwan = {
+  resolve: async () => ({
+    name: 'Taiwan',
+    bounds: { west: 119, south: 21, east: 123, north: 26 },
+  }),
+};
+
+test('earthquakes are filtered, ordered strongest first and capped', async () => {
+  const catalog = composeCatalog({
+    tools: coreTools,
+    services: { earthquakes, places: taiwan },
+  });
+  const all = await catalog.call('get_earthquakes', {});
+  assert.equal(
+    all.summary,
+    '3 earthquakes of M2.5+ in the last 24 hours worldwide; strongest M5.1 near Hualien.',
+  );
+  assert.deepEqual(
+    all.data.rows.map((row) => row.id),
+    ['us1', 'us2', 'c'],
+  );
+  assert.deepEqual(all.data.rows[0], {
+    id: 'us1',
+    magnitude: 5.1,
+    place: 'near Hualien',
+    time: '2026-01-01T01:00:00.000Z',
+    lat: 24,
+    lon: 121.5,
+    depth_km: 10,
+  });
+
+  const local = await catalog.call('get_earthquakes', {
+    area: { place: 'Taiwan' },
+    min_magnitude: 3,
+    limit: 1,
+  });
+  assert.equal(
+    local.summary,
+    '1 earthquake of M3+ in the last 24 hours in Taiwan; strongest M5.1 near Hualien.',
+  );
+  assert.deepEqual(
+    {
+      total: local.data.total,
+      returned: local.data.returned,
+      truncated: local.data.truncated,
+    },
+    { total: 1, returned: 1, truncated: false },
+  );
+
+  const capped = await catalog.call('get_earthquakes', { limit: 2 });
+  assert.equal(capped.data.truncated, true);
+  assert.equal(capped.data.total, 3);
+});
+
+test('fires need an area and report a missing key as unavailable', async () => {
+  const snapshot = {
+    fires: [
+      {
+        lat: 24,
+        lon: 121,
+        frp: 12,
+        confidence: 'h',
+        acqDate: '2026-01-01',
+        acqTime: '0130',
+        satellite: 'N',
+        daynight: 'N',
+      },
+      { lat: 25, lon: 122, frp: 40 },
+      { lat: -33, lon: 151, frp: 99 },
+    ],
+  };
+  const catalog = composeCatalog({
+    tools: coreTools,
+    services: { fires: fires(snapshot), places: taiwan },
+  });
+  await assert.rejects(catalog.call('get_active_fires', {}), /missing area/);
+  const result = await catalog.call('get_active_fires', {
+    area: { place: 'Taiwan' },
+  });
+  assert.equal(
+    result.summary,
+    '2 fire detections in Taiwan in the last 24 hours.',
+  );
+  assert.deepEqual(
+    result.data.rows.map((row) => row.frp_mw),
+    [40, 12],
+  );
+  assert.equal(result.data.rows[1].acquired, '2026-01-01 0130');
+
+  const keyless = composeCatalog({
+    tools: coreTools,
+    services: { fires: fires({ keyRequired: true }) },
+  });
+  await assert.rejects(
+    keyless.call('get_active_fires', { area: { bbox: [0, 0, 1, 1] } }),
+    (error) =>
+      error.code === 'unavailable' && /NASA FIRMS key/.test(error.message),
+  );
+});
+
+test('recent launches are newest first with missing fields as null', async () => {
+  const catalog = composeCatalog({
+    tools: coreTools,
+    services: {
+      launches: launches({
+        results: [
+          {
+            id: 'old',
+            name: 'Falcon 9 | Starlink',
+            net: '2026-01-01T00:00:00Z',
+            status: { name: 'Launch Successful' },
+          },
+          {
+            id: 'new',
+            name: 'Electron | Mission',
+            net: '2026-01-05T00:00:00Z',
+            launch_service_provider: { name: 'Rocket Lab' },
+            rocket: { configuration: { full_name: 'Electron' } },
+            pad: { name: 'LC-1A', location: { name: 'Mahia' } },
+            mission: { name: 'Mission', orbit: { name: 'Low Earth Orbit' } },
+          },
+          { id: 'unnamed' },
+        ],
+      }),
+    },
+  });
+  const result = await catalog.call('get_recent_launches', {});
+  assert.equal(
+    result.summary,
+    '2 launches in the last 30 days; latest Electron | Mission.',
+  );
+  assert.deepEqual(result.data.rows[0], {
+    id: 'new',
+    name: 'Electron | Mission',
+    time: '2026-01-05T00:00:00Z',
+    status: null,
+    provider: 'Rocket Lab',
+    rocket: 'Electron',
+    pad: 'LC-1A',
+    location: 'Mahia',
+    mission: 'Mission',
+    orbit: 'Low Earth Orbit',
+  });
+  const broken = composeCatalog({
+    tools: coreTools,
+    services: { launches: launches({}) },
+  });
+  await assert.rejects(
+    broken.call('get_recent_launches', {}),
+    (error) => error.code === 'malformed',
+  );
+});
+
+test('every core tool is a read-only query with a unique name', () => {
+  const names = coreTools.map((tool) => tool.name);
+  assert.equal(new Set(names).size, names.length);
+  for (const tool of coreTools) {
+    assert.equal(tool.kind, 'query', tool.name);
+    assert.equal(tool.annotations.readOnlyHint, true, tool.name);
+    assert.ok(tool.requires.length > 0, tool.name);
+  }
+});
@@ -0,0 +1,49 @@
+/** Space queries: launches. */
+
+import { defineTool, ToolError } from '../catalog.js';
+import { LIMIT_SCHEMA, capRows, countNoun } from '../results.js';
+
+const text = (value) => (typeof value === 'string' && value ? value : null);
+
+export const getRecentLaunches = defineTool({
+  name: 'get_recent_launches',
+  title: 'Recent launches',
+  description:
+    'Orbital launches from Launch Library 2 over the last 30 days, newest ' +
+    'first, with provider, rocket, pad, mission and outcome.',
+  inputSchema: {
+    type: 'object',
+    properties: { limit: LIMIT_SCHEMA },
+    additionalProperties: false,
+  },
+  requires: ['launches'],
+  async run(args, { services, signal }) {
+    const payload = await services.launches.getLaunches({ signal });
+    const launches = Array.isArray(payload) ? payload : payload.results;
+    if (!Array.isArray(launches))
+      throw new ToolError('malformed', 'The launch feed returned no launches');
+    const rows = launches
+      .map((launch) => ({
+        id: text(launch?.id),
+        name: text(launch?.name),
+        time: text(launch?.net),
+        status: text(launch?.status?.name),
+        provider: text(launch?.launch_service_provider?.name),
+        rocket: text(
+          launch?.rocket?.configuration?.full_name ??
+            launch?.rocket?.configuration?.name,
+        ),
+        pad: text(launch?.pad?.name),
+        location: text(launch?.pad?.location?.name),
+        mission: text(launch?.mission?.name),
+        orbit: text(launch?.mission?.orbit?.name),
+      }))
+      .filter((launch) => launch.name)
+      .sort((a, b) => String(b.time).localeCompare(String(a.time)));
+    const result = capRows(rows, args.limit);
+    return {
+      summary: `${countNoun(rows.length, 'launch', 'launches')} in the last 30 days${rows[0] ? `; latest ${rows[0].name}` : ''}.`,
+      data: result,
+    };
+  },
+});