picked 0.0.101-next.2 → 0.0.101

package/docs/reference/tools/mcp.md

@@ -0,0 +1,391 @@
+---
+type: reference
+layout: docs
+---
+
+# MCP server
+
+Control your Picked workspace from an AI tool that writes code, with the Model
+Context Protocol (MCP).
+
+## Tools
+
+Each tool has its own section. Link to a tool with its name as the anchor, for example
+`/reference/tools/mcp#create_feature`.
+
+### Discovery
+
+#### `list_projects`
+
+Lists your organizations and projects. Call it first: each other tool needs a project ID or a workspace ID.
+
+#### `list_workspaces`
+
+Lists the workspaces in a project.
+
+#### `get_workspace_overview`
+
+Reads the live version of the project, and the draft of a workspace with its experiences, features, steps and fields.
+
+#### `get_project_context`
+
+Reads the brief that the project owner wrote about the project, its goals and its entry points.
+
+#### `guide_create_organisation`
+
+Gives the link to create an organization in the dashboard. The MCP server cannot create an organization.
+
+#### `guide_create_project`
+
+Gives the link to create a project in the dashboard. The MCP server cannot create a project.
+
+### Documentation
+
+#### `get_schema_info`
+
+Reads the rules for an entity type, and the format of a flow graph. Call it before the first change to that type.
+
+#### `list_picked_docs`
+
+Lists every Picked documentation page with its URL.
+
+#### `read_picked_doc`
+
+Reads one documentation page, or one section of it.
+
+### Experiences
+
+#### `list_experiences`
+
+Lists the experiences in a workspace.
+
+#### `get_experience`
+
+Reads an experience, with its flow graph.
+
+#### `create_experience`
+
+Creates an experience.
+
+#### `update_experience_flow`
+
+Creates, updates, or deletes steps, conditions, actions, fields, nodes, and edges as one operation.
+
+#### `guide_delete_experience`
+
+Gives the link to the experience in the dashboard, where you delete it.
+
+### Steps, fields, conditions, and actions
+
+#### `list_steps`
+
+Lists the steps in a workspace.
+
+#### `get_step`
+
+Reads a step, with its fields.
+
+#### `update_step`
+
+Renames a step, or binds it to the content entry that it renders.
+
+#### `guide_delete_step`
+
+Gives the link to the step in the dashboard, where you delete it.
+
+#### `list_fields`
+
+Lists the fields in a workspace. A step ID filters the list.
+
+#### `get_field`
+
+Reads a field, with its options and the steps that use it.
+
+#### `guide_delete_field`
+
+Gives the link to the field in the dashboard, where you delete it.
+
+#### `list_conditions`
+
+Lists the conditions in a workspace.
+
+#### `get_condition`
+
+Reads a condition, with its JSON Logic rule.
+
+#### `list_actions`
+
+Lists the actions in a workspace.
+
+#### `get_action`
+
+Reads an action.
+
+### Feature flags
+
+#### `list_features`
+
+Lists your feature flags, with the variants of each one.
+
+#### `get_feature`
+
+Reads a feature flag.
+
+#### `create_feature`
+
+Creates a feature flag.
+
+#### `update_feature`
+
+Updates the name, description, state, or weight of a feature flag.
+
+### Content
+
+#### `list_content_models`
+
+Lists the content models in a workspace.
+
+#### `get_content_model`
+
+Reads a content model, with its field schema.
+
+#### `create_content_model`
+
+Creates a content model.
+
+#### `update_content_model`
+
+Renames a content model, or changes its schema. A schema change migrates the entries of the model.
+
+#### `list_content_blocks`
+
+Lists the content blocks in a workspace.
+
+#### `get_content_block`
+
+Reads a content block, with its field schema.
+
+#### `create_content_block`
+
+Creates a content block.
+
+#### `update_content_block`
+
+Renames a content block, or changes its schema. The entries do not change.
+
+#### `list_content_entries`
+
+Lists the content entries in a workspace. Give the ID of a content model to show only its entries.
+
+#### `get_content_entry`
+
+Reads a content entry, with its data.
+
+#### `create_content_entry`
+
+Creates a content entry of a content model.
+
+#### `update_content_entry`
+
+Changes the data of a content entry.
+
+#### `guide_delete_content_entry`
+
+Gives the link to the content entry in the dashboard, where you delete it.
+
+#### `validate_workspace_content_entries`
+
+Checks each content entry of a workspace against its schema, and names each entry that is not valid. It changes nothing.
+
+### Assets
+
+#### `list_assets`
+
+Lists the assets of a project.
+
+#### `get_asset`
+
+Reads an asset, with its file name, type, size and version.
+
+#### `init_asset_upload`
+
+Gives a URL to upload the file of an asset to.
+
+#### `commit_asset_upload`
+
+Records the asset after you upload its file.
+
+### Design systems
+
+#### `list_design_systems`
+
+Lists the design systems of a project.
+
+#### `get_design_system`
+
+Reads a design system, with the asset that holds its guidance.
+
+#### `create_design_system`
+
+Creates a design system from a Markdown asset.
+
+#### `update_design_system`
+
+Renames a design system, or replaces its Markdown asset.
+
+### Workflows
+
+A workflow runs a graph of nodes when its trigger occurs. The trigger is a domain
+event or one action.
+
+#### `list_workflows`
+
+Lists the workflows in a workspace, with search and sort.
+
+#### `get_workflow`
+
+Reads a workflow, with its trigger, graph, warnings, and the paths that its nodes use.
+
+#### `list_workflow_tools`
+
+Lists the tools that a tool node can run, with the arguments of each tool.
+
+#### `create_workflow`
+
+Creates a workflow with its trigger. You cannot change the trigger after this step.
+
+#### `update_workflow`
+
+Renames a workflow, and sets its visit cap.
+
+#### `update_workflow_graph`
+
+Creates, updates, or deletes nodes and edges as one operation.
+
+#### `guide_delete_workflow`
+
+Gives the link to the workflow in the dashboard, where you delete it.
+
+#### `list_workflow_runs`
+
+Lists the runs of a workflow, with the newest run first.
+
+#### `get_workflow_run`
+
+Reads the status of a run and the reason for a failure.
+
+#### `list_workflow_run_tasks`
+
+Lists the nodes that a run started, and the leads and labels that each node changed.
+
+#### `test_run_workflow`
+
+Runs the draft of a workflow one time as a test, and shows what each node did.
+
+If `update_workflow_graph` refuses a change, it saves nothing. The result names each
+node or edge that has a problem. If the origin node does not connect to a node, the
+change is saved, and the result gives a warning for that node.
+
+A workflow run uses the published version of the workflow. Publish the workspace to
+apply a change.
+
+`test_run_workflow` runs the draft, so you can test a change before you publish it. Give
+the `responses` of the action, or the `entity_id` of the event. The result shows the
+input, the output, the status, and the branch of each node.
+
+A tool that reads, such as `search_leads` or an `http` `GET`, runs. A tool that writes
+does not run: the result shows what it would send. A wait node does not wait. The test
+run saves nothing. You must have each scope that the workflow uses.
+
+### Leads
+
+#### `list_lead_fields`
+
+Lists the fields that you can use to search the leads of a project. These are the
+response keys and the labels of the newest leads. For each field, it gives the number of
+leads that have it. It gives only the names of the fields, not the values.
+
+#### `search_leads`
+
+Gives the number of leads that match a search, and a link to the leads list in the
+dashboard. It does not give the leads. Use `list_lead_fields` first to get the fields
+that you can search by.
+
+### Publish
+
+#### `get_preview_url`
+
+Makes a preview URL for your unpublished work.
+
+#### `guide_publish_workspace`
+
+Gives the link to publish the workspace in the dashboard. The MCP server cannot publish.
+
+#### `guide_workspace_version_publish`
+
+Gives the link to restore a published version in the dashboard.
+
+#### `list_workspace_versions`
+
+Lists the published versions of a project, and shows the live one.
+
+#### `compare_workspace_versions`
+
+Shows the differences between the live version, a version, and a draft.
+
+The `list_*` and `get_*` tools read the workspace draft. The draft can be
+different from the live version that visitors see. Use
+`compare_workspace_versions` to see what is live and what changes when you publish.
+
+### Code
+
+These tools let an agent call many tools in one step.
+
+#### `picked_run`
+
+Runs JavaScript in which each tool above is a function on the `tools` object. Only the value that the code returns comes back. See [MCP run tool](/reference/tools/mcp-run) for the arguments, examples and limits.
+
+#### `picked_search_api`
+
+Finds the tools that match the words you give, for use in `picked_run`.
+
+#### `picked_describe_api`
+
+Gives the arguments and the result of each tool that you name, for use in `picked_run`.
+
+### Reports
+
+#### `submit_feedback`
+
+Sends a report about a problem in the MCP server to the Picked team.
+
+:::note
+A PickedQL query is not available through the MCP server at this time.
+:::
+
+## Example prompts
+
+- "List my Picked projects and show me the options on each one"
+- "Create a feature flag called 'new-checkout' at 50% traffic"
+- "Create an experience with a step that collects an email address"
+- "Make a preview URL for my workspace on `https://example.com`"
+- "Create a workflow that adds the label `plan.pro` to each lead from the sign-up action"
+- "Show me why the last run of my workflow failed"
+- "Test my sign-up workflow with the email `a@example.com` and show me what each node does"
+
+## Tips
+
+- Ask your agent for a list of your projects first. Then ask it to read your
+  workspace and report the options on each record.
+- For a large experience, ask your agent about flow graphs and JSON Logic. The agent
+  can read the documentation for you.
+- An update to an experience flow is atomic. Your agent can create steps, fields,
+  nodes, and edges in one operation.
+- See a preview of your work on your site before you publish, to check that each page
+  is correct.
+- The `create_workflow` prompt tells your agent how to build a workflow. The resource
+  `picked://workflow/{workflowId}/graph` gives the graph of a workflow as JSON.
+
+## Related
+
+- [How to connect the MCP server](/how-to/connect-the-mcp-server)

package/docs/reference/tools/vite-plugin.md

@@ -0,0 +1,163 @@
+---
+type: reference
+layout: docs
+---
+
+# Vite Plugin
+
+`@picked/vite-plugin-picked` adds Picked to your Vite project. It reads the options
+of your project at build time. It then puts them in a module that gives them to the
+SDK, so the SDK makes no API request at runtime. In development it also serves a
+launcher page. On that page you can see a preview of an experience with your own
+feature flag values.
+
+## How it works
+
+### Build-time config injection
+
+When Vite starts, in both `dev` and `build`, the plugin does this:
+
+1. It reads the configuration of your project from the Picked API.
+2. It embeds those options in your bundle.
+3. The module gives the options to the SDK as the browser loads it.
+4. The SDK reads the embedded configuration at runtime and makes no network request.
+
+Step 3 is a function call. The module gives the options to the SDK as it loads, and does
+not wait for the SDK to ask.
+
+When a preview token is there at runtime, the SDK ignores the embedded configuration and
+reads fresh data from the API.
+
+### Preload of the data file
+
+Vite puts the options of your project in their own JavaScript file. For each HTML page
+in your build, the plugin adds a `<link rel="modulepreload">` for that file. The
+browser then gets it while it reads the page, and not later when the SDK starts.
+
+The CMS content of an experience stays in its own file and gets no preload. The
+browser gets it only when an experience needs it.
+
+Some applications make their HTML from the code, and not from an HTML file in your
+project. React Router in server mode is one of these. Such a build has no page for the
+plugin to add the link to. Add this line to the code that runs in the browser instead:
+
+:::code-group
+
+```ts [entry.client.ts]
+import 'virtual:picked/data'
+```
+
+:::
+
+Your framework then sees the file in its own list and adds the preload for you.
+
+The line reads no value from the module. It is there for the work the module does as it
+loads. A bundler removes a module that only declares values, and removes the line with
+it. This module gives your project options to the SDK, which is work, so the bundler
+keeps both.
+
+Your application is correct without this line. The SDK gets the same data later, as it
+starts. The line moves that work earlier.
+
+### Types for the data file
+
+The plugin makes `virtual:picked/data` at build time. Because the module is not a file in
+your project, TypeScript cannot find its types. The plugin gives you a type file for the
+module. Point your project at that type file to import from the module:
+
+:::code-group
+
+```json [tsconfig.json]
+{
+  "compilerOptions": {
+    "types": ["@picked/vite-plugin-picked/client"]
+  }
+}
+```
+
+```ts [picked-data.ts]
+/// <reference types="@picked/vite-plugin-picked/client" />
+```
+
+:::
+
+Use one of the two. The `types` option applies to all files in your project. The
+`reference` comment applies to one file.
+
+The module gives three values: `projectConfig`, `experienceContent` and
+`manifestMetadata`. You do not give these values to the SDK. The module gives them to
+the SDK itself as the browser loads it.
+
+### Dev launcher
+
+In development, the plugin serves an HTML page at `/`. On that page you can:
+
+- see every feature flag in your project with its current state;
+- turn a feature flag on or off for a local test;
+- see a preview of an experience with your own feature flag values.
+
+After the dev server starts, the launcher URL appears next to the Vite output:
+
+```
+  ➜  Picked:  http://localhost:5173/
+  ➜  Local:   http://localhost:5173/
+  ➜  Network: use --host to expose
+```
+
+## Options
+
+Project identity belongs in [`picked.config.ts`](/reference/sdk/type-generation). The two
+options that carry it are deprecated, and the table marks them.
+
+| Option           | Type                  | Default                  | Description                                                |
+| ---------------- | --------------------- | ------------------------ | ---------------------------------------------------------- |
+| `disableLauncher`| `boolean`             | `false`                  | Turns the launcher page off in both dev and build output.  |
+| `generateTypes`  | `boolean`             | `true`                   | Whether the plugin writes types from the workspace schema. |
+| `mode`           | `'bundle' \| 'api'`   | `'bundle'`               | Whether the build carries your project data.               |
+| `projectId`      | `string`              | —                        | **Deprecated.** Use `picked.config.ts`.                    |
+| `apiUrl`         | `string`              | —                        | **Deprecated.** Use `picked.config.ts`.                    |
+
+### projectId and apiUrl
+
+These two options moved to [`picked.config.ts`](/reference/sdk/type-generation), which the
+`picked` command and type generation also read. A later release removes them.
+
+The plugin still reads an option for a field that `picked.config.ts` leaves out, so a
+project that has yet to move needs no change. It stops when the two values are different,
+rather than choose one for you.
+
+### generateTypes
+
+The plugin reads the workspace schema and writes `picked-env.d.ts`, on `vite dev` and on
+`vite build`. [Type generation](/reference/sdk/type-generation) describes the output and
+the `picked.config.ts` options that control it.
+
+A failure stops the run. Set `generateTypes: false` for a build that must not write types,
+such as a build for one more entry point.
+
+### mode
+
+`'bundle'` reads your project options at build time and puts them in your bundle.
+
+`'api'` does not read them. Your build then makes no request to the Picked API, and
+writes no `.picked` directory. The SDK reads your project options from the API at
+runtime instead. Use this when your build must not depend on the Picked API.
+
+The SDK has no equivalent option. It uses the data your build gives it, and the API when
+your build gives none.
+
+## Build output
+
+For a production build, `vite build`, the plugin writes an `index.html` file that
+holds the launcher page. Set `disableLauncher` to stop this. The file lets you deploy
+the launcher next to your application, so that a stakeholder can see a preview.
+
+The plugin writes that file only when your build made no `index.html` of its own. An
+application that has an HTML entry keeps its own page at the root of the output.
+
+The plugin also writes a `.picked` directory next to your Vite `root`. It holds the
+options of your project and the CMS content of each experience.
+
+## Related
+
+- [How to install the Vite plugin](/how-to/install-the-vite-plugin)