AskMarcel HVAC Technical Knowledge

AskMarcel — HVAC 技术知识 MCP 服务

面向 AI Agent 的制造商来源 HVAC 技术文档：涵盖 126 个品牌和 905 个型号的搜索、诊断、错误代码、操作流程和产品资料。

AskMarcel 是一个远程托管的 MCP 服务（Streamable HTTP）。无需安装或自行托管——只需将 MCP 客户端指向端点并完成身份验证。该服务将 AI Agent 连接到真实的制造商文档，让回答引用准确的手册和页码，而不是凭空编造。

• 端点： https://mcp.askmarcel.app
• 注册表名称： io.github.askmarcel/mcphvac
• 清单： 1.3.1-beta.1 — 15 个工具已在生产环境上线
• 文档和 API 密钥： https://app.askmarcel.app/developers
• 参考文档： https://app.askmarcel.app/developers/reference
• Marcel Inside（B2B API / MCP）： https://askmarcel.app/fr/connecteurs
• 免费开发者套餐： 每月 250 次 API 调用

---

Marcel Inside — 集成到现有机器人中

将 AskMarcel 用作 Marcel Inside：将制造商来源的 HVAC 知识接入现有聊天机器人、语音机器人或 Agent，无需重建技术栈。兼容 ManyChat、ElevenLabs、Voiceflow、Intercom、Claude、ChatGPT、Gemini 和自定义 MCP 客户端。

• 销售与试点： https://askmarcel.app/fr/connecteurs（490€ 试点，Business 套餐每月 149€，不含税）
• 开发者沙盒： 免费套餐——每月 250 次调用，网址为 https://app.askmarcel.app/developers

---

为什么选择 AskMarcel

通用大模型会猜测 HVAC 专业信息——制冷剂充注量、错误代码含义、接线和故障树。AskMarcel 以经过索引的制造商 PDF 为依据生成每个回答，并返回来源页码，让现场技术人员或 Agent 能够信任并核实答案。请参阅 HVAC-Bench，了解相较于原始大模型输出的准确率测量结果。

• 126 个品牌 · 905 个型号 · 已索引超过 400,000 个错误代码
• 确定性的错误代码查询（不是猜测）
• 严格的 SKU 来源追踪（resolve_model、get_model_coverage、diagnose_v2）——不以系列型号替代
• 有来源依据的单次查询（diagnose），以及针对空气源热泵的多轮引导式故障排查（diagnose_guided）
• LIVE Beta Harness 会话——有状态的诊断循环，会话开始时查询制造商数据库（start_diagnostic … get_diagnostic_summary）
• 支持 FR / EN，专注于欧洲 HVAC/RACH 市场

Harness 会话与 diagnose_guided 的比较

场景	适用情况	配额
Harness 会话（start_diagnostic …）	对 PAC Air/Eau 或 PAC Air/Air 进行多轮现场诊断，包含假设、用于区分情况的 next_action 和技师日志	创建会话时扣除一次
diagnose_guided	仅适用于 PAC Air/Eau 的旧版引导循环——通过 continuation 封存状态	每轮扣除
diagnose_v2	一次性严格 SKU 查询	每次成功调用扣除
diagnose	不要求 SKU 的一次性查询	每次成功调用扣除

Harness Beta 已在生产环境中上线（DIAGNOSTIC_SESSIONS_PUBLIC=true）。调用 start_diagnostic 时，服务端会在 technical_error_codes（制造商数据库）中查询错误代码并将结果记入日志，而不只是使用资料包回退映射。当前启用的资料包：pac_air_eau 和 pac_air_air，版本为 0.0.1（Beta 期间可能变动）。

---

工具

该服务提供 15 个工具（10 个 GA + 5 个 Beta Harness 会话工具）。完整参考请参阅 docs/tools.md。

GA（10 个）

工具	功能
search_technical_docs	对技术文档进行语义搜索（≤10 条摘录）。可按 brand、model、error_code 筛选。
get_procedure	按 chunk_id 获取完整流程。
get_error_code	按 brand + error_code 确定性查询（可选 model）。
get_product_sheet	按 brand + model 获取产品信息表：规格、组成、常见错误代码。
get_pdf_page_snapshot	获取指向指定 PDF 页面的签名 URL，有效期 5 分钟（document_id + page）。
diagnose	根据症状或错误代码进行一次性来源查询（摘录 + 步骤 + 引用）。
diagnose_v2	相同查询，但要求严格的 SKU 来源依据。若没有已批准的精确型号手册，则不提供诊断（diagnostic: null）。
resolve_model	将 brand + model 解析为规范 SKU。仅接受精确匹配或别名匹配——绝不使用系列 LIKE 查询。
get_model_coverage	获取已解析 SKU 的文档标记：exact_manual、error_code_covered、market_verified。
diagnose_guided	面向空气-水热泵的多轮引导式故障排查（旧版；每轮扣除配额）。

Beta — Harness 会话（5 个）

工具	功能
start_diagnostic	启动有状态的 Harness 会话。启动时查询制造商错误代码。创建会话时扣除配额。
get_diagnostic	读取当前会话视图（hypotheses、next_action、故障代码）。
respond_to_diagnostic	添加类型化的观察、测量或技师评估。
close_diagnostic	关闭会话，可选填写原因（无需验证）。
get_diagnostic_summary	根据会话日志生成确定性、可导出的摘要。

稳定性：beta · 响应中包含 release_channel: beta · 必须由具备资质的 HVAC 专业人员使用。

---

快速开始

1. 获取 API 密钥

在 https://app.askmarcel.app/developers 免费创建密钥（Developer 套餐每月可调用 250 次）。该服务还支持 OAuth 2.0（PKCE + Dynamic Client Registration），供能自动发现身份验证方式的客户端使用。

2. 连接 MCP 客户端

可直接使用的配置位于 examples/。任何 Streamable HTTP MCP 客户端均可使用以下通用格式：

{
  "mcpServers": {
    "askmarcel": {
      "type": "streamable-http",
      "url": "https://mcp.askmarcel.app",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

**Claude Desktop / Cursor / VS Code：**请参阅 examples/ 中对应的文件。将 YOUR_API_KEY 替换为你的密钥。

3. 提出问题

连接后，可直接用自然语言提问，例如：

“Daikin Altherma 显示错误 U4——这代表什么？如何清除？”

Agent 会调用 resolve_model / diagnose_v2（或 get_error_code / diagnose），并返回原因、修复步骤和来源手册页；如果没有精确的手册，则会明确说明无法提供诊断。

如需对热泵进行完整的现场诊断循环，请使用 start_diagnostic → respond_to_diagnostic → close_diagnostic（参见技能 hvac-harnais-session）。

---

MCP 与 Chat API

AskMarcel 提供两个独立的集成接口——请勿混用其协议：

接口	端点	协议	使用场景
MCP 服务（本仓库）	https://mcp.askmarcel.app	JSON-RPC Streamable HTTP（tools/call）	将 Claude、Cursor、VS Code 或任何 MCP 客户端连接到 HVAC 工具
Chat API（Web / 移动端 / 扩展）	https://app.askmarcel.app/api/chat	AI SDK v5 SSE（UIMessageStream）	提供包含流式传输、工具和文档块的完整对话式 UI

MCP 服务不使用 AI SDK 聊天流（text-delta、data-* 部分）。如果你使用 Vercel AI SDK 构建自定义 Agent，请通过 JSON-RPC 使用 MCP 工具，而非 Web 聊天端点。

---

身份验证

支持两种方式（详情见 docs/authentication.md）：

1. API 密钥（Bearer）： Authorization: Bearer YOUR_API_KEY
2. OAuth 2.0： 通过以下地址发现 https://mcp.askmarcel.app/.well-known/oauth-protected-resource

---

Claude Skills

skills/ 文件夹包含可直接使用的 Agent Skills，可将这些工具整合到 HVAC 工作流中：

• hvac-error-lookup — 将品牌和错误代码转换为附有来源的说明和解决方案。
• hvac-diagnostic — 一次性查询症状并提供引用（diagnose）。
• hvac-guided-diagnosis — 针对空气源热泵的多轮引导式故障排查（diagnose_guided）。
• hvac-harnais-session — Beta Harness 会话循环（start_diagnostic … close_diagnostic）。

---

REST API SDK

对于直接调用 REST API（而非 MCP）的自定义 Agent，请使用 npm 包 @askmarcel/sdk——它包含 Harness 会话方法（startDiagnosticSession、respondToDiagnosticSession，…）、用于 POST /v1/diagnostic/turn 的 guidedTurn()，以及 V2 诊断所需的 resolveModel() / getModelCoverage()。

---

链接

• MCP 端点 — https://mcp.askmarcel.app
• 开发者门户和 API 密钥 — https://app.askmarcel.app/developers
• API 参考 — https://app.askmarcel.app/developers/reference
• Marcel Inside（B2B）— https://askmarcel.app/fr/connecteurs
• 模板 — https://app.askmarcel.app/templates
• 官方 MCP Registry — io.github.askmarcel/mcphvac
• 网站 — https://askmarcel.app

---

许可证

本仓库中的代码和内容（文档、示例、技能）依据 MIT License 发布。AskMarcel 托管服务及其底层数据为专有内容，受 AskMarcel 条款约束。

---

🇫🇷 法语

AskMarcel 是一个托管的远程 MCP 服务（Streamable HTTP），可将 AI Agent 连接到有制造商来源的 HVAC/RACH 技术文档。无需安装：将 MCP 客户端指向 endpoint 并完成身份验证即可。每条回答都会引用手册及准确页码，而不是凭空编造。

• Endpoint： https://mcp.askmarcel.app
• 注册表名称： io.github.askmarcel/mcphvac
• 清单： 1.3.1-beta.1 — 15 个工具已投入生产
• 文档和 API 密钥： https://app.askmarcel.app/developers
• Marcel Inside（B2B）： https://askmarcel.app/fr/connecteurs
• 免费 Developer 套餐： 每月 250 次调用
• 覆盖范围： 126 个品牌 · 905 个型号 · 已索引 400,000 多个错误代码

Marcel Inside — 将 AskMarcel 知识库接入现有的聊天机器人、语音机器人或 Agent。试点版 490€ · Business 149€/月（未含税）· 免费 Developer 套餐可供测试。

15 个工具： 10 个 GA 工具（search_technical_docs、get_procedure、get_error_code、get_product_sheet、get_pdf_page_snapshot、diagnose、diagnose_v2、resolve_model、get_model_coverage、diagnose_guided）+ 5 个 Harnais Beta 会话工具（start_diagnostic、get_diagnostic、respond_to_diagnostic、close_diagnostic、get_diagnostic_summary）。

Harnais Beta 已上线： 在 start_diagnostic 时查询制造商数据库（technical_error_codes），提供 pac_air_eau / pac_air_air 0.0.1 套件，仅在创建会话时扣减配额。与 diagnose_guided 不同（适用于 PAC Air/Eau 的旧版引导式诊断，按轮次扣减配额）。

Skills： 错误代码查询、单次诊断、PAC 引导式诊断、Harnais 会话 — 参见 skills/。

REST SDK（npm）： @askmarcel/sdk — Harnais 会话 + guidedTurn() + API v2。

快速连接： 在 https://app.askmarcel.app/developers 创建密钥，然后使用 examples/ 文件夹中的任一配置（Claude Desktop、Cursor、VS Code）。将 YOUR_API_KEY 替换为你的密钥。

MCP 与 Chat API： 此仓库介绍 MCP 服务（mcp.askmarcel.app 上的 JSON-RPC）。网页和移动端聊天使用独立 API（/api/chat 上的 SSE AI SDK v5）——两种协议不可互换。

工具详情：docs/tools.md · 身份验证：docs/authentication.md。