🛣️ My Jupyter MCP Server Tools Improvement Roadmap

[ChengJiale150]

📋 Overview

Currently, the Jupyter MCP Server tool implementation is basically complete, covering core functionalities of Server Management, Notebook Management, and Cell Operations. However, to truly enhance user experience and enable LLMs to better utilize these tools, we need to make in-depth improvements in the following three main areas:

1. Tool Description and Input Parameter Optimization - Making it easier for LLMs to understand tool purposes and usage methods
2. Tool Output and Error Message Enhancement - Providing more user-friendly and structured output information
3. Potential Bug Fixes - Identifying and fixing existing boundary issues and exceptions

---

🎯 Current Status Analysis

✅ Completed Work

• ✨ Complete core tool functionality (16 tools)
• 🔄 Support for multi-notebook management
• 📊 Support for multimodal output (text, images, etc.)

⚠️ Areas Needing Improvement

• 📝 Insufficient Tool Descriptions: Current tool descriptions are relatively brief, making it difficult for LLMs to understand applicable scenarios and parameter meanings
• 🔧 Incomplete Parameter Documentation: Input parameter constraints, optional values, boundary conditions, and other information are not clearly documented
• 📤 Inconsistent Output Formats: Return values from different tools may not be LLM-friendly enough
• 🚨 Unfriendly Error Handling: Error messages are not specific enough to help LLMs quickly locate problems
• 🐛 Insufficient Boundary Case Handling: Some exceptional situations (such as network errors, timeouts, resource shortages, etc.) lack comprehensive handling mechanisms

---

🚀 Improvement Roadmap

📌 Phase 1: Server Management Tools Enhancement

Target Tools:

• list_files - File system listing
• list_kernels - Kernel listing
• assign_kernel_to_notebook - Kernel assignment

Improvement Content

• Supplement detailed descriptions, usage scenarios, and precautions for each tool
• Add pagination support to list_files tool to avoid returning too many tokens at once
• Add result filtering options to list_files tool
• remove assign_kernel_to_notebook

---

📌 Phase 2: Notebook Management Tools Enhancement

Target Tools:

• use_notebook - Switch/Create Notebook
• list_notebooks - Notebook listing
• restart_notebook - Restart Kernel
• unuse_notebook - Disconnect

Improvement Content

• Supplement detailed descriptions, usage scenarios, and precautions for each tool
• Fix the bug of kernel and notebook don't start at same path
• rich the output return by use_notebook

---

📌 Phase 3: Cell Operations and Execution Tools Enhancement

Target Tools:

• list_cells - Cell listing
• read_cell / read_cells - Read Cell
• insert_cell - Insert Cell
• delete_cell - Delete Cell
• overwrite_cell_source - Overwrite Cell
• execute_cell - Execute Cell
• insert_execute_code_cell - Insert and Execute Cell
• execute_ipython - Execute IPython code

Improvement Content

• rename execute_ipython to execute_code
• better test for CI
• rename read_cells to read_notebook and add response_format option.
• ...

---

🎓 Background

This improvement roadmap aims to achieve the following objectives:

From "Functionally Complete" to "Usability Perfect" Transformation

Although the current tool set already supports all necessary Notebook operations, to truly become an LLM-friendly tool set, we need to:

• 🎯 Improve Clarity - Enable LLMs to accurately understand tool purposes and usage methods
• 🎯 Improve Consistency - Unify tool behavior and output formats
• 🎯 Improve Reliability - Enhance error handling and boundary cases
• 🎯 Improve Friendliness - Provide clear error messages and recovery suggestions

---

Last Updated: October 21, 2025
Discussion: Welcome to discuss and provide feedback in this Issue

[ChengJiale150]

@echarles, I'm curious about the reasoning behind your design of the assign_kernel_to_notebook tool, and I apologize that I can’t currently think of its potential use cases. Perhaps it could be used for sharing a kernel across multiple Notebooks, yet this functionality seems like it should also be covered by use_notebook. Could you share the intent behind your design to help me refine the tool description?

[eleonorecharles]

@ChengJiale150 I agree. With the kernel_id parameter in the use_notebook tool, keeping assign_kernel_to_notebook tool is not needed

[echarles]

👍

[TomLucidor]

@ChengJiale150 could you break down the whole list #128 (comment)

[ChengJiale150]

Close as Complete.