Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions plugins/deepnote/skills/deepnote-data-apps/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,13 +65,13 @@ 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('<notebook ID>')`, using the notebook ID from `get_project`.
- Connect with `const notebook = Deepnote.connect().notebook()`. Without an ID, it connects to the project's own notebook, so a copy of the project keeps working; never write that notebook's ID into the page or its files.
- On load, render `const {appData, agentBlockSummary, runCreatedAt} = await notebook.appData()` and show `runCreatedAt` as the time of the last update. When the app lets everyone with access see results without running it, 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.
- To show another app's data, connect to that app's notebook instead of copying its queries. Find its ID with `search`, check its JSON output with a read-only run, and do not change that notebook. Its keys can change, so show an error state when they are missing.
- To show another app's data, connect to that app's notebook with `Deepnote.connect().notebook('<its notebook ID>')` instead of copying its queries. Find the ID with `search`, check its JSON output with a read-only run, and do not change that notebook. Its keys can change, so show an error state when they are missing.
- Never put API keys, tokens, `.env` contents, or other secrets in the page or its files.

## Testing
Expand All @@ -81,7 +81,7 @@ Test a changed-input submission with `create_run`, its `inputs`, and `detachedRu
Preview the page locally before pushing it, against the same API and data it gets in Deepnote:

1. Mint a viewer token with `create_data_app_token` for the project. Pass it only on the command line; never write it into files or answers.
2. Run `node scripts/app-dev.mjs <folder with index.html> --token <token> --api-origin <apiOrigin>` in the background, with the script from this skill's directory. Have the same background command kill it after 15 minutes, for example after `sleep 900`, so previews do not pile up; the token expires then anyway. It needs Node 18 or later. It serves the page embedded the way Deepnote does, prints the preview URL, and logs files the page asks for that do not exist.
2. Run `node scripts/app-dev.mjs <folder with index.html> --token <token> --api-origin <apiOrigin> --notebook-id <notebookId>` in the background, with the script from this skill's directory. Have the same background command kill it after 15 minutes, for example after `sleep 900`, so previews do not pile up; the token expires then anyway. It needs Node 18 or later. It serves the page embedded the way Deepnote does, prints the preview URL, and logs files the page asks for that do not exist.
3. With a browser tool, open the preview URL. The bar above the page says whether the app connected to Deepnote and lists its errors. Look at the page and try the inputs; runs started there are real runs. Fix the files and reload until the bar shows no errors. When it stops, mint a new token and start it again.
4. Without a browser tool, give the user the preview URL, ask them to open it, and say that you did not check the page yourself.
5. Push the new and changed files, after asking the user first when the app existed before this conversation, and leave the preview running so the user can open it until it is killed after 15 minutes. Stop it sooner when the user asks, or before starting another preview on the same port. When the user still wants it after it stops, mint a new token and start it again.
Expand Down
14 changes: 8 additions & 6 deletions plugins/deepnote/skills/deepnote-data-apps/scripts/app-dev.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,11 @@ import http from 'node:http'
import path from 'node:path'
import { parseArgs } from 'node:util'

const USAGE = `Usage: node app-dev.mjs <folder with index.html> --token <token> --api-origin <apiOrigin> [--port <port>]
const USAGE = `Usage: node app-dev.mjs <folder with index.html> --token <token> --api-origin <apiOrigin> --notebook-id <notebookId> [--port <port>]

--token Viewer token from the create_data_app_token MCP tool. It is never printed.
--api-origin apiOrigin from the same create_data_app_token result.
--notebook-id notebookId from the same result, which Deepnote.connect().notebook() connects to when the page names none.
--port Port of the preview page; the app is served on the next one. Default 4747.`

// The common web types from the table Deepnote's server looks content types up in.
Expand Down Expand Up @@ -91,7 +92,7 @@ function createAppServer(root, origins, apiOrigin) {
})
}

function renderDeepnotePage({ appOrigin, apiOrigin, token }) {
function renderDeepnotePage({ appOrigin, apiOrigin, token, notebookId }) {
return `<!doctype html>
<html>
<head>
Expand All @@ -111,7 +112,7 @@ iframe { flex: 1; width: 100%; border: 0; color-scheme: light dark; }
<div id="status" role="status">Waiting for the app to connect to Deepnote.</div>
<iframe src="${appOrigin}/" allow="fullscreen" title="Data app"></iframe>
<script>
const { appOrigin, apiOrigin, token } = ${JSON.stringify({ appOrigin, apiOrigin, token })}
const { appOrigin, apiOrigin, token, notebookId } = ${JSON.stringify({ appOrigin, apiOrigin, token, notebookId })}
const status = document.getElementById('status')
const errors = []
let connected = false
Expand All @@ -137,7 +138,7 @@ window.addEventListener('message', event => {
const { type, message, line, source } = event.data ?? {}
if (type === 'deepnote-static-files-api-token-request') {
const expiresAtSeconds = Math.floor(Date.now() / 1000) + ${TOKEN_LIFETIME_SECONDS}
event.source.postMessage({ type: 'deepnote-static-files-api-token-response', token, apiOrigin, expiresAtSeconds }, appOrigin)
event.source.postMessage({ type: 'deepnote-static-files-api-token-response', token, apiOrigin, expiresAtSeconds, notebookId }, appOrigin)
return
}
if (type === 'deepnote-static-files-app-ready') {
Expand Down Expand Up @@ -170,6 +171,7 @@ async function main() {
options: {
token: { type: 'string' },
'api-origin': { type: 'string' },
'notebook-id': { type: 'string' },
port: { type: 'string', default: '4747' },
help: { type: 'boolean', default: false },
},
Expand All @@ -178,7 +180,7 @@ async function main() {
console.log(USAGE)
return
}
if (positionals.length !== 1 || !values.token || !values['api-origin']) {
if (positionals.length !== 1 || !values.token || !values['api-origin'] || !values['notebook-id']) {
fail(USAGE)
}
const root = path.resolve(positionals[0])
Expand All @@ -192,7 +194,7 @@ async function main() {
const deepnoteServer = http.createServer((req, res) =>
res
.writeHead(200, { 'cache-control': 'no-store', 'content-type': 'text/html; charset=utf-8' })
.end(renderDeepnotePage({ appOrigin: origins.app, apiOrigin, token: values.token }))
.end(renderDeepnotePage({ appOrigin: origins.app, apiOrigin, token: values.token, notebookId: values['notebook-id'] }))
)
origins.deepnote = await listen(deepnoteServer, port)
origins.app = await listen(createAppServer(root, origins, apiOrigin), port + 1)
Expand Down
2 changes: 1 addition & 1 deletion plugins/deepnote/skills/deepnote-mcp/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ This is the authoritative summary of tool arguments. Workflow skills add only th
- `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, 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_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`, `expiresAtSeconds`, and `notebookId`, the app's notebook. 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.
- `get_streamlit_app_status`: return `running`, `starting`, or `unavailable` for a `streamlitAppId`.
Expand Down