MCP Tools Guide

This document lists every tool exposed by the smart-community-video MCP server — its purpose, action enum, parameters, and return shape.

Every tool id is prefixed smart_community_. Every tool is keyed on monitor_id (the camera id, e.g., cam_child); ids are per-monitor and are never assumed unique across use cases. Times are ISO-8601 internally — present HH:MM / HH:MM:SS to users.

The tools fall into four groups:

Group	Tools
Query & report	alert_query · scene_query · generate_report · video_db
Monitor lifecycle	monitor_ctl · monitors_compose
Use-case authoring	use_case_validate · use_case_register
Rules & plans	plan_ctl · rule_eval

---

1. smart_community_alert_query

Query or acknowledge alerts. Switch mode via action.

Every row in alerts is already rule-engine-filtered, so you do not re-filter by severity/type. severity / event / desc are not stored on the alert — they live on the linked task and are returned via a task_id JOIN into video_summary_tasks.

Param	Type	Required	Description
monitor_id	string	✅	Monitor ID
action	enum	✅	See below
limit	number	—	Max rows (default 20, for latest)
start_date	string	—	YYYY-MM-DD, inclusive start (required for by_date; optional for stats)
end_date	string	—	YYYY-MM-DD, inclusive end. start_date == end_date = one day
alert_id	number	—	Alert to acknowledge (for ack)
ack_by	string	—	Who acknowledged (for ack)

Actions

action	Purpose	Returns
latest	Newest N alerts (limit), each LEFT-JOINed with its task + event	{ alerts: AlertWithTask[] }
by_date	Alerts within start_date ~ end_date, same JOIN shape	{ alerts: AlertWithTask[] }
ack	Acknowledge one alert (alert_id + ack_by)	{ success: true, alert_id }
stats	Aggregate counts only, optional date range	{ total, unacked }

AlertWithTask carries taskDetails (including the user-defined extension columns such as event / severity / desc) and eventDetails (motion type, start/end time).

---

2. smart_community_scene_query

One-shot VLM look at the live frame. Reads the monitor’s latest.jpg and asks vllm-serving-ipex (:41091, by default) to describe it now.

Param	Type	Required	Description
monitor_id	string	✅	Frame path is $SMART_COMMUNITY_DATA_DIR/segments/<monitor_id>/latest.jpg
prompt	string	—	Override prompt (default: describe the scene in 1–2 sentences)
vlm_url	string	—	VLM base URL (default config.vlmService.url)
model	string	—	VLM model id (default config.vlmService.model)
max_edge_px	number	—	Longest-edge cap in px (default config.vlmService.maxEdgePx, global 720)

Returns { scene } — the description with <think> tags stripped. Use it for any “what is happening right now?” question, or to ask targeted questions about the current frame via a custom prompt (e.g., “list every food item visible in the fridge”). Resized frames are archived under segments/<monitor_id>/queries/<date>/.

---

3. smart_community_generate_report

Build a period report from the DB: query a data source, build an SRT timeline, call multilevel-video-understanding (:8192) in caption-only mode, and write a row to reports.

Data source / filter / default type are derived from config.yaml use_case_dict[monitor.use_case].reports; tool params override the config.

Param	Type	Required	Description
monitor_id	string	✅	Monitor ID
type	enum	—	daily | weekly | monthly | custom (default: use-case config, else daily)
period_start	string	—	Inclusive start YYYY-MM-DD or YYYY-MM-DD HH:MM (for custom)
period_end	string	—	Inclusive end (for custom); supports half-day windows, e.g., 06:00–12:00
data_source	enum	—	events | alerts | video_summary_tasks (default: use-case config, else alerts)
filter	object	—	Key-value filter on the data-source columns (incl. user extension columns)

daily = today, weekly = last 7 days, monthly = last 30 days.

Returns { periodStart, periodEnd, type, dataSource, eventCount, reportText, latencySeconds }. A debug SRT is persisted under logs/reports/.

The report is a two-layer flow: this tool produces the raw reportText; the agent/persona then decides whether and how to push it (rewrite in the user’s voice, lead with the headline).

---

4. smart_community_video_db

Low-level read-only SQL escape hatch against the SQLite DB. SELECT only — any INSERT/UPDATE/DELETE is rejected. Use it for anything the typed tools don’t cover (e.g., reading monitor_state).

Param	Type	Required	Description
query	string	✅	SELECT statement (non-SELECT rejected)
params	array	—	Positional params for ? placeholders

Returns the result-row array.

---

5. smart_community_monitor_ctl

Single-monitor lifecycle, coordinating all three layers (DB + videostream-analytics + video-worker) atomically in one call.

For register_source, use_case must be a key in config.yaml’s use_case_dict; the tool runs smart_community_use_case_validate as a pre-check and rejects registration if it fails (no DB write, no analytics call, no worker start). video_summary_task is derived from the use case, not passed here.

Param	Type	Required	Description
action	enum	✅	list | status | start | stop | register_source | unregister
monitor_id	string	—	Required for all except list
source_url	string	—	Source URL — any protocol analytics supports: rtsp / http / onvif / file / … (required for register_source)
name	string	—	Display name (for register_source)
use_case	string	—	use_case_dict key (required for register_source)
pipeline_config	object	—	Analytics pipeline config (default: motion + recording)

Actions

action	Behavior	Returns
list	All registered monitors + live analytics reachability	Monitor[] (analyticsReachable, analyticsStatus)
status	One monitor: DB record + live analytics status	Monitor + reachability
register_source	Validate use case → coordinate DB / analytics / worker (graceful-stop stale worker, then rebuild)	{ success, monitor_id } or { status: "already_running" }
unregister	Graceful-stop worker → analytics DELETE → delete DB record	{ success, monitor_id }
start	Resume: analytics /resume + start worker + DB online	{ success, monitor_id, status }
stop	Pause: graceful-stop worker → analytics /pause → DB offline	{ success, monitor_id, status }

stop / unregister are destructive — confirm with the user first.

---

6. smart_community_monitors_compose

Docker-compose-style batch management of the monitors declared in a monitors.yaml file. The tool reads the file from disk every time (independent of the config.monitors loaded at server start), so it can act on a yaml at any path.

Param	Type	Required	Description
action	enum	✅	validate | up | down | restart | ps
file	string	✅	Path to monitors.yaml (absolute or relative to cwd)
monitor_id	string	—	Act on a single monitor (default: every monitor in the file)

Actions (compose analogues)

action	≈ compose	Behavior
validate	config	Validate fields only (source_url/use_case required; use_case must exist in useCaseDict); no state change
up	up -d	For each enabled !== false monitor: skip if DB+analytics+worker all consistent (already_running), else register_source
down	down	unregister each monitor (DB + analytics + worker cleanup)
restart	restart	down → up
ps	ps	Report each monitor’s DB / analytics / worker state; no change

down / restart are destructive — confirm first. Per-compose traces are written to logs/monitors/<monitor_id>/<YYYY-MM-DD>.log.

---

7. smart_community_use_case_validate

Validate a use case end-to-end. Also runs inline as the monitor_ctl register_source pre-check; callable standalone for a dry run.

Three sequential checks (any failure fails overall):

1. Known — use_case exists in config.yaml use_case_dict.

2. Task registered — its video_summary_task exists in multilevel-video-understanding (GET /v1/tasks/<name>).

3. Schema consistent — every required: true schema field appears in the task’s LOCAL_PROMPT (case-insensitive substring).

Param	Type	Required	Description
use_case	string	✅	use_case_dict key

Returns { valid, use_case, video_summary_task, checks, required_fields, optional_fields, missing_required_in_prompt, missing_optional_in_prompt, prompt_tail, suggestion }. valid is decided by required fields only; on failure prompt_tail gives the last ~200 chars of the prompt to help locate the fix.

---

8. smart_community_use_case_register

Manage a use case’s lifecycle at runtime, without restarting the server.

• action: generate_task — step 1 of the recommended two-step flow: run the schema↔prompt consistency check, POST /v1/tasks to multilevel-video-understanding (auto-PATCH on 409), and on success write $SMART_COMMUNITY_DATA_DIR/use-cases/<use_case>/prompt.md to disk (~/.mcp-smart-community is the default data directory). On the custom rule path, pass evaluate_rules_path; the tool reads that file for the consistency check, stages it to the same use-case directory as evaluate_rules.py, and smoke-tests the staged file. Does not touch the DB schema, use_case_dict, or config.yaml. prompt_text is required here.

• Any Final Schema field beyond severity/event/desc requires evaluate_rules.py. Both generate_task and register reject an extended schema without a rule before DB, VLM, config, or artifact side effects.

• action: register — (1) apply schema_extensions via ALTER TABLE (idempotent), (2) POST /v1/tasks to multilevel-video-understanding (auto-PATCH on 409), (3) inject the entry into the in-memory use_case_dict so the task-poller and other tools see it, (4) re-run use_case_validate. With persist: true, also writes the entry back to config.yaml (comment-preserving). As step 2 of the two-step flow, omit prompt_text — it is auto-read from the file generate_task wrote. If evaluate_rules_path is supplied it is staged to <data_dir>/use-cases/<use_case>/evaluate_rules.py (auto-discovered when the file is already there, e.g., staged by step 1), and that conventional absolute path is stored in config.yaml for runtime rule execution.

• action: unregister — DELETE /v1/tasks/<name> and remove from use_case_dict. The VLM delete is skipped when another use case shares the task. Every referencing monitor is detached (worker stopped, analytics source removed, DB row left offline with history retained). With persist: true, the entries are also removed from config.yaml and monitors.yaml, then <data_dir>/use-cases/<use_case>/ is moved to <data_dir>/use-cases/.backup/. Incomplete cleanup keeps ok: true for the removed in-memory entry but sets degraded: true and explains the failure in warnings.

• action: list — read-only inventory of the live in-memory use_case_dict; needs no other arguments. Returns one entry per use case with video_summary_task, schema_fields, rule_path (defaultRuleEvaluator | evaluate_rules.py | none), and report_source. This reflects what the running server actually uses — including entries registered with persist: false — so prefer it over parsing config.yaml from disk. Call it after a successful register/unregister to report the system’s current use cases.

Prompt authoring is out of scope here — draft the ## LOCAL_PROMPT with the smart-community-use-case-manager skill, then pass it via prompt_text (or let register auto-read <data_dir>/use-cases/<use_case>/prompt.md).

Param	Type	Required	Description
action	enum	✅	register | generate_task | unregister | list
use_case	string	✅ (not for list)	Key matching ^[a-z][a-z0-9_]{1,63}$
video_summary_task	string	—	VLM task name (default <use_case>_monitor; must not collide with builtins)
description	string	—	Human description shown by /v1/tasks
evaluate_rules_path	string	required for extended schema/custom alerts	Path to a custom evaluate_rules.py; read for consistency checks, staged to <data_dir>/use-cases/<use_case>/evaluate_rules.py, smoke-tested, and the conventional absolute path persisted into config.yaml
reports	object	—	{ data_source, default_type, filter }
summarize	object	—	Per-clip summarize config { method, processor_kwargs }
prompt_text	string	✅ for generate_task	Full 4-section prompt (Markdown or raw Python). For register, omit to auto-read <data_dir>/use-cases/<use_case>/prompt.md
schema_extensions	array	—	Extra video_summary_tasks columns { name, type: text|integer|real, required }. When omitted, inferred from prompt KEY: lines. Any extension selects the custom-rule path
overwrite	boolean	—	Replace an existing entry (default false)
persist	boolean	—	Mirror the mutation into the booted config.yaml (default true; on unregister also strips bound monitors from monitors.yaml and archives <data_dir>/use-cases/<use_case>/ to <data_dir>/use-cases/.backup/)

---

9. smart_community_plan_ctl

Per-monitor plans: arbitrary JSON records keyed by name. The rule engine can read today’s plan before deciding whether to fire. Plan shape is user-defined; the tool doesn’t interpret it.

Param	Type	Required	Description
monitor_id	string	✅	Monitor ID
action	enum	✅	list | upsert | delete
name	string	—	Unique plan name within the monitor (required for upsert / delete)
plan	object	—	Plan data (for upsert, arbitrary JSON)
plan_date	string	—	Optional YYYY-MM-DD hint stored with the plan (not the key)
active_only	boolean	—	Return only active plans (default true, for list)

delete is a soft delete (active=0, data retained) — still treated as destructive; confirm first.

---

10. smart_community_rule_eval

Manually re-run the rule evaluator against a completed task (defaults to the monitor’s latest completed task). Rebuilds the same RuleContext the task-poller uses. Dry by default.

Param	Type	Required	Description
monitor_id	string	✅	Monitor ID
task_id	number	—	Task to re-evaluate (default: latest completed for the monitor)
create_alert	boolean	—	When true, insert an alert row on shouldAlert (default false — dry run; cooldown honoured)

In normal operation you never call this: alerts are created automatically by the worker’s rule-engine callback when a summary task completes. rule_eval is a debugging / manual-replay aid.

---

Tool summary

Tool	Key traits
alert_query	latest/by_date/ack/stats; LEFT-JOIN task+event; severity traced via task
scene_query	vllm-serving-ipex; live-frame VLM; ffmpeg resize; frame archive; <think> stripped
generate_report	SRT build; caption-only VLM; writes reports; config-derived source/filter
video_db	read-only SELECT; writes rejected
monitor_ctl	single-monitor lifecycle; atomic DB+analytics+worker; use-case pre-check
monitors_compose	docker-compose over a yaml; validate/up/down/restart/ps; idempotent
use_case_validate	3-step wiring check; case-insensitive; returns missing fields
use_case_register	runtime use-case register/unregister; schema ALTER; /v1/tasks; optional persist; list inventory
plan_ctl	per-monitor JSON plans CRUD; soft-delete
rule_eval	manual re-run of the rule evaluator; dry by default

---

Data model (SQLite)

smart_community_video_db reads these tables (SELECT only):

• monitors — registered cameras: id (= monitor_id), name, source_url, use_case, video_summary_task, status.

• events — motion and static pipeline events: motion_type, start_time, end_time, duration_seconds, optional clip/prefilter fields, and trajectory_region. Continuous recording payloads are stored in the separate recordings table; VSA connection status is exposed by its control API and is not inserted here.

• video_summary_tasks — one per motion clip: id, monitor_id, event_id, summary_clip_input, status (pending | processing | completed | failed | ignored), summary_text (raw VLM output), error/latency/token fields, plus user-defined extension columns declared by that use case under use_case_dict.<use_case>.schema.video_summary_tasks.extensions (commonly event, severity, and desc).

• alerts — use-case-agnostic rule-engine output: id, monitor_id, task_id, event_id, use_case, description, notified, created_at, ack_at, ack_by. Read structured fields such as severity or event by joining task_id to video_summary_tasks.

• recordings — file_path, start_time, end_time, duration_seconds, file_size_bytes.

• reports — generated report rows (from generate_report).

• plans — per-monitor JSON plans (plan_ctl).

• monitor_state — per-monitor runtime state as JSON (e.g., last_alert_at, use-case keys such as last_get_up_at).