# Jupyter Collaboration MCP Server
A JupyterLab extension that provides MCP (Model Context Protocol) server endpoints to expose Jupyter Collaboration's real-time collaboration (RTC) functionalities to AI agents.
## Overview
This project enables AI agents to interact with collaborative Jupyter notebooks and documents in real-time. It leverages the existing Jupyter Collaboration system's robust RTC capabilities using YDoc (CRDT) technology and exposes them through MCP endpoints.
## Features
- **Notebook Collaboration**: Real-time collaboration on Jupyter notebooks with AI agents
- **Document Collaboration**: Shared document editing with version control and forking
- **User Awareness**: Track user presence, cursor positions, and activity
- **Real-time Communication**: Streamable HTTP for bidirectional communication
- **Authentication & Authorization**: Integrated with Jupyter's security infrastructure
- **Resumable Streams**: Clients can reconnect and resume from where they left off
## Installation
### Prerequisites
- Python 3.10 or higher
- Jupyter Server 2.0.0 or higher
- Jupyter Collaboration 2.0.0 or higher
### From Conda (when published)
```bash
conda install -c conda-forge jupyter-collaboration-mcp
```
### From PyPI (when published)
```bash
pip install jupyter-collaboration-mcp
```
### From Source
```bash
git clone https://github.com/jupyter/jupyter-collaboration-mcp.git
cd jupyter-collaboration-mcp
pip install -e .
```
## Configuration
The MCP server is automatically loaded as a Jupyter server extension when installed. No manual configuration is required.
## Authentication
The MCP server uses simple token-based authentication. When running as a Jupyter server extension, it automatically uses the token provided via the `--IdentityProvider.token` command line option.
### Using Jupyter Lab Tokens
When starting Jupyter Lab, you can provide a token for authentication:
```bash
jupyter lab --IdentityProvider.token=your-secret-token
```
This token can then be used to authenticate with the MCP server.
### MCP Client Configuration
For MCP clients, you'll need to configure the server URL and authentication token. The exact configuration depends on your MCP client, but it typically looks like this:
#### Example MCP Client Configuration
```json
{
"mcpServers": {
"jupyter-collaboration": {
"url": "http://localhost:8888/mcp",
"type": "streamable-http",
"headers": {
"Authorization": "Identity.token your-secret-token"
},
"disabled": false
}
}
}
```
#### Configuration Parameters
- `url`: The URL of the MCP server endpoint
- `type`: The transport type, must be "streamable-http" for this server
- `headers`: HTTP headers to include in requests, typically including the Authorization header with the token
- `disabled`: Set to `true` to disable this server configuration
- `alwaysAllow`: Optional list of tools that should always be allowed (if supported by your client)
### Finding Your Server URL
- When running as a Jupyter server extension, the MCP endpoint is typically at `http://localhost:8888/mcp` (or whatever port your Jupyter server is running on)
## Provided MCP Tools
The server exposes the following MCP tools:
### Notebook Operations
- `list_notebooks`: List available notebooks
- `get_notebook`: Get notebook content
- `create_notebook_session`: Create or retrieve a collaboration session
- `update_notebook_cell`: Update a notebook cell
- `insert_notebook_cell`: Insert a new cell
- `delete_notebook_cell`: Delete a cell
- `execute_notebook_cell`: Execute a cell
### Document Operations
- `list_documents`: List available documents
- `get_document`: Get document content
- `create_document_session`: Create or retrieve a collaboration session
- `update_document`: Update document content
- `insert_text`: Insert text at a position
- `delete_text`: Delete text from a position
- `get_document_history`: Get document version history
- `restore_document_version`: Restore a document to a previous version
- `fork_document`: Create a fork of a document
- `merge_document_fork`: Merge a fork back into the original
### Awareness Operations
- `get_online_users`: Get list of online users
- `get_user_presence`: Get user presence information
- `set_user_presence`: Set current user's presence status
- `get_user_cursors`: Get cursor positions in a document
- `update_cursor_position`: Update current user's cursor position
- `get_user_activity`: Get recent user activities
- `broadcast_user_activity`: Broadcast user activity
- `get_active_sessions`: Get active collaboration sessions
- `join_session`: Join a collaboration session
- `leave_session`: Leave a collaboration session
## Development Setup
### Prerequisites
- Python 3.10 or higher
- Git
- Node.js (for JupyterLab extension development, if needed)
### Clone the Repository
```bash
git clone https://github.com/jupyter/jupyter-collaboration-mcp.git
cd jupyter-collaboration-mcp
```
### Create a Virtual Environment
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
### Install Dependencies
```bash
pip install -e ".[dev]"
```
This will install the package in development mode along with all development dependencies.
### Code Formatting
The project uses Black for code formatting and isort for import sorting. You can format code manually:
```bash
black jupyter_collaboration_mcp tests
isort jupyter_collaboration_mcp tests
```
#### Auto-formatting on Commit
To set up automatic code formatting on each commit, run the setup script:
```bash
./scripts/setup-git-hooks.sh
```
This will set up a Git hook that automatically formats your Python files with black and isort before each commit.
### Type Checking
The project uses mypy for type checking:
```bash
mypy jupyter_collaboration_mcp
```
## Troubleshooting
### Common Issues
1. **Authentication Errors**: Make sure you're using the correct token in your Authorization header
2. **Connection Refused**: Verify that your Jupyter server is running and the MCP extension is loaded
3. **CORS Errors**: If running in a browser environment, make sure the server's CORS configuration allows your client's origin
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [Jupyter Collaboration](https://github.com/jupyter/jupyter-collaboration) for the underlying RTC functionality
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the AI agent communication standard
- [Jupyter Server](https://github.com/jupyter/jupyter_server) for the server infrastructure
