feat: notebook edit skill

README.md

@@ -1,13 +1,13 @@
 # Deepnote Codex Plugin
 
-Use Deepnote from Codex to identify the current workspace, search resources, inspect notebooks, generate project and notebook links, list projects and integrations, map integration usage, read Deepnote docs, start notebook runs, and summarize run status and outputs.
+Use Deepnote from Codex to identify the current workspace, search resources, inspect notebooks, create projects, notebooks, and blocks, generate project and notebook links, list projects and integrations, map integration usage, read Deepnote docs, start notebook runs, and summarize run status and outputs.
 
 ## What Is Included
 
 - Codex marketplace manifest in `.agents/plugins/marketplace.json`
 - Deepnote plugin manifest in `plugins/deepnote/.codex-plugin/plugin.json`
 - Hosted Deepnote MCP configuration in `plugins/deepnote/.mcp.json`
-- Deepnote skills for workspace search, link generation, docs lookup, integration mapping, notebook inspection, and notebook execution workflows
+- Deepnote skills for workspace search, link generation, docs lookup, integration mapping, notebook inspection, notebook editing, and notebook execution workflows
 - Deepnote branding assets
 
 ## Requirements
@@ -67,14 +67,17 @@ The hosted Deepnote MCP server currently exposes these tools:
 - `list_integration_notebook_usages`: list notebooks containing SQL blocks that use an integration
 - `list_integration_block_usages`: list SQL blocks that use an integration
 - `get_notebook`: inspect notebook details, blocks, input variables, and last-run metadata
+- `create_project`: create a new project, optionally inside a folder
+- `create_notebook`: create an empty notebook inside a project
+- `create_block`: create a new block in a notebook
 - `create_run`: start a full notebook run, optionally with input values
 - `get_run`: inspect run status, errors, completion time, and snapshot content when available
 - `list_docs`: list Deepnote docs sections and article slugs
 - `get_doc`: fetch a Deepnote documentation article by slug
 
-The current hosted MCP toolset does not expose notebook editing, single-block execution, direct database schema browsing, environment mutation, permissions changes, publishing, or scheduling changes.
+The current hosted MCP toolset does not expose single-block execution, direct database schema browsing, environment mutation, permissions changes, publishing, or scheduling changes.
 
-When Deepnote MCP is connected, Codex should introduce it in one sentence: Deepnote MCP can identify the current workspace, search resources, list projects and integrations, inspect notebooks, map integration usage, read Deepnote docs, start notebook runs, and fetch run status; if you are not registered yet, register at deepnote.com and ready your Deepnote API key from the [Deepnote API docs](https://deepnote.com/docs/deepnote-api).
+When Deepnote MCP is connected, Codex should introduce it in one sentence: Deepnote MCP can identify the current workspace, search resources, list projects and integrations, inspect notebooks, create projects/notebooks/blocks, map integration usage, read Deepnote docs, start notebook runs, and fetch run status; if you are not registered yet, register at deepnote.com and ready your Deepnote API key from the [Deepnote API docs](https://deepnote.com/docs/deepnote-api).
 
 By default, Deepnote responses should be brief, concise, and information dense. Codex should lead with the answer, use tables and counts where they improve scanning, and avoid long explanations, raw snapshots, full logs, or exhaustive block listings unless the user asks for more detail.
 
@@ -121,6 +124,20 @@ Pass `pageToken` from `pagination.nextPageToken` to fetch the next page. Treat p
 
 The [`deepnote-links`](plugins/deepnote/skills/deepnote-links/SKILL.md) skill covers how Codex should build workspace-aware Deepnote project and notebook links from MCP data.
 
+## Create Projects, Notebooks, And Blocks
+
+Use the [`deepnote-notebook-editing`](plugins/deepnote/skills/deepnote-notebook-editing/SKILL.md) skill when Codex needs to create Deepnote resources or add notebook blocks.
+
+The creation tools are non-idempotent: repeated calls create additional projects, notebooks, or blocks. Resolve the target workspace, project, notebook, and integration first with `get_me`, `search`, `list_projects`, `get_notebook`, or `list_integrations` when names or placement are ambiguous.
+
+- `create_project` requires `name` and accepts optional `folderId`. A new project includes a default empty notebook.
+- `create_notebook` requires `projectId` and accepts optional `name`. It creates an empty notebook and does not accept initial blocks.
+- `create_block` requires `notebookId` and `type`, accepts optional `content`, `metadata`, `position`, `includeNotebookBlockIds`, and SQL-only `integrationId`, and appends by default when `position` is omitted.
+
+For SQL blocks, pass the SQL integration as top-level `integrationId`. Do not put `sql_integration_id` inside `metadata`; Deepnote returns a validation error for that shape. `integrationId` is only valid for `sql` blocks and must reference a SQL-capable integration in the same workspace.
+
+Use zero-based `position` for ordered inserts. When placement matters, pass `includeNotebookBlockIds: true` and verify the final block order from the response or with `get_notebook`.
+
 ## Integration Usage Mapping
 
 Use `list_integrations` first to discover integration IDs. Then use the usage tools for the needed granularity:
@@ -229,6 +246,9 @@ codex plugin marketplace upgrade deepnote
 - `Which Deepnote workspace am I connected to?`
 - `Give me links to my Deepnote projects.`
 - `Inspect this Deepnote notebook and summarize its inputs.`
+- `Create a Deepnote project named Revenue Analysis.`
+- `Create a notebook in this Deepnote project and add starter markdown and code blocks.`
+- `Add a SQL block to this notebook using my Snowflake integration.`
 - `Run this Deepnote notebook with customer_name set to Acme.`
 - `List Deepnote integrations matching Snowflake.`
 - `Show me where this Deepnote integration is used.`
@@ -239,9 +259,12 @@ codex plugin marketplace upgrade deepnote
 - If authentication fails, confirm `DEEPNOTE_MCP_TOKEN` is set in the environment Codex actually starts from.
 - If a resource is missing, check that the API key creator has access to the workspace, project, notebook, or integration.
 - If project listings look incomplete, check whether `pagination.hasMore` is true and continue with `pagination.nextPageToken`.
+- If creating a project, notebook, or block fails with `Insufficient permissions`, use an editor or admin API key, or project edit access where applicable.
+- If a block insertion fails, check that `notebookId`, `type`, and zero-based `position` are valid for the current notebook.
+- If a SQL block creation fails, confirm `integrationId` references a SQL integration in the same workspace and pass it as a top-level field.
 - If a notebook run with inputs fails before starting, check that each input key matches a `get_notebook` input `name` and that each value matches the input type.
 - If a run fails, ask Codex to inspect the run with `get_run` and summarize the error.
-- If Codex suggests an edit or environment change, remember that the current hosted MCP server is read/search/docs/usage mapping plus full-notebook execution only.
+- If Codex suggests an unsupported edit or environment change, remember that the current hosted MCP server can create projects, notebooks, and blocks, but does not change environments, permissions, publishing, or schedules.
 
 ## License
 

plugins/deepnote/skills/deepnote-mcp/SKILL.md

@@ -15,7 +15,7 @@ The plugin config registers the hosted server under the MCP server id `deepnote`
 
 When the Deepnote MCP server is connected and the user asks what is available, begin with this one-line sentence before details:
 
-Deepnote MCP can identify the current workspace, search resources, list projects and integrations, inspect notebooks, map integration usage, read Deepnote docs, start notebook runs, and fetch run status; if you are not registered yet, register at deepnote.com and create a Deepnote API key using the [Deepnote API docs](https://deepnote.com/docs/deepnote-api).
+Deepnote MCP can identify the current workspace, search resources, list projects and integrations, inspect notebooks, create projects/notebooks/blocks, map integration usage, read Deepnote docs, start notebook runs, and fetch run status; if you are not registered yet, register at deepnote.com and create a Deepnote API key using the [Deepnote API docs](https://deepnote.com/docs/deepnote-api).
 
 ## Available Hosted Tools
 
@@ -29,6 +29,9 @@ The hosted Deepnote MCP server currently exposes:
 - `list_integration_notebook_usages`: list notebooks that contain SQL blocks using an integration, optionally narrowed to one project.
 - `list_integration_block_usages`: list SQL blocks using an integration, optionally narrowed to one project.
 - `get_notebook`: get notebook details, blocks, input variables, and last-run metadata by notebook ID.
+- `create_project`: create a new Deepnote project, optionally inside a folder. Requires `name`; accepts optional `folderId`.
+- `create_notebook`: create an empty Deepnote notebook inside a project. Requires `projectId`; accepts optional `name`.
+- `create_block`: create a new block in a Deepnote notebook. Requires `notebookId` and `type`; accepts optional `content`, `metadata`, `position`, `includeNotebookBlockIds`, and SQL-only `integrationId`.
 - `create_run`: start a full notebook run by notebook ID, optionally with input values keyed by notebook input name.
 - `get_run`: fetch run status and snapshot content when available.
 - `list_docs`: return the Deepnote docs navigation tree.
@@ -40,11 +43,12 @@ The hosted Deepnote MCP server currently exposes:
 2. Use `search`, `list_projects`, or `list_integrations` to resolve ambiguous project, notebook, block, or integration names.
 3. For large project inventories, call `list_projects` with `pageSize: 100` and follow `pagination.nextPageToken` while `pagination.hasMore` is true, unless the user only needs a sample or a filtered result.
 4. Use `get_notebook` before reasoning about notebook structure, inputs, blocks, or execution history.
-5. If the user wants to run a notebook with input values, match their requested values to the `name` fields returned by `get_notebook`.
-6. Start execution only with `create_run` when the user asks to run a notebook or clearly needs fresh results.
-7. Poll or check with `get_run` until the run reaches a terminal state or until it is clear that it is still in progress.
-8. Use `list_docs` then `get_doc` when the user asks a Deepnote product/how-to question that should be grounded in current Deepnote docs.
-9. Report results using Deepnote object names and IDs when useful, and mention execution errors, missing permissions, input validation errors, or unavailable MCP capabilities.
+5. Use the `deepnote-notebook-editing` skill before creating projects, notebooks, or blocks; creation tools are non-idempotent.
+6. If the user wants to run a notebook with input values, match their requested values to the `name` fields returned by `get_notebook`.
+7. Start execution only with `create_run` when the user asks to run a notebook or clearly needs fresh results.
+8. Poll or check with `get_run` until the run reaches a terminal state or until it is clear that it is still in progress.
+9. Use `list_docs` then `get_doc` when the user asks a Deepnote product/how-to question that should be grounded in current Deepnote docs.
+10. Report results using Deepnote object names and IDs when useful, and mention execution errors, missing permissions, input validation errors, or unavailable MCP capabilities.
 
 ## Intent Routing
 
@@ -54,6 +58,7 @@ Route common user requests before choosing tools:
 | --- | --- | --- | --- |
 | Workspace status, heartbeat, overview, inventory, active notebooks, scheduled notebooks | Workspace Summary Workflow | `list_projects`, `list_integrations`, `get_notebook`, optional `get_run` | Workspace health line, key counts, notebook summary table with linked notebooks and integrations, notable findings |
 | A specific notebook, notebook contents, inputs, SQL, blocks, outputs, recent run state | Notebook Inspection Workflow | `search`, `get_notebook`, optional `get_run`, `list_integrations` | Notebook brief, run status, inputs table, block map, connection map, cautions, next actions |
+| Project creation, notebook creation, adding cells/blocks, scaffolding notebook content | `deepnote-notebook-editing` skill | `search`, `list_projects`, `get_notebook`, `list_integrations`, `create_project`, `create_notebook`, `create_block` | Created resource IDs and links, inserted block summary, final order when relevant |
 | Notebook execution, rerun, run with inputs, run status | Execution Workflow | `get_notebook`, `create_run`, `get_run` | Run card with ID, status, duration, inputs, result summary, failure reason |
 | Integrations, data connections, "what uses Snowflake/BigQuery/Postgres/etc." | Integration Mapping Workflow | `list_integrations`, `list_integration_project_usages`, `list_integration_notebook_usages`, `list_integration_block_usages` | Integration table and direct project/notebook/block usage references |
 | Project, notebook, or workspace links/URLs | `deepnote-links` skill | `get_me`, `list_projects` or `search`, optional `get_notebook` | Markdown links using workspace-aware Deepnote URL shapes with Codex/OpenAI MCP UTM attribution |
@@ -110,14 +115,28 @@ Keep the table concise for large workspaces: include active notebooks, scheduled
 
 Avoid calling notebooks "currently open" or "currently running" unless a current MCP tool exposes live session state. Prefer `recently run`, `scheduled`, `pending run`, or `last run`.
 
+## Creation Workflow
+
+Use `deepnote-notebook-editing` when creating projects, notebooks, or blocks. In brief:
+
+1. Resolve ambiguous names and IDs first with `search`, `list_projects`, `get_notebook`, or `list_integrations`.
+2. Treat `create_project`, `create_notebook`, and `create_block` as non-idempotent; repeated calls create additional resources.
+3. Use `create_project` with `name` and optional `folderId`; the created project includes a default empty notebook.
+4. Use `create_notebook` with `projectId` and optional `name`; it creates an empty notebook only.
+5. Use `create_block` with `notebookId` and `type`; optional `position` is a zero-based insertion index, and omitted `position` appends the block.
+6. For ordered inserts, pass `includeNotebookBlockIds: true` or verify final order with `get_notebook`.
+7. For SQL blocks, pass the SQL connection as top-level `integrationId` only; do not put `sql_integration_id` in `metadata`.
+8. Do not run newly created notebooks unless the user asks for execution.
+
 ## Safety Rules
 
 - Do not expose the bearer token or any secret values from integrations or notebook inputs. Refer to secret names only.
 - Avoid downloading or printing large datasets. Sample, summarize, or aggregate data unless the user explicitly asks for an export.
 - Treat notebook execution as potentially stateful and costly. The hosted MCP `create_run` tool starts a notebook run, not a single-cell edit or targeted cell run.
+- Treat project, notebook, and block creation as persistent write actions. Resolve targets carefully and report created IDs.
 - Run input overrides apply to one run only. Do not claim they changed notebook defaults.
 - If a tool returns `isError`, surface the user-facing error message concisely. For `create_run` failures such as workspace or parallel run limits, only call `get_run` if the `create_run` response includes a valid run ID; otherwise do not poll `get_run`.
-- The hosted MCP toolset is mostly read/search/docs/usage mapping plus notebook execution. Do not claim to edit notebooks, projects, integrations, permissions, schedules, or publishing through the Deepnote MCP server unless such tools are exposed in the current session.
+- The hosted MCP toolset can create projects, notebooks, and blocks. Do not claim to change integrations, permissions, schedules, publishing, environments, or other resource settings unless such tools are exposed in the current session.
 
 ## Response Style
 

plugins/deepnote/skills/deepnote-notebook-editing/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: deepnote-notebook-editing
+description: Use when creating Deepnote projects or notebooks, adding blocks or cells, scaffolding notebook content, inserting SQL/code/markdown/input blocks, or otherwise editing notebook structure through the Deepnote MCP server.
+---
+
+# Deepnote Notebook Editing
+
+## When To Use
+
+Use this skill when the user asks Codex to create a Deepnote project, create a notebook, add a block or cell, scaffold starter notebook content, insert code, SQL, markdown, or input blocks, or make a structural notebook edit supported by the current MCP write tools.
+
+The current editing surface covered by this skill is:
+
+- `create_project`: create a new project. Requires `name`; accepts optional `folderId`.
+- `create_notebook`: create an empty notebook in a project. Requires `projectId`; accepts optional `name`.
+- `create_block`: create a block in a notebook. Requires `notebookId` and `type`; accepts optional `content`, `metadata`, `position`, `includeNotebookBlockIds`, and SQL-only `integrationId`.
+
+## Editing Workflow
+
+1. Resolve ambiguous names and IDs before writing. Use `get_me` for workspace identity, `search` or `list_projects` for projects/notebooks, `get_notebook` for current block order, and `list_integrations` for SQL connections.
+2. Treat `create_project`, `create_notebook`, and `create_block` as non-idempotent. Repeating the same call creates another resource.
+3. Use `create_project` only when the user wants a new project. A created project includes a default empty notebook.
+4. Use `create_notebook` only when adding an empty notebook to an existing project. It does not accept starter blocks; create blocks afterward with `create_block`.
+5. Use `create_block` for each new block. Omit `position` to append, or pass a zero-based `position` when placement matters.
+6. Pass `includeNotebookBlockIds: true` when the final block order matters, especially for ordered inserts or multi-block scaffolds.
+7. Verify meaningful edits with `get_notebook` after block creation when order, integration attachment, or multi-block content matters.
+8. Do not run the notebook after editing unless the user explicitly asks for execution.
+
+## Block Creation Guidance
+
+Choose the block `type` that matches Deepnote's block vocabulary. Common types include `code`, `sql`, `markdown`, input blocks such as `input-text`, `input-select`, `input-checkbox`, and text-cell variants such as `text-cell-h1`, `text-cell-p`, and `text-cell-callout`.
+
+For SQL blocks:
+
+- Resolve the integration first with `list_integrations` when the user gives a connection name.
+- Pass the connection as top-level `integrationId`.
+- Do not put `sql_integration_id` inside `metadata`.
+- Do not pass `integrationId` for non-SQL blocks.
+
+For input blocks, put block-type configuration in `metadata` and keep `content` for the visible/default textual content when applicable. Preserve existing notebook naming and variable conventions when adding inputs near related blocks.
+
+## Response Style
+
+After a successful edit, report the created project, notebook, or block name/ID, plus placement or final block order when relevant. Include Deepnote links when they can be safely constructed with `deepnote-links`.
+
+If a write tool returns an error, surface the user-facing message concisely and name the likely fix: missing permission, missing target resource, invalid block type, invalid position, duplicate notebook name, suspended project, or incompatible SQL integration.