AI导哈

自然语言转Jupyter笔记本自动化工具

AgentTool是一个将自然语言指令转换为安全、确定的Jupyter笔记本操作的工具，通过本地LLM实现，适用于需要自动化笔记本操作的数据分析和开发场景。

  • by Kiwi-520
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Kiwi-520/mcp-jupyter-server

使用说明

🧠 Agent工具--自然语言→ Jupyter笔记本自动化

一个以生产为导向、受MCP启发的系统，使用本地LLM将自然语言指令转换为安全、确定的Jupyter笔记本操作。

🚀 为什么这个项目存在

Jupyter笔记本功能强大，但程序控制脆弱且不安全：

  • 手动编辑容易出错
  • LLMs产生幻觉的API
  • 笔记本损坏很常见
  • 自动化缺乏护栏

AgentTool通过引入一个严格的、仅支持JSON的代理层来解决这个问题，该代理层将自然语言转换为经过验证的、可执行的笔记本操作。

该项目展示了：

  • 代理设计
  • LLM安全约束
  • 确定执行
  • 现实世界系统集成

🧩 这个项目做什么

✅ 接受自然语言命令 ✅ 将它们转换为严格的JSON行动计划 ✅ 验证针对允许的MCP端点的操作 ✅ 以原子和安全的方式执行笔记本操作 ✅ 完全在本地工作（不依赖于云）

例子：

"Create a notebook and add a markdown title called Analysis"

➡️ 自动创建：

# Analysis

内部a .ipynb 文件——安全。

🏗️ 高级体系结构

┌───────────────┐
│   User / CLI  │
└───────┬───────┘
        │ Natural Language
        ▼
┌────────────────────────┐
│  MCP Agent Server      │
│  (FastAPI)             │
│  - LLM prompt control  │
│  - JSON enforcement    │
│  - Action validation   │
└────────┬───────────────┘
         │ JSON Action Plan
         ▼
┌────────────────────────┐
│  MCP Jupyter Server    │
│  (Flask)               │
│  - Notebook CRUD       │
│  - Atomic writes       │
│  - File safety         │
└────────────────────────┘

📁 项目结构

AgentTool/
├── mcp-agent-server/        # LLM-powered agent
│   ├── agent_server.py
│   ├── requirements.txt
│   └── ui.html
│
└── mcp-jupyter-server/      # Deterministic execution layer
    ├── server.py
    ├── requirements.txt
    ├── openai.yaml
    ├── README.md

🧠 关键工程决策（招聘信号）

1.️⃣ 严格的JSON强制

  • 代理拒绝markdown、散文或无效的JSON
  • 防止产生幻觉的原料药
  • 保证机器可读的计划

2.️⃣ 行动白名单

仅允许的端点：

"/create_cell"

没有发明端点。这并不奇怪。

3.️⃣ 原子笔记本写入

通过以下方式避免笔记本损坏：

  • 写入临时文件
  • 原子性地替换原始

这反映了生产级文件系统的安全性。

4.️⃣ 当地第一法学硕士（Ollama）

  • 将Ollama与本地托管模型结合使用（例如。 phi3:mini, qwen2.5:7b)
  • 无外部API
  • 可复制且隐私安全

5.️⃣ 框架分离

层 技术 原因
代理 FastAPI 类型安全，异步就绪
Executor Flask 简单、稳定的文件操作

🔌 MCP代理服务器（FastAPI）

职责

  • 接受用户输入
  • 致电当地LLM
  • 强制只输出JSON
  • 验证MCP操作
  • 对连接的MCP服务器执行

跑

cd mcp-agent-server
pip install -r requirements.txt
uvicorn agent_server:app --reload

📓 MCP Jupyter服务器（Flask）

职责

  • 创建/编辑/删除/移动笔记本单元格
  • 自动创建笔记本
  • 防止文件损坏
  • 为代理提供REST API

跑

cd mcp-jupyter-server
pip install -r requirements.txt
python server.py

运行时间： http://localhost:5001

🧪 端到端流程示例

curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{ "message": "Create a notebook and add a markdown title called Analysis" }'

结果：

  • 自动创建笔记本
  • 已添加Markdown标题
  • 无幻觉
  • 没有腐败

🛡️ 故障处理

故障 处理
JSON无效 已拒绝
未知端点 已删除
LLM超时 安全错误
笔记本丢失 自动创建
文件已损坏 已重新初始化

📌 这个项目展示了什么

✔ 代理设计原则 ✔ 安全的LLM编排 ✔ MCP式工具 ✔ 真正的文件系统保证 ✔ 生产思维，而非演示

📈 将来的扩展

  • 多步骤计划
  • 通过代理编辑/删除/移动
  • 笔记本差异预览
  • 实时代理执行UI
  • 流式传输LLM响应

👩‍💻 作者

迪沙 Holmukhe AI系统|代理AI |机器学习工程|开源贡献者

📖 博客： 如何构建本地MCP服务器来控制Jupyter笔记本

相关 MCP