Inistate MCP

List workspaces the current user has access to. Typically the first call of a session. If exactly one workspace matches, it is selected automatically and its module list is returned — no set_workspace or list_modules needed; otherwise call set_workspace next. Administrators: without `search` this lists your own memberships; pass `search` to find any workspace by name.

Set the active workspace for the current session. The response includes the workspace's module list — go straight to list_entries / get_form / get_module_schema with those names; list_modules is only needed to refresh. In stateless/remote mode, prefer passing workspaceId directly to each tool instead. Workflow sequences after workspace is set: - Design: design_workflow → create_module (validates internally) - Execute: list_entries → get_form → submit_activity - Modify: get_module_canvas → validate_design → update_module - Query: list_entries → get_entry / get_entry_history; aggregate_entries for totals

List all discoverable modules in the current workspace. set_workspace already returns this list — call this only to refresh it or when operating stateless without set_workspace.

Read-only lookup of one module's schema; it changes nothing and performs no activity. Returns the canvas schema for a module. Use tier=basic (default) for fields and states only. Use tier=extended to also include activities and flows. Use basic for query operations. Use extended when you need to understand available activities and state transitions. What the module's designer wrote for an AI rides beside the name lists: `stateDetails` (both tiers) gives each state's ai_hint/ai_instruction — e.g. which states no longer count — and `activityDetails` (extended) gives each activity's `actor` (ai: you may submit it; hybrid: only after the user approves the planned submission; human: never — a person performs it), ai_hint/ai_instruction, confidence_threshold and `from` (the states it can be performed in). A top-level `ai_instruction` is the module's standing instruction — follow it. Both tiers include your accessible `listings`: each carries its designed filter in the SAME shape as list_entries' `filters` (applied automatically when that listing is queried — pick the listing whose conditions already match the question and do NOT re-add them as `filters`), plus partialFilter (an inexpressible formula/script condition also applies), profileOnly (rows limited to the current user's own entries) and scripted markers. Pass a listing's `name` as list_entries' `listing`.

Get the full module definition with stable IDs. The output is round-trippable — modify and send back via update_module. Use this when modifying a module to preserve IDs for renaming. Modify workflow: list_modules → get_module_canvas → (apply changes) → validate_design → update_module. Load resource inistate://schema before modifying to know valid field types, colors, and actors.

Query entries with filters, sorting, pagination. Filter keys are field display names; values are equality (simple) or operator objects (contains/startsWith/endsWith/min/max/above/below/between/after/before/empty/exists/yes/no/is/not/excludes). Use {or:[…]} for OR; multiple keys are AND-ed. Use 'me' for User-field self-match. See FilterOperators in inistate://schema/runtime for the full set. Access: non-admin users cannot query the unfiltered default 'Everything' view on modules that have listings — pass `listing` with one of their accessible listings (an access-denied response names them). Token control: use `fields` to restrict the returned `data` to just the columns you need. For modules with many fields this can shrink the response by an order of magnitude. Every item carries entryId, documentId and state whatever `fields` holds; the other system fields (date, createdBy, createdDate, updatedBy, updatedDate, assignees, due) come with the full row, but when `fields` is given only if it names them. Check each item's `state` before totalling, counting or ranking entries: a Cancelled or Draft entry usually must not count. get_module_schema's stateDetails says what each state means.

Totals without paging rows: count, sum, average (ave), min or max of a field over the entries list_entries would list, optionally grouped by a field (a date by day, week or month) and broken down by a second field. Use it for 'how many / how much / total / average / top N / per month' questions instead of adding up list_entries pages. The query parameters (module, listing, state, search, filters) ARE list_entries' — same names, same meaning, same access — so pass exactly what you would pass list_entries to read those entries. The answer: `groups` [{key, count, value}] (with a breakdown, `values` [{key, value}] per group), `total` {count, value} over EVERY matching entry, `complete` (false: the module's engine read only its first 501 entries, so the figures are partial — narrow the filters, or say they are partial) and `groupsTruncated` (only the largest `top` groups, or the latest periods, are listed; `total` is still whole). Filter or group by state when Cancelled or Draft entries must not count. What a figure means — signs, which entries belong in it — comes from the module's description and get_module_schema.

Read-only lookup of a single entry by its ID; it changes nothing and performs no activity. Returns current field values, state, audit metadata, and the names of the activities available on it (to perform one, use get_form then submit_activity).

Read-only lookup of the input form for one named activity of one module; it does not perform the activity (submit_activity does). Returns the form fields, current values, and options. Call this before the FIRST submit_activity on each (module, activity) pair — the form schema is stable within a session, so reuse it for subsequent entries (per-entry current values come from get_entry/list_entries). User values with no matching field: omit them and note the omission. Never fabricate form data — when a value is uncertain, submit with a lower ai.confidence and state the assumption instead of blocking to ask. A field may carry `label`: the name THIS activity's form shows for it (the designer relabelled it) — when the user names a field by that label, it means this field; key `input` by the field name (the label is accepted too). The response's `actor` says who may perform the activity: ai — submit it; hybrid — show the user what you plan to submit and get their explicit approval, then submit with confirmed: true; human — do not submit, a person performs it in Inistate. The response's ai_hint/ai_instruction are the designer's guidance for performing the activity; an `ai_hint` on a field or Table/List column says how to fill it.

Write operation: one call performs exactly one named activity on one entry of one module, and nothing else runs. The activity is the `activity` argument — a standard one (create [no entryId], edit, delete, changeStatus, comment, duplicate, manage) or a custom activity the workspace's designer defined (listed by get_module_schema tier=extended); activity names are data, not hidden tools. Call get_form before the first submission per (module, activity); reuse its schema for further entries. The `ai` object is REQUIRED (reasoning + model + confidence). If confidence < the activity's threshold, the transition is suppressed and the entry is flagged. Server-side guard rules (human/hybrid actor, state-change confirm, confidence-inflation) may block — see inistate://guardrails. Input shapes: ActivitySubmission in inistate://schema/runtime.

Write operation, the bulk variant of submit_activity: one call applies one named activity of one module to many entries (the same activity for every item; nothing else runs), each item with its own input. Use instead of N sequential submit_activity calls when creating/editing many rows — one tool turn instead of N. A per-item `ai` wholly replaces the top-level default (no partial merge). Items run sequentially fail-soft on the server: one failure does not abort the rest; per-item outcomes (success, entryId, flagged, validation details) return in `results` — use `clientRef` to correlate. Max 100 items; chunk beyond that. Guardrails match submit_activity at batch level: actor='human' rejects the whole batch; actor='hybrid', activity='changeStatus', or any state override (top-level or per-item) requires `confirmed: true`.

Get the audit trail and comments for an entry. Returns chronological list of actions (create, edit, state changes, comments) with field-level change details and AI traceability context.

FALLBACK ONLY — use request_upload_url + confirm_upload first; call this only after that presigned flow has actually failed. Uploads via base64. Returns { path, filename, mimeType, size } — use path as the File/Image field value in submit_activity. Max 50MB. Blocked: .exe, .bat, .cmd, .dll, .msi.

Download a file by module name. Construct the URL from a File/Image field value: field.path = '/s/{guid}/{fileName}'. Returns a pre-signed S3 URL (1hr TTL).

DEFAULT upload path for every file (up to 500MB); upload_file is only the fallback if this flow fails. Flow: 1) call this tool, 2) PUT the raw bytes to uploadUrl with Content-Type exactly matching contentType (S3 rejects mismatches with 403), 3) call confirm_upload({ s3Key }) — its returned path is the File/Image field value for submit_activity. uploadUrl expires in ~1 hour; call again on expiry.

Confirm a presigned upload after the PUT to uploadUrl succeeded. The server verifies the object in S3 and returns { url, filename, mimeType, size } — url is the /s/ path usable as a File/Image field value. Returns 400 if the file is not in S3 (ensure the PUT completed first).

Generate a scaffolded ModuleSchema template from a natural language description. Use when the user wants to create a new module or workflow. Design workflow: design_workflow → (complete template) → validate_design → create_module → get_module_schema(tier=extended). Load resources inistate://schema and inistate://design-guide before designing for valid field types, colors, and design rules.

Validate a module schema without submitting anything. create_module (and update_module on full-canvas payloads) runs these same checks internally, so this tool is optional there — use it to iterate on a draft, or before a partial update_module where the merged canvas cannot be checked client-side.

Create a new module. Supports workflow modules (states, activities, flows) and record list modules (fields only). Requires Administrator, Consultant, or Workspace Admin role. Validates internally with the same rules as validate_design and returns structured errors without creating anything — a separate validate_design call beforehand is optional. See inistate://schema/configure for field types, color palette, and design rules.

Update an existing module. A section you pass (information/states/activities/flows) replaces that section's entire list — include every existing item you want to keep (matched by id, which enables renaming; omit id to add new items). Omitted sections are left unchanged. Always call get_module_canvas first to obtain the stable module id and item ids. Full-canvas payloads (information included) are validated internally like create_module; for partial payloads, validate the merged canvas with validate_design first.

Switch tool surface. 'configure' (default) = entry CRUD + module design tools and design resources. 'runtime' = entry CRUD plus get_module_schema (available in every mode). 'frontend' = configure + the inistate://frontend-guide resource (REST reference for building Vue/React UIs that call the Inistate API directly) — use it when the user wants a custom UI. The tool/resource list refreshes via list_changed after this call.