使用说明

MCP 1.5-带人工智能的高级Hammerspace存储管理

用于Hammerspace存储管理的生产就绪模型上下文协议（MCP）服务器，具有自然语言界面、自动文件摄取和全面监控功能。

🚀 快速开始

先决条件

Python 3.8或更高版本
Linux系统（建议使用Ubuntu 20.04+）
Hammerspace存储集群（已安装HSTK CLI）
Anthropic API键（用于自然语言用户界面）
NVIDIA API密钥（可选，用于AI功能）
Kubernetes集群（用于自动文件摄取）
Milvus矢量数据库（用于文档嵌入）

安装

克隆存储库:

git clone https://github.com/mbloomhammerspace/mcp-1.5.git
cd mcp-1.5

创建虚拟环境:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

配置环境变量:

cp .env.example .env
nano .env

设置以下内容：

# Hammerspace Configuration
HS_ANVIL=10.200.120.90

# Anthropic API (for Web UI)
ANTHROPIC_API_KEY=your_anthropic_key_here

# NVIDIA API (optional)
NVIDIA_API_KEY=your_nvidia_key_here

用一个命令启动所有服务:
```
./start_all_services.sh start
```
访问Web UI： http://localhost:5000

📋 特性

🤖 自然语言接口

基于Web的用户界面 由Claude AI提供技术支持 http://localhost:5000
直接MCP集成 适用于所有Hammerspace运营
实时调试日志查看器 在 /debug
文件摄取监视器仪表板 在 /monitor
以行动为导向的应对措施 -执行命令，报告结果

📁 高级文件摄取系统

多格式支持 -BMP、DOCX、HTML、JPEG、JSON、MD、PDF、PNG、PPTX、SH、TIFF、TXT、MP3
实时文件监控 -NFS 4.2挂载上的基于轮询的检测
基于文件夹的处理 -新文件夹触发对所有支持文件的批处理
Kubernetes作业部署 -使用ConfigMaps自动接收文件作业
Milvus矢量数据库集成 -自动嵌入生成和存储
智能集合命名 -以文件夹或顺序编号命名的集合
基于标签的分层管理 -嵌入文件的自动tier0升级
事件流 -摄入管道的实时监测

📊 综合监控UI

实时事件流 -观看实时摄入的文件
事件过滤 -按事件类型、文件模式或时间戳过滤
吐司通知 -新文件到达时收到通知
状态仪表板 -监控服务运行状况、文件计数、CPU使用率
交互式用户界面 -用于跟踪摄入管道的美观、现代的界面
多业务监控 -跟踪所有MCP服务器和服务

🔧 持久服务管理

统一启动脚本 -用一个命令启动所有服务
屏幕会话持久性 -服务在SSH断开连接后仍能正常运行
自动重启功能 -服务崩溃时会自动重新启动
系统集成 -启动时可选择自动启动
综合录井 -所有服务的详细日志
健康监测 -实时服务状态和端口监控

API终点

/api/monitor/status -获取监视器服务状态
/api/monitor/events -使用过滤器查询摄取事件
/api/monitor/events/stream -服务器发送实时更新事件
/api/chat -自然语言聊天界面
/api/tools -列出可用的MCP工具
/api/logs/stream -实时流式传输调试日志

核心MCP工具

所有工具使用 真正的HSTK CLI命令 （无模拟数据）：

tag_directory_recursive -递归标记文件和目录
check_tagged_files_alignment -检查标记的文件是否与其目标对齐
apply_objective_to_path -应用Hammerspace目标（例如，“第0层位置”、“体积位置”）
remove_objective_from_path -从路径中删除目标
list_objectives_for_path -列出应用于路径的所有目标
ingest_new_files -按ctime/mtime查找新文件，标记它们并将其放置在第1层
refresh_mounts -刷新NFS装载以解析过时的文件句柄

高级功能

自动文件监控 -使用MD5哈希和MIME类型自动标记新文件的轮询服务
自动恢复陈旧文件句柄 -检测并自动刷新装载
共享相对路径支持 -使用 /modelstore/dir 而不是 /mnt/se-lab/modelstore/dir
多层支持 -第0层（高性能）和第1层（默认存储）
基于标签的工作流 -标记文件并将其作为集合进行管理
智能配料 -如果流量较小，则立即对文件事件（15秒）或进程进行分组

🆕 高级文件摄取工作流

运作原理

文件检测：文件监视器每5秒轮询NFS装载的新文件
标记：新文件会自动标记为：
- user.ingestid=<md5hash> -MD5哈希用于重复数据删除
- user.mimeid=<mimetype> -用于分类的MIME类型
- user.embedding -需要嵌入的文件标签
多格式处理：所有支持的文件类型都会触发Kubernetes摄取作业
馆藏管理：文件被组织到Milvus集合中：
- 基于文件夹：以文件夹命名的集合（例如。， cold_0011)
- 顺序的：命名的集合 intel_1, intel_2等等。
层级管理：标记为嵌入的文件会自动升级到tier0
嵌入生成：文件被处理为向量嵌入
存储：存储在Milvus中用于语义搜索的嵌入
级别降级：嵌入后，文件将移回默认层

文件夹处理

当检测到新文件夹时：

文件夹中所有支持的文件都作为批处理
创建一个以文件夹命名的Milvus集合
集合名称被净化（例如。， cold-0011 → cold_0011)
文件夹中的所有文件都上传到同一个集合中
文件被标记为 embedding 并升级为tier0进行处理
嵌入后，删除tier0目标

配置

文件监视器支持：

轮询间隔：营业时间为5秒（快速），追溯时间为30秒
追溯标记：可配置的时间窗口（默认：禁用测试）
路径监视：监视器 /mnt/anvil/hub/ 默认情况下
文件过滤：处理所有支持的文件类型（BMP、DOCX、HTML、JPEG、JSON、MD、PDF、PNG、PPTX、SH、TIFF、TXT、MP3）
递归文件夹标记：标记整个文件夹层次结构，以提高40倍的性能

Kubernetes集成

作业模板：用途 k8s-templates/ingest.yaml 用于PDF处理
ConfigMaps：通过Kubernetes ConfigMaps传递给作业的文件列表
PVC集成：用途 hammerspace-hub-pvc 用于持久存储
路径映射：从映射的容器路径 /mnt/anvil/hub/ 到 /data/

🎯 用法

示例命令（Web UI）

在自然语言界面中尝试以下操作：

Tag all files in /modelstore/nvidia-test-thurs as modelsetid=my-demo
Promote all modelsetid=my-demo tagged files to tier0
Check alignment status of files tagged with modelsetid=my-demo
Remove the Place-on-tier0 objective from /modelstore/nvidia-test-thurs
List all objectives for /modelstore/incoming-models
Refresh Hammerspace mounts

🆕 文件摄取命令

Start the file monitor daemon
Check file monitor status
View recent file ingestion events
Stop the file monitor

直接使用MCP服务器

添加到您的MCP客户端配置中（例如，Cursor IDE）：

{
  "mcpServers": {
    "hammerspace": {
      "command": "python",
      "args": ["/home/mike/mcp-1.5/src/aiq_hstk_mcp_server.py"],
      "env": {
        "PYTHONPATH": "/home/mike/mcp-1.5"
      }
    }
  }
}

可用的MCP工具

标签管理

tag_directory_recursive -递归标记目录中的所有文件

{
  "path": "/mnt/se-lab/modelstore/my-models",
  "tag_name": "user.modelsetid",
  "tag_value": "my-tag-value"
}

check_tagged_files_alignment -查找并检查标记文件的对齐情况

{
  "tag_name": "user.modelsetid",
  "tag_value": "my-tag-value",
  "share_path": "/mnt/se-lab/modelstore/"
}

层级管理

apply_objective_to_path -应用分层促销等目标

{
  "objective_name": "Place-on-tier0",
  "path": "/mnt/se-lab/modelstore/my-models"
}

remove_objective_from_path -删除目标

{
  "objective_name": "Place-on-tier0",
  "path": "/mnt/se-lab/modelstore/my-models"
}

文件摄入

ingest_new_files -查找新文件，标记它们，并将其放置在第1层

{
  "path": "/mnt/se-lab/modelstore/",
  "tag_name": "user.modelsetid",
  "tag_value": "new-batch",
  "age_minutes": 60
}

系统工具

refresh_mounts -刷新NFS装载以解析过时的文件句柄
```
{
  "mount_type": "all"
}
```

文件监控和摄入

start_inotify_monitor -启动自动文件监控服务
```
{}
```
监控所有Hammerspace共享，自动标记新文件：
- user.ingestid=<md5hash> -MD5哈希用于重复数据删除
- user.mimeid=<mimetype> -用于分类的MIME类型
事件每15秒进行一次批处理，如果交通流量很小，则立即处理。
get_file_monitor_status -获取监视器状态
```
{}
```
返回：运行状态、监视的路径、挂起的事件、标记的文件、CPU使用率
get_file_ingest_events -查询文件摄取/标记事件
```
{
  "limit": 100,
  "event_type": "NEW_FILE",
  "file_pattern": ".pdf",
  "since_timestamp": "2025-10-09T20:00:00"
}
```
返回最近的文件摄取事件以及完整的元数据，包括：
- 事件类型（NEW_FILE或RETROACTIVE_TAG）
- 文件路径和名称
- MD5哈希（摄入）
- MIME类型（mimeid）
- 文件大小和时间戳
使用案例：
- 跟踪已摄入的文件
- 基于文件事件构建自动化工作流
- 监测摄入管道
- 审计文件处理
stop_inotify_monitor -停止监控服务
```
{}
```
list_objectives_for_path -列出路径的所有目标
```
{
  "path": "/mnt/se-lab/modelstore/my-models"
}
```

🔧 建筑

组件

MCP服务器 (src/aiq_hstk_mcp_server.py)
- 实施MCP协议
- 执行Hammerspace HSTK CLI命令
- 处理过时文件句柄的自动重试
- 使用真实的HSTK操作（无模拟数据）
Web用户界面 (web_ui/app.py)
- 基于Flask的自然语言界面
- 用于NL理解的人-克劳德整合
- 用于工具执行的MCP客户端
- 实时调试日志流
🆕 文件监控 (src/file_monitor.py)
- NFS 4.2挂载的基于轮询的文件检测
- 使用MD5和MIME类型自动标记
- 基于文件夹的批处理
- 用于PDF摄取的Kubernetes作业部署
- Milvus收藏管理
🆕 文件监视器守护程序 (src/file_monitor_daemon.py)
- 用于运行文件监视器的独立守护进程
- 用于持续监控的后台服务
- 日志记录和错误处理
装载刷新脚本 (refresh_mounts.sh)
- 卸载和重新装载Hammerspace NFS共享
- 解决过时的文件句柄错误
- 支持选择性装载刷新

数据流

User Input (NL) → Claude AI → MCP Tool Selection → HSTK CLI → Hammerspace
                     ↓
                 MCP Server
                     ↓
              Real Operations

🆕 文件摄取数据流

New File/Folder → File Monitor → Tagging → Kubernetes Job → PDF Processing → Milvus Collection
                     ↓
                 Event Logging → Web UI Dashboard → Real-time Monitoring

🧪 测试

Web UI测试

cd tests
./test_web_ui_curl.sh
python test_web_ui.py

单指令测试

cd tests
./test_single_question.sh "Tag all files in /modelstore/test as modelsetid=test123"

🆕 文件摄入测试

# Start file monitor daemon
python3 src/file_monitor_daemon.py

# Check monitor status
curl http://localhost:5000/api/monitor/status

# View ingestion events
curl http://localhost:5000/api/monitor/events

# Test with new files
cp test.pdf /mnt/anvil/hub/

🛠️ 服务管理

统一服务管理

# Start all services with one command
./start_all_services.sh start

# Check service status
./start_all_services.sh status

# Stop all services
./start_all_services.sh stop

# Restart all services
./start_all_services.sh restart

个性化服务管理

# View logs for specific services
./start_all_services.sh logs web-ui
./start_all_services.sh logs file-monitor
./start_all_services.sh logs hammerspace-mcp
./start_all_services.sh logs milvus-mcp

# Attach to service screen sessions
./start_all_services.sh attach web-ui
./start_all_services.sh attach file-monitor

# Clean up old logs
./start_all_services.sh cleanup

服务URL

一旦启动，服务可在以下网址获得：

Web用户界面: http://localhost:5000
Web用户界面（局域网）: http://10.0.0.236:5000
Hammerspace MCP：基于stdio（无HTTP端点）
Milvus MCP: http://localhost:9902/sse（如果Milvus正在跑步）
Kubernetes MCP: http://localhost:9903/sse（未实施）

查看日志

# Web UI logs
tail -f logs/web_ui.log

# MCP Server logs
tail -f logs/aiq_hstk_mcp.log

# File monitor logs
tail -f logs/retroactive_fully_disabled.log

# Real-time streaming (in browser)
# Visit http://localhost:5000/debug

🐛 故障排除

过时的文件句柄错误

当出现过时的文件句柄时，MCP服务器会自动检测并重试操作。如果问题仍然存在：

# Manual mount refresh
./refresh_mounts.sh

# Or via Web UI
"Refresh Hammerspace mounts"

标签操作不起作用

确保您的目标是已装载的目录
验证HSTK CLI是否可访问： /home/mike/hs-mcp-1.0/.venv/bin/hs --version
检查支架： mount | grep hammerspace

🆕 文件摄入问题

未检测到文件：检查文件监视器是否正在运行
```
ps aux | grep file_monitor_daemon
```

Kubernetes作业失败：检查吊舱状态

kubectl get pods -l app=pdf-ingest
kubectl logs -l app=pdf-ingest

Milvus收藏空：检查摄取服务日志
```
kubectl logs -l app=ingestor-server
```

NFS装载问题：验证安装点

mount | grep anvil
ls -la /mnt/anvil/hub/

常见标签格式

Hammerspace中的标签使用以下格式： namespace.key=value

示例：

user.modelsetid=my-demo
user.project=gtc-2025
user.tier=critical

📚 文档

🚀 快速开始

快速参考指南 -常见操作指南
服务管理 -完整的服务管理指南

🏗️ 架构和API

架构文档 -全面的系统架构
API文档 -所有MCP服务器的完整API参考资料

🔗 集成指南

集成指南 -连接到Cursor、Windsurf、NVIDIA游乐场

📖 功能指南

🧪 测试指南

Web UI测试指南

🔒 生产部署

安全考虑

在反向代理（nginx、Apache）后面运行Web UI
使用HTTPS进行生产部署
通过身份验证限制访问
审查和限制MCP工具权限

性能调整

调整 max_files_to_check 对于大型文件系统（默认值：500）
使用特定 share_path 限制搜索范围的参数
监控日志文件以发现性能问题

📞 支持

有关支持和问题：

在中创建问题 GitHub存储库
查看文档 docs/ 文件夹
查看上面的故障排除部分

🎉 最新动态

🆕 2025年10月23日-高级服务管理+多格式支持

✅ 新：统一服务管理脚本(start_all_services.sh)适用于所有MCP服务
✅ 新：屏幕会话持久性-服务在SSH断开连接后仍然存在
✅ 新：崩溃服务的自动重启功能
✅ 新：系统集成，启动时自动启动
✅ 新：多格式文件支持（BMP、DOCX、HTML、JPEG、JSON、MD、PDF、PNG、PPTX、SH、TIFF、TXT、MP3）
✅ 新：基于标记的层管理，具有自动的tier0升级/降级功能
✅ 新：递归文件夹标记，性能提高40倍
✅ 新：增强的事件过滤和监控UI
✅ 新：全面的健康监测和港口冲突解决
✅ 固定的：日志和CLI输出中的Unicode处理
✅ 固定的：NFS重试机制的定时问题
✅ 固定的：使用回退方法的Hammerspace CLI标签操作
✅ 固定的：单个文件与文件夹级标记优化

🆕 2025年10月16日-自动文件摄取+Kubernetes+MCP

✅ 新：与Kubernetes集成的完整自动文件摄取系统
✅ 新：NFS 4.2挂载的基于轮询的文件监控（不支持inotify）
✅ 新：基于文件夹的批处理-新文件夹触发集合创建
✅ 新：用于PDF嵌入的Milvus矢量数据库集成
✅ 新：使用ConfigMaps进行Kubernetes作业部署以进行文件处理
✅ 新：智能集合命名（基于文件夹和顺序）
✅ 新：实时事件流和监控仪表板
✅ 新：用于连续操作的独立文件监视器守护进程
✅ 固定的：仅轮询方法的NFS兼容性问题
✅ 固定的：Kubernetes PVC集成和路径映射
✅ 固定的：Milvus集合命名约定（下划线与连字符）
✅ 固定的：容器环境中的文件路径处理
✅ 固定的：作业完成跟踪和错误处理
✅ 固定的：追溯标记时间窗口配置
✅ 固定的：线程和异步操作协调

2025年10月9日-文件摄入事件系统和监控UI

✅ 新：通过代理事件消费 get_file_ingest_events MCP工具
✅ 新：实时监控仪表板位于 /monitor 通过实时事件流媒体
✅ 新：用于事件查询和监视的API终结点
✅ 固定的：重复文件处理-文件现在只标记一次
✅ 固定的：内存跟踪可防止重复标记相同的文件
✅ 重复数据删除验证工具： check_duplicates.sh 和 find-dup.sh
✅ 完整事件元数据：时间戳、文件路径、MD5哈希、MIME类型、文件大小
✅ 事件过滤：按类型、文件模式或时间戳
✅ Toast新文件到达通知
✅ 带有MD5/MIME标记的自动文件监控服务

以前的更新

✅ 添加了对过时文件句柄错误的自动装载刷新
✅ 日志中已抑制的Anthropic API弃用警告
✅ 在所有聊天消息中添加了复制按钮
✅ 修复了部分对齐状态检测
✅ 基于Web的自然语言控制台与Claude AI

MCP 1.5 -具有自然语言界面和自动文件摄取的生产就绪Hammerspace存储管理。

使用说明

MCP 1.5-带人工智能的高级Hammerspace存储管理

🚀 快速开始

先决条件

安装

📋 特性

🤖 自然语言接口

📁 高级文件摄取系统

📊 综合监控UI

🔧 持久服务管理

API终点

核心MCP工具

高级功能

🆕 高级文件摄取工作流

运作原理

文件夹处理

配置

Kubernetes集成

🎯 用法

示例命令（Web UI）

🆕 文件摄取命令

直接使用MCP服务器

可用的MCP工具

标签管理

层级管理

文件摄入

系统工具

文件监控和摄入

🔧 建筑

组件

数据流

🆕 文件摄取数据流

🧪 测试

Web UI测试

单指令测试

🆕 文件摄入测试

🛠️ 服务管理

统一服务管理

个性化服务管理

服务URL

查看日志

🐛 故障排除

过时的文件句柄错误

标签操作不起作用

🆕 文件摄入问题

常见标签格式

📚 文档

🚀 快速开始

🏗️ 架构和API

🔗 集成指南

📖 功能指南

🧪 测试指南

🔒 生产部署

安全考虑

性能调整

📞 支持

🎉 最新动态

🆕 2025年10月23日-高级服务管理+多格式支持

🆕 2025年10月16日-自动文件摄取+Kubernetes+MCP

2025年10月9日-文件摄入事件系统和监控UI

以前的更新

相关 MCP

Flomo笔记服务

3D资产生成服务

文档搜索服务

Microsoft 365命令行管理服务器

AI文本人性化服务

APISIX MCP服务器