~ 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
587 lines · 14.7 KB Raw History
{
	"lexicon": 1,
	"id": "place.hud.defs",
	"description": "The shapes HUD's workspace methods share: canvases, their members and tiles, tabs, and the live events.",
	"defs": {
		"actor": {
			"type": "object",
			"description": "A person, by DID and handle.",
			"required": [
				"did"
			],
			"properties": {
				"did": {
					"type": "string",
					"format": "did"
				},
				"handle": {
					"type": "string",
					"maxLength": 253,
					"description": "Their handle, verified, where known."
				}
			}
		},
		"by": {
			"type": "object",
			"description": "Who caused a change.",
			"required": [
				"did"
			],
			"properties": {
				"did": {
					"type": "string",
					"format": "did",
					"description": "The person, or the person an agent acts for."
				},
				"handle": {
					"type": "string",
					"maxLength": 253,
					"description": "Their handle, where known."
				},
				"kind": {
					"type": "string",
					"knownValues": [
						"person",
						"agent"
					],
					"description": "person: on a workspace page, or another client of these methods; agent: an MCP client of theirs, through HUD's canvas tools."
				}
			}
		},
		"member": {
			"type": "object",
			"description": "A member of a canvas: its owner, or someone it invited.",
			"required": [
				"did"
			],
			"properties": {
				"did": {
					"type": "string",
					"format": "did"
				},
				"handle": {
					"type": "string",
					"maxLength": 253,
					"description": "Their handle, verified when they were invited or signed in."
				},
				"role": {
					"type": "string",
					"knownValues": [
						"owner",
						"editor",
						"viewer"
					]
				},
				"pending": {
					"type": "boolean",
					"description": "True while their invitation waits: they are not in it yet."
				},
				"invitedBy": {
					"type": "string",
					"format": "did",
					"description": "Who invited them; none for the owner."
				}
			}
		},
		"storage": {
			"type": "object",
			"description": "Where a canvas is kept.",
			"required": [
				"kind"
			],
			"properties": {
				"kind": {
					"type": "string",
					"knownValues": [
						"file",
						"space"
					],
					"description": "space: a personal space on the owner's PDS; file: the HUD server's own files."
				},
				"uri": {
					"type": "string",
					"format": "at-uri",
					"description": "The canvas's space, for kind space."
				},
				"reason": {
					"type": "string",
					"maxLength": 1000,
					"description": "Why it is not in a space, where spaces are on."
				}
			}
		},
		"canvasView": {
			"type": "object",
			"description": "A canvas, apart from its tiles.",
			"required": [
				"key",
				"owner",
				"record"
			],
			"properties": {
				"key": {
					"type": "string",
					"minLength": 12,
					"maxLength": 12,
					"description": "The canvas's id: 12 hex digits, its space's key where it is kept in one."
				},
				"owner": {
					"type": "string",
					"format": "did",
					"description": "The canvas's owner, its space's authority."
				},
				"record": {
					"type": "unknown",
					"description": "The canvas's info, a place.hud.canvas record, as kept: its name, createdAt and updatedAt."
				},
				"members": {
					"type": "array",
					"maxLength": 20,
					"items": {
						"type": "ref",
						"ref": "place.hud.defs#member"
					},
					"description": "Its owner and those it invited."
				},
				"tileCount": {
					"type": "integer",
					"minimum": 0,
					"description": "How many tiles it holds."
				},
				"storage": {
					"type": "ref",
					"ref": "place.hud.defs#storage"
				},
				"viewer": {
					"type": "ref",
					"ref": "place.hud.defs#canvasViewerState"
				}
			}
		},
		"canvasViewerState": {
			"type": "object",
			"description": "The person asking, in a canvas.",
			"properties": {
				"role": {
					"type": "string",
					"knownValues": [
						"owner",
						"editor",
						"viewer"
					],
					"description": "The person's role in it."
				},
				"invitedBy": {
					"type": "string",
					"format": "did",
					"description": "Who invited the person, while the invitation waits: an invitation, not yet a canvas they are in."
				}
			}
		},
		"tab": {
			"type": "object",
			"description": "A canvas open as a tab.",
			"required": [
				"canvas"
			],
			"properties": {
				"canvas": {
					"type": "ref",
					"ref": "place.hud.defs#canvasView"
				}
			}
		},
		"tileView": {
			"type": "object",
			"description": "A tile: one of HUD's read tools and its arguments, never its result, as a column of the strip, or stacked in one.",
			"required": [
				"key",
				"author",
				"record"
			],
			"properties": {
				"key": {
					"type": "string",
					"minLength": 12,
					"maxLength": 12,
					"description": "The tile's id: 12 hex digits, its record's key."
				},
				"uri": {
					"type": "string",
					"format": "at-uri",
					"description": "The tile's record, in its canvas's space, where the canvas is kept in one; none for one kept on the HUD server."
				},
				"author": {
					"type": "string",
					"format": "did",
					"description": "The member who added it, in whose repo its record is."
				},
				"record": {
					"type": "unknown",
					"description": "The tile, a place.hud.tile record, as kept: its tool and arguments (or argumentsJson), title, order, width, stack, by, createdAt and from."
				},
				"icon": {
					"type": "string",
					"format": "uri",
					"description": "The icon of the app whose data it shows: its favicon, from this server's /icon/<domain>, the domain the NSID's first two segments reversed (app.bsky → bsky.app), of the collection a record tile shows or the method a query tile calls. None where it names no NSID; it answers 404 where the app has no icon."
				}
			}
		},
		"tileEvent": {
			"type": "object",
			"description": "A tile of an open canvas changed. One change may move others, each its own event: a column's head taken off, the next in its stack heads it.",
			"required": [
				"canvas",
				"op",
				"key"
			],
			"properties": {
				"canvas": {
					"type": "string",
					"minLength": 12,
					"maxLength": 12,
					"description": "A canvas's id: 12 hex digits, its space's key where it is kept in one."
				},
				"op": {
					"type": "string",
					"knownValues": [
						"add",
						"update",
						"remove"
					],
					"description": "add: a tile added; update: its place, width, stack or title changed; remove: taken off."
				},
				"key": {
					"type": "string",
					"minLength": 12,
					"maxLength": 12,
					"description": "The tile's id."
				},
				"tile": {
					"type": "ref",
					"ref": "place.hud.defs#tileView",
					"description": "The tile as it now is; none once removed."
				},
				"by": {
					"type": "ref",
					"ref": "place.hud.defs#by"
				}
			}
		},
		"presenceEvent": {
			"type": "object",
			"description": "Who is on an open canvas: as a stream opens it, and as anyone comes or goes, by whom.",
			"required": [
				"canvas",
				"present"
			],
			"properties": {
				"canvas": {
					"type": "string",
					"minLength": 12,
					"maxLength": 12,
					"description": "A canvas's id: 12 hex digits, its space's key where it is kept in one."
				},
				"present": {
					"type": "array",
					"items": {
						"type": "ref",
						"ref": "place.hud.defs#actor"
					},
					"description": "Who has it open now, each once."
				},
				"by": {
					"type": "ref",
					"ref": "place.hud.defs#by"
				}
			}
		},
		"canvasesEvent": {
			"type": "object",
			"description": "The person's workspace changed: a canvas made, renamed, shared, deleted, opened, closed or reordered, an invitation, where canvases are kept. Read getWorkspace again.",
			"properties": {
				"canvas": {
					"type": "string",
					"minLength": 12,
					"maxLength": 12,
					"description": "The canvas that changed; none when it concerns all the person's, as where they are kept."
				},
				"by": {
					"type": "ref",
					"ref": "place.hud.defs#by"
				}
			}
		},
		"tabRef": {
			"type": "object",
			"description": "A tab, by its canvas.",
			"required": [
				"canvas"
			],
			"properties": {
				"canvas": {
					"type": "string",
					"minLength": 12,
					"maxLength": 12,
					"description": "A canvas's id: 12 hex digits, its space's key where it is kept in one."
				}
			}
		},
		"launcher": {
			"type": "object",
			"description": "A query a bundled view offers a workspace's New tile: its app, the domain whose icon it shows, its title, and the query to call, its params made the person's.",
			"required": [
				"app",
				"domain",
				"title",
				"method",
				"service",
				"params"
			],
			"properties": {
				"app": {
					"type": "string",
					"maxLength": 64,
					"description": "The app's name, as an account's profile names the domain of its method (Bluesky for bsky.app)."
				},
				"domain": {
					"type": "string",
					"maxLength": 253,
					"description": "The domain of the app, from its method's NSID: its icon is /icon/<domain>."
				},
				"title": {
					"type": "string",
					"maxLength": 120
				},
				"method": {
					"type": "string",
					"format": "nsid"
				},
				"service": {
					"type": "string",
					"maxLength": 2048,
					"description": "The service the query is called at, as did:…#fragment."
				},
				"params": {
					"type": "unknown",
					"description": "The query's params, as an object."
				}
			}
		},
		"theme": {
			"type": "object",
			"description": "A theme the workspace is drawn in: one of HUD's, by key, or a person's place.hud.theme record, by uri; never both. Light and dark are HUD's own look in that scheme, as each platform draws it, so they have no palette; every other theme is a palette, drawn over its scheme's look.",
			"required": [
				"name",
				"colorScheme"
			],
			"properties": {
				"key": {
					"type": "string",
					"maxLength": 64,
					"knownValues": [
						"light",
						"dark",
						"amber",
						"blueprint",
						"dusk",
						"frost",
						"paper",
						"phosphor"
					],
					"description": "One of HUD's themes, as setTheme names it."
				},
				"uri": {
					"type": "string",
					"format": "at-uri",
					"description": "A person's theme: its place.hud.theme record, as setTheme names it."
				},
				"creator": {
					"type": "ref",
					"ref": "#actor",
					"description": "Who made a person's theme."
				},
				"name": {
					"type": "string",
					"maxLength": 640,
					"maxGraphemes": 64,
					"description": "What it is called, as the workspace lists it."
				},
				"colorScheme": {
					"type": "string",
					"maxLength": 16,
					"knownValues": [
						"light",
						"dark"
					],
					"description": "Whether it is light or dark: what its palette falls back on, and how a platform draws what the theme does not colour, as scrollbars and system controls."
				},
				"palette": {
					"type": "ref",
					"ref": "#palette",
					"description": "Its colours; none for light and dark, HUD's own look."
				}
			}
		},
		"palette": {
			"type": "object",
			"description": "A theme's colours, each named for what it colours rather than its hue, as a hex colour #rrggbb. Every text reads at 4.5:1 or better on what it is drawn on.",
			"required": [
				"canvas",
				"background",
				"panel",
				"soft",
				"border",
				"borderStrong",
				"text",
				"textMuted",
				"textFaint",
				"primary",
				"onPrimary",
				"accent",
				"accentSoft",
				"success",
				"danger",
				"done",
				"attention",
				"neutral",
				"onSolid",
				"notice",
				"onNotice"
			],
			"properties": {
				"canvas": {
					"type": "string",
					"maxLength": 7,
					"description": "The grey behind the tiles."
				},
				"background": {
					"type": "string",
					"maxLength": 7,
					"description": "A tile's body, and the page's chrome: what is drawn on the canvas."
				},
				"panel": {
					"type": "string",
					"maxLength": 7,
					"description": "A surface a little apart from the background: a header."
				},
				"soft": {
					"type": "string",
					"maxLength": 7,
					"description": "A surface further apart: a hovered row, a field."
				},
				"border": {
					"type": "string",
					"maxLength": 7,
					"description": "Lines between parts, and a card's hairline."
				},
				"borderStrong": {
					"type": "string",
					"maxLength": 7,
					"description": "A stronger edge, for a field or a column that has focus nearby."
				},
				"text": {
					"type": "string",
					"maxLength": 7,
					"description": "The body's text."
				},
				"textMuted": {
					"type": "string",
					"maxLength": 7,
					"description": "Text said quietly: times, counts."
				},
				"textFaint": {
					"type": "string",
					"maxLength": 7,
					"description": "Text said more quietly still: hints, placeholders."
				},
				"primary": {
					"type": "string",
					"maxLength": 7,
					"description": "The main buttons, and the edge of what has focus."
				},
				"onPrimary": {
					"type": "string",
					"maxLength": 7,
					"description": "Text on the main buttons."
				},
				"accent": {
					"type": "string",
					"maxLength": 7,
					"description": "What marks rather than acts: links, the tab one is on, the row a search picks."
				},
				"accentSoft": {
					"type": "string",
					"maxLength": 7,
					"description": "Behind what the accent marks: the row a search picks."
				},
				"success": {
					"type": "string",
					"maxLength": 7,
					"description": "What is open, passed, or added."
				},
				"danger": {
					"type": "string",
					"maxLength": 7,
					"description": "What failed, is removed, or is dangerous."
				},
				"done": {
					"type": "string",
					"maxLength": 7,
					"description": "What is done: a pull merged."
				},
				"attention": {
					"type": "string",
					"maxLength": 7,
					"description": "What waits or runs, and an agent's work."
				},
				"neutral": {
					"type": "string",
					"maxLength": 7,
					"description": "What closed or was skipped."
				},
				"onSolid": {
					"type": "string",
					"maxLength": 7,
					"description": "Text on a state's pill, drawn in success, danger, done, attention or neutral."
				},
				"notice": {
					"type": "string",
					"maxLength": 7,
					"description": "A notice's surface: what a reader should know, and the toast that says what an agent did."
				},
				"onNotice": {
					"type": "string",
					"maxLength": 7,
					"description": "A notice's text."
				}
			}
		},
		"contrastProblem": {
			"type": "object",
			"description": "A text of a palette that reads at under 4.5:1 on a surface it is drawn on.",
			"required": [
				"text",
				"on",
				"ratio"
			],
			"properties": {
				"text": {
					"type": "string",
					"maxLength": 32,
					"description": "The palette's colour drawn as text, by its field."
				},
				"on": {
					"type": "string",
					"maxLength": 32,
					"description": "The palette's colour it is drawn on, by its field."
				},
				"ratio": {
					"type": "string",
					"maxLength": 8,
					"description": "How it reads, as 3.21 for 3.21:1."
				}
			}
		}
	}
}