~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
172 lines · 12.9 KB Raw History
{
	"lexicon": 1,
	"id": "place.hud.view",
	"defs": {
		"main": {
			"type": "record",
			"description": "A view of a collection's records: the joins that gather their related records, and a layout of components that draws them. Its record key is the NSID of the collection it renders. HUD's own validator, not this lexicon, is the authority on whether a view is valid.",
			"key": "nsid",
			"record": {
				"type": "object",
				"required": ["collection", "description"],
				"properties": {
					"collection": { "type": "string", "format": "nsid", "description": "The collection the view renders." },
					"description": { "type": "string", "maxLength": 200, "description": "What the view shows, in one line." },
					"pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Records per page of a list, by default." },
					"list": { "type": "ref", "ref": "#mode", "description": "How a page of records is drawn." },
					"record": { "type": "ref", "ref": "#mode", "description": "How one record is drawn." },
					"app": { "type": "string", "maxLength": 400, "maxGraphemes": 40, "description": "The app the view's collection or query is of, as people name it (Bluesky): the name of its NSID's domain (app.bsky is bsky.app), where accounts' apps are shown. A bundled view's alone." },
					"profile": { "type": "ref", "ref": "#profile", "description": "The section the view adds to an account's profile, where the account uses what it draws. A bundled view's alone." },
					"activity": { "type": "string", "maxLength": 200, "maxGraphemes": 20, "description": "What an account did in making one of the collection's records, a short past-tense verb (Posted), for its profile's recent activity: the verb, then the record's label as the list's summary reads it. A bundled collection view's alone, with a list summary." },
					"records": { "type": "array", "maxLength": 8, "items": { "type": "ref", "ref": "#recordRoute" }, "description": "The collections a method view draws as its query: a record of one opened by its at-uri answers as the query does, with params read from the record. No other bundled view names or draws the collection. A bundled method view's alone." },
					"domain": { "type": "string", "maxLength": 253, "description": "The domain of the app whose page the view draws (knotless.dev), in place of a collection: an app page view, with page. A bundled view's alone." },
					"page": { "type": "ref", "ref": "#page", "description": "How an app page view draws its app's page. A bundled view's alone." },
					"measure": { "type": "string", "maxLength": 16, "knownValues": ["content", "wide", "full"], "description": "How wide the view would be drawn, where its host can give it the room: content, the host's reading width (the default); wide, a wider one (a profile's grid of pictures); full, all the room its host has for a view. A host decides how wide each is, or draws every view alike; a view drawn inside another's takes the room it is given." },
					"measureWhen": { "type": "array", "minLength": 1, "maxLength": 8, "items": { "type": "ref", "ref": "#measureCase" }, "description": "How wide an answer is drawn, by what it holds: the measure of the first case whose when it holds something at, else measure. One view of a query so draws some answers wide (a camera's feed of galleries) and others at the reading width (a home feed)." }
				}
			}
		},
		"measureCase": {
			"type": "object",
			"description": "A measure an answer is drawn at where it holds something at a path.",
			"required": ["when", "measure"],
			"properties": {
				"when": { "type": "string", "maxLength": 200, "description": "A path in the answer's scope (params.camera): the case holds where it is neither null, false, 0, \"\" nor empty." },
				"measure": { "type": "string", "maxLength": 16, "knownValues": ["content", "wide", "full"], "description": "How wide the answer is then drawn, as the view's measure." }
			}
		},
		"profile": {
			"type": "object",
			"description": "A section of an account's profile, drawn with the view's own layout. A collection view's shows that collection's newest records (limit), where the account holds it; a method view's calls its query with params, each a literal or {\"$actor\": \"did\"}, the account's DID, where the account holds any collection of the query's domain.",
			"required": ["title"],
			"properties": {
				"title": { "type": "string", "maxLength": 400, "maxGraphemes": 40, "description": "The section's heading." },
				"limit": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "A collection view's: how many records it shows." },
				"params": { "type": "unknown", "description": "A method view's: its query's params, each a string, number or boolean, or {\"$actor\": \"did\"}." }
			}
		},
		"recordRoute": {
			"type": "object",
			"description": "A collection a method view draws as its query, and what making one of its records is.",
			"required": ["collection", "params"],
			"properties": {
				"collection": { "type": "string", "format": "nsid", "description": "The collection, a record's NSID." },
				"params": { "type": "unknown", "description": "The query's params, each a string, number or boolean, or a binding {\"$\": path} read against the record as { uri, cid, did, value }." },
				"at": { "type": "unknown", "description": "What the query's answer shows first, where it shows one thing at a time (a story in its account's archive): a binding {\"$\": path} read against the record as params are." },
				"activity": { "type": "ref", "ref": "#recordActivity" }
			}
		},
		"recordActivity": {
			"type": "object",
			"description": "What an account did in making one of the collection's records, for its profile's recent activity: the verb, then the record's label, or its noun where it has none.",
			"required": ["verb", "noun"],
			"properties": {
				"verb": { "type": "string", "maxLength": 200, "maxGraphemes": 20, "description": "A short past-tense verb (Posted)." },
				"noun": { "type": "unknown", "description": "The record's noun: [singular, plural], two strings of at most 32 characters, as a summary's noun." },
				"label": { "type": "unknown", "description": "A binding {\"$\": path} read against the record, its label." }
			}
		},
		"mode": {
			"type": "object",
			"required": ["layout"],
			"properties": {
				"join": { "type": "array", "maxLength": 8, "items": { "type": "ref", "ref": "#join" } },
				"summary": { "type": "ref", "ref": "#summary" },
				"head": { "type": "ref", "ref": "#head" },
				"layout": { "type": "ref", "ref": "#node" }
			}
		},
		"page": {
			"type": "object",
			"description": "An app's page: query joins and a layout over its main scope, { domain, name, icon, actor, me, mine, entries, joins }: the app's domain, name and icon; the page's account (actor, { did, handle }: the one asked of, else the one signed in) and the one signed in (me, or null); whether they are one (mine); the app's entry points, each { title, call }; and the joins' answers.",
			"required": ["layout"],
			"properties": {
				"join": { "type": "array", "maxLength": 4, "items": { "type": "ref", "ref": "#join" }, "description": "Query joins alone, their params read from the main scope." },
				"head": { "type": "ref", "ref": "#head" },
				"layout": { "type": "ref", "ref": "#node" },
				"tag": { "type": "unknown", "description": "What a #tag in the app's text opens, wherever a bundled view of the app draws it: { query, params, service? }, each param a literal or a binding into { tag, hashtag } (the word, and it after a #)." },
				"pages": { "type": "string", "maxLength": 64, "description": "The as of the join that pages the page: a List, Covers, Gallery or Player of its answer is the page list, which a page more (its answer's cursor, given that join alone) grows." }
			}
		},
		"join": {
			"type": "object",
			"description": "Gathers related records for each record in scope, stored at joins.<as>: by an at-uri or strongRef (ref), by each element of an array (each, with ref within it), or by the records of the same repository whose path holds the record's uri (backlinks). Or, at a mode's top level, a query join (query): a related query called once on the whole answer, its answer at joins.<as>.",
			"required": ["as"],
			"properties": {
				"as": { "type": "string", "maxLength": 64 },
				"ref": { "type": "string", "maxLength": 1024, "description": "A path to an at-uri or a strongRef." },
				"each": { "type": "string", "maxLength": 1024, "description": "A path to an array; ref is then a path within each element." },
				"backlinks": { "type": "ref", "ref": "#backlinks" },
				"collection": { "type": "string", "format": "nsid", "description": "Refuses ref targets of any other collection." },
				"orderBy": { "type": "array", "maxLength": 4, "items": { "type": "string", "maxLength": 1024 } },
				"limit": { "type": "integer", "minimum": 1, "maximum": 500 },
				"join": { "type": "array", "maxLength": 8, "items": { "type": "ref", "ref": "#join" } },
				"query": { "type": "string", "format": "nsid", "description": "A query join's method: a query, called once on the whole answer." },
				"params": { "type": "unknown", "description": "A query join's params: each a literal, a binding {\"$\": path} or {\"$root\": path} into the main scope." },
				"service": { "type": "string", "maxLength": 2048, "description": "A query join's service: a DID with its service's #fragment." },
				"say": { "type": "ref", "ref": "#say" },
				"fresh": { "type": "boolean", "description": "A query join asked each time, never an answer HUD keeps a few seconds for whoever asked it." }
			}
		},
		"say": {
			"type": "object",
			"description": "What a tool's text says of a query join's answer: how many count finds in it, or the first line of label.",
			"required": ["noun"],
			"properties": {
				"noun": { "type": "array", "minLength": 2, "maxLength": 2, "items": { "type": "string", "maxLength": 32 } },
				"count": { "type": "string", "maxLength": 1024, "description": "A path in the answer to an array or an integer." },
				"label": { "type": "string", "maxLength": 1024, "description": "A path in the answer to text." }
			}
		},
		"backlinks": {
			"type": "object",
			"required": ["collection", "path"],
			"properties": {
				"collection": { "type": "string", "format": "nsid" },
				"path": { "type": "string", "maxLength": 1024 }
			}
		},
		"head": {
			"type": "object",
			"description": "What a page drawing the mode says of itself in its HTML head, to search engines and link previews, read against the mode's scope as an action's record is: each field a literal, a binding, or {\"$join\": [values]}, {\"$first\": [values]}, {\"$rkey\": path} and the rest of a template; one that reads nothing is left out. A trusted view's alone reaches the tree (_meta.ui.head).",
			"properties": {
				"title": { "type": "unknown", "description": "The page's title, text once read." },
				"description": { "type": "unknown", "description": "What the page shows, text once read." },
				"image": { "type": "unknown", "description": "The picture a preview shows: a blob, or an https URL on the view's origins, once read." },
				"imageAlt": { "type": "unknown", "description": "The picture's alt text, text once read." },
				"type": { "type": "string", "maxLength": 16, "knownValues": ["website", "article", "profile"], "description": "What the page is, as Open Graph's og:type." },
				"canonical": { "type": "unknown", "description": "The page's own path on its app's site, starting with /, once read." },
				"noindex": { "type": "unknown", "description": "Whether search engines should not index the page: true, or once read true or a list with something in it (labels)." },
				"jsonLd": { "type": "unknown", "description": "schema.org structured data: an object of templates, where {\"$each\": [array, template]} is the template read against each element of the array; what reads nothing is left out." }
			}
		},
		"summary": {
			"type": "object",
			"description": "The short text a tool answers with: a count of nouns, each record's label, and a detail count.",
			"required": ["noun"],
			"properties": {
				"noun": { "type": "array", "minLength": 2, "maxLength": 2, "items": { "type": "string", "maxLength": 32 } },
				"label": { "type": "unknown", "description": "A binding, or a literal string." },
				"detail": { "type": "ref", "ref": "#detail" }
			}
		},
		"detail": {
			"type": "object",
			"required": ["count", "noun"],
			"properties": {
				"count": { "type": "unknown", "description": "A binding, or a literal integer." },
				"noun": { "type": "array", "minLength": 2, "maxLength": 2, "items": { "type": "string", "maxLength": 32 } }
			}
		},
		"node": {
			"type": "object",
			"description": "A component of the catalog, its props (literal values or bindings {\"$\": path}), and its children where the component takes them.",
			"required": ["component"],
			"properties": {
				"component": { "type": "string", "maxLength": 32 },
				"props": { "type": "unknown" },
				"children": { "type": "array", "items": { "type": "ref", "ref": "#node" } }
			}
		}
	}
}