CONTRIBUTING.md•3.77 kB
<!--
~ Copyright (c) 2023-2024 Datalayer, Inc.
~
~ BSD 3-Clause License
-->
# Contributing to Jupyter MCP Server
First off, thank you for considering contributing to Jupyter MCP Server! It's people like you that make this project great. Your contributions help us improve the project and make it more useful for everyone!
## Code of Conduct
This project and everyone participating in it is governed by the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior.
## How Can I Contribute?
We welcome contributions of all kinds, including:
- 🐛 Bug fixes
- 📝 Improvements to existing features or documentation
- ✨ New feature development
### Reporting Bugs or Suggesting Enhancements
Before creating a new issue, please **ensure one does not already exist** by searching on GitHub under [Issues](https://github.com/datalayer/jupyter-mcp-server/issues).
- If you're reporting a bug, please include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
- If you're suggesting an enhancement, clearly state the enhancement you are proposing and why it would be a good addition to the project.
## Development Setup
To get started with development, you'll need to set up your environment.
1. **Clone the repository:**
```bash
git clone https://github.com/datalayer/jupyter-mcp-server
cd jupyter-mcp-server
```
2. **Install dependencies:**
```bash
# Install the project in editable mode with test dependencies
pip install -e ".[test]"
```
3. **Make Some Amazing Changes!**
```bash
# Make some amazing changes to the source code!
```
4. **Run Tests:**
```bash
make test
```
## (Optional) Manual Agent Testing
1. **Build Python Package:**
```bash
make build
```
2. **Set Up Your Environment:**
```bash
pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 ipykernel
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17
```
3. **Start Jupyter Server:**
```bash
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0
```
4. **Set Up Your MCP Client:**
We recommend using `uvx` to start the MCP server, first install `uvx` with `pip install uv`.
```bash
pip install uv
uv --version
# should be 0.6.14 or higher
```
Then, set up your MCP client with the following configuration file.
```json
{
"mcpServers": {
"Jupyter-MCP": {
"command": "uvx",
"args": [
"--from",
"your/path/to/jupyter-mcp-server/dist/jupyter_mcp_server-x.x.x-py3-none-any.whl",
"jupyter-mcp-server"
],
"env": {
"DOCUMENT_URL": "http://localhost:8888",
"DOCUMENT_TOKEN": "MY_TOKEN",
"DOCUMENT_ID": "notebook.ipynb",
"RUNTIME_URL": "http://localhost:8888",
"RUNTIME_TOKEN": "MY_TOKEN",
"ALLOW_IMG_OUTPUT": "true"
}
}
}
}
```
5. **Test Your Changes:**
You Can Test Your Changes with your favorite MCP client(e.g. Cursor, Gemini CLI, etc.).
## Pull Request Process
1. Once you are satisfied with your changes and tests, commit your code.
2. Push your branch to your fork and attach with detailed description of the changes you made.
3. Open a pull request to the `main` branch of the original repository.
We look forward to your contributions!