feat: add public camera and radio tools

Add find_cctv_cameras, get_cctv_snapshot and find_radio_stations. A
snapshot returns the camera's current frame as image content with its
credit. Tool results may now carry base64 images, which the MCP adapter
sends as image content.
This commit is contained in:
Sameh Khamis committed 2026-10-01 12:11:00 -07:00
1 parent d65402eae3
commit 85fee59da1
10 files changed
+468 -4

No files matched your search

+202
View File
@@ -0,0 +1,202 @@
/** Public camera and radio queries over the CCTV and radio sources. */
import { defineTool, ToolError } from '../catalog.js';
import {
AREA_SCHEMA,
areaCenter,
areaContains,
distanceKm,
resolveArea,
} from '../area.js';
import { LIMIT_SCHEMA, capRows, countNoun } from '../results.js';
const FRAME_TYPES = new Set(['image/jpeg', 'image/png', 'image/webp']);
const MAX_FRAME_BYTES = 3 * 1024 * 1024;
const round = (value, digits) =>
Number.isFinite(value) ? Number(value.toFixed(digits)) : null;
const text = (value) => (typeof value === 'string' && value ? value : null);
async function readCameras(services, signal) {
const payload = await services.cctv.getCatalog({ signal });
return payload.sources.filter(
(camera) =>
camera?.id && Number.isFinite(camera.lat) && Number.isFinite(camera.lon),
);
}
export const findCctvCameras = defineTool({
name: 'find_cctv_cameras',
title: 'Public cameras in an area',
description:
'Public traffic and city cameras in an area, nearest the center first. ' +
'Use get_cctv_snapshot with a camera id to see its current view.',
inputSchema: {
type: 'object',
properties: { area: AREA_SCHEMA, limit: LIMIT_SCHEMA },
required: ['area'],
additionalProperties: false,
},
requires: ['cctv'],
async run(args, { services, signal }) {
const area = await resolveArea(args.area, { services, signal });
const center = areaCenter(area);
const rows = (await readCameras(services, signal))
.filter((camera) => areaContains(area, camera))
.map((camera) => ({
id: camera.id,
name: text(camera.name),
city: text(camera.city),
provider: text(camera.provider),
lat: round(camera.lat, 6),
lon: round(camera.lon, 6),
heading_deg: round(camera.headingDeg, 0),
feed_type: text(camera.feedType),
credit: text(camera.credit),
distance_km: round(distanceKm(center, camera), 2),
}))
.sort((a, b) => a.distance_km - b.distance_km);
return {
summary: `${countNoun(rows.length, 'public camera')} in ${area.label}.`,
data: capRows(rows, args.limit),
};
},
});
export const getCctvSnapshot = defineTool({
name: 'get_cctv_snapshot',
title: 'Current camera view',
description:
'The current image from one public camera, by the id from find_cctv_cameras.',
inputSchema: {
type: 'object',
properties: { camera_id: { type: 'string', minLength: 1, maxLength: 200 } },
required: ['camera_id'],
additionalProperties: false,
},
requires: ['cctv'],
async run(args, { services, signal }) {
const camera = (await readCameras(services, signal)).find(
(candidate) => candidate.id === args.camera_id,
);
if (!camera)
throw new ToolError(
'invalid_arguments',
`No camera has id ${args.camera_id}; use find_cctv_cameras first`,
);
const frame = await services.cctv.getFrame(camera, { signal });
if (!FRAME_TYPES.has(frame.contentType))
throw new ToolError(
'unavailable',
`Camera ${camera.name || camera.id} has no still image right now`,
);
if (frame.bytes.byteLength > MAX_FRAME_BYTES)
throw new ToolError(
'unavailable',
'The camera image is too large to return',
);
const name = text(camera.name) || camera.id;
return {
summary: `Current view from ${name}${camera.city ? ` in ${camera.city}` : ''}${camera.credit ? `, courtesy of ${camera.credit}` : ''}.`,
data: {
id: camera.id,
name,
city: text(camera.city),
provider: text(camera.provider),
credit: text(camera.credit),
mime_type: frame.contentType,
bytes: frame.bytes.byteLength,
},
images: [{ mimeType: frame.contentType, data: base64(frame.bytes) }],
};
},
});
export const findRadioStations = defineTool({
name: 'find_radio_stations',
title: 'Radio stations',
description:
'Internet radio stations from the Radio Browser directory, by area and/or ' +
'a search term matched against name, tags, language and country. Each ' +
"result includes the broadcaster's public stream URL.",
inputSchema: {
type: 'object',
properties: {
area: AREA_SCHEMA,
query: {
type: 'string',
minLength: 1,
maxLength: 80,
description: 'Words such as "jazz", "news" or "Tokyo".',
},
limit: LIMIT_SCHEMA,
},
additionalProperties: false,
},
requires: ['radio'],
async run(args, { services, signal }) {
if (!args.area && !args.query)
throw new ToolError('invalid_arguments', 'Give an area, a query or both');
const area = args.area
? await resolveArea(args.area, { services, signal })
: null;
const terms = String(args.query || '')
.toLowerCase()
.split(/\s+/)
.filter(Boolean);
const directory = await services.radio.getDirectory({ signal });
if (!Array.isArray(directory?.stations))
throw new ToolError(
'malformed',
'The radio directory returned no stations',
);
const center = area ? areaCenter(area) : null;
const rows = directory.stations
.filter((station) => !area || areaContains(area, station))
.filter((station) => {
if (!terms.length) return true;
const haystack = [
station.name,
...(station.tags || []),
...(station.languages || []),
station.country,
station.state,
]
.join(' ')
.toLowerCase();
return terms.every((term) => haystack.includes(term));
})
.map((station) => ({
id: station.id,
name: text(station.name),
country: text(station.country),
state: text(station.state),
tags: station.tags || [],
languages: station.languages || [],
codec: text(station.codec),
bitrate_kbps: Number.isFinite(station.bitrate) ? station.bitrate : null,
stream_url: text(station.streamUrl),
homepage: text(station.homepage),
lat: round(station.lat, 4),
lon: round(station.lon, 4),
...(center
? { distance_km: round(distanceKm(center, station), 1) }
: {}),
}));
if (center) rows.sort((a, b) => a.distance_km - b.distance_km);
const where = area ? ` in ${area.label}` : '';
const what = args.query ? ` matching "${args.query}"` : '';
return {
summary: `${countNoun(rows.length, 'radio station')}${what}${where}.`,
data: capRows(rows, args.limit),
};
},
});
/** Base64-encode bytes with the platform's btoa, in chunks. */
function base64(bytes) {
let binary = '';
for (let offset = 0; offset < bytes.length; offset += 0x8000)
binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
return btoa(binary);
}