MVG Metallverkaufsgesellschaft — Leitfaden fuer Agenten (API-Version 1) ====================================================================== Wir fertigen Blechteile: Zuschnitte, Kantteile, Laserteile aus CAD-Datei, dazu Halbzeuge (Rohre, Profile, Flach- und Rundmaterial) ab Lager. Standort Frankfurt am Main, Abholung moeglich, Versand innerhalb Deutschlands. Grundregeln ----------- 1. Alle Laengen in Millimeter, Winkel in Grad. Nie Text mit Einheit senden. 2. Alle Betraege sind ganze Cent, netto ausgewiesen, zuzueglich 19 % USt. {"net": 5200, "vat": 988, "gross": 6188} heisst 52,00 EUR netto. 3. Preise nennt immer der Server. Es gibt kein Feld fuer einen eigenen Preis. 4. Diese API bezahlt nichts. Eine Bestellung liefert eine checkout_url, die ein MENSCH oeffnet. Fordere den Nutzer auf, sie zu oeffnen; erfinde nie eine Zahlungsbestaetigung. 5. Nimm nie stillschweigend ein Fertigungsrisiko an. Siehe "requirements". Reihenfolge ----------- GET /v1 Selbstbeschreibung (Einheiten, Grenzen) GET /v1/me Fuer wen spricht mein Token, welcher Rahmen? GET /v1/materials Blech-Werkstoffe: Name, variant_code, Dicken (label "2,0/3,5"), Formate, Tafelgewicht, REACH GET /v1/profiles Halbzeuge suchen (q, kategorie, werkstoff, Masse) GET /v1/dfm/rules Konstruktionsgrenzen (Loch, Steg, Rand, Kante) POST /v1/uploads signierter Link fuer eine STEP- oder DXF-Datei PUT die Datei (ohne Schluessel, der Link genuegt) POST /v1/designs {"upload_id": "...", "material_id": "..."} POST /v1/quotes Positionen -> verbindliches Angebot (24 h) POST /v1/orders {"quote_id": "...", "payment_method": "..."} GET /v1/orders/ Status POST /v1/orders//reorder Teile einer frueheren Bestellung des Kundenkontos neu anbieten (heutiger Preis, neu geprueft) -> cart_url. Bestellt NICHTS. Positionsarten im Angebot ------------------------- sheet eigenes Blechteil: material_id, thickness_mm, depth_mm (zweite Kante), segments_mm (Schenkel entlang der Kontur), bends (angle_deg, direction up|down). Flachteil = ein Segment, keine Biegung. Es gilt: Anzahl bends = Anzahl segments_mm minus 1. Optional (Pflichtfragen Kantteil, preisneutral): measure_mode (outside|inside = Schenkel aussen/innen gemessen), visible_side (outside|inside|any = Sichtseite, wichtig bei geschliffen, Folie, eloxiert, lackiert, Riffel), hem (open|closed = Umschlag unter 30 Grad offen mit Spalt oder zugedrueckt). Fehlt eine Angabe, gibt es keinen Fehler — die Position wird in der Auftragspruefung geklaert. Frage den Nutzer danach, statt zu raten. design zuvor geprueftes CAD-Teil: design_id + quantity. profile Halbzeug ab Lager: article_nr + cuts [{length_mm, quantity}]. ERST GET /v1/profiles (MCP: find_materials mit kind=halbzeug) suchen, dann die art_nr als article_nr senden. Nie eine Artikelnummer raten. accessory ProFix-Zubehoer: article_nr + quantity. Beispiel (Winkel 100/50 mm, 2 mm Aluminium, 300 mm lang, 2 Stueck): POST /v1/quotes {"items":[{"type":"sheet","quantity":2,"material_id":"aluminium-almg3", "thickness_mm":2,"depth_mm":300,"segments_mm":[100,50], "bends":[{"angle_deg":90,"direction":"up"}], "reference":"Winkel links"}], "delivery":{"mode":"pickup"}} Versand: "delivery":{"mode":"shipping","postal_code":"60314"}. Die Postleitzahl der Bestellung muss zu der des Angebots passen — sonst ein neues Angebot anfordern. Fertigbarkeit (requirements) ---------------------------- Jedes Angebot und jedes Design traegt requirements[] mit severity: "block" — so nicht fertigbar. NICHT bestellen. Erklaere dem Nutzer den Grund (title/detail) und schlage eine Aenderung vor. "warn" — bestellbar, aber der KUNDE muss zustimmen. Zeige den Hinweis, frage nach, und sende die codes erst danach in accepted_requirements. Niemals ungefragt. Zugang ------ Lesen (/v1, /v1/materials, /v1/profiles, /v1/dfm/rules, /v1/guide.txt) ist frei. Alles Schreibende braucht "Authorization: Bearer ". Zwei Wege: * Zustimmung des Kunden im Browser: OAuth 2.1 mit PKCE. Beschreibung unter /.well-known/oauth-authorization-server, Selbstregistrierung ueber POST /oauth/register. Der Kunde legt dabei eine Betragsgrenze fest. * Ein im Buero ausgestellter Schluessel (bw_live_...). Traegt das Token ein Kundenkonto (GET /v1/me -> customer.bound = true), darf der customer-Block der Bestellung fehlen; Anschrift und USt-IdNr. kommen aus dem Konto. Doppelte Aufrufe ---------------- Sende bei POST /v1/quotes und POST /v1/orders einen "Idempotency-Key" im Header (oder "operation_key" im Rumpf, wenn du keine Header setzen kannst). Gleiche Eingabe erneut = gleiche Antwort. Geaenderte Eingabe = NEUER Schluessel, sonst 409 idempotency_reuse. Fehler ------ Jeder Fehler ist ein JSON-Dokument nach RFC 9457: code stabiler Name, z. B. "not_manufacturable" param betroffenes Feld, z. B. "items.material_id" retryable true = unveraendert erneut versuchen sinnvoll request_id bei Rueckfragen nennen Wichtige codes: invalid_request, unauthorized, insufficient_scope, not_manufacturable, requirements_open, quote_expired, price_changed, limit_exceeded, pricing_unavailable (retryable), rate_limited (retryable). Beschreibung: /entwickler Was du NICHT tun sollst ----------------------- * Keine Preise schaetzen oder aus alten Angeboten uebernehmen — immer rechnen. * Keine "warn"-Hinweise selbst annehmen. * Keine Zahlung behaupten, keine Zahlungsdaten erfragen. * Keine Bestellung ohne ausdruecklichen Auftrag des Nutzers. * Keine Dateibytes in Werkzeugargumente packen — immer /v1/uploads nutzen. Als MCP-Server einbinden ------------------------ Adresse: https://metallgesellschaft.org/mcp (Streamable HTTP, Spezifikation 2026-07-28, zustandslos; initialize-Fassungen bis 2025-11-25 gehen weiter). Ohne Anmeldung: find_materials, get_price, check_manufacturability, get_lead_time, get_shipping_estimate, list_part_templates, configure_part, configure_plate, search_docs, get_agent_guidance. Mit Anmeldung (OAuth, resource=https://metallgesellschaft.org/mcp, oder Schluessel): whoami (catalog:read), create_upload (designs:write), create_quote + update_quote_parts (quotes:write), get_quote (quotes:read), list_orders, check_order_status, reorder_from_order (orders:read, nur OAuth mit Kundenkonto). Der MCP-Server bestellt und bezahlt NICHT: create_quote liefert eine checkout_url in den Warenkorb der Website. Ein MCP-Token traegt kein Bestellrecht und gilt nicht an /v1. Einrichten in Claude Code: claude mcp add --transport http mvg https://metallgesellschaft.org/mcp Teil ohne Datei konfigurieren (frei, ohne Anmeldung) ---------------------------------------------------- GET /v1/part-templates Formen des Teile-Editors mit Parametern POST /v1/parts/configure {template, params, material, thickness_mm, quantity, extra_holes[{x_mm,y_mm,diameter_mm}]} POST /v1/parts/configure-plate {length_mm, width_mm, material, thickness_mm, holes[...], corner_radius_mm, quantity} GET /v1/parts/drafts/{draft_id}/preview.svg bemasste Zeichnung (7 Tage) POST /v1/parts/drafts/{draft_id}/design (designs:write) Entwurf als Design ablegen -> design_id fuer POST /v1/quotes Antwort: Preis netto/brutto (Shop-Preis), Pruefung, preview_url, editor_url (Teile-Editor zum Bestellen), draft_id (7 Tage). Beispiel-Auftraege eines Nutzers -------------------------------- "Was kosten 20 Winkel 80x40 mm aus 3 mm Edelstahl, 500 mm lang?" "Pruef mir diese STEP-Datei auf Fertigbarkeit und nenne den Preis fuer 5 Stueck." "Bestell die zuletzt angebotenen Teile zur Abholung." "Was kosten 4 Stueck Alu-Flachstange 20 x 5, je 1200 mm?" -> GET /v1/profiles?q=flach 20 x 5&werkstoff=aluminium (MCP: find_materials mit kind=halbzeug), dann create_quote mit {"type":"profile","article_nr":, "cuts":[{"length_mm":1200,"quantity":4}]}. Werkstoff-Anzeige ----------------- Nenne dem Nutzer "name" bzw. "variant_code" (z. B. EDS-1.4301-K240-1S), nicht die material_id. Dicken mit "label" ("2,0/3,5" = Riffelblech Grund/Gesamt). Steht ein reach_hinweis (Blei > 0,1 %), gib ihn weiter. Sortiment und Grenzen (aus den Website-Daten erzeugt) ----------------------------------------------------- Laserschneiden bis: Stahl bis 22 mm, Edelstahl bis 20 mm, Aluminium bis 20 mm, Kupfer bis 8 mm, Messing bis 8 mm. Kanten bis: Stahl bis 6 mm, Edelstahl bis 6 mm, Aluminium bis 8 mm. Groesstes Laserteil: 2980 x 1490 mm, laengste Kantung 3230 mm. Gewinde: M3 bis M16. Toleranz-Zusagen: Kantwinkel ± 0,5° (typisch ± 0,3° mit Winkelmessung), Laserschnitt ± 0,1 mm, DIN EN ISO 9013 Klasse 2 — sofern in der Auftragsbestätigung nicht anders vereinbart. ProFix: Aluminium-Systemprofile AlMgSi 0,5 (F25) nach EN 755-9: 20 × 20 MINI mit Nut 5; 30er MIDI mit Nut 8 (30 × 30 bis 60 × 60); 40er Serie mit Nut 8 (40 × 40 bis 40 × 160, Leicht/Schwer/Extraleicht); 80er Serie mit Nut 8 (80 × 80 bis 80 × 160, Leicht/Schwer/Extraleicht); dazu Sonderprofile (R80 45° Nut 8, 40 × 16 Nut 8). Zuschnitt auf Fixlänge ab 10 mm, Stangenlänge 6000 mm. Versand: Versand innerhalb Deutschlands, Abholung in Frankfurt am Main. Lieferzeit und Preis nie selbst nennen: get_lead_time / get_price bzw. GET /api/online/lead-times und POST /v1/quotes fragen. Details je Werkstoff und Blechstaerke: /konstruktionsregeln, /v1/dfm/rules.