AskMarcel HVAC Technical Knowledge
15 HVAC MCP tools: lookups, SKU provenance, guided PAC, Beta Harness sessions. 126 brands.
Open source Repository Open in the app JSON README (API)
About
15 HVAC MCP tools: lookups, SKU provenance, guided PAC, Beta Harness sessions. 126 brands.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- askmarcel
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.3.1-beta.1
- Last push
- 2026-08-26T12:08:31Z
- Repository state
- ativo
- License
- MIT
- Added
- 2026-08-29 03:02:27
- Updated
- 2026-08-29 03:02:27
- Origin id
io.github.askmarcel/mcphvac
README
<p align="center">
<img src="docs/assets/askmarcel-icon.png" width="128" height="128" alt="AskMarcel">
</p>
<h1 align="center">AskMarcel — HVAC Technical Knowledge MCP Server</h1>
<p align="center">
Manufacturer-sourced HVAC technical documentation for AI agents: search, diagnostics, error codes, procedures and product sheets across <strong>126 brands</strong> and <strong>905 models</strong>.
</p>
<p align="center">
<a href="https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.askmarcel/mcphvac"><img src="https://img.shields.io/badge/MCP_Registry-io.github.askmarcel%2Fmcphvac-blue" alt="MCP Registry"></a>
<a href="https://smithery.ai/servers/askmarcelapp/mcphvac"><img src="https://smithery.ai/badge/askmarcelapp/mcphvac" alt="smithery badge"></a>
<a href="https://mcp.askmarcel.app"><img src="https://img.shields.io/badge/transport-streamable--http-green" alt="Transport"></a>
<a href="https://app.askmarcel.app/developers"><img src="https://img.shields.io/badge/auth-OAuth_2.0_%2B_API_key-orange" alt="Auth"></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="License"></a>
</p>
AskMarcel is a **remote, hosted MCP server** (Streamable HTTP). There is nothing to install or self-host — point your MCP client at the endpoint and authenticate. The server connects AI agents to real manufacturer documentation so answers cite the exact manual and page number instead of hallucinating.
- **Endpoint:** `https://mcp.askmarcel.app`
- **Registry name:** `io.github.askmarcel/mcphvac`
- **Manifest:** `1.3.1-beta.1` — **15 tools** live in production
- **Docs & API key:** https://app.askmarcel.app/developers
- **Reference:** https://app.askmarcel.app/developers/reference
- **Marcel Inside (B2B API / MCP):** https://askmarcel.app/fr/connecteurs
- **Free Developer tier:** 250 API calls / month
---
## Marcel Inside — branch it behind your bot
Use AskMarcel as **Marcel Inside**: plug manufacturer-sourced HVAC knowledge behind your existing chatbot, voicebot, or agent — without rebuilding your stack. Compatible with ManyChat, ElevenLabs, Voiceflow, Intercom, Claude, ChatGPT, Gemini, and custom MCP clients.
- **Sales & pilot:** https://askmarcel.app/fr/connecteurs (490€ pilot, Business 149€/mois HT)
- **Developer sandbox:** free tier — 250 calls/month at https://app.askmarcel.app/developers
---
## Why AskMarcel
General-purpose LLMs guess at HVAC specifics — refrigerant charge, error-code meanings, wiring, fault trees. AskMarcel grounds every response in indexed manufacturer PDFs and returns the **source page**, so a field technician or an agent can trust and verify the answer. See [HVAC-Bench](https://askmarcel.app) for measured accuracy vs. raw LLM output.
- 126 brands · 905 models · 400,000+ error codes indexed
- Deterministic error-code lookup (not a guess)
- Strict SKU provenance (`resolve_model`, `get_model_coverage`, `diagnose_v2`) — no family substitution
- Sourced one-shot lookups (`diagnose`) and multi-turn guided troubleshooting for air-to-water heat pumps (`diagnose_guided`)
- **LIVE Beta Harness sessions** — stateful diagnostic loop with manufacturer DB lookup at session start (`start_diagnostic` … `get_diagnostic_summary`)
- FR / EN, focused on the European HVAC/RACH market
### Harness session vs `diagnose_guided`
| Surface | Use when | Quota |
|---------|----------|-------|
| **Harness session** (`start_diagnostic` …) | Multi-turn field diagnostic on **PAC Air/Eau** or **PAC Air/Air** with hypotheses, discriminating `next_action`, technician journal | **Once** at session creation |
| **`diagnose_guided`** | Legacy guided loop for **PAC Air/Eau only** — server-sealed state via `continuation` | **Per turn** |
| **`diagnose_v2`** | One-shot strict SKU lookup | Per successful call |
| **`diagnose`** | One-shot lookup without SKU gate | Per successful call |
Harness Beta is **live in production** (`DIAGNOSTIC_SESSIONS_PUBLIC=true`). At `start_diagnostic`, the server looks up error codes in `technical_error_codes` (manufacturer DB) and journals the result — not only pack fallback maps. Active packs: `pac_air_eau` and `pac_air_air` at **`0.0.1`** (mutable during Beta).
---
## Tools
The server exposes **15 tools** (10 GA + 5 Beta Harness session). Full reference in [`docs/tools.md`](./docs/tools.md).
### GA (10)
| Tool | What it does |
|------|--------------|
| `search_technical_docs` | Semantic search over technical documentation (≤10 excerpts). Filter by `brand`, `model`, `error_code`. |
| `get_procedure` | Retrieve a full procedure by `chunk_id`. |
| `get_error_code` | Deterministic lookup by `brand` + `error_code` (optional `model`). |
| `get_product_sheet` | Product sheet: specs, composition, frequent error codes, by `brand` + `model`. |
| `get_pdf_page_snapshot` | Signed, 5-minute URL to a specific PDF page (`document_id` + `page`). |
| `diagnose` | One-shot sourced lookup from a symptom or error code (excerpt + steps + citation). |
| `diagnose_v2` | Same lookup with **strict SKU provenance**. Abstains (`diagnostic: null`) if no approved exact-model manual exists. |
| `resolve_model` | Resolve `brand` + `model` to a canonical SKU. Exact or alias only — never a series LIKE. |
| `get_model_coverage` | Documentary flags for a resolved SKU: `exact_manual`, `error_code_covered`, `market_verified`. |
| `diagnose_guided` | Multi-turn guided troubleshooting for **air-to-water heat pumps** (legacy; quota per turn). |
### Beta — Harness session (5)
| Tool | What it does |
|------|--------------|
| `start_diagnostic` | Open a stateful Harness session. Manufacturer error-code lookup at start. Quota on creation. |
| `get_diagnostic` | Read current session projection (`hypotheses`, `next_action`, fault code). |
| `respond_to_diagnostic` | Append typed observation, measurement, or technician assessment. |
| `close_diagnostic` | Close session with optional reason (verification not required). |
| `get_diagnostic_summary` | Deterministic exportable summary from the session journal. |
Stability: `beta` · `release_channel: beta` on responses · qualified HVAC professional required.
---
## Quick start
### 1. Get an API key
Create a free key at **https://app.askmarcel.app/developers** (250 calls/month on the Developer tier). The server also supports OAuth 2.0 (PKCE + Dynamic Client Registration) for clients that discover auth automatically.
### 2. Connect your MCP client
Ready-to-use configs live in [`examples/`](./examples). The general form for any Streamable HTTP MCP client:
```json
{
"mcpServers": {
"askmarcel": {
"type": "streamable-http",
"url": "https://mcp.askmarcel.app",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
**Claude Desktop / Cursor / VS Code:** see the matching file in [`examples/`](./examples). Replace `YOUR_API_KEY` with your key.
### 3. Ask a question
Once connected, prompt naturally, e.g.:
> "Daikin Altherma showing error **U4** — what does it mean and how do I clear it?"
The agent calls `resolve_model` / `diagnose_v2` (or `get_error_code` / `diagnose`) and returns the cause, the fix steps, and the source manual page — or an explicit abstention when no exact manual exists.
For a full field diagnostic loop on a heat pump, use `start_diagnostic` → `respond_to_diagnostic` → `close_diagnostic` (see skill [`hvac-harnais-session`](./skills/hvac-harnais-session)).
---
## MCP vs Chat API
AskMarcel exposes **two separate integration surfaces** — do not mix their protocols:
| Surface | Endpoint | Protocol | Use case |
|---------|----------|----------|----------|
| **MCP server** (this repo) | `https://mcp.askmarcel.app` | JSON-RPC Streamable HTTP (`tools/call`) | Connect Claude, Cursor, VS Code, or any MCP client to HVAC tools |
| **Chat API** (web / mobile / extension) | `https://app.askmarcel.app/api/chat` | AI SDK v5 SSE (`UIMessageStream`) | Full conversational UI with streaming, tools, and document blocks |
The MCP server does **not** use the AI SDK chat stream (`text-delta`, `data-*` parts). If you build a custom agent with the Vercel AI SDK, use MCP tools via JSON-RPC — not the web chat endpoint.
---
## Authentication
Two supported methods (details in [`docs/authentication.md`](./docs/authentication.md)):
1. **API key (Bearer):** `Authorization: Bearer YOUR_API_KEY`
2. **OAuth 2.0:** discovery via
`https://mcp.askmarcel.app/.well-known/oauth-protected-resource`
---
## Claude Skills
The [`skills/`](./skills) folder contains ready-to-use [Agent Skills](https://docs.claude.com) that wrap these tools into HVAC workflows:
- [`hvac-error-lookup`](./skills/hvac-error-lookup) — turn a brand + error code into a sourced explanation and fix.
- [`hvac-diagnostic`](./skills/hvac-diagnostic) — one-shot symptom lookup with citations (`diagnose`).
- [`hvac-guided-diagnosis`](./skills/hvac-guided-diagnosis) — multi-turn guided troubleshooting for air-to-water heat pumps (`diagnose_guided`).
- [`hvac-harnais-session`](./skills/hvac-harnais-session) — Beta Harness session loop (`start_diagnostic` … `close_diagnostic`).
---
## REST API SDK
For custom agents that call the REST API directly (not MCP), use the npm package [`@askmarcel/sdk`](https://www.npmjs.com/package/@askmarcel/sdk) — includes Harness session methods (`startDiagnosticSession`, `respondToDiagnosticSession`, …), `guidedTurn()` for `POST /v1/diagnostic/turn`, plus `resolveModel()` / `getModelCoverage()` / V2 diagnose.
---
## Links
- MCP endpoint — https://mcp.askmarcel.app
- Developer portal & API key — https://app.askmarcel.app/developers
- API reference — https://app.askmarcel.app/developers/reference
- Marcel Inside (B2B) — https://askmarcel.app/fr/connecteurs
- Templates — https://app.askmarcel.app/templates
- Official MCP Registry — `io.github.askmarcel/mcphvac`
- Website — https://askmarcel.app
---
## License
Code and content in this repository (documentation, examples, skills) are released under the [MIT License](./LICENSE). The AskMarcel hosted service and its underlying data are proprietary and governed by the [AskMarcel terms](https://askmarcel.app).
---
## 🇫🇷 En français
**AskMarcel** est un **serveur MCP distant et hébergé** (Streamable HTTP) qui connecte les agents IA à la documentation technique HVAC/RACH sourcée constructeur. Rien à installer : on pointe son client MCP sur l'endpoint et on s'authentifie. Chaque réponse cite le manuel et la page exacte plutôt que d'halluciner.
- **Endpoint :** `https://mcp.askmarcel.app`
- **Nom registre :** `io.github.askmarcel/mcphvac`
- **Manifeste :** `1.3.1-beta.1` — **15 outils** en production
- **Doc & clé API :** https://app.askmarcel.app/developers
- **Marcel Inside (B2B) :** https://askmarcel.app/fr/connecteurs
- **Tier Developer gratuit :** 250 appels / mois
- **Couverture :** 126 marques · 905 modèles · 400 000+ codes erreur indexés
**Marcel Inside** — branchez la base AskMarcel derrière votre chatbot, voicebot ou agent existant. Pilote 490€ · Business 149€/mois HT · tier Developer gratuit pour tester.
**15 outils :** 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 session Harnais Beta (`start_diagnostic`, `get_diagnostic`, `respond_to_diagnostic`, `close_diagnostic`, `get_diagnostic_summary`).
**Harnais Beta LIVE :** lookup DB fabricant (`technical_error_codes`) au `start_diagnostic`, packs `pac_air_eau` / `pac_air_air` **`0.0.1`**, quota **à la création** de session seulement. Distinct de `diagnose_guided` (guidé legacy PAC Air/Eau, quota par tour).
**Skills :** lookup code erreur, diagnostic one-shot, guidé PAC, session Harnais — voir [`skills/`](./skills).
**SDK REST (npm) :** [`@askmarcel/sdk`](https://www.npmjs.com/package/@askmarcel/sdk) — sessions Harnais + `guidedTurn()` + API v2.
**Connexion rapide :** créez une clé sur https://app.askmarcel.app/developers, puis utilisez une des configs du dossier [`examples/`](./examples) (Claude Desktop, Cursor, VS Code). Remplacez `YOUR_API_KEY` par votre clé.
**MCP vs Chat API :** ce dépôt documente le serveur MCP (JSON-RPC sur `mcp.askmarcel.app`). Le chat web/mobile utilise une API distincte (SSE AI SDK v5 sur `/api/chat`) — les deux protocoles ne sont pas interchangeables.
Détails des outils : [`docs/tools.md`](./docs/tools.md) · Authentification : [`docs/authentication.md`](./docs/authentication.md).