Skip to content
Merged
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
32 changes: 32 additions & 0 deletions DIRECTORY-EDITION.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Claude plugin directory edition

This branch (`Claude`) is the version of the Deepnote plugin that the Claude plugin directory tracks. It is `main` with a few items removed. Do not merge it into `main`.

## Why it exists

The directory accepts scripts, file types outside its allowed list, and extra config fields only from Verified organizations. Deepnote's Claude organization is not Verified, so the directory refused the plugin as it is on `main`. `main` stays unchanged for Codex and for the Claude Code marketplace in this repository.

## How it differs from main

All differences are inside `plugins/deepnote/`, the only folder the directory reads:

- `skills/deepnote-data-apps/scripts/app-dev.mjs` is removed. The directory does not accept scripts.
- `assets/deepnote-icon.svg` is removed. SVG is not an allowed image type. The listing uses `assets/icon.png`.
- `.codex-plugin/plugin.json` is removed. It is not used by Claude and referred to the SVG.
- `.mcp.json` has no `bearer_token_env_var` field. Claude signs in with OAuth.
- `skills/deepnote-data-apps/SKILL.md` has no local preview steps. It tells Claude to say the page was not checked and to ask the user to open it.
- `README.md` in the plugin folder describes this edition.

The Codex marketplace file in `.agents/` and the root `README.md` are left as they are on `main`. They do not apply to this branch.

## Updating it for a release

1. Merge `main` into this branch: `git checkout Claude && git merge main`.
2. Resolve conflicts by keeping this branch's side for the items listed above. A change on `main` to a removed file shows up as a modify/delete conflict; keep the deletion.
3. Check that nothing in `plugins/deepnote/` refers to the removed files: `grep -rn -E "app-dev|scripts/|bearer_token|\.svg" plugins/deepnote`. The one expected match is the `logo.svg` example in the data apps skill.
4. Run `claude plugin validate --strict plugins/deepnote`.
5. Push. The directory scans the new commit and shows the result in the developer portal.

## Retiring it

Once the organization is Verified, set the plugin's tracked branch back to `main` on its Settings tab in the developer portal, then delete this branch.
47 changes: 0 additions & 47 deletions plugins/deepnote/.codex-plugin/plugin.json

This file was deleted.

3 changes: 1 addition & 2 deletions plugins/deepnote/.mcp.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,7 @@
"mcpServers": {
"deepnote": {
"type": "http",
"url": "https://deepnote.com/mcp",
"bearer_token_env_var": "DEEPNOTE_MCP_TOKEN"
"url": "https://deepnote.com/mcp"
}
}
}
5 changes: 3 additions & 2 deletions plugins/deepnote/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ If you already added the Deepnote connector in Claude, the plugin uses the same

Then run `/mcp`, choose the Deepnote server, and sign in.

Installed this way, the plugin also includes a script that previews data apps on your computer before publishing. The directory edition leaves that script out.

## Requirements

- A Deepnote account with access to the workspace you want to use.
Expand All @@ -35,8 +37,7 @@ Then run `/mcp`, choose the Deepnote server, and sign in.
## Data and network access

- The plugin sends requests to `https://deepnote.com/mcp` on your behalf. What Claude reads there, such as notebook content, run outputs, file contents, and integration metadata, becomes part of your conversation with Claude.
- The plugin has no hooks and runs nothing on its own.
- The data apps skill ships one optional script, `skills/deepnote-data-apps/scripts/app-dev.mjs`, which Claude can run to preview a data app page before publishing it. It needs Node 18 or later and uses built-in modules only. It starts two servers on `127.0.0.1` (ports 4747 and 4748 by default), serves the page folder from your computer, and makes no outbound requests itself. The previewed page calls the Deepnote API from your browser with a short-lived viewer token that is passed on the command line and never written to a file. The preview only works where Claude can run local commands.
- The plugin has no hooks, ships no scripts, and runs nothing on your computer.
- Data app pages that Claude writes with this skill load the Deepnote app client from `deepnote.com`, the Tailwind CSS browser build from `cdn.jsdelivr.net`, and the Inter font from `fonts.googleapis.com`.

## Links
Expand Down
10 changes: 0 additions & 10 deletions plugins/deepnote/assets/deepnote-icon.svg

This file was deleted.

17 changes: 3 additions & 14 deletions plugins/deepnote/skills/deepnote-data-apps/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ A data app project has two parts: the page, a responsive HTML page in `_deepnote
## The Page

- `index.html` can load other files from `_deepnote_static/` by relative path, such as `styles.css`, `app.js`, or `logo.svg`. Keep the app client script and the Tailwind setup below in `index.html`, and move the rest into files of their own when that keeps the page easier to change.
- Keep a local copy of `_deepnote_static/` in a folder of its own. Read each file the page loads or you will change with `read_file` once, unless you wrote it in this conversation; `get_project` lists them. Images that `read_file` cannot read show as broken in the local preview. Edit the files there, and once the page works in the local preview in Testing, push each new or changed file with `write_file` at its path under `_deepnote_static/` and `overwrite: true`. Where you cannot run local commands, write the files with `write_file` directly. When the app existed before this conversation, ask the user before the first push whether to update it in Deepnote, with the preview URL when there is one: pushing overwrites the app for good, and viewers of a published app see the change at once. Once they agree, push later changes they ask for in this conversation without asking again.
- Read each file the page loads or you will change with `read_file` once, unless you wrote it in this conversation; `get_project` lists them. Write each new or changed file with `write_file` at its path under `_deepnote_static/` and `overwrite: true`. When the app existed before this conversation, ask the user before the first push whether to update it in Deepnote: pushing overwrites the app for good, and viewers of a published app see the change at once. Once they agree, push later changes they ask for in this conversation without asking again.
- Start the `<head>` of `index.html` with `<script src="https://deepnote.com/static/app-client/v1.js"></script>`, before any other script, and load CDN scripts with `crossorigin="anonymous"`. The script exposes `Deepnote.connect()`, not React components or `DeepnoteApp`.
- Style the page with Tailwind CSS 4.3.3. After the app client script, add the Tailwind browser build, Inter, and the default theme below, then use its colors in classes (`bg-surface`, `text-muted`, `border-border`, `bg-accent`, `text-positive`, ...). Its dark values apply on their own, so don't add `dark:` variants for theme colors. Chart code reads series colors with `getComputedStyle(document.documentElement).getPropertyValue('--color-chart-1')`.

Expand Down Expand Up @@ -78,23 +78,12 @@ A data app project has two parts: the page, a responsive HTML page in `_deepnote

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, when the app lets everyone with access see results without running it, they see the latest editor run until they run it themselves. Delete scratch blocks when done.

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.
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.

A client that cannot run local commands, such as ChatGPT or claude.ai, cannot load the page: say the page itself was not checked and ask the user to open it. Do not install browser tools in the notebook to check it.
This edition of the plugin has no local preview, so the page cannot be loaded before it is pushed. After pushing, say the page itself was not checked and ask the user to open it. Do not mint a viewer token with `create_data_app_token` or install browser tools in the notebook to check it.

## Publishing

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. MCP also can't see or change **Let everyone with access see results without running the app**, which editors find under **General** in the project's settings sidebar.

## Reporting

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 `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.
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 app URL from `dataApp.url` in `get_project`, and never construct it. When the changes were not pushed, say the app in Deepnote is unchanged instead.
Loading
Loading