Metadata-Version: 2.4
Name: jupyter_mcp_spaces
Version: 0.1.3
Summary: Datalayer spaces extension for Jupyter MCP Server (list and open the notebooks of a space, in place of a Jupyter filesystem)
Author-email: Datalayer <info@datalayer.io>
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/datalayer/jupyter-mcp-server
Keywords: jupyter,mcp,datalayer,spaces,extension
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: datalayer-core>=1.1.54
Requires-Dist: datalayer-reactor
Requires-Dist: jupyter-mcp-server
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
Provides-Extra: build
Requires-Dist: build>=1.2.1; extra == "build"
Requires-Dist: twine>=5.1.1; extra == "build"

<!--
  ~ Copyright (c) 2024- Datalayer, Inc.
  ~
  ~ BSD 3-Clause License
-->

# Jupyter MCP Spaces

Lists and opens the notebooks of a [Datalayer](https://datalayer.ai) space.

Datalayer keeps notebooks in **spaces**, addressed by uid. There is no
filesystem and no kernels API, so the tools that assume a Jupyter server have
nothing to answer:

| Tool | On a Jupyter server | On Datalayer |
|---|---|---|
| `list_files` | lists the directory | nothing to list |
| `list_kernels` | lists kernels | runtimes, provisioned on demand |
| `list_notebooks` | notebooks bound this session | — |

This extension replaces `list_notebooks` with one that answers the question
people actually ask, adds `list_spaces` and `find_notebook`, and hides the
tools that cannot work — so an agent is never offered a tool that always
fails.

## Install

```bash
pip install jupyter-mcp-spaces
```

It registers itself on the `jupyter_mcp_server.extensions` entry point and
activates only when the server runs with `--document-provider datalayer`.
Pointed at a Jupyter server it does nothing, and the ordinary tools stay.

```bash
jupyter-mcp-server start --transport streamable-http \
  --document-provider datalayer \
  --document-url https://prod1.datalayer.run
```

## Tools

| Tool | What it answers |
|---|---|
| `list_spaces` | The spaces you can reach |
| `list_notebooks` | The notebooks in them, with uid and space |
| `find_notebook` | Which notebook a name means — or the candidates, when it is ambiguous |

`find_notebook` never picks between candidates. Guessing which notebook
somebody meant is how an agent edits the wrong one.

## Credentials

Every call carries the token of the request being served, from
`jupyter_mcp_server.identity`. A server acting for several people over its
life must use the credential each request arrived with, not one configured at
startup — see the [identity
documentation](https://jupyter-mcp-server.datalayer.tech/features/identity).
