{
  "_note": "Descripteur du serveur MCP de Margeo. Il n'existe pas encore de norme ratifiée pour la découverte MCP : ce fichier suit la convention émergente `/.well-known/mcp.json` et décrit ce qui est VÉRIFIABLE en appelant l'endpoint. Il est GÉNÉRÉ depuis `MCP_TOOLS` dans `_worker.js` par `scripts/generer_mcp_json.py` — ne pas l'éditer à la main.",
  "name": "margeo",
  "title": "Margeo — gestion de stock, ventes, marges et fiscalité des revendeurs",
  "description": "Serveur MCP de Margeo, logiciel français de gestion pour revendeurs d'occasion (Vinted, Leboncoin, eBay, Rakuten, Facebook Marketplace). Un agent autorisé peut lire et modifier le stock, les ventes groupées, les achats, dépenses, plateformes, catalogue, réglages fiscaux, factures et boutiques secondaires, avec des listes paginées.",
  "version": "1.1.0",
  "protocol_versions": [
    "2026-07-28",
    "2025-11-25",
    "2025-06-18",
    "2025-03-26",
    "2024-11-05"
  ],
  "endpoint": "https://margeoapp.com/mcp",
  "transport": {
    "type": "http",
    "protocol": "json-rpc-2.0",
    "method": "POST",
    "content_type": "application/json"
  },
  "authentication": {
    "type": "bearer",
    "header": "Authorization",
    "scheme": "Bearer",
    "note": "Le jeton est celui du compte Margeo de l'utilisateur. Il se demande dans l'application, jamais en paramètre d'URL : un jeton en query string fuit dans les journaux, les proxys et l'historique."
  },
  "availability": {
    "plans": [
      "pro",
      "business"
    ],
    "note": "Le connecteur est inclus dans les plans Pro et Business. En Starter, l'endpoint répond 403 avec un message qui indique à l'utilisateur comment activer un plan payant."
  },
  "rate_limit": {
    "calls_per_hour": 200,
    "reads_per_hour": 100000,
    "writes_per_hour": 2000,
    "scope": "par compte"
  },
  "capabilities": {
    "tools": true,
    "resources": true,
    "resource_templates": true,
    "prompts": true
  },
  "resources": [
    "margeo://workspace/self/profile",
    "margeo://workspace/self/overview",
    "margeo://guide"
  ],
  "resource_templates": [
    "margeo://workspace/{workspaceId}/profile",
    "margeo://workspace/{workspaceId}/overview"
  ],
  "prompts": [
    "analyze_business",
    "prepare_tax_review",
    "audit_inventory"
  ],
  "tools": [
    {
      "name": "get_profile",
      "description": "Get user profile: plan (starter/pro/business), name, email, fiscal regime (micro/societe/none), corporate tax rate (societeIsRate: reduit/normal/exonere), ACRE status, TVA, fiscal year selected. In the societe regime the ACRE and versement-libératoire flags are NOT returned: they have no effect there (a company pays no contribution on turnover) and the corporate tax is estimated on the profit. Company legal mentions (SIREN, RCS, share capital, intra-community VAT number) are returned when they are set."
    },
    {
      "name": "get_stats",
      "description": "Get full financial stats for the user: total revenue (soldPrice of sold items), total pack purchases, total expenses (frais), net profit, margin %, item counts by status (sold/pending/shipping/in-stock)."
    },
    {
      "name": "list_items",
      "description": "List stock items. Each item has: id, name, purchasePrice (item purchase cost in €), estimatedPrice (expected sell price), soldPrice (actual sell price when sold), sold (bool), pending (bool = not yet received), shipping (bool = sold, in transit), soldDate, soldPlatform, saleNote (buyer/comment/reference), packId (parent pack), receivedDate, shippingDate, declared (bool = declared for tax)."
    },
    {
      "name": "create_item",
      "description": "Create one or several identical stock items linked to a pack. Accepts the FULL item state (category, description, pending, receivedDate, shipping, shippingDate, sold, soldPrice, soldDate, soldPlatform, saleNote, declared, purchasePriceAuto, sale totals and commissions, buyer fields, invoice flags), so an item can be copied from another boutique in one call. soldPrice must be > 0 when a sale is recorded; declared requires the item to be sold or shipping."
    },
    {
      "name": "create_items",
      "description": "Create up to 20 stock items in ONE call. Each entry accepts exactly the same fields as create_item. Returns {created, items, failed:[{index, error}]}: one bad line never discards the batch. Each entry of items carries its input index (items[i].index) — pair results by THAT, never by position. Prefer this over looping create_item: the connector allows 200 requests per hour."
    },
    {
      "name": "update_items",
      "description": "Update up to 20 stock items in ONE call. Each entry needs an id plus any field accepted by update_item. Returns {updated, ids, failed:[{index, id, error}]}: one bad line never discards the batch."
    },
    {
      "name": "update_item",
      "description": "Update a stock item: mark as sold (sold=true, soldPrice, soldDate, soldPlatform), mark as shipping (shipping=true, shippingDate), mark as declared (declared=true — allowed on a sold OR shipping item), move it to another pack (packId), or correct any item field (category, description, notes, purchasePriceAuto, sale totals/commissions, buyer fields, invoiceRequested, invoiceGenerated). sold=false cancels the sale and clears the whole sale block."
    },
    {
      "name": "delete_items",
      "description": "Delete up to 20 stock items in ONE call (explicit ids only — a bad id never discards the batch). Returns {deleted, ids, absent, failed:[{index, id, error}]}. An id that no longer exists is reported in absent, not as an error: the operation is idempotent and never claims to have deleted something it did not find."
    },
    {
      "name": "delete_item",
      "description": "Delete a stock item by id."
    },
    {
      "name": "list_packs",
      "description": "List purchase packs (lots d'achat). Each pack has: id, name, price (total purchase cost in €), date, singleItem (bool), purchaseQuantity, unitPurchasePrice (price ÷ quantity), removedPurchaseCost (purchase cost of items already taken out of the pack), seller (where it was bought). Items linked to a pack share the same packId."
    },
    {
      "name": "create_pack",
      "description": "Create a new purchase pack (lot d'achat). Accepts the full pack state (name, price, date, singleItem, notes, purchaseQuantity, unitPurchasePrice, removedPurchaseCost, seller) so a pack can be copied from another boutique in one call."
    },
    {
      "name": "delete_pack",
      "description": "Delete a purchase pack by id."
    },
    {
      "name": "list_frais",
      "description": "List all business expenses (frais): packaging, shipping supplies, tools, etc. Each frais has: id, description, amount (€), date."
    },
    {
      "name": "create_frais",
      "description": "Create a new business expense."
    },
    {
      "name": "delete_frais",
      "description": "Delete an expense by id."
    },
    {
      "name": "list_platforms",
      "description": "List selling platforms configured by the user (e.g. Vinted, Leboncoin, Rakuten, eBay)."
    },
    {
      "name": "list_catalogue",
      "description": "List catalogue products (product templates with target buy/sell prices for simulation)."
    },
    {
      "name": "get_item",
      "description": "Get full detail of a single stock item by id."
    },
    {
      "name": "list_sales",
      "description": "List sold items (ventes). Each sale has: id, name, purchasePrice, soldPrice, soldDate, soldPlatform, saleNote, declared, packId, estimatedPrice. Filterable by year, platform, and declared status."
    },
    {
      "name": "mark_item_sold",
      "description": "Mark an existing stock item as sold. Sets sold=true, records price, date, platform. Refuses if already sold unless force:true."
    },
    {
      "name": "mark_declared",
      "description": "Mark sold items as fiscally declared. Pass a list of ids, or a year/month to declare all undeclared sales in that period."
    },
    {
      "name": "list_undeclared",
      "description": "List undeclared sold items (ventes non déclarées fiscalement). Returns count, total revenue, and item list."
    },
    {
      "name": "get_stats_by_platform",
      "description": "Get sales stats grouped by selling platform: count, revenue, average price per platform."
    },
    {
      "name": "get_stats_by_period",
      "description": "Get financial stats over time grouped by month, quarter or year: revenue, purchases, expenses, profit per period."
    },
    {
      "name": "create_sale",
      "description": "Create a new item and immediately record it as sold in one step. Use when you want to log a past sale without going through the stock workflow (create_item + mark_item_sold). Returns the created item."
    },
    {
      "name": "create_sale_group",
      "description": "Record one past sale containing 2 to 25 different items. Every item receives the same saleGroupId and transaction total; provide each item’s allocated soldPrice."
    },
    {
      "name": "update_pack",
      "description": "Update a purchase pack (lot d'achat): name, price, date, singleItem, notes, purchaseQuantity, unitPurchasePrice, removedPurchaseCost, seller."
    },
    {
      "name": "update_frais",
      "description": "Update an existing business expense (frais): description (or alias name), amount, date."
    },
    {
      "name": "get_tax_summary",
      "description": "Estimate Margeo social contributions and separate commercial CFP from sold items marked declared, using the workspace regime and ACRE dates. Includes the 1% versement-libératoire estimate only when the workspace setting is explicitly enabled. In the societe regime there is no contribution on turnover: the corporateTax block (base, rate, rateMode, estimated) carries the corporate-income-tax estimate on the exercise profit, and estimatedTotalDue includes it. Returns undeclared sales separately; not a tax filing or legal advice."
    },
    {
      "name": "simulate_profitability",
      "description": "Run a deterministic revenue, purchase-cost, expense, commission and tax-estimate calculation. Commercial micro-BIC simulations include separate 0.10% CFP; include the optional 1% versement-libératoire estimate only when includeVersementLiberatoire is true."
    },
    {
      "name": "list_workspaces",
      "description": "List the account and secondary Margeo boutiques the token owner can access. Use a returned boutiqueId as workspaceId on other tools."
    },
    {
      "name": "create_boutique",
      "description": "Create a secondary boutique on a Business account. Returns its boutiqueId for workspaceId on other tools."
    },
    {
      "name": "update_profile_settings",
      "description": "Update an allowlisted set of fiscal and invoice settings. The payment plan, access roles, bank details and MCP tokens cannot be changed here. Changing the regime applies the same default transitions as the app (TVA 0% → 20% for a company unless the rate was explicitly chosen; the personal fee rate is reset). Only micro, societe and the international none are supported. The legal mentions of a company invoice can be set here too: SIREN, RCS, share capital and intra-community VAT number."
    },
    {
      "name": "list_invoices",
      "description": "List invoice records and their status, totals, dates, buyer details and line items. Results are paginated."
    },
    {
      "name": "get_invoice",
      "description": "Read one invoice record by its Firestore document id. This returns the stored invoice data, not a PDF file."
    },
    {
      "name": "create_platform",
      "description": "Add a custom selling platform to the account."
    },
    {
      "name": "update_platform",
      "description": "Rename one custom selling platform by id."
    },
    {
      "name": "delete_platform",
      "description": "Delete one custom selling platform by id."
    },
    {
      "name": "create_catalogue_item",
      "description": "Create a reusable catalogue product for the simulator."
    },
    {
      "name": "update_catalogue_item",
      "description": "Update a reusable catalogue product by id."
    },
    {
      "name": "delete_catalogue_item",
      "description": "Delete a reusable catalogue product by id."
    }
  ],
  "documentation": "https://margeoapp.com/fonctionnalites/",
  "publisher": {
    "name": "Margeo",
    "country": "FR",
    "url": "https://margeoapp.com",
    "contact_email": "ceo@margeoapp.com"
  }
}