Skip to main content
Glama
AskMarcel

AskMarcel

Official
by askmarcel
README.md
<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: equipment resolution, sourced fault lookups, cited sources and tracked diagnostic sessions across <strong>126 brands</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 — or abstain when the source is missing.

- **Endpoint:** `https://mcp.askmarcel.app`
- **Registry name:** `io.github.askmarcel/mcphvac`
- **Manifest:** `1.3.0-beta.1` — **7 tools** live in production (3 GA + 4 Beta session tools)
- **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:** 50 API calls / month (live values: https://api.askmarcel.app/v2/pricing.json)

> **Breaking change (November 2026).** The server went from 15 tools to 7, and REST moved to `/v2`. The old tool names (`diagnose`, `diagnose_v2`, `diagnose_guided`, `search_technical_docs`, `get_error_code`, `get_procedure`, `get_product_sheet`, `get_pdf_page_snapshot`, `resolve_model`, `get_model_coverage`, `get_diagnostic_summary`) are removed, with no alias. See the [migration table](./docs/tools.md#migrating-from-the-15-tool-server) and the [changelog](./CHANGELOG.md).

---

## 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
- **Developer sandbox:** free tier 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/fr/preuve) for the published benchmark.

- 126 brands · 900+ models · 400,000+ error codes indexed
- Deterministic error-code lookup (not a guess), tied to an **exact equipment** — no family substitution
- **Abstention** when no exact manual exists, and an **emergency stop** when a danger is reported (CO, gas, high voltage…): no search, no handling instructions
- Cited sources: a `provenance_token` per hit gives the full procedure or the exact PDF page
- **Tracked diagnostic sessions (Beta)** — hypotheses, discriminating next action, technician journal
- FR / EN, focused on the European HVAC/RACH market

### Two uses, one contract

| Use | Tools | Access units |
|-----|-------|--------------|
| **Documentary lookup** (read): what does the manufacturer say for this equipment and this code? | `resolve_equipment`, `lookup_fault`, `get_source` | `lookup_fault`: 1 unit, only when a source is actually served. Everything else: 0 |
| **Tracked intervention** (session, Beta): hypotheses, actions, measurements, repair, verification | `start_diagnostic`, `respond_to_diagnostic`, `get_diagnostic`, `close_diagnostic` | A session quota, consumed once at creation |

A lookup does not diagnose. A session consumes the evidence, it does not replace it. Every lookup answer carries a next step towards the session.

---

## Tools

The server exposes **7 tools**. Full reference in [`docs/tools.md`](./docs/tools.md).

### GA — documentary lookup (3)

| Tool | What it does |
|------|--------------|
| `resolve_equipment` | Resolve `brand` + `model` to an exact equipment (exact or alias, never a range). Optional `error_code` / `market` add the documentary coverage. Free. |
| `lookup_fault` | Sourced lookup from an error code or symptom. Status: `found`, `no_exact_source`, `model_ambiguous`, `equipment_required`, `emergency`. |
| `get_source` | Full procedure by `provenance_token`, or the cited PDF page (`view: "page"`, signed 5-minute URL). Free. The token is the capability: no bare `chunk_id` or `document_id`. |

### Beta — diagnostic session (4)

| Tool | What it does |
|------|--------------|
| `start_diagnostic` | Open a tracked session (equipment resolution, manufacturer fault lookup, hypotheses, first safe action). `request_id` required. |
| `respond_to_diagnostic` | Append a typed observation, measurement or technician assessment. |
| `get_diagnostic` | Read or resume a session. `include: "summary"` returns the deterministic summary. |
| `close_diagnostic` | Close the session (terminal). |

Annotations are honest: the three lookup tools and `get_diagnostic` are `readOnlyHint: true`; session writes are not; `close_diagnostic` is `destructiveHint: true`. All tools set `openWorldHint: false` (closed corpus). Unknown input fields are rejected (strict schemas).

Stability: `beta` · `release_channel: beta` on session responses · qualified HVAC professional required.

---

## Quick start

### 1. Get an API key

Create a free key at **https://app.askmarcel.app/developers**. The server also supports OAuth 2.0 (PKCE + Dynamic Client Registration) for clients that discover auth automatically. Session tools need the `diagnostics.*` scopes (see [authentication](./docs/authentication.md)).

### 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

> "Daikin Altherma showing error **U4** — what does it mean and how do I clear it?"

The agent calls `resolve_equipment`, then `lookup_fault`, and returns the cause, the steps and the source manual page — or an explicit abstention when no exact manual exists. If the user reports a danger, the answer is the emergency message and nothing else.

For a full field loop on a heat pump, use `start_diagnostic` → `respond_to_diagnostic` → `close_diagnostic` (see skill [`hvac-harnais-session`](./skills/hvac-harnais-session)).

---

## MCP vs REST vs Chat API

| 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 |
| **REST v2** | `https://api.askmarcel.app/v2` | JSON over HTTPS | `POST /v2/lookups`, `POST /v2/equipment/resolve`, `GET /v2/sources/{token}`, `/v2/diagnostic-sessions`. OpenAPI: `/v2/openapi.json` |
| **Chat API** (web / mobile / extension) | `https://app.askmarcel.app/api/chat` | AI SDK v5 SSE | Full conversational UI — not for MCP clients |

The MCP server does **not** use the AI SDK chat stream. If you build a custom agent with the Vercel AI SDK, use MCP tools via JSON-RPC — not the web chat endpoint. The `/v1/*` REST routes are gone.

---

## 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`

Scopes: `docs.read` (lookup, equipment, sources), `diagnostics.read`, `diagnostics.write`.

---

## 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) — brand + error code → sourced explanation (`resolve_equipment`, `lookup_fault`, `get_source`).
- [`hvac-diagnostic`](./skills/hvac-diagnostic) — symptom lookup with citations and the emergency stop (`lookup_fault`).
- [`hvac-harnais-session`](./skills/hvac-harnais-session) — Beta 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) or the Python client generated from the OpenAPI — both target `/v2` (lookups, equipment resolution, sources, diagnostic sessions).

---

## Links

- MCP endpoint — https://mcp.askmarcel.app
- Developer portal & API key — https://app.askmarcel.app/developers
- API reference — https://app.askmarcel.app/developers/reference
- OpenAPI — https://api.askmarcel.app/v2/openapi.json
- Marcel Inside (B2B) — https://askmarcel.app/fr/connecteurs
- 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 — ou s'abstient quand la source manque.

- **Endpoint :** `https://mcp.askmarcel.app`
- **Nom registre :** `io.github.askmarcel/mcphvac`
- **Manifeste :** `1.3.0-beta.1` — **7 outils** en production (3 GA + 4 session Beta)
- **Doc & clé API :** https://app.askmarcel.app/developers
- **Marcel Inside (B2B) :** https://askmarcel.app/fr/connecteurs
- **Tier Developer gratuit :** 50 appels / mois
- **Couverture :** 126 marques · 900+ modèles · 400 000+ codes erreur indexés

**Changement cassant (novembre 2026).** 15 outils → 7, REST passe en `/v2`. Les anciens noms sont supprimés, sans alias : table de migration dans [`docs/tools.md`](./docs/tools.md).

**Deux usages, un contrat.** *Lookup documentaire* (lecture) : `resolve_equipment`, `lookup_fault`, `get_source`. *Intervention suivie* (session Beta) : `start_diagnostic`, `respond_to_diagnostic`, `get_diagnostic`, `close_diagnostic`. Le lookup ne diagnostique pas ; la session consomme la preuve, elle ne la remplace pas.

**Unités d'accès.** Seul `lookup_fault` consomme, 1 unité, quand une source est réellement servie. Abstention, urgence, équipement manquant, résolution et sources : 0. La session a son propre quota, consommé à la création.

**Urgence et abstention.** Un danger signalé (CO, gaz, haute tension…) renvoie `emergency` : aucune recherche, aucune consigne de manipulation. Sans manuel exact : `no_exact_source` ou `model_ambiguous`.

**Skills :** lookup code erreur, lookup symptôme, session Beta — voir [`skills/`](./skills).

**SDK REST :** [`@askmarcel/sdk`](https://www.npmjs.com/package/@askmarcel/sdk) (npm) et client Python généré depuis l'OpenAPI, sur `/v2`.

**Connexion rapide :** créez une clé sur https://app.askmarcel.app/developers, puis utilisez une des configs du dossier [`examples/`](./examples). 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).