diff --git a/README.md b/README.md index 05237eb..6f1d3a9 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,7 @@ Things to know: - Sign-in says the workspace cannot use the MCP connector, or that MCP access is disabled: a workspace admin needs to enable MCP access for that workspace. - A project, notebook, or integration is missing: the signed-in user, or the API key's creator, needs access to it. - Creating or editing fails with `Insufficient permissions`: use an editor or admin key, or a user with edit access to the project. -- `update_project` fails with `Insufficient permissions`: publishing a data app or changing a project's Streamlit app API access or environment needs full access to the project, not just edit access. +- `update_project` fails with `Insufficient permissions`: publishing a data app needs edit access to the project, and changing its environment or folder needs full access. - Attaching or detaching an integration returns a conflict: inspect the project because the integration is already in the requested state. - `copy_file` reports `File already exists`: the target project already has the same path; the tool never overwrites. - `write_file` wrote to a different path than requested: the path was taken, so a unique path was generated. Ask the agent to overwrite the file if you meant to replace it. diff --git a/plugins/deepnote/skills/deepnote-data-apps/SKILL.md b/plugins/deepnote/skills/deepnote-data-apps/SKILL.md index 8e6338d..19b1785 100644 --- a/plugins/deepnote/skills/deepnote-data-apps/SKILL.md +++ b/plugins/deepnote/skills/deepnote-data-apps/SKILL.md @@ -28,7 +28,7 @@ A data app project has two parts: the page, a responsive HTML page in `_deepnote - Queries, heavy computation, credentials, and authenticated calls stay in the notebook. The page only filters, sorts, and charts. - The app's controls are the notebook's input blocks. Reuse them by name and add only the missing ones. - For AI-written text, such as a summary of the data, keep an agent block as the last block and ask for that text in its prompt. The page reads it as `agentBlockSummary`. -- The page shows each viewer's own newest successful detached run, so running blocks in the editor changes nothing. After changing the notebook, start a run with `create_run` and `detachedRunStorageMode: "readonly"`, wait until `get_run` with `snapshotDelivery: "blocks"` reports success, and check the JSON output's keys, types, and first rows before wiring the page to it. Changes to the page alone need no new run. +- The page shows each viewer's own newest successful detached run, or, in a public app without private outputs, the editors' newest one until the viewer runs it, so running blocks in the editor changes nothing. After changing the notebook, start a run with `create_run` and `detachedRunStorageMode: "readonly"`, wait until `get_run` with `snapshotDelivery: "blocks"` reports success, and check the JSON output's keys, types, and first rows before wiring the page to it. Changes to the page alone need no new run. ## The Page @@ -66,8 +66,8 @@ A data app project has two parts: the page, a responsive HTML page in `_deepnote - By default, make it calm and compact like Deepnote without copying Deepnote's UI: neutral surfaces with one blue accent, 1px borders, `rounded-lg` controls and `rounded-xl` cards, sentence case, solid backgrounds without gradients, no emoji or decorative icons, shadows only on floating elements, and at most one primary button per view. When the user asks for another look or their brand, change the theme and classes freely. - Connect with `const notebook = Deepnote.connect().notebook('')`, using the notebook ID from `get_project`. - - On load, render `const {appData, agentBlockSummary} = await notebook.appData()`. It throws when the viewer has no run yet, their results expired, or the run has no JSON output: show the message in an empty state with a button that runs the notebook with `{}`. - - `const {run} = await notebook.run(values, {onProgress})` runs the whole notebook for this viewer. When `run.status === 'success'`, render `await notebook.appData()` again. Run it on submission, or with `{}` from a refresh button when the app has no inputs. + - On load, render `const {appData, agentBlockSummary, runCreatedAt} = await notebook.appData()` and show `runCreatedAt` as the time of the last update. In a public app without private outputs, a viewer with no run of their own gets the latest results of the app's editors. It throws when the viewer has no run yet, their results expired, or the run has no JSON output: show the message in an empty state with a button that runs the notebook with `{}`. + - `const {run} = await notebook.run(values, {onProgress})` runs the whole notebook for this viewer. When `run.status === 'success'`, render `await notebook.appData()` again. Run it on submission, or with `{}` from a refresh button when the app has no inputs. Public visitors with **View** access can't run the app, so the call rejects: show its message. - Build the form from `await notebook.inputs()`, which returns each input's label, value, min, max, step, and options, so input changes in the notebook reach the app. Never overwrite input variables with hardcoded values. Values are keyed by input name and are strings (sliders too), booleans, or string arrays. - Show loading, empty, and error states, prevent duplicate submissions, and handle rejected calls, missing results, and `run.error`. When a failed run has no error text, show its status and point to run history. - Lay out dashboards as a title with one line of context, filters, a row of key numbers, one to three main charts, then a detail table. Format numbers and dates for reading, and label units. @@ -76,7 +76,7 @@ A data app project has two parts: the page, a responsive HTML page in `_deepnote ## Testing -Test a changed-input submission with `create_run`, its `inputs`, and `detachedRunStorageMode: "readonly"`, then read it with `get_run` and `snapshotDelivery: "blocks"`. When it fails, inspect its status and output and fix the cause; when it is still pending after several checks, point to run history without claiming the flow works. Delete scratch blocks when done. +Test a changed-input submission with `create_run`, its `inputs`, and `detachedRunStorageMode: "readonly"`, then read it with `get_run` and `snapshotDelivery: "blocks"`. When it fails, inspect its status and output and fix the cause; when it is still pending after several checks, point to run history without claiming the flow works. Finish with a run using `{}` and check that it succeeds, since in a public app the latest editor run is what visitors see. Delete scratch blocks when done. Preview the page locally before pushing it, against the same API and data it gets in Deepnote: @@ -90,11 +90,11 @@ A client that cannot run local commands, such as ChatGPT or claude.ai, cannot lo ## Publishing -A new data app is unpublished, so only the project's editors can open it. Publish it to its viewers only when the user asks, with `update_project` and `staticFiles.published: true`; `false` makes it editor-only again. Viewers need access to the project and the workspace must allow static file sharing; link sharing isn't available. People are invited from the Share menu in Deepnote, not through MCP. +Published and public are different settings. Published lets people with access to the project open the app; public lets anyone with its link open it, without a Deepnote account. A new data app is unpublished, so only the project's editors can open it. Publish it only when the user asks, with `update_project` and `dataApp.published: true`; `false` makes it editor-only again and ends public access for good: publishing it again doesn't bring it back. MCP and the API can't make an app public or see whether it is: when the user asks for that, tell them a project admin can turn on **Anyone with a link to this app** in the Share menu in Deepnote, with View to show results or Execute to also let visitors run it. People are invited from the Share menu too, not through MCP. ## Reporting -Report the project and whether the app is published, and describe the work as changes to the app. End with the links as two options, labeled with where each one runs: +Report the project and whether the app is published, and describe the work as changes to the app. MCP can't tell whether the app is public, so don't say either way. End with the links as two options, labeled with where each one runs: -1. Deepnote (cloud): the app URL from `staticFiles.url` in `get_project`. Never construct it. When the changes were not pushed, say the app in Deepnote is unchanged instead. +1. Deepnote (cloud): the app URL from `dataApp.url` in `get_project`. Never construct it. When the changes were not pushed, say the app in Deepnote is unchanged instead. 2. Local preview (this computer only): the preview URL and the time it stops, while a preview is running. diff --git a/plugins/deepnote/skills/deepnote-links/SKILL.md b/plugins/deepnote/skills/deepnote-links/SKILL.md index 2a33442..addd167 100644 --- a/plugins/deepnote/skills/deepnote-links/SKILL.md +++ b/plugins/deepnote/skills/deepnote-links/SKILL.md @@ -69,7 +69,7 @@ folder/notebook 10% + a1b2c3d4 - File paths, when exposed and requested, append after the project segment as `/{encodeURIComponent(filePath)}`. - Cell or block anchors append after the UTM query string as `#anchor`. - Use Streamlit URLs returned by `create_streamlit_app` or `list_streamlit_apps`; do not assemble them from an app ID. -- Use the data app URL from `staticFiles.url` in `get_project`; never construct it. +- Use the data app URL from `dataApp.url` in `get_project`; never construct it. ## UTM Parameters diff --git a/plugins/deepnote/skills/deepnote-mcp/SKILL.md b/plugins/deepnote/skills/deepnote-mcp/SKILL.md index 070e791..70b6311 100644 --- a/plugins/deepnote/skills/deepnote-mcp/SKILL.md +++ b/plugins/deepnote/skills/deepnote-mcp/SKILL.md @@ -21,7 +21,7 @@ This is the authoritative summary of tool arguments. Workflow skills add only th - `search`: search workspace resources across projects, notebooks, blocks, and integrations. - `list_folders`: list all workspace folders and their `parentFolderId` relationships, optionally filtered by `nameContains`. - `list_projects`: list workspace projects, optionally filtered by name, with cursor pagination (`pageSize`, `pageToken`, `pagination.nextPageToken`, `pagination.hasMore`). Notebook rows expose `isInit`, `isScheduled`, and `lastRunAt`. -- `get_project`: get a project's type, folder, notebooks, attached integration summaries, recursive file inventory, data app settings (`staticFiles`), `streamlitAppApiAccessEnabled`, and environment (Docker image) by `projectId`. `environment` is `null` when the project builds its image from a Dockerfile or has none set. +- `get_project`: get a project's type, folder, notebooks, attached integration summaries, recursive file inventory, data app settings (`dataApp` with `published` and `url`, `null` when the project is not a data app), and environment (Docker image) by `projectId`. `environment` is `null` when the project builds its image from a Dockerfile or has none set. `dataApp.published` doesn't say whether the app is public; MCP can't see that. - `list_environments`: list the environments (Docker images) projects in the workspace can run on, Deepnote's and the workspace's custom ones, in one unpaginated response. Each has `id`, `name`, `image`, `type` (`deepnote` or `custom`), `language` (`python` or `r`), `isDefault` (one CPU and one GPU default), `isGpu`, and `isDeprecated`; deprecated environments keep working for projects already on them but should not be chosen. A custom image from a private registry is pulled only when its registry integration is attached to the project. - `list_integrations`: list workspace integrations, optionally filtered by name or type. - `get_integration`: get integration details and cached table structure, optionally filtered by `databaseName`, `schemaName`, or exact `tableName`. For large integrations, `search` takes a natural-language description and returns only the 20 most relevant tables. @@ -32,7 +32,7 @@ This is the authoritative summary of tool arguments. Workflow skills add only th - `attach_integration`: attach an integration to a project. Requires `integrationId` and `projectId`; returns a conflict if already attached. - `detach_integration`: detach an integration from a project. Requires `integrationId` and `projectId`; returns a conflict if not attached. - `create_folder`: create a workspace folder. Requires `name`; accepts optional `parentFolderId` from `list_folders` (omitted means the workspace root). Folder names are not unique, so reuse an existing folder from `list_folders` instead of creating a duplicate. -- `create_project`: create a new project. Requires `name`; accepts optional `folderId`, `projectType` (`standard`, `notebook`, `agent`, `data_app`, or `streamlit_app`; defaults to `standard`), and `environmentId` from `list_environments` (defaults to the default environment). The created project includes a default notebook. A `streamlit_app` project also starts with a placeholder `app.py` that is already served as a Streamlit app, with `streamlitAppApiAccessEnabled` on; a `data_app` project starts with a placeholder `_deepnote_static/index.html`, with sharing and viewer API access on. `notebook`, `agent`, `data_app`, and `streamlit_app` projects have a single notebook and reject creating, renaming, duplicating, or deleting notebooks. +- `create_project`: create a new project. Requires `name`; accepts optional `folderId`, `projectType` (`standard`, `notebook`, `agent`, `data_app`, or `streamlit_app`; defaults to `standard`), and `environmentId` from `list_environments` (defaults to the default environment). The created project includes a default notebook. A `streamlit_app` project also starts with a placeholder `app.py` that is already served as a Streamlit app, with viewer API access on; a `data_app` project starts with a placeholder `_deepnote_static/index.html`, with sharing and viewer API access on. `notebook`, `agent`, `data_app`, and `streamlit_app` projects have a single notebook and reject creating, renaming, duplicating, or deleting notebooks. - `delete_project`: move a project and all its notebooks to the workspace trash by `projectId`, where it can be restored for 30 days. Its schedules are deleted for good, and its machine is stopped. Requires full access to the project. - `create_notebook`: create an empty notebook inside a project. Requires `projectId`; accepts optional `name`. Does not accept starter blocks. - `get_notebook`: get notebook details, blocks, input variables, and last-run metadata by notebook ID. Each block carries only its `id`, `type`, `content`, and `contentHash`. @@ -48,7 +48,7 @@ This is the authoritative summary of tool arguments. Workflow skills add only th - `read_file`: read one small text-based file, such as a script, config, or CSV, by `projectId` and project-relative `path`, to inspect or edit it. Optional `startLine` and `endLine` (inclusive, starting at 1) read part of it. Returns `content`, `startLine`, `endLine`, and `hasMore`. A call returns at most 64 KiB and fails beyond that, so read a long file in line ranges, continuing while `hasMore` is true. It is not for large or binary files. View access is enough. - `write_file`: write one small text-based file, such as a script, config, or CSV, into a project. Requires `projectId`, project-relative `path`, and `content`; accepts `encoding` (`utf8` by default, or `base64` for small binary files) and `overwrite` (default `false`). Without `overwrite`, an existing path is left alone and the file is written to a generated unique path; the returned `file.path` is the path actually written. With `overwrite: true` it replaces the file, and a directory path returns a conflict. It is not a way to upload large files or big binary blobs. - `delete_file`: permanently delete one file by `projectId` and project-relative `path`; a directory path returns an error. A Streamlit app that uses the file as its entrypoint is deleted with it. -- `update_project`: change a project's data app publishing, hosted Streamlit app API access, environment, or folder. Requires `projectId`, full access to the project, and at least one of `staticFiles.published`, `streamlitAppApiAccessEnabled`, `environmentId` from `list_environments`, or `folderId` from `list_folders` or `create_folder` (`null` moves the project to the workspace root). `staticFiles.published` publishes or unpublishes a data app for its viewers; editors can always open it. Leave the other `staticFiles` settings as they are. `streamlitAppApiAccessEnabled` lets the project's hosted Streamlit apps call the public API as their signed-in viewers. Changing the environment restarts a running machine in the background, which clears kernel state. +- `update_project`: change a project's data app publishing, environment, or folder. Requires `projectId`, edit access to the project (full access to change the environment or folder), and at least one of `dataApp.published`, `environmentId` from `list_environments`, or `folderId` from `list_folders` or `create_folder` (`null` moves the project to the workspace root). `dataApp.published` publishes or unpublishes a data app for its viewers; editors can always open it. It never makes the app public, and unpublishing ends public access, which publishing again doesn't restore. Changing the environment restarts a running machine in the background, which clears kernel state. - `create_data_app_token`: mint a short-lived viewer token for a `data_app` project by `projectId`, so its page can be previewed locally against the real API. Returns `token`, `apiOrigin`, and `expiresAtSeconds`. The token acts as the caller in that project, so never write it into files. - `create_streamlit_app`: serve an existing project file as a Streamlit app. Requires `projectId` and project-relative `entrypoint`; returns the app record and URL. - `list_streamlit_apps`: list all Streamlit apps served by a project. Requires `projectId`; the response is unpaginated. @@ -81,11 +81,11 @@ Before telling a user that a Deepnote action is impossible, check the tools the - Avoid downloading or printing large datasets. Sample, summarize, or aggregate unless the user explicitly asks for an export. - Do not paste `snapshotDownloadUrl` values into answers unless the user asks for a download or file handoff. Snapshot handling is defined in `deepnote-runs`. - Treat notebook execution as potentially stateful and costly. -- Treat resource creation, notebook duplication or renaming, block edits, file writes and copies, deleting projects, notebooks, blocks, or files, integration creation or attachment changes, app creation, data app publishing, Streamlit app API access changes, environment, folder, and sandbox environment changes, and machine type or idle shutdown changes as persistent writes. Do them only when the user asked, resolve targets carefully, and report affected IDs. +- Treat resource creation, notebook duplication or renaming, block edits, file writes and copies, deleting projects, notebooks, blocks, or files, integration creation or attachment changes, app creation, data app publishing, environment, folder, and sandbox environment changes, and machine type or idle shutdown changes as persistent writes. Do them only when the user asked, resolve targets carefully, and report affected IDs. - Delete only what the user named, and say what can be undone: `delete_notebook` can be restored from version history and `delete_project` from the trash for 30 days, but a deleted project's schedules are gone. `delete_file` cannot be undone, nor can the old content `write_file` replaces with `overwrite: true`. - A running machine uses machine time. Start, stop, or restart it, or change its type or the project's environment, only when the user asked; a live run the user asked for may start it. Stopping or restarting it, changing its type or sandbox environment with `restart: true`, and changing the project's environment clear kernel state for everyone working in the project, so say that kernel state will be lost. - If a tool returns `isError`, surface the user-facing error message concisely. -- Capability boundary: the hosted server can create folders, integrations, and Streamlit apps; create and delete projects, notebooks, and blocks; rename and duplicate notebooks; update and reorder blocks; read and write small text-based project files, copy files between projects, and delete files; attach and detach integrations; publish and unpublish data apps; mint short-lived viewer tokens to preview a data app page locally; move a project to another folder and change its Streamlit app API access and environment; and start, stop, restart, or resize the project machine. It cannot read or upload large files or big binary blobs, delete folders or integrations, delete a Streamlit app other than by deleting its entrypoint file, move notebooks between projects, create custom environments, or change schedules, permissions, package versions, credentials, or secrets. Check the advertised tools before relying on this boundary. +- Capability boundary: the hosted server can create folders, integrations, and Streamlit apps; create and delete projects, notebooks, and blocks; rename and duplicate notebooks; update and reorder blocks; read and write small text-based project files, copy files between projects, and delete files; attach and detach integrations; publish and unpublish data apps; mint short-lived viewer tokens to preview a data app page locally; move a project to another folder and change its environment; and start, stop, restart, or resize the project machine. It cannot make a data app public, read or upload large files or big binary blobs, delete folders or integrations, delete a Streamlit app other than by deleting its entrypoint file, move notebooks between projects, create custom environments, or change schedules, permissions, package versions, credentials, or secrets. Check the advertised tools before relying on this boundary. ## Response Style diff --git a/plugins/deepnote/skills/deepnote-streamlit-apps/SKILL.md b/plugins/deepnote/skills/deepnote-streamlit-apps/SKILL.md index fcc4ae1..de065ea 100644 --- a/plugins/deepnote/skills/deepnote-streamlit-apps/SKILL.md +++ b/plugins/deepnote/skills/deepnote-streamlit-apps/SKILL.md @@ -11,7 +11,7 @@ A Streamlit app project has two parts: the app, Python code in `app.py` hosted o ## Creating An App -1. Create the project with `create_project` and `projectType: "streamlit_app"`. It starts with its notebook and a placeholder `app.py` that is already served, with `streamlitAppApiAccessEnabled` on. +1. Create the project with `create_project` and `projectType: "streamlit_app"`. It starts with its notebook and a placeholder `app.py` that is already served, with viewer API access already on. 2. Get the app ID and URL from `list_streamlit_apps`. Do not call `create_streamlit_app`; the project serves one app. 3. Look for data in the project's integrations and files first, then build a small, polished first version. If nothing fits, use clearly labeled sample data and offer to connect real data, unless the user named specific data: then ask where it is.