nutstore-mcp 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. nutstore_mcp-1.0.0/.env.example +20 -0
  2. nutstore_mcp-1.0.0/.gitignore +48 -0
  3. nutstore_mcp-1.0.0/Dockerfile +13 -0
  4. nutstore_mcp-1.0.0/PKG-INFO +237 -0
  5. nutstore_mcp-1.0.0/README.md +211 -0
  6. nutstore_mcp-1.0.0/app/__init__.py +1 -0
  7. nutstore_mcp-1.0.0/app/config.py +36 -0
  8. nutstore_mcp-1.0.0/app/main.py +274 -0
  9. nutstore_mcp-1.0.0/app/webdav.py +717 -0
  10. nutstore_mcp-1.0.0/docker-compose.yml +12 -0
  11. nutstore_mcp-1.0.0/pyproject.toml +41 -0
  12. nutstore_mcp-1.0.0/requirements.txt +5 -0
nutstore_mcp-1.0.0/.env.example ADDED
@@ -0,0 +1,20 @@
1
+ # 坚果云账号（邮箱）- 必填
2
+ NUTSTORE_USER=your-email@example.com
3
+
4
+ # 坚果云第三方应用密码 - 必填
5
+ # 在坚果云网页版「账号」→「安全选项」→「第三方应用密码」中生成
6
+ NUTSTORE_PASS=your-app-password
7
+
8
+ # WebDAV 服务器地址 - 可选
9
+ # 官方公共坚果云默认值：https://dav.jianguoyun.com/dav/
10
+ # 企业私有部署示例：https://drive.company.com/dav/
11
+ # NUTSTORE_HOST=https://dav.jianguoyun.com/dav/
12
+
13
+ # 根路径限制 - 可选，限定所有操作在指定目录下
14
+ # ROOT_PATH=/我的坚果云
15
+
16
+ # 只读模式 - 可选，设为 true 后禁止所有写操作
17
+ # READ_ONLY=false
18
+
19
+ # 日志级别 - 可选（DEBUG/INFO/WARNING/ERROR）
20
+ # LOG_LEVEL=WARNING
nutstore_mcp-1.0.0/.gitignore ADDED
@@ -0,0 +1,48 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.so
6
+ .Python
7
+ build/
8
+ develop-eggs/
9
+ dist/
10
+ downloads/
11
+ eggs/
12
+ .eggs/
13
+ lib/
14
+ lib64/
15
+ parts/
16
+ sdist/
17
+ var/
18
+ wheels/
19
+ *.egg-info/
20
+ .installed.cfg
21
+ *.egg
22
+
23
+ # Virtual environments
24
+ venv/
25
+ ENV/
26
+ env/
27
+ .venv/
28
+
29
+ # Environment variables
30
+ .env
31
+
32
+ # IDE
33
+ .idea/
34
+ .vscode/
35
+ *.swp
36
+ *.swo
37
+ *~
38
+
39
+ # Logs
40
+ logs/
41
+ *.log
42
+
43
+ # OS
44
+ .DS_Store
45
+ Thumbs.db
46
+
47
+ # Docker
48
+ .docker/
nutstore_mcp-1.0.0/Dockerfile ADDED
@@ -0,0 +1,13 @@
1
+ # 注意：stdio 本地模式是推荐的使用方式（见 README）。
2
+ # Docker 仅用于有特殊需求的自托管场景。
3
+
4
+ FROM m.daocloud.io/docker.io/library/python:3.11-slim
5
+
6
+ WORKDIR /app
7
+
8
+ COPY requirements.txt .
9
+ RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
10
+
11
+ COPY app/ ./app/
12
+
13
+ CMD ["python", "-m", "app.main"]
nutstore_mcp-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,237 @@
1
+ Metadata-Version: 2.4
2
+ Name: nutstore-mcp
3
+ Version: 1.0.0
4
+ Summary: 坚果云网盘 MCP 服务 - 支持通过 AI 助手管理坚果云文件
5
+ Project-URL: Homepage, https://github.com/silverze/nutstore-mcp
6
+ Project-URL: Repository, https://github.com/silverze/nutstore-mcp
7
+ Project-URL: Issues, https://github.com/silverze/nutstore-mcp/issues
8
+ License: MIT
9
+ Keywords: ai,jianguoyun,mcp,nutstore,webdav
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Topic :: Internet :: WWW/HTTP
18
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
19
+ Requires-Python: >=3.10
20
+ Requires-Dist: fastmcp>=2.4.0
21
+ Requires-Dist: pydantic-settings>=2.0.0
22
+ Requires-Dist: python-dotenv>=1.0.0
23
+ Requires-Dist: requests>=2.28.0
24
+ Requires-Dist: webdavclient3>=3.2
25
+ Description-Content-Type: text/markdown
26
+
27
+ # nutstore-mcp
28
+
29
+ 坚果云网盘 MCP 服务，支持通过 AI 助手（OpenCode、Claude Desktop、Cursor 等）管理坚果云文件。
30
+
31
+ 基于 WebDAV 协议实现，以本地 stdio 进程方式运行，**文件上传/下载直接在你的本机与坚果云之间传输**，支持任意格式文件（文本、图片、PDF、压缩包等）。
32
+
33
+ ## 快速开始
34
+
35
+ ### 第 1 步：安装 uv
36
+
37
+ ```bash
38
+ # macOS / Linux
39
+ curl -LsSf https://astral.sh/uv/install.sh | sh
40
+
41
+ # Windows (PowerShell)
42
+ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
43
+ ```
44
+
45
+ ### 第 2 步：获取坚果云应用密码
46
+
47
+ 1. 登录坚果云网页版
48
+ 2. 进入「账号」→「安全选项」→「第三方应用密码」
49
+ 3. 点击「添加应用密码」，记录生成的密码
50
+
51
+ ### 第 3 步：配置 MCP 客户端
52
+
53
+ #### OpenCode
54
+
55
+ 编辑 `~/.config/opencode/opencode.json`：
56
+
57
+ ```json
58
+ {
59
+ "mcp": {
60
+ "nutstore": {
61
+ "type": "local",
62
+ "command": ["uvx", "nutstore-mcp"],
63
+ "enabled": true,
64
+ "environment": {
65
+ "NUTSTORE_USER": "your-email@example.com",
66
+ "NUTSTORE_PASS": "your-app-password"
67
+ }
68
+ }
69
+ }
70
+ }
71
+ ```
72
+
73
+ #### Claude Desktop
74
+
75
+ 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）
76
+ 或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
77
+
78
+ ```json
79
+ {
80
+ "mcpServers": {
81
+ "nutstore": {
82
+ "command": "uvx",
83
+ "args": ["nutstore-mcp"],
84
+ "env": {
85
+ "NUTSTORE_USER": "your-email@example.com",
86
+ "NUTSTORE_PASS": "your-app-password"
87
+ }
88
+ }
89
+ }
90
+ }
91
+ ```
92
+
93
+ #### Cursor
94
+
95
+ 在 MCP 设置中添加：
96
+
97
+ ```json
98
+ {
99
+ "mcpServers": {
100
+ "nutstore": {
101
+ "command": "uvx",
102
+ "args": ["nutstore-mcp"],
103
+ "env": {
104
+ "NUTSTORE_USER": "your-email@example.com",
105
+ "NUTSTORE_PASS": "your-app-password"
106
+ }
107
+ }
108
+ }
109
+ }
110
+ ```
111
+
112
+ > **企业私有部署**（如 `drive.company.com`）额外添加：
113
+ > ```json
114
+ > "NUTSTORE_HOST": "https://drive.company.com/dav/"
115
+ > ```
116
+
117
+ ---
118
+
119
+ ## 环境变量
120
+
121
+ | 变量 | 说明 | 默认值 |
122
+ |------|------|--------|
123
+ | `NUTSTORE_USER` | 坚果云账号（邮箱）| **必填** |
124
+ | `NUTSTORE_PASS` | 第三方应用密码 | **必填** |
125
+ | `NUTSTORE_HOST` | WebDAV 服务器地址 | `https://dav.jianguoyun.com/dav/` |
126
+ | `ROOT_PATH` | 根路径限制（限定操作范围）| `/` |
127
+ | `READ_ONLY` | 只读模式 | `false` |
128
+ | `LOG_LEVEL` | 日志级别 | `WARNING` |
129
+
130
+ ---
131
+
132
+ ## 可用工具
133
+
134
+ ### 目录与搜索
135
+ | 工具 | 说明 |
136
+ |------|------|
137
+ | `list_files` | 列出指定目录内容 |
138
+ | `search_files` | 按关键词搜索文件（支持递归） |
139
+ | `get_directory_tree` | 获取目录树结构 |
140
+
141
+ ### 文件信息
142
+ | 工具 | 说明 |
143
+ |------|------|
144
+ | `get_file_info` | 获取文件/目录详细信息 |
145
+ | `exists` | 检查路径是否存在 |
146
+ | `is_dir` | 判断路径是否为目录 |
147
+ | `check_connection` | 检查 WebDAV 连接状态 |
148
+
149
+ ### 文本文件读写（AI 直接处理内容）
150
+ | 工具 | 说明 |
151
+ |------|------|
152
+ | `read_file_content` | 读取文本文件内容（.txt/.md/.json 等）|
153
+ | `write_file_content` | 将文本内容写入远端文件 |
154
+
155
+ ### 本地 ↔ 坚果云 文件传输（支持二进制/大文件）
156
+ | 工具 | 说明 |
157
+ |------|------|
158
+ | `download_file` | 从坚果云下载单个文件到本机 |
159
+ | `upload_file` | 从本机上传单个文件到坚果云 |
160
+ | `download_dir` | 从坚果云递归下载整个目录到本机 |
161
+ | `upload_dir` | 从本机递归上传整个目录到坚果云 |
162
+
163
+ ### 文件管理
164
+ | 工具 | 说明 |
165
+ |------|------|
166
+ | `move_file` | 移动或重命名 |
167
+ | `copy_file` | 复制文件/目录 |
168
+ | `delete_file` | 删除文件或目录 |
169
+ | `batch_delete` | 批量删除（逗号分隔路径）|
170
+ | `create_directory` | 创建目录 |
171
+ | `mkdirs` | 递归创建多级目录 |
172
+
173
+ ---
174
+
175
+ ## 对话示例
176
+
177
+ 连接成功后，可直接用自然语言操作：
178
+
179
+ - "列出坚果云/我的坚果云/下的所有文件"
180
+ - "把坚果云上的 /文档/报告.pdf 下载到 ~/Downloads/"
181
+ - "把本地 ~/项目/report.xlsx 上传到坚果云 /我的坚果云/工作/"
182
+ - "搜索坚果云中包含'项目计划'的文件"
183
+ - "在坚果云创建目录 /我的坚果云/2026/Q2"
184
+ - "把坚果云 /我的坚果云/旧目录 整个下载到本地 /tmp/backup"
185
+
186
+ ---
187
+
188
+ ## 本地开发
189
+
190
+ ```bash
191
+ git clone https://github.com/silverze/nutstore-mcp.git
192
+ cd nutstore-mcp
193
+
194
+ # 安装依赖
195
+ pip install -e ".[dev]"
196
+
197
+ # 复制并配置环境变量
198
+ cp .env.example .env
199
+ vim .env
200
+
201
+ # 直接运行
202
+ python -m app.main
203
+ ```
204
+
205
+ ---
206
+
207
+ ## 发布到 PyPI
208
+
209
+ ```bash
210
+ pip install hatch
211
+ hatch build
212
+ hatch publish
213
+ ```
214
+
215
+ ---
216
+
217
+ ## 项目结构
218
+
219
+ ```
220
+ nutstore-mcp/
221
+ ├── app/
222
+ │ ├── __init__.py
223
+ │ ├── config.py # 配置（从环境变量读取）
224
+ │ ├── webdav.py # WebDAV 客户端封装
225
+ │ └── main.py # FastMCP stdio 服务入口 + 所有工具定义
226
+ ├── .env.example # 环境变量模板
227
+ ├── pyproject.toml # 包元数据与入口点
228
+ ├── requirements.txt # 依赖列表
229
+ ├── Dockerfile # 可选：自托管 Docker 镜像
230
+ └── docker-compose.yml # 可选：Docker Compose 配置
231
+ ```
232
+
233
+ ---
234
+
235
+ ## License
236
+
237
+ MIT
nutstore_mcp-1.0.0/README.md ADDED
@@ -0,0 +1,211 @@
1
+ # nutstore-mcp
2
+
3
+ 坚果云网盘 MCP 服务，支持通过 AI 助手（OpenCode、Claude Desktop、Cursor 等）管理坚果云文件。
4
+
5
+ 基于 WebDAV 协议实现，以本地 stdio 进程方式运行，**文件上传/下载直接在你的本机与坚果云之间传输**，支持任意格式文件（文本、图片、PDF、压缩包等）。
6
+
7
+ ## 快速开始
8
+
9
+ ### 第 1 步：安装 uv
10
+
11
+ ```bash
12
+ # macOS / Linux
13
+ curl -LsSf https://astral.sh/uv/install.sh | sh
14
+
15
+ # Windows (PowerShell)
16
+ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
17
+ ```
18
+
19
+ ### 第 2 步：获取坚果云应用密码
20
+
21
+ 1. 登录坚果云网页版
22
+ 2. 进入「账号」→「安全选项」→「第三方应用密码」
23
+ 3. 点击「添加应用密码」，记录生成的密码
24
+
25
+ ### 第 3 步：配置 MCP 客户端
26
+
27
+ #### OpenCode
28
+
29
+ 编辑 `~/.config/opencode/opencode.json`：
30
+
31
+ ```json
32
+ {
33
+ "mcp": {
34
+ "nutstore": {
35
+ "type": "local",
36
+ "command": ["uvx", "nutstore-mcp"],
37
+ "enabled": true,
38
+ "environment": {
39
+ "NUTSTORE_USER": "your-email@example.com",
40
+ "NUTSTORE_PASS": "your-app-password"
41
+ }
42
+ }
43
+ }
44
+ }
45
+ ```
46
+
47
+ #### Claude Desktop
48
+
49
+ 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）
50
+ 或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
51
+
52
+ ```json
53
+ {
54
+ "mcpServers": {
55
+ "nutstore": {
56
+ "command": "uvx",
57
+ "args": ["nutstore-mcp"],
58
+ "env": {
59
+ "NUTSTORE_USER": "your-email@example.com",
60
+ "NUTSTORE_PASS": "your-app-password"
61
+ }
62
+ }
63
+ }
64
+ }
65
+ ```
66
+
67
+ #### Cursor
68
+
69
+ 在 MCP 设置中添加：
70
+
71
+ ```json
72
+ {
73
+ "mcpServers": {
74
+ "nutstore": {
75
+ "command": "uvx",
76
+ "args": ["nutstore-mcp"],
77
+ "env": {
78
+ "NUTSTORE_USER": "your-email@example.com",
79
+ "NUTSTORE_PASS": "your-app-password"
80
+ }
81
+ }
82
+ }
83
+ }
84
+ ```
85
+
86
+ > **企业私有部署**（如 `drive.company.com`）额外添加：
87
+ > ```json
88
+ > "NUTSTORE_HOST": "https://drive.company.com/dav/"
89
+ > ```
90
+
91
+ ---
92
+
93
+ ## 环境变量
94
+
95
+ | 变量 | 说明 | 默认值 |
96
+ |------|------|--------|
97
+ | `NUTSTORE_USER` | 坚果云账号（邮箱）| **必填** |
98
+ | `NUTSTORE_PASS` | 第三方应用密码 | **必填** |
99
+ | `NUTSTORE_HOST` | WebDAV 服务器地址 | `https://dav.jianguoyun.com/dav/` |
100
+ | `ROOT_PATH` | 根路径限制（限定操作范围）| `/` |
101
+ | `READ_ONLY` | 只读模式 | `false` |
102
+ | `LOG_LEVEL` | 日志级别 | `WARNING` |
103
+
104
+ ---
105
+
106
+ ## 可用工具
107
+
108
+ ### 目录与搜索
109
+ | 工具 | 说明 |
110
+ |------|------|
111
+ | `list_files` | 列出指定目录内容 |
112
+ | `search_files` | 按关键词搜索文件（支持递归） |
113
+ | `get_directory_tree` | 获取目录树结构 |
114
+
115
+ ### 文件信息
116
+ | 工具 | 说明 |
117
+ |------|------|
118
+ | `get_file_info` | 获取文件/目录详细信息 |
119
+ | `exists` | 检查路径是否存在 |
120
+ | `is_dir` | 判断路径是否为目录 |
121
+ | `check_connection` | 检查 WebDAV 连接状态 |
122
+
123
+ ### 文本文件读写（AI 直接处理内容）
124
+ | 工具 | 说明 |
125
+ |------|------|
126
+ | `read_file_content` | 读取文本文件内容（.txt/.md/.json 等）|
127
+ | `write_file_content` | 将文本内容写入远端文件 |
128
+
129
+ ### 本地 ↔ 坚果云 文件传输（支持二进制/大文件）
130
+ | 工具 | 说明 |
131
+ |------|------|
132
+ | `download_file` | 从坚果云下载单个文件到本机 |
133
+ | `upload_file` | 从本机上传单个文件到坚果云 |
134
+ | `download_dir` | 从坚果云递归下载整个目录到本机 |
135
+ | `upload_dir` | 从本机递归上传整个目录到坚果云 |
136
+
137
+ ### 文件管理
138
+ | 工具 | 说明 |
139
+ |------|------|
140
+ | `move_file` | 移动或重命名 |
141
+ | `copy_file` | 复制文件/目录 |
142
+ | `delete_file` | 删除文件或目录 |
143
+ | `batch_delete` | 批量删除（逗号分隔路径）|
144
+ | `create_directory` | 创建目录 |
145
+ | `mkdirs` | 递归创建多级目录 |
146
+
147
+ ---
148
+
149
+ ## 对话示例
150
+
151
+ 连接成功后，可直接用自然语言操作：
152
+
153
+ - "列出坚果云/我的坚果云/下的所有文件"
154
+ - "把坚果云上的 /文档/报告.pdf 下载到 ~/Downloads/"
155
+ - "把本地 ~/项目/report.xlsx 上传到坚果云 /我的坚果云/工作/"
156
+ - "搜索坚果云中包含'项目计划'的文件"
157
+ - "在坚果云创建目录 /我的坚果云/2026/Q2"
158
+ - "把坚果云 /我的坚果云/旧目录 整个下载到本地 /tmp/backup"
159
+
160
+ ---
161
+
162
+ ## 本地开发
163
+
164
+ ```bash
165
+ git clone https://github.com/silverze/nutstore-mcp.git
166
+ cd nutstore-mcp
167
+
168
+ # 安装依赖
169
+ pip install -e ".[dev]"
170
+
171
+ # 复制并配置环境变量
172
+ cp .env.example .env
173
+ vim .env
174
+
175
+ # 直接运行
176
+ python -m app.main
177
+ ```
178
+
179
+ ---
180
+
181
+ ## 发布到 PyPI
182
+
183
+ ```bash
184
+ pip install hatch
185
+ hatch build
186
+ hatch publish
187
+ ```
188
+
189
+ ---
190
+
191
+ ## 项目结构
192
+
193
+ ```
194
+ nutstore-mcp/
195
+ ├── app/
196
+ │ ├── __init__.py
197
+ │ ├── config.py # 配置（从环境变量读取）
198
+ │ ├── webdav.py # WebDAV 客户端封装
199
+ │ └── main.py # FastMCP stdio 服务入口 + 所有工具定义
200
+ ├── .env.example # 环境变量模板
201
+ ├── pyproject.toml # 包元数据与入口点
202
+ ├── requirements.txt # 依赖列表
203
+ ├── Dockerfile # 可选：自托管 Docker 镜像
204
+ └── docker-compose.yml # 可选：Docker Compose 配置
205
+ ```
206
+
207
+ ---
208
+
209
+ ## License
210
+
211
+ MIT
nutstore_mcp-1.0.0/app/__init__.py ADDED
@@ -0,0 +1 @@
1
+ # Nutstore MCP Server
nutstore_mcp-1.0.0/app/config.py ADDED
@@ -0,0 +1,36 @@
1
+ """配置管理模块"""
2
+
3
+ from pydantic_settings import BaseSettings, SettingsConfigDict
4
+
5
+
6
+ class Settings(BaseSettings):
7
+ """应用配置，所有字段均可通过环境变量覆盖"""
8
+
9
+ model_config = SettingsConfigDict(
10
+ env_file=".env",
11
+ env_file_encoding="utf-8",
12
+ # pydantic-settings v2: field names are uppercased automatically as env var names
13
+ # e.g. nutstore_host -> NUTSTORE_HOST
14
+ )
15
+
16
+ # 坚果云 WebDAV 服务器地址
17
+ # 官方公共坚果云默认地址；企业私有部署请设置 NUTSTORE_HOST
18
+ nutstore_host: str = "https://dav.jianguoyun.com/dav/"
19
+
20
+ # 坚果云账号（邮箱）
21
+ nutstore_user: str = ""
22
+
23
+ # 坚果云第三方应用密码
24
+ nutstore_pass: str = ""
25
+
26
+ # 根路径限制（限定所有操作在此目录下）
27
+ root_path: str = "/"
28
+
29
+ # 只读模式
30
+ read_only: bool = False
31
+
32
+ # 日志级别
33
+ log_level: str = "WARNING"
34
+
35
+
36
+ settings = Settings()