Skip to content

feat: support logging to stderr in Jupyter Notebook environments (#156)#1706

Closed
dgenio wants to merge 9 commits intomodelcontextprotocol:mainfrom
dgenio:feature/156-jupyter-stderr-support
Closed

feat: support logging to stderr in Jupyter Notebook environments (#156)#1706
dgenio wants to merge 9 commits intomodelcontextprotocol:mainfrom
dgenio:feature/156-jupyter-stderr-support

Conversation

@dgenio
Copy link

@dgenio dgenio commented Nov 30, 2025

Summary

Fixes #156 - Adds support for displaying stderr output in Jupyter Notebook environments.

Changes

  • Added Jupyter/IPython detection using IPython.get_ipython()
  • Implemented async stderr reader that reads stderr asynchronously (similar to stdout)
  • Added IPython display integration for colored stderr output in Jupyter notebooks
  • Updated process creation to pipe stderr instead of redirecting (enables async reading)
  • Updated Windows process creation and fallback to support piped stderr
  • Updated FallbackProcess to wrap stderr in async-compatible streams

Design Decisions

  • Backward compatibility: errlog parameter is kept but behavior adapts based on environment
  • Error handling: Non-critical errors are logged but don't stop execution
  • Performance: Matches stdout_reader behavior (line-by-line buffering)
  • Platform support: Works on both Unix and Windows (including fallback path)

Testing

  • Added comprehensive tests for stderr capture, Jupyter detection, and display integration
  • All existing tests pass
  • Linting and type checking pass

Behavior

  • In Jupyter: stderr is displayed using IPython's display system with red HTML formatting
  • Outside Jupyter: stderr is printed to the provided errlog stream (defaults to sys.stderr)
  • Fallback: If IPython display fails, falls back to regular print

This enables proper debugging of MCP servers in Jupyter notebook environments, addressing the issue where server crashes or command errors were invisible.

dgenio and others added 9 commits November 30, 2025 07:11
@dgenio
feat: add Jupyter notebook detection and stderr helpers
9fc1d36 
- Add _is_jupyter_notebook() to detect Jupyter/IPython environments
- Add _print_stderr() to handle stderr output with IPython display support
@dgenio
test: fix IPython import mocking in Jupyter stderr tests
54b3817 
- Mock builtins.__import__ instead of patching IPython.display directly

- Handle 'from IPython.display import HTML, display' import pattern

- Tests now work without IPython installed in test environment
@dgenio
Merge branch 'main' into feature/156-jupyter-stderr-support
c7281aa
@dgenio
test: add coverage for missing lines in stderr handling
5bdaf05 
- Add test for _is_jupyter_notebook with valid IPython instances

- Add test for stderr_reader exception handling

- Improve test coverage to reach 100%
@dgenio
test: fix recursion error and invalid JSON in tests
06e21f2 
- Store original __import__ before patching to avoid recursion

- Fix test_stderr_reader_no_stderr to not print to stdout

- Apply ruff formatting fixes
@dgenio
test: fix recursion in _is_jupyter_notebook test
c83b5ed
@dgenio
style: fix import sorting in test_stdio.py
850fba2
@dgenio
refactor: extract helper functions to reduce stdio_client complexity
c17e2cd
@dgenio
test: add coverage for stderr exception handlers and empty lines
7a6d762
@dgenio dgenio closed this Nov 30, 2025
@dgenio dgenio deleted the feature/156-jupyter-stderr-support branch November 30, 2025 08:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

support logging to stderr in Jupyter Notebook Environments.

1 participant

@dgenio