Hudu

hudu-mcp

适用于 Hudu IT 文档平台的 MCP（Model Context Protocol）服务。提供 39 个工具和 6 个资源，可通过任何兼容 MCP 的客户端管理公司、资产、文章、密码、网站等。

功能

• 39 个 MCP 工具，覆盖 Hudu 的所有主要资源
• 6 个 MCP 资源，用于直接访问数据
• 双重身份验证模式：经典的 HUDU_API_KEY REST 访问，或 oauth——通过经过身份验证的轻量代理，连接到新版 Hudu 实例自带的原生 MCP 服务
• 支持双重传输方式：stdio（默认）和 HTTP Streamable
• 延迟初始化——首次调用工具时创建 SDK 客户端
• 内置连接测试
• 所有日志均写入 stderr，避免污染 MCP stdio 传输

一键部署

重要

**开始前请注意：**此服务依赖 @wyre-technology/node-hudu，该包托管在 GitHub Packages npm 注册表中。GitHub Packages 不支持匿名访问——即使该包是公开的，每次执行 npm install 也都需要令牌。云端构建器会代你运行 npm install，因此必须向其提供令牌，否则构建将失败，并显示 npm error 401 Unauthorized ... npm.pkg.github.com。

1. 创建具有 read:packages 权限范围的 GitHub Personal Access Token（classic token）。任何 GitHub 帐户都可以——读取其公开包不需要加入 wyre-technology 组织。
2. 部署流程提示时，将其添加为构建变量：
   • DigitalOcean App Platform → 将一个名为 NODE_AUTH_TOKEN 的加密环境变量设为你的 PAT，范围选择 Build Time（Dockerfile 会通过 ARG NODE_AUTH_TOKEN 读取它，以验证 npm ci）。
   • Cloudflare Workers → 将一个名为 NODE_AUTH_TOKEN 的构建变量设为你的 PAT（Workers → Settings → Build → Variables and Secrets）。

说明

DigitalOcean 目标会构建完整的 Docker 镜像，并通过 HTTP 运行完整的 MCP 服务——这是面向运维人员的推荐方式。此仓库未提供 wrangler.json/Workers 入口点，因此对于可自托管的服务，建议使用 DigitalOcean 或预构建的容器镜像（ghcr.io/wyre-ai/hudu-mcp）。

安装

此项目依赖于发布在 GitHub Packages npm 注册表中的 @wyre-technology/node-hudu，即使该包是公开的，也需要令牌。 安装前请先对 npm 进行一次身份验证：

git clone https://github.com/WYRE-AI/hudu-mcp.git
cd hudu-mcp

# Authenticate npm to GitHub Packages (token needs the read:packages scope)
export NODE_AUTH_TOKEN=$(gh auth token)   # or a PAT with read:packages

npm install
npm run build

仓库的 .npmrc 已将 @wyre-technology 范围指向 GitHub Packages，并从 NODE_AUTH_TOKEN 读取令牌，因此无需其他配置。

配置

变量	必填	默认值	描述
HUDU_BASE_URL	是	-	Hudu 实例 URL（例如，https://docs.example.com）
HUDU_API_KEY	否	-	Hudu API 密钥。设置此项会选择 api_key 身份验证模式（见下文）；省略此项则默认使用 oauth 模式。
HUDU_AUTH_MODE	否	自动检测	显式强制使用 api_key 或 oauth。优先级高于下方的自动检测。
MCP_TRANSPORT	否	stdio	传输类型：stdio 或 http
AUTH_MODE	否	env	env 从环境中读取 HUDU_*。gateway 要求每个 /mcp 请求都包含 X-Hudu-Base-URL 和 X-Hudu-API-Key，且不会回退到这些变量。
CONDUIT_S2S_SECRET	HTTP 必填	-	服务间密钥。若此项为空或为已知占位值（changeme、secret、replace-me、your-s2s-secret 及其他示例值），HTTP 会记录错误并以非零状态码退出。使用 openssl rand -hex 32 生成。切勿提交真实值。此值绝不会被记录。
MCP_ALLOW_INSECURE_DEV	否	-	仅在本地开发时，准确设置为 1，即可在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会强制要求 X-Gateway-S2S，且只绑定到 127.0.0.1。非环回地址的 MCP_HTTP_HOST 会被忽略，并记录此覆盖行为。若设置了已知占位密钥，仍会拒绝启动。
MCP_HTTP_PORT	否	8080	HTTP 服务端口（使用 http 传输时）
MCP_HTTP_HOST	否	127.0.0.1	设置了真实 CONDUIT_S2S_SECRET 时的绑定地址。容器镜像会设置为 0.0.0.0。若没有真实密钥，监听器会强制绑定到 127.0.0.1。
MCP_SERVER_NAME	否	hudu-mcp	向 MCP 客户端报告的服务名称
MCP_SERVER_VERSION	否	1.0.0	向 MCP 客户端报告的服务版本
LOG_LEVEL	否	info	日志级别：error、warn、info、debug
LOG_FORMAT	否	simple	日志格式：json 或 simple

认证模式

此服务通过以下两种方式之一与 Hudu 通信。HUDU_AUTH_MODE 用于选择模式；如果未设置，则会根据是否设置了 HUDU_API_KEY 自动检测：

• api_key（设置了 HUDU_API_KEY 时自动选择）——经典模式。此服务通过 @wyre-technology/node-hudu 直接调用 Hudu 的 REST API，并自行实现全部 39 个工具，与此前完全相同。所有现有部署都已使用此模式，以下所有内容都不会对其产生任何影响。

• oauth（未设置 HUDU_API_KEY 时自动选择）——适用于启用了原生 MCP 服务的较新 Hudu 实例（Hudu Admin -> External Apps -> MCP），该服务通过交互式 OAuth 而非静态 API 密钥进行保护。在此模式下，hudu-mcp 不会重新实现任何工具，而是充当轻量级的认证代理，将 MCP 请求直接转发到 {HUDU_BASE_URL}/mcp，并将响应转回，因此你会自动获得该 Hudu 实例所提供的全部工具。

  OAuth 流程（RFC 9728/8414 发现、RFC 7591 动态客户端注册、PKCE authorization_code，不使用客户端密钥——这是一个公共客户端）会在首次需要令牌的请求中运行：

  1. hudu-mcp 从 {HUDU_BASE_URL}/.well-known/oauth-protected-resource/mcp 和 {HUDU_BASE_URL}/.well-known/oauth-authorization-server 发现实例的 OAuth 元数据。
  2. 它通过动态客户端注册将自身注册为公共 OAuth 客户端（每个 Hudu 实例只注册一次——已签发的 client_id 会被缓存）。
  3. 它会将授权 URL 输出到 stderr。在浏览器中打开该 URL 并批准访问。
  4. 本地短时服务器会在 http://127.0.0.1:<ephemeral-port>/callback 接收重定向，并使用授权码换取令牌。
  5. 令牌会缓存在 ~/.hudu-mcp/credentials-<hash-of-base-url>.json 中（文件模式为 0600），之后运行时会自动刷新——只有在刷新令牌本身过期或被撤销时，你才会再次看到浏览器授权提示。

  由于此流程需要一个能够访问绑定到运行 hudu-mcp 的计算机上 127.0.0.1 的回调服务器的浏览器，因此它适用于 stdio（始终在调用 MCP 客户端的本地运行），以及运行在你浏览网页的同一台计算机上的可自托管 http 传输——例如在 localhost:8080 上进行本地测试。它不适用于部署在你无法通过浏览器访问的远程主机上的 http 传输（例如云 VM、容器等）：浏览器无法访问该计算机自身的环回接口来完成重定向，因此首次授权会一直挂起。这与网关模式（AUTH_MODE=gateway）无关；网关模式是无状态的多租户代理，通过请求头注入凭据，并不存在可以运行浏览器流程的单个用户——同时设置 HUDU_AUTH_MODE=oauth 和 AUTH_MODE=gateway 会导致启动错误。

  HTTP 传输（api_key 和 oauth 模式）还需要 CONDUIT_S2S_SECRET 或 MCP_ALLOW_INSECURE_DEV=1。开发标志只会绑定到 127.0.0.1。请参阅HTTP 认证。stdio 传输不使用 CONDUIT_S2S_SECRET。

用法

Claude Desktop（stdio）

将以下内容添加到你的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "hudu": {
      "command": "node",
      "args": ["/path/to/hudu-mcp/dist/entry.js"],
      "env": {
        "HUDU_BASE_URL": "https://docs.example.com",
        "HUDU_API_KEY": "your-api-key"
      }
    }
  }
}

对于启用了原生 MCP 服务的较新 Hudu 实例（参见认证模式），请省略 HUDU_API_KEY，只设置 HUDU_BASE_URL——首次启动 hudu-mcp 时，它会在终端中输出授权 URL：

{
  "mcpServers": {
    "hudu": {
      "command": "node",
      "args": ["/path/to/hudu-mcp/dist/entry.js"],
      "env": {
        "HUDU_BASE_URL": "https://docs.example.com"
      }
    }
  }
}

HTTP 传输

/health 无需认证，且不会读取凭据。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
HUDU_BASE_URL=https://docs.example.com \
HUDU_API_KEY=your-api-key \
MCP_TRANSPORT=http \
MCP_HTTP_PORT=8080 \
npm start

不使用服务间密钥的本地 HTTP 仅供开发使用。它会绑定到 127.0.0.1 并记录一条警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

HTTP 身份验证

使用 MCP_TRANSPORT=http 且配置了真实的 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含 X-Gateway-S2S。验证逻辑位于 src/mcp/s2s-verify.ts 中的 verifyS2sHeader：请求头的值为 t=<unix seconds>,v1=<hex>，其中十六进制值是以 CONDUIT_S2S_SECRET 为密钥、对字面字符串 t=<unix seconds> 计算的 HMAC-SHA256（64 个小写十六进制字符）。时间戳必须与服务器时钟相差不超过 300 秒。缺少或无效的请求头会导致 HTTP 401，且在此之前不会读取 Hudu 凭据。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-Hudu-Base-URL: $HUDU_BASE_URL" \
  -H "X-Hudu-API-Key: $HUDU_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

在 AUTH_MODE=gateway 模式下，/mcp 还需要 X-Hudu-Base-URL 和 X-Hudu-API-Key。这些请求头是该请求唯一的凭据来源。缺少请求头会导致 HTTP 401，且不会回退使用环境中的 HUDU_BASE_URL 或 HUDU_API_KEY。

未设置 CONDUIT_S2S_SECRET 时，Compose 会拒绝启动。gateway 服务会设置 AUTH_MODE=gateway，不会注入 HUDU_BASE_URL 或 HUDU_API_KEY，并会发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET=your-s2s-secret docker compose up

镜像会在容器内监听 0.0.0.0，且没有真实密钥时仍会拒绝启动。请将端口发布到回环地址：

docker run \
  -e CONDUIT_S2S_SECRET=your-s2s-secret \
  -e AUTH_MODE=gateway \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/hudu-mcp

工具（39）

Companies（8 个工具）

工具	说明
hudu_list_companies	列出公司，可选筛选条件
hudu_get_company	按 ID 获取公司
hudu_create_company	创建新公司
hudu_update_company	更新现有公司
hudu_delete_company	删除公司
hudu_archive_company	归档公司
hudu_unarchive_company	取消归档公司
hudu_test_connection	测试与 Hudu API 的连接

Assets（6 个工具）

工具	说明
hudu_list_assets	列出资产，可选筛选条件
hudu_get_asset	按 ID 获取资产
hudu_create_asset	创建新资产
hudu_update_asset	更新现有资产
hudu_delete_asset	删除资产
hudu_archive_asset	归档资产

Asset Layouts（4 个工具）

工具	说明
hudu_list_asset_layouts	列出资产布局
hudu_get_asset_layout	按 ID 获取资产布局
hudu_create_asset_layout	创建新资产布局
hudu_update_asset_layout	更新现有资产布局

Asset Passwords（5 个工具）

工具	说明
hudu_list_asset_passwords	列出资产密码
hudu_get_asset_password	按 ID 获取资产密码
hudu_create_asset_password	创建新资产密码
hudu_update_asset_password	更新现有资产密码
hudu_delete_asset_password	删除资产密码

Articles（6 个工具）

工具	说明
hudu_list_articles	列出知识库文章
hudu_get_article	按 ID 获取文章
hudu_create_article	创建新文章
hudu_update_article	更新现有文章
hudu_delete_article	删除文章
hudu_archive_article	归档文章

Websites（5 个工具）

工具	说明
hudu_list_websites	列出受监控的网站
hudu_get_website	按 ID 获取网站
hudu_create_website	创建新网站
hudu_update_website	更新现有网站
hudu_delete_website	删除网站

Other Resources（5 个工具）

工具	说明
hudu_list_folders	列出文件夹
hudu_list_procedures	列出流程
hudu_list_activity_logs	列出活动日志
hudu_list_relations	列出关联
hudu_list_magic_dash	列出 Magic Dash 项目

资源

URI	说明
hudu://companies	所有公司的列表
hudu://companies/{id}	按 ID 获取公司详情
hudu://assets	所有资产的列表
hudu://assets/{id}	按 ID 获取资产详情
hudu://articles	所有文章的列表
hudu://articles/{id}	按 ID 获取文章详情

开发

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Clean build output
npm run clean

许可证

Apache-2.0