Supply Interface

Full specification: 00-product-spec.md.

YZOS supplies data, it does not converse. Every query for activity, entities, knowledge, clipboard history, or AI tool state must go through MCP, the HTTP API, or the CLI, and must return real data.

1. Interface Overview

Interface	Consumers	Status
MCP HTTP /mcp	Claude Code, Codex, Cursor	Shipped
HTTP /api/call	Tauri frontend, CLI, scripts	Shipped
CLI yzos	Terminal, CI, manual queries	In progress
Skill yzos-data	Agents that support SKILL.md	Shipped

2. MCP over HTTP

The recommended configuration uses the HTTP transport, at:

http://127.0.0.1:17432/mcp

Check runtime status with:

curl -s http://127.0.0.1:17432/status | python3 -m json.tool

When YZOS.app quits, /mcp connections are refused. Reopening /Applications/YZOS.app restores them.

3. HTTP API

curl -s -X POST http://127.0.0.1:17432/api/call \
  -H 'Content-Type: application/json' \
  -d '{"method":"entity.list","params":{"kind":"project","limit":10}}'

Endpoint	Description
GET /status	Runtime and preflight status
GET /permissions	macOS TCC permission status
POST /api/call	Typed method calls
/mcp	MCP HTTP transport

4. MCP Tools

Tool	Purpose
yzos_activity_summary	Daily summary
yzos_activity_sessions	List of activity sessions (including UI state counts and behavior events)
yzos_activity_screen_segments	Screen recording segments and OCR text within a session (added in v0.5)
yzos_activity_screen_semantics	VLM tags and region semantics within a session (planned for v0.5)
yzos_ai_sessions	List of AI tool sessions
yzos_ai_session_detail	Detail of one AI tool session
yzos_entity_list	List of persons / projects / tasks
yzos_entity_get	Full entity record
yzos_entity_search	Entity search
yzos_entity_links	Entity relationships
yzos_knowledge_search	Hybrid search over OKF chunks and AI session prompts
yzos_knowledge_read	Raw OKF content
yzos_clipboard_recent	Recent clipboard entries
yzos_clipboard_search	Clipboard search
yzos_ui_state_summary	Row-count summary of the UI State tables for a session
yzos_ui_state_behavior_events	List of behavior events within a session, with evidence
yzos_ui_state_behavior_event_detail	Full evidence chain for a single event (planned for v0.5)
yzos_cron_create	Create a user-defined cron job
yzos_cron_list	List maintenance and user cron jobs
yzos_cron_delete	Delete a user cron job
yzos_cron_toggle	Enable or disable a cron job
yzos_cron_run_now	Run a job immediately

As of v0.5, YZOS exposes more than 20 MCP tools through tools/list.

5. CLI

yzos status
yzos entity list --kind person
yzos entity search "query"
yzos clipboard list
yzos clipboard search "query"
yzos paths show

The CLI is an HTTP client; it never connects to PostgreSQL directly.

6. Error Semantics

Condition	Response
YZOS.app is not running	Connection refused
Preflight has not passed	error plus the preflight report
Permission missing	permission_denied plus the missing permission
Query result is empty	Empty result; nothing is fabricated to fill the gap
Method does not exist	method_not_found