Metadata-Version: 2.4
Name: data-wise-jupyter-mcp-server
Version: 1.0.0
Summary: Jupyter Lab MCP Server - 提供远程控制 Jupyter Lab 的 MCP 服务
Project-URL: Homepage, https://github.com/datawisecenter/jupyter-mcp-server
Project-URL: Repository, https://github.com/datawisecenter/jupyter-mcp-server
Project-URL: Documentation, https://github.com/datawisecenter/jupyter-mcp-server#readme
Author-email: DataWiseCenter <contact@datawisecenter.com>
License: MIT
Keywords: fastmcp,jupyter,lab,mcp,notebook,remote
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: fastmcp>=2.14.1
Requires-Dist: jupyter-client>=8.0.0
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# DataWise Jupyter Lab MCP Server

提供远程控制 Jupyter Lab 的 MCP (Model Context Protocol) 服务。

## 功能特性

- 🔗 **远程连接**: 连接到远程或本地 Jupyter Lab 服务器
- 📓 **笔记本管理**: 创建、查看、列出笔记本
- ⚡ **代码执行**: 在笔记本中执行 Python 代码
- 🔄 **内核控制**: 管理和重启 Jupyter 内核
- 📊 **服务器监控**: 获取服务器状态和会话信息
- 🔒 **HTTPS 支持**: 完整的 SSL/TLS 安全连接支持
- 📥 **文件下载**: 通过内容 API 下载文件到本地
- 📁 **目录浏览**: 列出远程目录内容
- 📄 **文件信息**: 获取文件元数据而不下载内容

## 安装

```bash
pip install data-wise-jupyter-mcp-server
```

## 使用方法

### 启动 MCP 服务器

```bash
data-wise-jupyter-mcp-server
```

或者

```bash
datawise-jupyter-mcp
```

### 可用工具

#### 1. 服务器管理
- **`get_server_info`** - 获取 Jupyter Lab 服务器信息
  - 服务器状态、版本、会话数、内核数

#### 2. 笔记本管理  
- **`list_notebooks`** - 列出所有笔记本
- **`create_notebook`** - 创建新笔记本
- **`get_notebook_content`** - 获取笔记本内容

#### 3. 代码执行
- **`execute_code`** - 执行代码
  - 在指定笔记本中执行 Python 代码

#### 4. 内核控制
- **`list_kernels`** - 列出所有内核
- **`restart_kernel`** - 重启内核

#### 5. 文件操作 🆕
- **`download_file`** - 下载文件到本地
  - 支持文本、二进制、笔记本文件
- **`get_file_info`** - 获取文件信息
  - 文件大小、类型、修改时间等元数据
- **`list_directory_contents`** - 列出目录内容
  - 浏览远程目录结构

## 配置

### Jupyter Lab 服务器设置

确保你的 Jupyter Lab 服务器允许远程访问：

```bash
jupyter lab --no-browser --port=8888 --ip=0.0.0.0
```

### 获取访问令牌

启动 Jupyter Lab 时，会在控制台显示带有 token 的 URL，例如：
```
http://localhost:8888/lab?token=4aa4a5e0aec1f504f1738921c9c823ec28515c72bb5d7247
```

token 就是 `4aa4a5e0aec1f504f1738921c9c823ec28515c72bb5d7247`

### HTTPS 配置 🆕

支持安全的 HTTPS 连接：

```python
# 基本 HTTPS 连接
get_server_info({
    "url": "https://your-jupyter-server.com:8888",
    "token": "your_token",
    "verify_ssl": True
})

# 自签名证书（开发环境）
get_server_info({
    "url": "https://localhost:8888",
    "token": "your_token", 
    "verify_ssl": False
})

# 自定义 CA 证书
get_server_info({
    "url": "https://company-server.com:8888",
    "token": "your_token",
    "verify_ssl": True,
    "cert_path": "/path/to/ca-cert.pem"
})
```

### 文件操作示例 🆕

```python
# 下载文件到本地
download_file({
    "url": "http://localhost:8888",
    "token": "your_token",
    "file_path": "data/report.csv",
    "local_path": "./downloaded_report.csv"
})

# 获取文件信息
get_file_info({
    "url": "http://localhost:8888",
    "token": "your_token",
    "file_path": "analysis.ipynb"
})

# 列出目录内容
list_directory_contents({
    "url": "http://localhost:8888",
    "token": "your_token",
    "dir_path": "data/"
})
```

详细配置请参考：[HTTPS_GUIDE.md](HTTPS_GUIDE.md)

## 开发

### 环境设置

```bash
# 克隆仓库
git clone https://github.com/datawisecenter/jupyter-mcp-server.git
cd jupyter-mcp-server

# 安装依赖
pip install -r requirements.txt

# 安装为开发版本
pip install -e .
```

### 运行测试

```bash
pytest
```

## API 参考

### 错误处理

所有工具返回的 JSON 格式：

成功响应：
```json
{
    "success": true,
    "data": {...},
    "message": "操作成功"
}
```

错误响应：
```json
{
    "success": false,
    "error": "错误信息",
    "data": null
}
```

### 支持的 Jupyter Lab 版本

- Jupyter Lab 3.x
- Jupyter Lab 4.x

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

- 邮箱: contact@datawisecenter.com
- GitHub: https://github.com/datawisecenter/jupyter-mcp-server
