docs: document the write_file MCP tool

[tkislan]

The hosted Deepnote MCP server now has a write_file tool that writes one small, mostly text-based file, such as a script, config, or CSV, into a project. This documents it in the skills so agents use it and the nightly drift check stays green. It also removes the claims, in four skills and the README, that MCP cannot write project files.

Closes #25

• New tool: write_file (deepnote-internal#20967) takes projectId, a project-relative path, content, optional encoding (utf8 by default, or base64), and optional overwrite (default false). It creates missing parent directories and requires edit access.
  • The content travels inline in the tool call, so the tool is for small text-based files. It is not a way to upload large files or big binary blobs, which MCP still cannot do; base64 is for small binary files only.
  • Without overwrite, an existing path is left alone and the file is written to a generated unique path. The response's file.path is the path that was actually written.
  • With overwrite: true it replaces the file. Targeting a directory returns a conflict.
• Skills:
  • deepnote-mcp: catalogue entry for write_file. File writes are added to the persistent-write rule. The capability boundary now allows writing small text-based files, still rules out uploading large files or big binary blobs, and says MCP cannot delete files (there is no delete tool).
  • deepnote-workspace: a short "Project File Writes" workflow (small text-based files only, check the inventory first, overwrite only on request, report the returned path), and the description now covers file writes
  • deepnote-static-sites: replaced "do not look for generic file-write tools" with why publish_static_site beats per-file write_file (pruning, sharing, one call)
  • deepnote-streamlit-apps: an entrypoint can now be written with write_file, not only copied with copy_file
• README, manifests: writing small text files added to the capability list, plus a troubleshooting line for the unique-path behaviour. The Codex long description now mentions writing small text files. The plugin is bumped to 0.8.0.

Every tool in the deepnote-internal develop manifest (apps/webapp/server/mcp/mcp-tools-manifest.json) is now mentioned in a skill. claude plugin validate --strict passes for both manifests. I did not run the drift script against the live server, because no DEEPNOTE_TOKEN was available locally.

The public docs (docs/deepnote-mcp.md in deepnote/deepnote) list no file tools at all, not even copy_file or publish_static_site. Adding them needs a separate pull request there.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WzyquQoEzcqS2WiDUVJkfU

Summary by CodeRabbit

• New Features
  • Added support for writing small text files to Deepnote projects, alongside existing file-copying capabilities.
  • Existing files are preserved by default; when a requested path is already taken, the file is saved to a generated path.
• Documentation
  • Updated guidance for file writing, access requirements, and static-site publishing.
• Chores
  • Updated the Deepnote plugin version to 0.8.0.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Essentials
• Run ID: 4622eb27-519c-4780-b253-44fbc76ef710

📥 Commits

Reviewing files that changed from the base of the PR and between cd0619c and a18352b.

📒 Files selected for processing (4)

• README.md
• plugins/deepnote/.codex-plugin/plugin.json
• plugins/deepnote/skills/deepnote-mcp/SKILL.md
• plugins/deepnote/skills/deepnote-workspace/SKILL.md

🚧 Files skipped from review as they are similar to previous changes (2)

• README.md
• plugins/deepnote/.codex-plugin/plugin.json

Included review availability: This review used your included allowance. 3 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

---

📝 Walkthrough

Walkthrough

The plugin documentation now describes write_file, including its arguments, constraints, overwrite behavior, and generated-path behavior. Workspace, static-site, and Streamlit guidance addresses how to use the tool. The README and Codex plugin description include project-file writing. Both plugin manifests now report version 0.8.0.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Suggested reviewers: jamesbhobbs

Merge Risk: ⚪ Minimal · up to a1835

The updated guides consistently describe project-file writing and distinguish static-site publishing; no actionable documentation conflict is evident.

🚥 Pre-merge checks | ✅ 5 | ❓ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Updates Docs	❓ Inconclusive	The PR updates the agent-plugin documentation: README.md and the Deepnote skills now describe write_file. However, the review range contains no changes to the primary deepnote/deepnote OSS docum…	Please verify and update the deepnote/deepnote documentation and the deepnote-internal landing-page roadmap for write_file, or link the documentation changes before merging.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Issue #25 requires a write_file description in plugins/deepnote. The deepnote-mcp skill documents its inputs, encoding, overwrite behavior, generated-path behavior, directory creation, and edit-…
Out of Scope Changes check	✅ Passed	The README, manifests, and skill changes support the #25 documentation objective. The workspace, static-site, and Streamlit updates clarify valid use of write_file. No unrelated change is identified…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: documenting the write_file MCP tool and its behavior in the Deepnote plugin documentation.

Full details: Updates Docs

Explanation

The PR updates the agent-plugin documentation: README.md and the Deepnote skills now describe write_file. However, the review range contains no changes to the primary deepnote/deepnote OSS documentation or the deepnote-internal landing-page roadmap. AGENTS.md identifies those repositories as the product documentation sources, but linked-repository inspection is unavailable.

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[dinohamzic]

Generally speaking, we should emphasize that write_file should be avoided when uploading big binary blobs, and is instead intended mainly for smaller text based files (eg. CVSs). Uploading bigger blobs via MCP is still not supported, nor there is an easy way to do that.

[tkislan]

@dinohamzic good catch 👍