Skip to content

Conversation

Zsailer
Copy link
Contributor

@Zsailer Zsailer commented Aug 19, 2025

Summary

This PR refactors the MCP server extension to use a simplified, trait-based architecture that removes complex abstractions while providing more flexibility and better Jupyter integration.

Key Changes

  • Simplified MCPServer: Direct function registration without tool provider/registry abstractions
  • Trait-based Configuration: Full traitlets integration for server and extension configuration
  • Dynamic Tool Loading: String-based tool specifications in format module:function
  • Modern Extension API: Updated to use current Jupyter Server extension lifecycle
  • Comprehensive Documentation: Updated README with usage examples and troubleshooting guide

Architecture Improvements

  • Removed complex tool provider and registry classes
  • MCPServer now inherits from LoggingConfigurable for proper Jupyter integration
  • Extension supports configurable tool lists via mcp_tools trait
  • Automatic tool registration from popular packages (jupyter-ai-tools, jupyterlab-commands-toolkit)
  • Simplified async lifecycle management with proper cleanup

Configuration Example

c = get_config()

c.MCPExtensionApp.mcp_name = "Jupyter MCP Server"  
c.MCPExtensionApp.mcp_port = 8080
c.MCPExtensionApp.mcp_tools = [
    "os:getcwd",
    "jupyter_ai_tools.toolkits.notebook:read_notebook",
    "jupyterlab_commands_toolkit.tools:clear_all_outputs_in_notebook",
]

Testing

  • All tests pass (35/35) with comprehensive coverage
  • Updated tests to match simplified API
  • Removed tests for deleted abstractions
  • Added integration tests for real-world usage

Documentation

  • Complete README rewrite with usage examples
  • Troubleshooting guide for common issues
  • API documentation for all components
  • Configuration examples from minimal to advanced

This refactor maintains full backward compatibility for the MCP protocol while significantly simplifying the internal architecture and improving maintainability.

Test Plan

  • All existing tests pass
  • New integration tests added
  • Manual testing with real Jupyter environments
  • Documentation verified with examples
  • Configuration validation tested

…guration

- Simplified MCPServer class with direct function registration
- Removed complex tool provider and registry abstractions
- Added trait-based configuration for extension and server
- Updated extension to use modern Jupyter Server lifecycle
- Removed unnecessary logging configuration methods
- Fixed all test compatibility issues
- Updated comprehensive README with usage examples
- Added tool loading via string specifications (module:function format)
- Supports dynamic loading from jupyter-ai-tools and jupyterlab-commands-toolkit

All tests pass (35/35) with robust error handling and complete API coverage.
@Zsailer Zsailer changed the title Refactor to simplified architecture with trait-based configuration Initial implementation of an MCP server as an extension Aug 19, 2025
@Zsailer Zsailer merged commit 35ec316 into jupyter-ai-contrib:main Aug 21, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant