한국어 설명

Jupythunder

Jupythunder is a middleware that connects the LLM chat interface (Claude) with Jupyter Notebook. This project allows users to interact with Jupyter Notebook in a way that's closer to natural language.

Key Features

• Natural Language Code Conversion: LLM converts code written by users in a natural language style into correct Python code
• Jupyter Remote Connection: Supports remote connections via user-provided Jupyter Notebook URL (with token)
• Code Execution: Executes converted code in Jupyter Notebook and returns results
• Code Questions: Query information about defined functions, variables, etc. via the /question command
• State Management: Manages connection state and session information
• Notebook File Management: Supports creating, opening, cell management and saving .ipynb files
• Natural Language Data Analysis: Data analysis and visualization workflow through natural language requests
• Cell Query and Execution: View specific cell contents, execute specific cells, execute all cells sequentially

Installation

Prerequisites

• Python 3.10 or higher
• Jupyter Notebook
• Claude for Desktop (or another MCP client)

Installation Steps

1. Clone the repository:

   git clone https://github.com/username/jupythunder.git
   cd jupythunder
   

2. Install dependencies:

   pip install -r requirements.txt
   

Usage

1. Run Jupyter Notebook Server

Run the Jupyter Notebook server in a separate terminal:

jupyter notebook

Check the logs for the URL and token (e.g., http://localhost:8888/?token=abcdef1234567890).

2. Run MCP Server

python jupythunder_server.py

3. Configure Claude for Desktop

Add the MCP server to the claude_desktop_config.json file of Claude for Desktop:

{
  "mcpServers": {
    "jupythunder": {
      "command": "/absolute/path/python",
      "args": ["/absolute/path/jupythunder_server.py"]
    }
  }
}

Important: You must use the absolute path of Python and the script file.

4. Restart Claude for Desktop

Restart Claude for Desktop after changing the configuration.

5. Usage Examples

1. Connect to Jupyter:

   Connect to Jupyter Notebook. URL is http://localhost:8888/tree?token=abcdef1234567890
   

2. Create New Notebook:

   /notebook:data_analysis_notebook
   

3. Open Existing Notebook:

   /open:data_analysis_notebook
   

4. Natural Language Data Analysis Request:

   Generate random data
   

5. Data Analysis and Visualization:

   Show statistical analysis results for the generated data
   
   Visualize the correlation between age and income on a graph
   

6. Writing and Executing Code:

   def calculate_savings(income, expense):
       return income - expense
       
   df['savings'] = calculate_savings(df['income'], df['expenses'])
   df.head()
   

7. Function Information Lookup:

   /question: What functions are currently defined?
   

8. Notebook Content Lookup:

   What is the current notebook content?
   

9. Specific Cell Lookup and Execution:

   Show the content of the first cell
   Execute the second cell
   

10. Execute All Cells:

    Execute all cells in the notebook sequentially
    

Detailed Feature Description

Notebook Management Features

• Create New Notebook: Create a new notebook with the /notebook:notebook_name command
• Open Existing Notebook: Open an existing notebook with the /open:notebook_name command
• View Notebook Content: Check the cell composition of the current notebook

Cell Management Features

• View Cell Content: Check the code or markdown content of specific cells
• Execute Specific Cell: Selectively execute desired cells
• Execute All Cells: Execute all cells in the notebook sequentially
• Add Markdown Cell: Natural language explanations are automatically added as markdown cells
• Add Code Cell: Converted Python code is added as code cells
• Save Execution Results: Code execution results are automatically saved in the notebook

Natural Language Data Analysis Features

• Data Generation: Generate test data with natural language requests like "Generate random data"
• Statistical Analysis: Perform data analysis with requests like "Show summary statistics for the data"
• Data Visualization: Visualize with natural language requests like "Draw a graph of the age distribution"
• Correlation Analysis: Analyze relationships with requests like "Analyze the correlation between variables"

Command List

Command	Description	Example
/notebook:name	Create new notebook	/notebook:data_analysis
/open:name	Open existing notebook	/open:test
/question:content	Code-related question	/question:function list
/help	Display help	/help

Troubleshooting

could not connect to MCP server jupythunder: spawn pythonENOENT

This error occurs when the Python executable file cannot be found. Resolve it with these methods:

1. Use Python Absolute Path:

   {
     "mcpServers": {
       "jupythunder": {
         "command": "/absolute/path/python",
         "args": ["/absolute/path/jupythunder_server.py"]
       }
     }
   }
   

   You can find the Python absolute path with these commands:

   which python  # macOS/Linux
   where python  # Windows
   

2. Use python3 Command:

   {
     "mcpServers": {
       "jupythunder": {
         "command": "python3",
         "args": ["/absolute/path/jupythunder_server.py"]
       }
     }
   }
   

Jupyter Connection Failure

• Check if the Jupyter server is running
• Verify that the provided URL and token are correct
• Check firewall settings

Notebook Creation or Opening Failure

• Check if you have write permissions to the Jupyter server
• Make sure the notebook name does not contain special characters
• Check if a notebook with the same name already exists

Cell Execution Issues

• Check for syntax errors in the code
• Verify that necessary variables or functions are defined in previous cells
• Restart the server if execution results are not displayed in the notebook

Project Structure

jupythunder/
├── jupythunder_server.py  # Main server implementation
├── jupythunder_client.py  # Jupyter API client
├── tools.py               # MCP tool implement
├── utils.py               # Utility functions
└── requirements.txt       # Project dependencies

Key Components

• FastMCP Server: MCP protocol handling
• JupyterClient Class: Jupyter API interaction and notebook management
• Tools: Tools for connection, execution, query, and notebook management
• Command Handling: Special command parsing
• State Management: Lifespan context management
• Natural Language Processing: Converting natural language requests to Python code
• Cell Management: Functions for viewing cell content, execution, and saving results

Future Improvements

1. LLM Integration: Enhance natural language conversion capabilities using actual LLMs
2. Data Visualization Extensions: Support for various visualization types
3. Notebook Templates: Provide purpose-specific templates for data analysis, machine learning, etc.
4. File Upload: Support for data file upload and automatic analysis
5. Collaboration Features: Multi-user support and sharing features
6. Interactive Widgets: Enhanced support for Jupyter widgets
7. GPU Acceleration: GPU acceleration support for deep learning tasks

Dependencies

• mcp[cli] >= 1.5.0: MCP protocol implementation
• requests >= 2.31.0: HTTP request handling
• websocket-client >= 1.6.0: WebSocket communication
• python-dotenv >= 1.0.0: Environment variable management
• urllib3 >= 2.0.0: HTTP client

License

MIT License

---

Jupythunder (한국어)

Jupythunder는 LLM 채팅 인터페이스(Claude)와 Jupyter Notebook을 연결해주는 미들웨어입니다. 이 프로젝트를 통해 사용자는 자연어에 가까운 방식으로 Jupyter Notebook과 상호작용할 수 있습니다.

주요 기능

• 자연어 코드 변환: 사용자가 자연어에 가까운 방식으로 작성한 코드를 LLM이 올바른 Python 코드로 변환
• Jupyter 원격 연결: 사용자가 제공한 Jupyter Notebook URL(토큰 포함)을 통해 원격 연결 지원
• 코드 실행: 변환된 코드를 Jupyter Notebook에서 실행하고 결과 반환
• 코드 질문: /question 명령어를 통해 정의된 함수, 변수 등의 정보 조회
• 상태 관리: 연결 상태 및 세션 정보 관리
• 노트북 파일 관리: .ipynb 파일 생성, 열기, 셀 관리 및 저장 기능 지원
• 자연어 데이터 분석: 자연어 요청을 통한 데이터 분석 및 시각화 워크플로우
• 셀 조회 및 실행: 특정 셀 내용 조회, 특정 셀 실행, 모든 셀 순차 실행 지원

설치 방법

사전 요구사항

• Python 3.10 이상
• Jupyter Notebook
• Claude for Desktop (또는 다른 MCP 클라이언트)

설치 단계

1. 저장소 복제:

   git clone https://github.com/username/jupythunder.git
   cd jupythunder
   

2. 의존성 설치:

   pip install -r requirements.txt
   

사용 방법

1. Jupyter Notebook 서버 실행

별도의 터미널에서 Jupyter Notebook 서버를 실행합니다:

jupyter notebook

로그에서 URL과 토큰을 확인하세요 (예: http://localhost:8888/?token=abcdef1234567890).

2. MCP 서버 실행

python jupythunder_server.py

3. Claude for Desktop 설정

Claude for Desktop의 claude_desktop_config.json 파일에 MCP 서버를 추가합니다:

{
  "mcpServers": {
    "jupythunder": {
      "command": "/절대/경로/python",
      "args": ["/절대/경로/jupythunder_server.py"]
    }
  }
}

중요: Python과 스크립트 파일의 절대 경로를 사용해야 합니다.

4. Claude for Desktop 재시작

설정 변경 후 Claude for Desktop을 재시작합니다.

5. 사용 예시

1. Jupyter에 연결:

   Jupyter Notebook에 연결해줘. URL은 http://localhost:8888/tree?token=abcdef1234567890
   

2. 새 노트북 생성:

   /notebook:데이터분석_노트북
   

3. 기존 노트북 열기:

   /open:데이터분석_노트북
   

4. 자연어로 데이터 분석 요청:

   랜덤 데이터를 생성해줘
   

5. 데이터 분석 및 시각화:

   생성된 데이터에 대한 통계 분석 결과를 보여줘
   
   나이와 수입의 상관관계를 그래프로 시각화해줘
   

6. 코드 작성 및 실행:

   def calculate_savings(income, expense):
       return income - expense
       
   df['저축액'] = calculate_savings(df['수입'], df['지출'])
   df.head()
   

7. 함수 정보 조회:

   /question: 지금 정의된 함수가 뭐가 있지?
   

8. 노트북 내용 조회:

   현재 노트북의 내용이 어떻게 되어 있어?
   

9. 특정 셀 조회 및 실행:

   첫번째 셀의 내용을 보여줘
   두번째 셀을 실행해줘
   

10. 모든 셀 실행:

    노트북의 모든 셀을 순차적으로 실행해줘
    

주요 기능 상세 설명

노트북 관리 기능

• 새 노트북 생성: /notebook:노트북이름 명령어로 새 노트북을 생성합니다.
• 기존 노트북 열기: /open:노트북이름 명령어로 기존 노트북을 엽니다.
• 노트북 내용 조회: 현재 작업 중인 노트북의 셀 구성을 확인할 수 있습니다.

셀 관리 기능

• 셀 내용 조회: 특정 셀의 코드나 마크다운 내용을 확인할 수 있습니다.
• 특정 셀 실행: 원하는 셀만 선택적으로 실행할 수 있습니다.
• 모든 셀 실행: 노트북의 모든 셀을 순차적으로 실행할 수 있습니다.
• 마크다운 셀 추가: 자연어 설명이 마크다운 셀로 자동 추가됩니다.
• 코드 셀 추가: 변환된 Python 코드가 코드 셀로 추가됩니다.
• 실행 결과 저장: 코드 실행 결과가 노트북에 자동으로 저장됩니다.

자연어 데이터 분석 기능

• 데이터 생성: "랜덤 데이터 생성" 같은 자연어 요청으로 테스트 데이터를 생성합니다.
• 통계 분석: "데이터 요약 통계 보여줘" 등의 요청으로 데이터 분석을 수행합니다.
• 데이터 시각화: "나이 분포를 그래프로 그려줘"처럼 자연어 요청으로 시각화합니다.
• 상관관계 분석: "변수 간 상관관계 분석해줘"와 같은 요청으로 관계를 분석합니다.

명령어 목록

명령어	설명	예시
/notebook:이름	새 노트북 생성	/notebook:데이터분석
/open:이름	기존 노트북 열기	/open:test
/question:내용	코드 관련 질문	/question:함수 목록
/help	도움말 표시	/help

문제 해결

could not connect to MCP server jupythunder: spawn pythonENOENT

이 오류는 Python 실행 파일을 찾지 못할 때 발생합니다. 다음 방법으로 해결하세요:

1. Python 절대 경로 사용:

   {
     "mcpServers": {
       "jupythunder": {
         "command": "/절대/경로/python",
         "args": ["/절대/경로/jupythunder_server.py"]
       }
     }
   }
   

   Python 절대 경로는 다음 명령어로 확인할 수 있습니다:

   which python  # macOS/Linux
   where python  # Windows
   

2. python3 명령어 사용:

   {
     "mcpServers": {
       "jupythunder": {
         "command": "python3",
         "args": ["/절대/경로/jupythunder_server.py"]
       }
     }
   }
   

Jupyter 연결 실패

• Jupyter 서버가 실행 중인지 확인
• 제공한 URL과 토큰이 올바른지 확인
• 방화벽 설정 확인

노트북 생성 또는 열기 실패

• Jupyter 서버에 쓰기 권한이 있는지 확인
• 노트북 이름에 특수 문자가 포함되어 있지 않은지 확인
• 이미 같은 이름의 노트북이 있는지 확인

셀 실행 관련 문제

• 코드에 구문 오류가 없는지 확인
• 이전 셀에서 필요한 변수나 함수가 정의되었는지 확인
• 실행 결과가 노트북에 표시되지 않으면 서버를 재시작해보세요

프로젝트 구조

jupythunder/
├── jupythunder_server.py  # 메인 서버 구현
├── jupythunder_client.py  # Jupyter API 클라이언트 
├── tools.py               # MCP 도구 구현
├── utils.py               # 유틸리티 함수
└── requirements.txt       # 프로젝트 의존성

주요 구성 요소

• FastMCP 서버: MCP 프로토콜 처리
• JupyterClient 클래스: Jupyter API 상호작용 및 노트북 관리
• 도구: 연결, 실행, 조회, 노트북 관리를 위한 도구
• 명령어 처리: 특별 명령어 구문 분석
• 상태 관리: 라이프스팬 컨텍스트 관리
• 자연어 처리: 자연어 요청을 Python 코드로 변환
• 셀 관리: 셀 내용 조회, 실행, 결과 저장 기능

향후 개선 사항

1. LLM 통합: 실제 LLM을 이용한 자연어 변환 기능 강화
2. 데이터 시각화 확장: 다양한 시각화 유형 지원
3. 노트북 템플릿: 데이터 분석, 머신러닝 등 목적별 템플릿 제공
4. 파일 업로드: 데이터 파일 업로드 및 자동 분석 기능
5. 협업 기능: 다중 사용자 지원 및 공유 기능
6. 인터랙티브 위젯: Jupyter 위젯 지원 강화
7. GPU 가속: 딥러닝 작업을 위한 GPU 가속 지원

의존성

• mcp[cli] >= 1.5.0: MCP 프로토콜 구현
• requests >= 2.31.0: HTTP 요청 처리
• websocket-client >= 1.6.0: WebSocket 통신
• python-dotenv >= 1.0.0: 환경 변수 관리
• urllib3 >= 2.0.0: HTTP 클라이언트

라이센스

MIT 라이센스