Hue MCP服务器

一个MCP（模型上下文协议）服务器，它公开 HueClientRest 功能，允许AI助手与Hadoop Hue交互，以执行SQL查询和管理HDFS文件。

这是什么？

此服务器使AI助手（如GitHub Copilot、Claude Desktop或其他MCP兼容客户端）能够：

使用Hive、SparkSQL或Impala在Hadoop Hue上执行SQL查询
管理HDFS文件（列表、上传、下载）
将查询结果导出到CSV文件
浏览和管理目录结构

模型上下文协议（MCP）是一个开放标准，用于将人工智能助手连接到外部工具和数据源，使其更强大、更具上下文感知能力。

特性

SQL查询执行：使用Hive、SparkSQL或Impala方言执行查询
结果导出：将查询结果保存到CSV文件，并在大型数据集上自动重试
HDFS运营：从HDFS中列出、上传和下载文件
目录管理：检查目录是否存在并浏览文件结构
稳健的错误处理：内置重试机制和详细的错误报告

先决条件

在安装此MCP服务器之前，您需要：

Python 3.10或更高版本 - 下载Python
星光紫外线 -快速Python包安装程序和环境管理器
Visual Studio Code -用于MCP与GitHub Copilot的集成
GitHub Copilot订阅 -VS Code MCP集成所需
访问Hadoop Hue服务器 -您需要主机URL、用户名和密码

依赖项

此项目使用以下关键依赖项：

星光紫外线 -一个非常快的Python包和项目管理器，用Rust编写。它比pip快10-100倍，处理依赖关系解析也要好得多。
[mcp\[cli\]](https://github.com/modelcontextprotocol/python-sdk) -用于模型上下文协议的官方Python SDK，包括CLI工具
hueclientrest -用于与Hadoop Hue REST API交互的Python客户端库
皮丹提克 -使用Python类型注释进行数据验证

安装

第一步：安装Astral uv

uv是一个现代、快速的Python包管理器，用于依赖关系管理。

在Windows（PowerShell）上：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

在macOS/Linux上：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装后，重新启动终端或按照安装程序的指示将uv添加到PATH中。

验证安装：

uv --version

步骤2：克隆并安装项目

# Clone the repository
git clone 
cd hueclientrest-mpc

# Install dependencies and create virtual environment
uv sync

这 uv sync 命令将：

创建虚拟环境(.venv)
从安装所有依赖项 pyproject.toml
建立开发项目

替代方案：使用pip

如果你更喜欢pip而不是uv：

pip install -e .

但是，强烈建议使用uv以获得更好的性能和依赖关系管理。

配置

环境变量

服务器需要以下环境变量才能连接到Hue服务器：

变量	必填	描述
`HUE_HOST`	是	色调服务器URL（例如。， `https://hue.example.com`)
`HUE_USERNAME`	是	Hue身份验证的用户名
`HUE_PASSWORD`	是	Hue身份验证密码
`HUE_VERIFY_SSL`	否	验证SSL证书（默认值： `true`)
`HUE_SSL_WARNINGS`	否	显示SSL警告（默认值： `false`)

设置环境变量

选项1：使用.env文件（建议用于本地开发）

# Create a .env file in the project root
HUE_HOST=https://your-hue-server.com
HUE_USERNAME=your_username
HUE_PASSWORD=your_password
HUE_VERIFY_SSL=true
HUE_SSL_WARNINGS=false

选项2：系统环境变量

在Windows（PowerShell）上：

$env:HUE_HOST="https://your-hue-server.com"
$env:HUE_USERNAME="your_username"
$env:HUE_PASSWORD="your_password"

在macOS/Linux上：

export HUE_HOST="https://your-hue-server.com"
export HUE_USERNAME="your_username"
export HUE_PASSWORD="your_password"

VS代码与GitHub Copilot的集成

VS代码集成的先决条件

Visual Studio Code - 下载VS代码
GitHub Copilot扩展 -从VS代码市场安装
GitHub Copilot订阅 -需要MCP支持
此MCP服务器已安装并配置

步骤1：找到您的MCP配置文件

MCP配置文件的位置取决于您的操作系统：

视窗: %APPDATA%\Code\User\mcp.json

- 完整路径： C:\Users\\AppData\Roaming\Code\User\mcp.json

macOS: ~/Library/Application Support/Code/User/mcp.json
Linux: ~/.config/Code/User/mcp.json

如果文件不存在，请创建它。

步骤2：在VS代码中配置MCP服务器

将以下配置添加到您的 mcp.json 文件：

{
  "mcpServers": {
    "hue": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\Projects\\hueclientrest-mpc",
        "hue-mcp-server"
      ],
      "env": {
        "HUE_HOST": "https://your-hue-server.com",
        "HUE_USERNAME": "your_username",
        "HUE_PASSWORD": "your_password",
        "HUE_VERIFY_SSL": "true",
        "HUE_SSL_WARNINGS": "false"
      }
    }
  }
}

重要提示：

替换 C:\\Projects\\hueclientrest-mpc 与项目的实际路径
在Windows上，使用双反斜杠(\\)或正斜杠(/)在路径
将环境变量值替换为实际的色调凭据
这 command 是 uv 它将使用uv包管理器来运行服务器

步骤3：验证配置

重新启动VS代码 完全（关闭所有窗口）
打开GitHub Copilot聊天 （Ctrl+Shift+I或Cmd+Shift+I）
检查色调MCP工具：类型 @workspace 并寻找与色调相关的功能
测试连接：要求Copilot“列出HDFS目录/user中的文件”

步骤4：使用带有Copilot的MCP服务器

配置后，您可以要求GitHub Copilot与您的Hue服务器进行交互：

示例查询：

“执行Hive查询以显示表”
“列出HDFS目录/user/data中的文件”
“从HDFS下载文件/user/data/results.csv”
“执行此SQL查询并将结果保存到CSV：SELECT\*FROM my_table LIMIT 100”

VS代码集成故障排除

问题：MCP服务器未出现在副驾驶中

验证 mcp.json 路径正确
检查uv是否已安装并位于PATH中
完全重新启动VS代码
检查VS Code的输出面板（查看>输出），然后从下拉列表中选择“GitHub Copilot”

问题：身份验证错误

验证您的HUE_HOST、HUE_USERNAME和HUE_PASSWORD是否正确
直接测试与Hue服务器的连接
检查SSL验证是否导致问题（尝试将HUE_VERIFY_SSL设置为false进行测试）

问题：找不到命令

确保安装了uv：运行 uv --version 终端中
验证mcp.json中的项目路径是否正确，并使用正确的转义
确保你跑了 uv sync 在项目目录中

替代方案：使用绝对Python路径

如果uv不工作或不在你的PATH中，你可以使用Python解释器的绝对路径：

Windows示例：

{
  "mcpServers": {
    "hue": {
      "command": "C:\\Projects\\hueclientrest-mpc\\.venv\\Scripts\\python.exe",
      "args": ["-m", "hue_mcp_server.server"],
      "env": {
        "HUE_HOST": "https://your-hue-server.com",
        "HUE_USERNAME": "your_username",
        "HUE_PASSWORD": "your_password"
      }
    }
  }
}

macOS/Linux示例：

{
  "mcpServers": {
    "hue": {
      "command": "/full/path/to/hueclientrest-mpc/.venv/bin/python",
      "args": ["-m", "hue_mcp_server.server"],
      "env": {
        "HUE_HOST": "https://your-hue-server.com",
        "HUE_USERNAME": "your_username",
        "HUE_PASSWORD": "your_password"
      }
    }
  }
}

其他使用方法

Claude桌面集成

如果您使用的是Claude Desktop而不是VS Code，请将其添加到您的Claude配置中(~/.config/claude/claude_desktop_config.json 在Mac/Linux或 %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

{
  "mcpServers": {
    "hue": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/hueclientrest-mpc", "hue-mcp-server"],
      "env": {
        "HUE_HOST": "https://your-hue-server.com",
        "HUE_USERNAME": "your_username",
        "HUE_PASSWORD": "your_password"
      }
    }
  }
}

发展模式

使用MCP检查器交互式测试服务器：

uv run mcp dev src/hue_mcp_server/server.py

这将打开一个交互式界面，您可以在其中测试工具并实时查看请求/响应。

直接命令行执行

您也可以直接运行服务器：

# Using the installed script (after uv sync)
uv run hue-mcp-server

# Or via Python module
uv run python -m hue_mcp_server.server

可用工具

SQL查询工具

`hue_execute_query`

执行SQL查询并直接返回结果。

Arguments:
  - statement: SQL statement to execute
  - dialect: 'hive', 'sparksql', or 'impala' (default: 'hive')
  - timeout: Max wait time in seconds (default: 300)
  - batch_size: Rows per batch (default: 1000)

`hue_run_query_to_csv`

执行查询并将结果保存到CSV文件。

Arguments:
  - statement: SQL statement to execute
  - filename: Output CSV filename (default: 'results.csv')
  - dialect: SQL dialect (default: 'hive')
  - batch_size: Rows per batch (default: 1000)

`hue_export_and_download`

执行INSERT OVERWRITE DIRECTORY并下载结果文件。

Arguments:
  - statement: SQL with INSERT OVERWRITE DIRECTORY
  - hdfs_directory: HDFS output directory
  - local_directory: Local download directory (default: '.')
  - dialect: SQL dialect (default: 'hive')
  - file_pattern: Regex to filter files (optional)
  - timeout: Max wait time (default: 300)

HDFS文件工具

`hue_list_directory`

列出HDFS目录的内容。

Arguments:
  - directory_path: HDFS path (e.g., '/user/data')
  - page_size: Max items to return (default: 1000)

`hue_check_directory_exists`

检查HDFS目录是否存在。

Arguments:
  - directory_path: HDFS path to check

`hue_download_file`

从HDFS下载一个文件。

Arguments:
  - remote_path: Full HDFS file path
  - local_filename: Local filename (optional)

`hue_download_directory`

从HDFS目录下载所有文件。

Arguments:
  - directory_path: HDFS directory path
  - local_directory: Local directory (default: '.')
  - file_pattern: Regex to filter files (optional)

`hue_upload_file`

将本地文件上传到HDFS。

Arguments:
  - local_file_path: Path to local file
  - hdfs_destination: HDFS destination directory

运作原理

模型上下文协议（MCP）

MCP是一个开放协议，规范了人工智能助手与外部工具和数据源的通信方式。把它想象成一个通用适配器，让人工智能助手“插入”不同的服务。

关键部件：

MCP 服务器 （本项目）：展示工具和功能
MCP客户端 （VS Code/Claude Desktop）：使用工具并将其呈现给AI
协议：定义他们的沟通方式

架构流程

┌─────────────────┐        ┌──────────────────┐        ┌─────────────────┐
│   GitHub        │  MCP   │   Hue MCP        │  REST  │   Hadoop Hue    │
│   Copilot       │◄──────►│   Server         │◄──────►│   Server        │
│   (VS Code)     │Protocol│   (This Project) │  API   │                 │
└─────────────────┘        └──────────────────┘        └─────────────────┘
                                     │
                                     ▼
                           ┌──────────────────┐
                           │  HueClientRest   │
                           │  Library         │
                           └──────────────────┘

用户询问Copilot 查询色调数据
副驾驶识别 该请求需要Hue MCP工具
MCP服务器接收 请求并将其转换为Hue REST API调用
HueClientRest库 处理身份验证和API通信
结果反馈 通过链条到达用户

依赖关系详细信息

星光紫外（包装管理器）

它是什么： 用Rust编写的下一代Python包和项目管理器。

我们为什么使用它：

速度：比pip快10-100倍
更好的依赖关系解决方案：更可靠地处理复杂的依赖关系
统一工具：结合pip、pip工具、pipx、诗歌、pyenv功能
可复制环境：锁定文件确保安装一致
跨平台：在Windows、macOS和Linux上无缝工作

关键命令：

uv sync -安装/更新依赖项
`uv add

` -添加新的依赖项

uv run -在虚拟环境中运行命令
`uv pip install

` -如果需要，可以像pip一样使用

了解更多： https://docs.astral.sh/uv/

mcp\[cli\]（Python SDK）

它是什么： 用于构建MCP服务器的官方Python SDK。

主要特点：

FastMCP框架：使用装饰器简化服务器创建
类型验证：用于请求/响应验证的Pydantic集成
命令行工具: mcp dev 为了测试， mcp install 用于设置
异步支持：基于asyncio构建，实现高效I/O
SSE运输：服务器发送事件以进行实时通信

在本项目中：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Hue MCP Server")

@mcp.tool()
def hue_execute_query(statement: str, dialect: str = "hive"):
    """Execute SQL query on Hue"""
    # Implementation

hueclientrest（Hue客户端库）

它是什么： Hadoop Hue REST API的Python客户端。

能力：

SQL查询执行（Hive、SparkSQL、Impala）
HDFS文件操作
会话管理
身份验证处理
错误处理和重试

在本项目中：

from hueclientrest import HueClientREST

client = HueClientREST(host, username, password)
client.login()
result = client.execute_query(statement, dialect)

pydantic（数据验证）

它是什么： 使用Python类型提示的数据验证库。

我们为什么使用它：

类型安全性：在运行时验证工具输入/输出
自动文档：从类型提示生成架构
错误消息：清除调试的验证错误
JSON模式：MCP的自动模式生成

在本项目中：

from pydantic import BaseModel, Field

class QueryResult(BaseModel):
    rows: List[dict]
    columns: List[str]
    row_count: int

示例使用场景

场景1：执行Hive查询

在VS Code with Copilot中：

You: "Execute a Hive query to show the first 10 tables"
Copilot: [Uses hue_execute_query tool]
Result: Returns table list from your Hue server

已执行查询：

SELECT database_name, table_name 
FROM information_schema.tables 
LIMIT 10

场景2：列出HDFS文件

在VS Code with Copilot中：

You: "List all files in /user/hive/warehouse directory"
Copilot: [Uses hue_list_directory tool]
Result: Shows file names, sizes, and permissions

场景3：将数据导出到CSV

在VS Code with Copilot中：

You: "Query the sales table for 2024 and save to CSV"
Copilot: [Uses hue_run_query_to_csv tool]
Result: Creates sales_2024.csv with query results

已执行查询：

SELECT * FROM sales WHERE year = 2024

场景4：复杂数据管道

在VS Code with Copilot中：

You: "Check if /user/data/processed exists, if not list /user/data, 
     then download all CSV files from there"
Copilot: 
  1. [Uses hue_check_directory_exists]
  2. [Uses hue_list_directory]
  3. [Uses hue_download_directory with file_pattern=".*\.csv$"]
Result: Downloads all CSV files to local directory

发展

为发展而设立

# Clone and install
git clone 
cd hueclientrest-mpc
uv sync

# Install development dependencies
uv sync --dev

运行测试

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=hue_mcp_server

# Run specific test file
uv run pytest tests/test_server.py

添加新工具

要添加新的MCP工具：

在中定义工具功能 server.py:

@mcp.tool()
def hue_new_feature(param: str) -> dict:
    """Description of what this tool does."""
    client = get_client()
    result = client.some_operation(param)
    return {"status": "success", "data": result}

这 @mcp.tool() 自动装饰器：

- 在MCP服务器上注册该工具 - 根据类型提示生成JSON模式 - 使用Pydantic验证输入 - 处理错误和响应

测试您的工具：

uv run mcp dev src/hue_mcp_server/server.py

调试

启用详细日志记录：

import logging
logging.basicConfig(level=logging.DEBUG)

直接测试MCP服务器：

# Interactive testing
uv run mcp dev src/hue_mcp_server/server.py

# Check server can start
uv run python -m hue_mcp_server.server

VS代码调试：

检查输出面板：查看>输出>GitHub Copilot
查找MCP服务器连接消息
检查身份验证或网络错误

项目结构

hueclientrest-mpc/
├── .venv/                  # Virtual environment (created by uv)
├── pyproject.toml          # Project metadata and dependencies
├── README.md               # This comprehensive guide
├── .env.example            # Example environment variables
├── .gitignore              # Git ignore patterns
└── src/
    └── hue_mcp_server/
        ├── __init__.py     # Package initialization
        └── server.py       # MCP server implementation
            ├── Server setup and configuration
            ├── Tool definitions (@mcp.tool decorators)
            ├── Hue client wrapper functions
            └── Main entry point

依赖关系管理

查看已安装的软件包：

uv pip list

添加新的依赖关系：

uv add

更新依赖关系：

uv sync --upgrade

删除依赖关系：

uv remove

安全考虑

凭据管理

最佳实践：

从不提交凭据 到版本控制
使用环境变量 或安全保险库
旋转密码 定期地
使用.env文件 仅用于当地发展
使用机密管理 （Azure密钥库、AWS密钥管理器）投入生产

SSL/TLS配置

对于生产环境：

# Always verify SSL certificates
HUE_VERIFY_SSL=true
HUE_SSL_WARNINGS=false

对于开发/测试（自签名证书）：

# Only for development!
HUE_VERIFY_SSL=false
HUE_SSL_WARNINGS=false

网络安全

确保Hue服务器可从您的开发计算机访问
如果连接失败，请检查防火墙规则
如果您的组织需要，请使用VPN
确保身份验证令牌的安全

常见问题排查

问题：找不到uv命令

解决方案：

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Then restart terminal or add to PATH

问题：Python版本不匹配

错误： requires-python = ">=3.10" 但是你有Python 3.9

解决方案：

# Install Python 3.10+ from python.org
# Or use uv to manage Python versions
uv python install 3.11
uv venv --python 3.11

问题：MCP服务器未加载VS代码

检查表：

\[\]uv已安装并位于PATH中(uv --version)
\[\]已安装项目依赖项(uv sync)
\[\]mcp.json路径适合您的操作系统
\[\]mcp.json中的项目路径使用了正确的转义
\[\]VS代码完全重新启动（所有窗口均已关闭）
\[\]GitHub Copilot扩展已启用
\[\]主动Copilot订阅

问题：身份验证失败

错误： “身份验证失败”或“401未经授权”

解决方案：

验证凭据是否正确
检查Hue服务器URL是否可访问
直接在浏览器中测试登录
检查密码中的特殊字符（可能需要转义）
验证用户在Hue中是否具有必要的权限

问题：查询超时

错误： “查询执行超时”

解决方案：

# Increase timeout when calling tools
hue_execute_query(
    statement="SELECT * FROM large_table",
    timeout=600  # 10 minutes instead of default 5
)

问题：找不到HDFS文件

错误： “找不到文件或目录”

解决方案：

验证路径是否为绝对路径（以开头 /)
检查HDFS上的权限
使用 hue_list_directory 浏览可用路径
验证用户是否具有读/写权限

性能提示

查询优化

使用batch_size 对于大型结果集：

hue_execute_query(statement="...", batch_size=5000)

使用限制 在探索时的查询中：

SELECT * FROM large_table LIMIT 1000

导出大型数据集 直接到HDFS：

INSERT OVERWRITE DIRECTORY '/tmp/export'
SELECT * FROM large_table

然后使用 hue_export_and_download 检索文件。

HDFS运营

下载特定文件 有图案：

hue_download_directory(
    directory_path="/user/data",
    file_pattern=".*\\.csv$"  # Only CSV files
)

使用流媒体 用于大文件传输
批量上传 在可能的情况下

常见问题解答

Q：我可以在Claude Desktop上使用这个吗？

A. 对！有关配置详细信息，请参阅“Claude桌面集成”部分。

Q：这在Windows上有效吗？

A. 是的，在Windows、macOS和Linux上完全支持。

Q：支持哪些Hue版本？

A. 支持REST API的任何版本。已使用Hue 4.x及更高版本进行测试。

Q：多个用户可以共享一个MCP服务器吗？

A. 每个用户都应该使用自己的凭据运行自己的MCP服务器实例。

Q：如何更新到最新版本？

git pull
uv sync --upgrade

Q：我的密码安全吗？

A. 凭据存储在环境变量或mcp.json中。保护这些文件的安全，永远不要将其提交给版本控制。

资源

文档

社区

MCP Discord服务器

贡献

欢迎投稿！请随时提交问题或拉取请求。

开发设置

git clone 
cd hueclientrest-mpc
uv sync --dev

运行测试

uv run pytest
uv run pytest --cov=hue_mcp_server

代码的风格

本项目使用：

黑色用于代码格式化
isort用于导入排序
mypy用于类型检查

更新日志

v0.1.0（当前）

初始版本
SQL查询执行（Hive、SparkSQL、Impala）
HDFS文件操作
CSV导出功能
VS Code和Claude Desktop集成

许可证

MIT许可证-有关详细信息，请参阅许可证文件

学分

HueClientRest -Hue REST API的底层Python客户端
模型上下文协议 -AI工具集成的开放标准
星体 -uv包管理器的创建者
Anthropic -MCP规范和实施

支持

对于问题、疑问或功能请求：

检查故障排除部分
搜索现有的GitHub问题
创建包含详细信息的新问题

______________________________________________________________________

快乐查询！ 🚀

Hueclientrest Mpc

快速接入

详细介绍

Hue MCP服务器

这是什么？

特性

先决条件

依赖项

安装

第一步：安装Astral uv

步骤2：克隆并安装项目

替代方案：使用pip

配置

环境变量

设置环境变量

VS代码与GitHub Copilot的集成

VS代码集成的先决条件

步骤1：找到您的MCP配置文件

步骤2：在VS代码中配置MCP服务器

步骤3：验证配置

步骤4：使用带有Copilot的MCP服务器

VS代码集成故障排除

替代方案：使用绝对Python路径

其他使用方法

Claude桌面集成

发展模式

直接命令行执行

可用工具

SQL查询工具

hue_execute_query

hue_run_query_to_csv

hue_export_and_download

HDFS文件工具

hue_list_directory

hue_check_directory_exists

hue_download_file

hue_download_directory

hue_upload_file

运作原理

模型上下文协议（MCP）

架构流程

依赖关系详细信息

星光紫外（包装管理器）

mcp\[cli\]（Python SDK）

hueclientrest（Hue客户端库）

pydantic（数据验证）

示例使用场景

场景1：执行Hive查询

场景2：列出HDFS文件

场景3：将数据导出到CSV

场景4：复杂数据管道

发展

为发展而设立

运行测试

添加新工具

调试

项目结构

依赖关系管理

安全考虑

凭据管理

SSL/TLS配置

网络安全

常见问题排查

问题：找不到uv命令

问题：Python版本不匹配

问题：MCP服务器未加载VS代码

问题：身份验证失败

问题：查询超时

问题：找不到HDFS文件

性能提示

查询优化

HDFS运营

常见问题解答

Q： 我可以在Claude Desktop上使用这个吗？

Q： 这在Windows上有效吗？

Q： 支持哪些Hue版本？

Q： 多个用户可以共享一个MCP服务器吗？

Q： 如何更新到最新版本？

Q： 我的密码安全吗？

资源

`hue_execute_query`

`hue_run_query_to_csv`

`hue_export_and_download`

`hue_list_directory`

`hue_check_directory_exists`

`hue_download_file`

`hue_download_directory`

`hue_upload_file`

Q：我可以在Claude Desktop上使用这个吗？

Q：这在Windows上有效吗？

Q：支持哪些Hue版本？

Q：多个用户可以共享一个MCP服务器吗？

Q：如何更新到最新版本？

Q：我的密码安全吗？