md2ipynb (Oscar Pellicer)

md2pynb

md2ipynb 将Jupyter笔记本转换为Markdown，然后再转换回来，Markdown格式旨在使编码代理更容易安全地编辑。

该项目提供：

• 可安装的CLI命令： ipynb2md 和 md2ipynb
• 用于全局指令和Python路径管理的共享配置文件
• 一个MCP服务器，教模型在笔记本电脑繁重的工作中更喜欢Markdown往返
• Cursor全局安装路径，因此工作流可跨存储库使用
• 核心转换和配置行为的Pytest覆盖率

为什么存在

许多代理在编辑Markdown方面比原始要好得多 .ipynb JSON。此工具支持代理执行以下操作的工作流：

1. 使用将笔记本转换为Markdown ipynb2md
2. 编辑Markdown文件
3. 将其转换回 md2ipynb

该工作流程对于新笔记本电脑和涉及多个单元格的编辑特别有用。

安装

从签出安装：

pip install .

使用开发依赖项进行安装：

pip install -e .[dev]

这将在环境中公开这些命令：

• ipynb2md
• md2ipynb
• notebook-converter
• md2ipynb-mcp

打印代理的打包终端快速入门：

md2ipynb --agents

遗留入口点仍然从repo根目录工作：

python notebook_converter.py ipynb2md

CLI使用情况

将笔记本转换为Markdown

将当前目录中的每个笔记本转换为单独的Markdown文件：

ipynb2md

转换特定笔记本：

ipynb2md lesson.ipynb

将多个文件和目录转换为单独的Markdown文件并创建索引：

ipynb2md notebooks lecture.ipynb --output exported_md --index notebook_index.md

将多个输入合并到一个Markdown文件中：

ipynb2md notebooks lecture.ipynb --join --output combined_notebooks.md

将Markdown转换为笔记本

将当前目录中的每个Markdown文件转换为单独的笔记本：

md2ipynb

转换特定的Markdown文件：

md2ipynb lesson.md appendix.md

将目录转换为单独的笔记本并写入索引：

md2ipynb markdown_sources --output generated_notebooks --index markdown_index.md

将多个Markdown源合并到一个笔记本中：

md2ipynb markdown_sources appendix.md --join --output combined_notebook.ipynb

别名

子命令还支持这些别名：

• extract 和 export 为了 ipynb2md
• create 和 import 为了 md2ipynb

CLI还支持仅用于终端指导的顶级标志：

• --agents 打印包装好的 agents_quickstart.md 引导和出口

Markdown格式期望

当前特定于回购的创作规则存在于 instructions.md.

重要行为：

• 仅 ``` `python ... ` ``` 块变成笔记本代码单元。
• 普通围栏块 ``` ` ... ` ``` 保留Markdown内容。
• 导出笔记本时，任何已包含的Markdown单元格 ``` `python ``` 围栏被改写为普通围栏，并发出警告。这避免了在返回过程中将Markdown示例意外转换为真实的代码单元格。

全局配置

该工具从以下位置读取全局配置：

• 窗户： %APPDATA%\md2ipynb\config.toml
• 其他平台： ~/.config/md2ipynb/config.toml

打印解析的配置路径：

md2ipynb config path

创建配置文件：

md2ipynb config init \
  --python-executable "c:\Users\Oscar\miniconda3\envs\nlp3\python.exe" \
  --instructions-file "c:\Users\Oscar\md2ipynb\instructions.md"

显示有效配置：

md2ipynb config show

支持的配置字段：

• python_executable：用于Cursor MCP注册的Python
• instructions_file：包含笔记本编写说明的外部文件
• instructions_text：内联指令而不是单独的文件
• markdown_edit_cell_threshold：在选择Markdown往返之前直接编辑的最大单元格数
• [cursor].root：覆盖游标全局目录
• [cursor].mcp_config_path：覆盖光标 mcp.json 路径
• [cursor].rules_dir：覆盖游标全局规则目录

MCP服务器

使用stdio传输启动MCP服务器：

md2ipynb-mcp

或者：

python -m md2ipynb.mcp_server

服务器公开：

• ipynb2md
• md2ipynb
• md2ipynb://instructions
• md2ipynb://config
• 提示提醒模型更喜欢Markdown工作流来处理笔记本繁重的任务

MCP服务器指令明确告诉模型：

1. 首先通过Markdown创建新笔记本
2. 将现有笔记本转换为Markdown，以进行超过配置阈值的编辑
3. 仅对微小更改保留直接单元格编辑

游标全局集成

安装全局游标MCP条目和全局游标规则：

md2ipynb config install-cursor

文中写道：

• 指向的全局游标MCP条目 python -m md2ipynb.mcp_server
• 一个全局Cursor规则，告诉Cursor代理更喜欢笔记本电脑的Markdown往返工作流

默认情况下，安装目标为：

• ~/.cursor/mcp.json
• ~/.cursor/rules/md2ipynb-workflow.mdc

如果您已配置 python_executable，该解释器用于生成的游标MCP条目。这使得无论Cursor当前打开哪个存储库，该工具都可用。

安装后，重新启动Cursor，使其重新加载MCP服务器和规则。

工作流程示例

这 example/ 目录包含一个示例笔记本及其Markdown源代码：

• example/text_processing_basics.ipynb
• example/text_processing_basics.md

当您想测试需要大量重写而不是微小单元格编辑的笔记本的工作流程时，请使用此选项。

手动工作流程

将笔记本转换为Markdown：

ipynb2md example/text_processing_basics.ipynb --output example/workdir --force

这将创建：

• example/workdir/text_processing_basics.md

编辑Markdown后，将其转换回笔记本：

md2ipynb example/workdir/text_processing_basics.md --output example/text_processing_basics_reworked.ipynb --force

给Cursor代理的说明

当笔记本需要大量编辑时，使用这样的提示：

I want you to heavily rewrite example/text_processing_basics.ipynb using the md2ipynb workflow instead of editing notebook cells directly.

Requirements:
- First convert the notebook to Markdown.
- Edit the Markdown file, not the .ipynb JSON.
- Treat this as a substantial rewrite: reorganize sections, improve explanations, add more examples, and update the code cells accordingly.
- Follow the notebook authoring instructions from instructions.md or the configured md2ipynb global instructions.
- Keep illustrative code examples inside markdown cells as plain fenced blocks ``` ... ```, not ```python ... ```.
- Use ```python ... ``` only for content that should become actual notebook code cells.
- When finished, convert the Markdown back to a notebook.
- Summarize what changed and mention any warnings emitted during conversion.

然后，您可以向代理附加一个笔记本，并询问以下内容：

Edit the given notebook to add few further examples

如果代理可以访问MCP服务器，它应该更喜欢 ipynb2md 和 md2ipynb MCP工具。否则，它可以直接运行CLI命令。

这个例子是为了什么

示例笔记本故意简单。要求代理人：

• 把一节简短的课变成一个更完整的教程
• 在代码单元之间添加更多叙述
• 将大单元拆分为更小的教学步骤
• 扩展学生应该检查的示例和输出

发展

运行测试：

pytest

新用户须知

• 该工具在覆盖文件方面故意保守。没有 --force，当目标路径已存在时，它会创建唯一的输出名称。
• 单独输出是默认模式，因此 --output 除非您通过，否则将被视为输出目录 --join.
• 在 --join 模式， --output 被视为单个文件路径。