@maideo/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maideo Services
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @maideo/mcp
+
+Official MCP (Model Context Protocol) server for the Maideo Agent API.
+
+Lets any MCP-compatible AI agent (Claude Desktop, Claude Code, ChatGPT desktop, Continue.dev, Cursor, etc.) book professional home cleaning services (ménage à domicile) anywhere in France, end-to-end, without human intervention.
+
+## What it does
+
+- Checks coverage by postal code
+- Returns a firm price quote
+- Creates a booking in Maideo's back-office (visible to the ops team)
+- Enrolls the end user with URSSAF for the 50% immediate tax credit advance (no card payment needed — SEPA direct debit after each intervention)
+- Polls booking status
+
+## Tools exposed
+
+| Tool | Purpose |
+|------|---------|
+| `search_coverage` | Check if Maideo serves a zip code |
+| `get_quote` | Get a firm 72h-valid price quote |
+| `create_booking` | Create the booking (returns a 72h `bookingToken`) |
+| `enroll_avance_immediate` | Submit URSSAF enrollment (IBAN + identity) |
+| `get_booking_status` | Poll status (order, worker, URSSAF) |
+
+## Install
+
+```bash
+npm install -g @maideo/mcp
+# or use npx without installing:
+npx @maideo/mcp
+```
+
+## Configure Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "maideo": {
+      "command": "npx",
+      "args": ["-y", "@maideo/mcp"],
+      "env": {
+        "MAIDEO_AGENT_NAME": "claude-desktop"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You can now ask Claude:
+
+> "Can you book me a weekly 3-hour cleaning at 12 rue de Rivoli, 75001 Paris, starting next Monday?"
+
+Claude will chain the 5 tools automatically.
+
+## Configure Claude Code
+
+```bash
+claude mcp add maideo npx -- -y @maideo/mcp
+```
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MAIDEO_API_BASE` | `https://api.maideo.fr/public/agent` | API base URL (override for staging/dev) |
+| `MAIDEO_AGENT_NAME` | `maideo-mcp-client` | Identifier sent via `X-Agent-Name` header (used for rate limiting and analytics) |
+
+## Anti-fraud hold
+
+All bookings created via this MCP server are held for 48h before worker dispatch. The Maideo ops team may phone/SMS the end user to verify. **Do not submit bookings with fake data in production.** Your `MAIDEO_AGENT_NAME` may be blocklisted.
+
+You must also collect explicit consent from the end user before calling `create_booking`. Pass `agentConsent: true` as a binding attestation.
+
+## How payment works (there is no payment step)
+
+Maideo uses the URSSAF **avance immédiate de crédit d'impôt** (immediate tax credit advance), a French government program for home services.
+
+1. End user enrolls via `enroll_avance_immediate` — provides identity, birth place, address, IBAN
+2. Worker does the cleaning
+3. Maideo declares the hours to URSSAF
+4. URSSAF pays Maideo directly for 50% of the amount (the tax credit portion)
+5. URSSAF collects the remaining 50% from the end user via SEPA direct debit
+
+**No card, no Stripe, no upfront payment, no signed PDF.** The IBAN + identity are enough.
+
+## Links
+
+- [Maideo website](https://www.maideo.fr)
+- [OpenAPI spec](https://www.maideo.fr/openapi.json)
+- [Agents policy](https://www.maideo.fr/agents.txt)
+- [LLMs manifest](https://www.maideo.fr/llms.txt)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@maideo/mcp",
+  "version": "0.1.0",
+  "description": "Official MCP server for the Maideo Agent API — book home cleaning services in France end-to-end",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "maideo-mcp": "src/index.js"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "MAIDEO_API_BASE=http://localhost:3000/public/agent node src/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "maideo",
+    "cleaning",
+    "menage",
+    "france",
+    "claude",
+    "chatgpt",
+    "agent"
+  ],
+  "author": "Maideo <dev@maideo.fr>",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maideo/maideo-mcp"
+  },
+  "homepage": "https://www.maideo.fr/agents.txt"
+}

package/src/index.js

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+/**
+ * @maideo/mcp — Official MCP server for the Maideo Agent API.
+ *
+ * Exposes 5 tools that map 1:1 on the public HTTP API:
+ *   - search_coverage
+ *   - get_quote
+ *   - create_booking
+ *   - enroll_avance_immediate
+ *   - get_booking_status
+ *
+ * Runs over stdio. Install with `npm i -g @maideo/mcp` then add to your
+ * Claude Desktop / Claude Code / ChatGPT MCP client config.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const API_BASE =
+  process.env.MAIDEO_API_BASE || "https://api.maideo.fr/public/agent";
+const AGENT_NAME =
+  process.env.MAIDEO_AGENT_NAME || "maideo-mcp-client";
+
+async function apiRequest(path, { method = "GET", body, bookingToken } = {}) {
+  const headers = {
+    "Content-Type": "application/json",
+    "X-Agent-Name": AGENT_NAME,
+  };
+  if (bookingToken) {
+    headers["Authorization"] = `Bearer ${bookingToken}`;
+  }
+  const res = await fetch(`${API_BASE}${path}`, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : {};
+  } catch {
+    data = { raw: text };
+  }
+  if (!res.ok) {
+    const err = new Error(
+      `Maideo API ${res.status}: ${data.error || res.statusText}`
+    );
+    err.statusCode = res.status;
+    err.details = data.details;
+    throw err;
+  }
+  return data;
+}
+
+const server = new Server(
+  {
+    name: "@maideo/mcp",
+    version: "0.1.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+const TOOLS = [
+  {
+    name: "search_coverage",
+    description:
+      "Check whether Maideo serves a given French postal code and get the estimated hourly rate (gross, before the 50% tax credit advance). Use this BEFORE get_quote.",
+    inputSchema: {
+      type: "object",
+      required: ["zip"],
+      properties: {
+        zip: {
+          type: "string",
+          pattern: "^[0-9]{5}$",
+          description: "5-digit French postal code",
+        },
+        prestation: {
+          type: "string",
+          enum: ["MENAGE"],
+          default: "MENAGE",
+        },
+      },
+    },
+  },
+  {
+    name: "get_quote",
+    description:
+      "Get a firm price quote for a cleaning booking. Returns a quoteToken valid for 72h that must be passed to create_booking.",
+    inputSchema: {
+      type: "object",
+      required: ["zip", "nbHeuresSemaine", "frequency"],
+      properties: {
+        zip: { type: "string", pattern: "^[0-9]{5}$" },
+        city: { type: "string" },
+        nbHeuresSemaine: {
+          type: "number",
+          minimum: 2,
+          description: "Number of hours per intervention",
+        },
+        nbPrestaSemaine: {
+          type: "integer",
+          default: 1,
+          description: "Number of interventions per week",
+        },
+        frequency: {
+          type: "string",
+          enum: ["one_shot", "weekly", "bi_weekly", "monthly"],
+        },
+        prestation: {
+          type: "string",
+          enum: ["MENAGE"],
+          default: "MENAGE",
+        },
+        prestationInfo: {
+          type: "object",
+          properties: {
+            houseType: { type: "string" },
+            houseSize: { type: "integer" },
+            repassage: { type: "boolean" },
+            pets: {
+              type: "object",
+              properties: {
+                dog: { type: "boolean" },
+                cat: { type: "boolean" },
+              },
+            },
+            comments: { type: "string" },
+          },
+        },
+      },
+    },
+  },
+  {
+    name: "create_booking",
+    description:
+      "Create a booking. Requires a quoteToken from get_quote plus the end-user's identity, address, and explicit consent. Returns a bookingToken (72h) for subsequent calls and a bookingId. The booking is held for 48h before worker dispatch as anti-fraud protection.",
+    inputSchema: {
+      type: "object",
+      required: [
+        "quoteToken",
+        "client",
+        "address",
+        "dateDebut",
+        "agentConsent",
+      ],
+      properties: {
+        quoteToken: { type: "string" },
+        client: {
+          type: "object",
+          required: ["firstName", "lastName", "email", "phone"],
+          properties: {
+            firstName: { type: "string" },
+            lastName: { type: "string" },
+            email: { type: "string", format: "email" },
+            phone: { type: "string" },
+          },
+        },
+        address: {
+          type: "object",
+          required: ["street", "city", "zip"],
+          properties: {
+            street: { type: "string" },
+            city: { type: "string" },
+            zip: { type: "string", pattern: "^[0-9]{5}$" },
+            country: { type: "string", default: "France" },
+          },
+        },
+        dateDebut: {
+          type: "string",
+          format: "date-time",
+          description: "First intervention date (ISO 8601)",
+        },
+        frequency: {
+          type: "string",
+          enum: ["one_shot", "weekly", "bi_weekly", "monthly"],
+        },
+        nbHeuresSemaine: { type: "number" },
+        nbPrestaSemaine: { type: "integer", default: 1 },
+        comments: { type: "string" },
+        agentConsent: {
+          type: "boolean",
+          description:
+            "Attest that the end-user explicitly consented to share their data via your agent",
+        },
+      },
+    },
+  },
+  {
+    name: "enroll_avance_immediate",
+    description:
+      "Enroll the end user with URSSAF for the 50% immediate tax credit advance. After this succeeds, the user pays only half the gross hourly rate via SEPA. Required: bookingToken from create_booking, full identity, birth place, postal address, IBAN.",
+    inputSchema: {
+      type: "object",
+      required: [
+        "bookingId",
+        "bookingToken",
+        "civilite",
+        "nomNaissance",
+        "prenoms",
+        "dateNaissance",
+        "lieuNaissance",
+        "numeroTelephonePortable",
+        "adresseMail",
+        "adressePostale",
+        "coordonneeBancaire",
+      ],
+      properties: {
+        bookingId: { type: "string" },
+        bookingToken: { type: "string" },
+        civilite: {
+          type: "string",
+          enum: ["1", "2"],
+          description: "1=Monsieur, 2=Madame (NOT M/MME)",
+        },
+        nomNaissance: { type: "string" },
+        nomUsage: { type: "string" },
+        prenoms: { type: "string" },
+        dateNaissance: { type: "string", format: "date" },
+        lieuNaissance: {
+          type: "object",
+          properties: {
+            codePaysNaissance: { type: "string" },
+            departementNaissance: { type: "string" },
+            communeNaissance: {
+              type: "object",
+              properties: {
+                codeCommune: { type: "string" },
+                libelleCommune: { type: "string" },
+              },
+            },
+          },
+        },
+        numeroTelephonePortable: {
+          type: "string",
+          pattern: "^(0|\\+33)[6-7]([0-9]{2}){4}$",
+        },
+        adresseMail: { type: "string", format: "email" },
+        adressePostale: {
+          type: "object",
+          properties: {
+            libelleVoie: { type: "string" },
+            libelleCommune: { type: "string" },
+            codeCommune: { type: "string" },
+            codePostal: { type: "string" },
+            codePays: { type: "string" },
+          },
+        },
+        coordonneeBancaire: {
+          type: "object",
+          required: ["bic", "iban", "titulaire"],
+          properties: {
+            bic: { type: "string" },
+            iban: { type: "string" },
+            titulaire: { type: "string" },
+          },
+        },
+      },
+    },
+  },
+  {
+    name: "get_booking_status",
+    description:
+      "Poll the current status of a booking (order, mission, worker assignment, URSSAF enrollment). Requires bookingId + bookingToken from create_booking.",
+    inputSchema: {
+      type: "object",
+      required: ["bookingId", "bookingToken"],
+      properties: {
+        bookingId: { type: "string" },
+        bookingToken: { type: "string" },
+      },
+    },
+  },
+];
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS,
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    let result;
+    switch (name) {
+      case "search_coverage": {
+        const qs = new URLSearchParams({
+          zip: args.zip,
+          prestation: args.prestation || "MENAGE",
+        });
+        result = await apiRequest(`/coverage?${qs.toString()}`);
+        break;
+      }
+      case "get_quote": {
+        result = await apiRequest("/quote", {
+          method: "POST",
+          body: args,
+        });
+        break;
+      }
+      case "create_booking": {
+        result = await apiRequest("/book", {
+          method: "POST",
+          body: args,
+        });
+        break;
+      }
+      case "enroll_avance_immediate": {
+        const { bookingId, bookingToken, ...urssafPayload } = args;
+        result = await apiRequest(
+          `/booking/${bookingId}/enroll-urssaf`,
+          {
+            method: "POST",
+            body: urssafPayload,
+            bookingToken,
+          }
+        );
+        break;
+      }
+      case "get_booking_status": {
+        const { bookingId, bookingToken } = args;
+        result = await apiRequest(`/booking/${bookingId}`, {
+          bookingToken,
+        });
+        break;
+      }
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+    };
+  } catch (err) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Error calling ${name}: ${err.message}${
+            err.details ? `\nDetails: ${JSON.stringify(err.details)}` : ""
+          }`,
+        },
+      ],
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[@maideo/mcp] Server running on stdio");