index
Prepare .fig files and build local searchable workspaces for coding agents, with source management, refresh, change tracking, semantic embeddings, and visual rendering.
Instructions
Local workspace indexes for search: prepare registers a .fig (file) in its own workspace, or in a project workspace (workspace: a project directory), and with scope starts a background build of exactly that stored scope; status reports sources, indexed scopes and storage; add, remove and relocate change the registered sources (remove withdraws their indexes; add of a directory registers up to 10 .fig files under it in one step, in path order, never through a link leading out of it, and replies directory {added, existing, skipped, notFig, truncated, nextCursor}; pass nextCursor as cursor to add the next 10; a repeat adds nothing, and a moved file is a new source unless relocated); refresh rebuilds changed scopes and rebuild every indexed scope even when unchanged (sourceId and scope narrow both), while the previous index keeps serving; track starts recording one scope's changes, read with the changes tool, with a baseline build, and untrack stops it, keeping its history; embed runs the configured local model (models tool) over published scopes for semantic search, as jobs beside the text builds (mode_unavailable without a profile), and a text build this server runs queues it after publishing; visual (scope required, never widened to the whole file) renders that published scope's screens and components, and the scope node below a page, for image search, and embeds them when a vision profile is configured (hash-only otherwise), as a job on the model lane beside text builds; called again it resumes a partial layer, retrying units that failed; a scope that had a visual layer is rendered again after a text build this server runs republishes it, and no other scope is rendered implicitly; a reply that could not admit every job has admission partial and deferred items, each with the nextStep that builds it later; clear_cache deletes only what a build can recreate; reset deletes this workspace's database after the user confirmed it, keeping every .fig and export. Builds run as jobs: the reply has job {jobId, state}; poll the jobs tool, cancel there. Nothing is built implicitly: connecting, listing, find, inspect and file search create no database. Errors carry _meta.figlens.recovery with only the actions that apply; recreate_elsewhere and reset need the user's confirmation.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"action": "<action>"
},
"name": "index"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | a local .fig: the source to prepare, add or relocate to (add also takes a directory under the roots, or without --root a gs://bucket/object, downloaded pinned to its generation); also selects its source-scoped workspace | |
| scope | No | stored node id to index (prepare), refresh, rebuild, track, untrack, embed or visual (required); 0:0 is the whole file | |
| action | Yes | prepare, status, add, remove, relocate, refresh, rebuild, track, untrack, embed, visual, clear_cache or reset | |
| cursor | No | add of a directory only: directory.nextCursor of the previous add of it; a cursor of another directory is cursor_stale | |
| storage | No | absolute custom storage directory, only for a workspace kept outside the default storage; must be under the server's --storage-root | |
| sourceId | No | a registered source, for remove, relocate, refresh, rebuild, track, untrack, embed and visual | |
| requestId | No | an idempotency key: repeating a prepare, refresh, rebuild, track, embed or visual of one source and scope with it returns the same job; one first used for another request (track is its own) is refused | |
| workspace | No | a project directory: selects or prepares that project's workspace | |
| workspaceId | No | ws_... from a previous index reply | |
| replaceUnavailable | No | prepare only, after the user confirmed: recreate a workspace whose storage is unavailable, denied or unreadable in storage, knowing only file; the old files stay untouched |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| job | No | the build prepare started or joined: jobId, state, stage, progress | |
| jobs | No | refresh, rebuild, track, embed and visual: one job per admitted source and scope, each with joined | |
| paths | No | workspace, database and lock paths (the lock sits beside the workspace directory); null when the workspace does not exist | |
| state | Yes | initialized, ready, absent or reset | |
| partial | No | clear_cache: true when a source left this caller's view meanwhile and kept its data; retry later | |
| sources | No | visible sources: sourceId, path, present and indexed scopes with snapshotId, records, complete and current; a gs:// source adds remote {uri, generation its download was pinned to}, not proof the object is unchanged | |
| storage | No | ||
| coverage | No | prepare without scope: text and relations not_requested | |
| deferred | No | partial admission: sourceId, scope and the nextStep index call that builds it later | |
| admission | No | refresh and rebuild: complete, or partial when some jobs were not admitted | |
| directory | No | add of a directory: path, added and existing [{sourceId, path}], skipped [{path relative to it, reason escaping_link, linked_directory, unreadable, inside_storage or outside_roots}], notFig count, truncated null or {reason source_cap or entry_budget, limit}, nextCursor for the next 10 or null | |
| nextSteps | No | ||
| incarnation | No | changes when the database is recreated; cached results of another incarnation are void | |
| workspaceId | Yes | ||
| schemaVersion | No | ||
| deferredBecause | No | partial admission: the error that stopped admission, {code, message} |