内容
# Nasuni 桌面端 MCP 解决方案适用于 SMB 文件夹
## 概述
该项目提供了一个桌面端模型上下文协议（MCP）服务器解决方案，允许 Claude Desktop 安全地浏览、读取和检索 Nasuni SMB 文件夹中的文件。
它适用于 Nasuni 管理员和高级用户在本地计算机上使用，以便使用 AI 对 Nasuni 数据进行实验。
**如需更多信息和指导培训，请访问 https://nasuni-customer-academy.workramp.io/training/01999637-8154-7340-ad76-f24dace6a8d5/overview（需要注册）。**
## 先决条件
### - **uv**（运行和管理项目依赖）
安装说明请参见官方文档：[https://docs.astral.sh/uv/getting-started/installation/](https://docs.astral.sh/uv/getting-started/installation/)
#### **Mac**
1. 检查是否已安装 Homebrew：`command -v brew && brew --version` 如果打印出版本号，请跳到步骤 4。
2. 安装 Homebrew：
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
3. 将 Homebrew 添加到 shell 的 PATH 中（选择一个）：
a. Apple Silicon（M1/M2/M3，arm64）— Homebrew 前缀为 `/opt/homebrew`
```
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
```
b. Intel（x86_64）— Homebrew 前缀为 `/usr/local`
```
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"
```
4. 安装 uv：
```
brew update
brew install uv
```
5. 验证安装并检查是否在全局路径上：
a. 确认二进制文件可以运行：`uv --version`
b. 确认 shell 将使用哪个可执行文件（应该在 Homebrew 的 bin 目录下）：
```
command -v uv
# 期望输出：
# /opt/homebrew/bin/uv （Apple Silicon）
# /usr/local/bin/uv （Intel）
```
c. 确保没有用户本地副本遮蔽 Homebrew 安装：
```
which -a uv
# 第一行应该是上面的 Homebrew 路径。
# 如果您看到类似 ~/.local/bin/uv 在其之前列出，则是本地安装遮蔽了全局安装。
```
7. 可选 - 快速修复
a. uv 未找到：打开新的终端（重新加载 PATH）或重新运行 shellenv 步骤，然后：`hash -r # 清除 shell 命令缓存`
b. 错误的 uv 被选中（例如，从 ~/.local/bin）：删除该路径在 shell 配置文件中的 PATH 前面，或者卸载本地副本，以便 Homebrew 路径生效。
c. 一般健康检查：
```
brew doctor
brew info uv
```
### - Python
下载：https://www.python.org/downloads/
#### Windows
在安装过程中选择 *Add python.exe to PATH.* 选项。
### - 访问一个或多个 Nasuni SMB 文件夹，安装在桌面上
### - Claude Desktop，或另一个 MCP 兼容的 AI 代理
---
## 配置您的代理
### Claude Desktop - 安装扩展
1. 从此仓库下载软件包 *nasuni-mcp-desktop-solution.dxt*：[DXT 软件包](nasuni-mcp-desktop-solution.dxt)
2. 在 Claude Desktop 中，前往 设置 → 扩展 → 高级设置 → 扩展开发者 → 安装扩展，并选择 .dxt 文件。
### 其他 MCP 客户端 - 手动安装
如果您正在使用其他工具（例如，VS Code，Cursor），请手动安装和配置 MCP 服务器：
1. 将此仓库提取到本地文件夹。
2. 在您的工具配置中，类似以下代码段（插入到适当的位置）：
```json
"mcp_config": {
"command": "uv",
"args": [
"run",
"--quiet",
"--directory",
"MCP_SERVER_PATH",
"server.py"
],
"env": {
"FILE_SYSTEM_PATH": "/path/to/mounted/share",
"MAX_SCAN_ITEMS": 1000,
"MAX_RETURN_FILE_SIZE": 1048576
}
}
```
其中 `MCP_SERVER_PATH` 是安装此代码的文件夹的绝对路径（此仓库中 mcp 目录的内容）。
#### VS Code
对于 VS Code，配置文件 `.vscode/mcp.json` 应类似以下内容：
```json
{
"servers": {
"my-nasuni-server": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"--quiet",
"--directory",
"SERVER_PATH",
"server.py"
],
"env": {
"FILE_SYSTEM_PATH": "/path/to/mounted/share",
"MAX_SCAN_ITEMS": 1000,
"MAX_RETURN_FILE_SIZE": 1048576
}
}
},
"inputs": []
}
```
#### 手动安装参数
- SERVER_PATH - 必需。安装此代码的文件夹的绝对路径。
- FILE_SYSTEM_PATH - 必需。本地机器上安装的 SMB 文件夹的路径。在 Windows 上，通常为 `\\server\share` 或映射驱动器，如 `Z:\`。
- MAX_SCAN_ITEMS - 可选。扫描文件夹时要扫描的最大项目数。默认值：1000。如果文件夹包含超过此数字的项目（文件/子文件夹），则只返回前 N 个。
- MAX_RETURN_FILE_SIZE - 可选。服务器将返回给客户端的数据的最大大小。默认值：1,048,576 字节（≈1 MB）。大于此大小的项目不会被返回。
- MAX_READ_FILE_SIZE - 可选。服务器将从 SMB 文件夹中读取的文件的最大大小。默认值：20,048,576 字节（≈20 MB）。大于此大小的文件不会被读取。
- LOG_DESTINATION - 可选。写入日志的位置。默认值：空（无日志）。如果提供有效的文件路径，则日志将被写入该文件；否则，日志将被写入控制台。
`MAX_RETURN_FILE_SIZE` 与 `MAX_READ_FILE_SIZE` - 这些限制用于不同的目的：
* MAX_READ_FILE_SIZE 限制服务器将加载以进行处理的文件的原始大小（例如，缩略图生成，文本提取）。
* MAX_RETURN_FILE_SIZE 限制服务器处理后将发送回的输出大小（例如，缩略图或提取的文本）。
示例
cat.png 为 2,048 KB。AI 代理调用 image_file_contents，参数为 thumb_width=512（生成一个 512 像素宽的缩略图）。
* 如果 `MAX_READ_FILE_SIZE` = 1,024 KB，则原始文件太大，无法读取 → 错误。
* 如果 `MAX_READ_FILE_SIZE` = 4,096 KB，则服务器读取文件，创建缩略图，然后将缩略图的大小与 `MAX_RETURN_FILE_SIZE` 进行比较：
* 如果缩略图大小 ≤ `MAX_RETURN_FILE_SIZE` → 返回缩略图。
* 如果缩略图大小 > `MAX_RETURN_FILE_SIZE` → 错误。
---
## 支持的工具
所有路径相对于配置的根目录（`FILE_SYSTEM_PATH`），并使用 / 作为分隔符。
1. **folder_contents(path: str = "") -> FolderContents**
- **参数：** `path`（str，可选）
- **描述：** 返回路径内的文件和子文件夹列表。如果路径为空，则返回根文件夹的内容。
2. **file_metadata(path: str) -> FileMetadata**
- **参数：** `path`（str，必需）
- **描述：** 返回文件元数据（例如，大小，类型，是否可作为图像读取，是否可以提取文本）。
3. **file_contents(path: str) -> str**
- **参数：** `path`（str，必需）
- **描述：** 下载文件并返回其内容为字符串。适用于文本或基于文本的格式。 二进制文件可能产生不可读的输出；对于二进制数据，请优选 `file_contents_base64()`，对于图像，请优选 `image_file_contents()`。
4. **file_contents_base64(path: str) -> str**
- **参数：** `path`（str，必需）
- **描述：** 下载文件并返回其内容为 Base64 编码字符串。推荐用于二进制文件。
5. **image_file_contents(path: str, thumb_width: int = 0) -> Image**
- **参数：** `path`（str，必需），`thumb_width`（int，可选）
- **描述：** 下载 PNG 或 JPEG 图像并返回 Image 对象。如果 `thumb_width > 0`，则返回缩略图，调整为指定宽度，同时保持宽高比。
6. **file_file_contents_as_text(path: str) -> str**
- **参数：** `path`（str，必需）
- **描述：** 检索文件并在支持的情况下返回提取的文本（PDF，DOCX）。对于其他类型，返回原始内容为字符串（与 `file_contents()` 行为相同）。
---
## 安全免责声明
本软件按原样提供，存在固有的安全风险。大语言模型（LLM）和相关系统目前无法完全防范恶意输入，这可能导致意外行为或数据暴露。使用此 MCP 集成时，您承担与之相关的所有风险，并同意作者不对任何安全事件或后果承担责任。
## Nasuni Labs 免责声明
Nasuni Labs 项目由社区支持，在此仓库中维护。它们按原样提供，不保证或正式的 Nasuni 支持。请自行判断使用。
