AskMarcel-MCP

<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`
- **Docs & API key:** https://app.askmarcel.app/developers
- **Reference:** https://app.askmarcel.app/developers/reference
- **Free Developer tier:** 250 API calls / month

---

## 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`)
- FR / EN, focused on the European HVAC/RACH market

## Tools

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

| 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** (server-computed diagnostic state). |

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

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

## 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 `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
- 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`
- **Doc & clé API :** https://app.askmarcel.app/developers
- **Tier Developer gratuit :** 250 appels / mois
- **Couverture :** 126 marques · 905 modèles · 400 000+ codes erreur indexés

**10 outils :** `search_technical_docs`, `get_procedure`, `get_error_code`, `get_product_sheet`, `get_pdf_page_snapshot`, `diagnose` (lookup sourcé), `diagnose_v2` (même lookup, provenance SKU stricte — abstention si pas de manuel exact), `resolve_model` (SKU exact ou alias), `get_model_coverage` (flags documentaires), `diagnose_guided` (dépannage guidé PAC Air/Eau).

**Skills :** lookup code erreur, diagnostic one-shot, diagnostic guidé PAC — voir [`skills/`](./skills).

**SDK REST (npm) :** [`@askmarcel/sdk`](https://www.npmjs.com/package/@askmarcel/sdk) pour intégrer l'API REST (`guidedTurn()` → `POST /v1/diagnostic/turn`).

**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).