Dataproc MCP Server

Dataproc MCP 服务

面向 Google Cloud Dataproc 操作的生产就绪型模型上下文协议（MCP）服务，具备智能参数注入、企业级安全性和全面的工具集。专为与 Roo（VS Code） 无缝集成而设计。

🚀 快速开始

推荐：Roo（VS Code）集成

将以下内容添加到 Roo MCP 设置中：

{
  "mcpServers": {
    "dataproc": {
      "command": "npx",
      "args": ["@dipseth/dataproc-mcp-server@latest"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

使用自定义配置文件

{
  "mcpServers": {
    "dataproc": {
      "command": "npx",
      "args": ["@dipseth/dataproc-mcp-server@latest"],
      "env": {
        "LOG_LEVEL": "info",
        "DATAPROC_CONFIG_PATH": "/path/to/your/config.json"
      }
    }
  }
}

替代方案：全局安装

# Install globally
npm install -g @dipseth/dataproc-mcp-server

# Start the server
dataproc-mcp-server

# Or run directly
npx @dipseth/dataproc-mcp-server@latest

5 分钟快速设置

1. 安装软件包：

   npm install -g @dipseth/dataproc-mcp-server@latest
   

2. 运行设置：

   dataproc-mcp --setup
   

3. 配置身份验证：

   # Edit the generated config file
   nano config/server.json
   

4. 启动服务：

   dataproc-mcp
   

🌐 Claude.ai Web 应用兼容性

✅ 生产就绪：通过 HTTPS 隧道和 OAuth 实现与 Claude.ai 的完整集成

Dataproc MCP 服务现在提供完整的 Claude.ai Web 应用兼容性，包含可正常使用的解决方案，并提供全部 22 个 MCP 工具！

🚀 可用解决方案（已测试并验证）

终端 1 - 启动 MCP 服务：

DATAPROC_CONFIG_PATH=config/github-oauth-server.json npm start -- --http --oauth --port 8080

终端 2 - 启动 Cloudflare 隧道：

cloudflared tunnel --url https://localhost:8443 --origin-server-name localhost --no-tls-verify

结果：Claude.ai 可以成功查看并使用所有工具！🎉

主要功能：

• ✅ 完整的工具访问权限 - Claude.ai 中提供全部 22 个 MCP 工具
• ✅ HTTPS 隧道 - 使用 Cloudflare 隧道实现安全的外部访问
• ✅ OAuth 身份验证 - 使用 GitHub OAuth 进行安全身份验证
• ✅ 可信证书 - 不会出现浏览器警告或连接问题
• ✅ WebSocket 支持 - 完全兼容 Claude.ai 的 WebSocket
• ✅ 生产就绪 - 经过测试和验证的可用解决方案

快速设置：

1. 设置 GitHub OAuth（5 分钟）
2. 生成 SSL 证书：npm run ssl:generate
3. 启动服务（按上述说明使用 2 个终端）
4. 将 Claude.ai 连接到你的隧道 URL

📖 完整指南： 有关详细设置说明、故障排除和高级功能，请参阅 docs/claude-ai-integration.md。

📖 证书设置： 有关 SSL 证书配置，请参阅 docs/trusted-certificates.md。

✨ 功能

🎯 核心功能

• 22 个生产就绪的 MCP 工具 - 完整的 Dataproc 管理套件
• 🧠 知识库语义搜索 - 支持自然语言查询，可选集成 Qdrant
• 🚀 响应优化 - 使用 Qdrant 存储可减少 60-96% 的 token
• 🔄 通用类型转换系统 - 自动执行类型安全的数据转换
• 减少 60-80% 的参数 - 智能注入默认值
• 多环境支持 - 开发/预发布/生产环境配置
• 服务账号模拟 - 企业级身份验证
• 实时作业监控 - 全面的状态跟踪

🚀 响应优化

• 减少 96.2% 的 token - list_clusters：7,651 → 292 个 token
• 自动存储到 Qdrant - 完整保留数据并支持搜索
• 资源 URI 访问 - dataproc://responses/clusters/list/abc123
• 平滑回退 - 无需 Qdrant 也可运行，并回退到完整响应
• 9.95 毫秒处理时间 - 优化速度极快，内存使用量低于 1 MB

🔄 通用类型转换系统

• 减少 75% 的代码 - 消除各服务中的手动转换逻辑
• 类型安全的转换 - 自动检测和映射字段
• 智能压缩 - 支持配置阈值的字段级压缩
• 0.50 毫秒转换时间 - 处理速度极快，压缩率达 100%
• 零配置 - 自动适配现有 TypeScript 类型
• 向后兼容 - 与现有功能无缝集成

� 企业级安全

• 输入验证 - 为全部 16 个工具提供 Zod 模式
• 速率限制 - 可配置的滥用防护
• 凭据管理 - 安全处理和轮换凭据
• 审计日志 - 全面跟踪安全事件
• 威胁检测 - 防止注入攻击

📊 质量保障

• 测试覆盖率达 90% 以上 - 全面的测试套件
• 性能监控 - 可配置的阈值
• 多环境测试 - 跨平台验证
• 自动化质量门禁 - 集成 CI/CD
• 安全扫描 - 漏洞管理

🚀 开发者体验

• 5 分钟完成设置 - 快速入门指南
• 交互式文档 - 含示例的 HTML 文档
• 丰富的示例 - 多环境配置
• 故障排除指南 - 常见问题及解决方案
• IDE 集成 - 支持 TypeScript

🛠️ 完整的 MCP 工具套件（22 个工具）

🔄 通用类型转换增强：所有工具现在都支持自动、类型安全的数据转换，并具备智能压缩和字段映射功能。

🚀 集群管理（8 个工具）

工具	描述	智能默认值	主要功能
start_dataproc_cluster	创建并启动新集群	✅ 参数减少 80%	基于配置档案，自动配置
create_cluster_from_yaml	根据 YAML 配置创建	✅ 注入项目/区域	模板驱动的设置
create_cluster_from_profile	使用预定义配置档案创建	✅ 参数减少 85%	内置 8 个配置档案
list_clusters	列出所有集群并进行筛选	✅ 无需参数	语义查询、分页
list_tracked_clusters	列出由 MCP 创建的集群	✅ 按配置档案筛选	跟踪创建记录
get_cluster	获取集群详细信息	✅ 参数减少 75%	语义数据提取
delete_cluster	删除现有集群	✅ 项目/区域默认值	安全删除
get_zeppelin_url	获取 Zeppelin 笔记本 URL	✅ 自动发现	Web 界面访问

💼 作业管理（7 个工具）

工具	描述	智能默认值	主要功能
submit_hive_query	向集群提交 Hive 查询	✅ 参数减少 70%	支持异步、超时
submit_dataproc_job	提交 Spark/PySpark/Presto 作业	✅ 参数减少 75%	支持多种引擎、本地文件暂存
cancel_dataproc_job	取消正在运行或等待中的作业	✅ 只需 JobID	紧急取消、成本控制
get_job_status	获取作业执行状态	✅ 只需 JobID	实时监控
get_job_results	获取作业输出和结果	✅ 自动分页	结果格式化
get_query_status	获取 Hive 查询状态	✅ 最少参数	查询跟踪
get_query_results	获取 Hive 查询结果	✅ 智能分页	增强的异步支持

📋 配置与配置文件（3 个工具）

工具	描述	智能默认值	主要功能
list_profiles	列出可用的集群配置文件	✅ 按类别筛选	8 个生产环境配置文件
get_profile	获取详细的配置文件配置	✅ 只需配置文件 ID	访问模板
query_cluster_data	查询存储的集群数据	✅ 自然语言	语义搜索

📊 分析与洞察（4 个工具）

工具	描述	智能默认值	主要功能
check_active_jobs	快速查看所有活动作业的状态	✅ 无需参数	多项目视图
get_cluster_insights	全面的集群分析	✅ 自动发现	机器类型、组件
get_job_analytics	作业性能分析	✅ 成功率	错误模式、指标
query_knowledge	查询全面的知识库	✅ 自然语言	集群、作业、错误

🎯 主要功能

• 🧠 语义搜索：通过 Qdrant 集成支持自然语言查询
• ⚡ 智能默认值：通过智能注入减少 60-80% 的参数
• 📊 响应优化：在完整保留数据的同时减少 96% 的令牌用量
• 🔄 异步支持：非阻塞式作业提交与监控
• 🏷️ 配置文件系统：8 个适用于生产环境的集群模板
• 📈 分析：全面的洞察与性能跟踪

📋 配置

基于项目的配置

服务支持基于项目的配置格式：

# profiles/@analytics-workloads.yaml
my-company-analytics-prod-1234:
  region: us-central1
  tags:
    - DataProc
    - analytics
    - production
  labels:
    service: analytics-service
    owner: data-team
    environment: production
  cluster_config:
    # ... cluster configuration

身份验证方式

1. 服务账号模拟（推荐）
2. 直接使用服务账号密钥
3. 应用默认凭据
4. 带回退机制的混合身份验证

📚 文档

• 快速入门指南 - 5 分钟内开始使用
• 知识库语义搜索 - 自然语言查询与设置
• 通用类型转换系统 - 架构设计与实现
• 通用转换器迁移指南 - 从手动转换迁移
• API 参考 - 完整的工具文档
• 配置示例 - 实际配置示例
• 安全指南 - 最佳实践与合规性
• 安装指南 - 详细的设置说明

🔧 MCP 客户端集成

Claude Desktop

{
  "mcpServers": {
    "dataproc": {
      "command": "npx",
      "args": ["@dataproc/mcp-server"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Roo（VS Code）

{
  "mcpServers": {
    "dataproc-server": {
      "command": "npx",
      "args": ["@dataproc/mcp-server"],
      "disabled": false,
      "alwaysAllow": [
        "list_clusters",
        "get_cluster",
        "list_profiles"
      ]
    }
  }
}

🏗️ 架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │────│  Dataproc MCP    │────│  Google Cloud   │
│  (Claude/Roo)   │    │     Server       │    │    Dataproc     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                       ┌──────┴──────┐
                       │   Features  │
                       ├─────────────┤
                       │ • Security  │
                       │ • Profiles  │
                       │ • Validation│
                       │ • Monitoring│
                       │ • Generic    │
                       │   Converter  │
                       └─────────────┘

🔄 通用类型转换系统架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Source Types   │────│ Generic Converter │────│ Qdrant Payloads │
│ • ClusterData   │    │    System        │    │ • Compressed    │
│ • QueryResults  │    │                  │    │ • Type-Safe     │
│ • JobData       │    │ ┌──────────────┐ │    │ • Optimized     │
└─────────────────┘    │ │Field Analyzer│ │    └─────────────────┘
                       │ │Transformation│ │
                       │ │Engine        │ │
                       │ │Compression   │ │
                       │ │Service       │ │
                       │ └──────────────┘ │
                       └──────────────────┘

🚦 性能

响应时间成果

• 架构验证：约 2ms（目标：<5ms）✅
• 参数注入：约 1ms（目标：<2ms）✅
• 泛型类型转换：约 0.50ms（目标：<2ms）✅
• 凭证验证：约 25ms（目标：<50ms）✅
• MCP 工具调用：约 50ms（目标：<100ms）✅

吞吐量成果

• 架构验证：约 2000 ops/sec ✅
• 参数注入：约 5000 ops/sec ✅
• 泛型类型转换：约 2000 ops/sec ✅
• 凭证验证：约 200 ops/sec ✅
• MCP 工具调用：约 100 ops/sec ✅

压缩成果

• 字段级压缩：压缩率最高可达 100% ✅
• 内存优化：内存使用量减少 30-60% ✅
• 类型安全：通过自动验证实现运行时类型错误零发生 ✅

🧪 测试

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:performance

# Run with coverage
npm run test:coverage

🤝 参与贡献

欢迎贡献！详情请参阅我们的贡献指南。

开发环境设置

# Clone the repository
git clone https://github.com/dipseth/dataproc-mcp.git
cd dataproc-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Start development server
npm run dev

📄 许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

🆘 支持

• GitHub Issues：报告错误并提出功能请求
• 文档：完整文档
• NPM 软件包：软件包信息

🏆 致谢

• Model Context Protocol - 让这一切成为可能的协议
• Google Cloud Dataproc - 我们集成的服务
• Qdrant - 为我们的语义搜索和知识索引提供支持的高性能向量数据库
• TypeScript - 为类型安全和开发者体验提供支持

---

为 MCP 和 Google Cloud 社区倾情打造 ❤️