jupyter-mcp-server: Instructions file for GitHub Copilot

Jupyter MCP Server

Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

Jupyter MCP Server is a Python-based Model Context Protocol (MCP) server implementation that enables real-time interaction with Jupyter Notebooks. The project uses a modern Python build system with hatch, and includes comprehensive testing, linting, and documentation.

Working Effectively

Environment Setup

• Python Requirements: Python 3.10 or higher (tested with 3.9-3.13)
• Network Considerations: PyPI installs may fail due to SSL certificate issues or timeout limitations. This is a known environment constraint.

Build and Install (CRITICAL: Network Limitations)

# Standard installation (may fail with network issues)
pip install ".[test,lint,typing]"

# Alternative if pip install fails:
# 1. Install dependencies individually with longer timeouts
pip install --timeout=300 pytest
pip install --timeout=300 ruff
pip install --timeout=300 mypy

# 2. Or use Docker approach (preferred for consistency)
docker build -t jupyter-mcp-server .

NETWORK TIMEOUT WARNING: pip install commands may fail with SSL certificate errors or read timeouts when connecting to PyPI. If installs fail:

• Try increasing timeout: pip install --timeout=300
• Use Docker build which handles dependencies internally
• Document the network limitation in any testing notes

Core Development Commands

# Development installation (when network allows)
make dev
# Equivalent to: pip install ".[test,lint,typing]"

# Basic installation
make install
# Equivalent to: pip install .

# Build the package
make build
# Equivalent to: pip install build && python -m build .

Testing (CRITICAL: Use Long Timeouts)

# Run tests using hatch (when available)
make test
# Equivalent to: hatch test

# Run tests directly with pytest (when network allows install)
pytest .

# NEVER CANCEL: Test suite timing expectations
# - Full test suite: Allow 15-20 minutes minimum
# - Network-dependent tests may take longer
# - Set timeout to 30+ minutes for safety