AI-agenttirajapinta (MCP) — Rakentaja Outlet

AI-agenttirajapinta — Model Context Protocol

Rakentaja Outlet tarjoaa Model Context Protocol (MCP) -rajapinnan AI-agenteille kuten Claude Desktop, Cursor ja ChatGPT Developer Mode. Rajapinta noudattaa Shopify Storefront MCP:n nimeämiskäytäntöjä (mukaan lukien Shopify-tarkka search_shop_catalog-alias), joten agentit ymmärtävät työkalut ilman uutta oppimista. Endpoint https://rakentajaoutlet.fi/mcp lisätään manuaalisesti MCP-clientin asetuksiin (ks. Palvelun löydettävyys -osio alempana).

Vaihtoehtona MCP:lle tarjolla on myös julkinen REST API v1 integraatioille jotka eivät käytä MCP:tä (Google Merchant, Bing feed, oma backend). Ks. /api/v1/docs.

Julkiset endpointit

MCP-endpoint: https://rakentajaoutlet.fi/mcp (JSON-RPC 2.0, Streamable HTTP stateless)
MCP-manifesti: https://rakentajaoutlet.fi/.well-known/mcp.json (schema_version 1.2.0)
Virallinen MCP Registry: fi.rakentajaoutlet/rakentaja-outlet — registry.modelcontextprotocol.io (status active)
REST API v1 meta: https://rakentajaoutlet.fi/api/v1/ (JSON: provider, shop, endpoints)
REST API v1 OpenAPI-spec: https://rakentajaoutlet.fi/api/v1/openapi.json
REST API v1 dokumentaatio: https://rakentajaoutlet.fi/api/v1/docs (ihmisluettava HTML)

Vastaus-headerit (kaikki /api/v1/* ja MCP)

API-Version: 1.0 — sopimusversio (rikkovat muutokset menevät v2:een)
X-API-Provider: Miamo Intelligence Oy — alustatoimittaja (integraattori tunnistaa "Powered by Miamo")

Kytkeytyminen Claude Desktopiin

Lisää Claude Desktopin claude_desktop_config.json -tiedostoon:

{
  "mcpServers": {
    "rakentaja-outlet": {
      "url": "https://rakentajaoutlet.fi/mcp"
    }
  }
}

Kytkeytyminen ChatGPT Developer Mode -tilaan

Asetukset → Personalization → Developer Mode → Add Custom Connector (tai vastaava) → lisää URL https://rakentajaoutlet.fi/mcp. Auth: none (julkinen rate-limitattu).

Kytkeytyminen Cursoriin

Cursor Settings → MCP-osio → Add new MCP server → URL https://rakentajaoutlet.fi/mcp. Cursor käyttää samaa stateless Streamable HTTP -transporttia kuin Claude Desktop.

Tarjolla olevat työkalut (5 kpl, kaikki read-only)

1. search_catalog

Hae yli 12 000 tuotetta nimen, SKU:n, EAN-koodin tai kategorian mukaan. Suodattimet: kategoria, saatavuus, järjestys (nimi/hinta nousevasti/laskevasti/uusimmat). Kategorialista: /api/categories.

2. search_shop_catalog

Shopify-drop-in-alias (lisätty 5.8.2026): sama toteutus kuin search_catalog, mutta Shopifyn tarkalla nimellä. Agentit joilla on Shopify-koulutus toimivat suoraan.

3. get_product_details

Yksittäisen tuotteen täydet tiedot: kuvaus, hinta (sis. 25,5 % ALV), price_net valmiiksi laskettu (ALV0), kuvat, saatavuus (reaaliaikainen), availability_status (in_stock/supplier_stock/out_of_stock) + estimated_delivery_min/max_days (2–5 arkipäivää), gtin (GS1 Luhn-validoitu, ~88 % täyttö), mpn (valmistajan osanumero kun ean ≠ gtin), package_qty (minimitilausmäärä), weight_kg.

4. create_cart_link

Luo esitäytetyn ostoskorilinkin (esim. ?items=9437:2,4927:1). Tärkeää: linkki ei mutatoi tilaa — ostoskori syntyy vasta kun käyttäjä avaa linkin selaimessa ja hyväksyy sisällön näkyvästi. Rajoitukset: max 20 tuoteriviä, max 50 kpl/rivi. Kori pyöristää määrät package_qty:n monikertaan (jos MOQ > 1) — 5.8.2026 lisätty MOQ-suojaus, joka estää tappiollisten alle-pakkauskoko-tilausten syntymisen.

5. search_shop_policies_and_faqs

Hae kauppaehdot, palautus, toimitus, maksutavat, tietosuoja, yritystiedot. 8 sivun kokonaisuus (mukana AI-ohje tämä sivu) + FAQ Q&A -parit.

Vastauskentät (product-objekti)

Sekä MCP-työkalut että REST API v1 palauttavat samat kentät. Tärkeimmät integraatioiden kannalta:

id, name, sku, brand, category
price_gross (ALV mukana), price_net (ALV0, valmiiksi laskettu), vat_percent, currency: "EUR"
ean (raakadata Ahlsell:sta — voi olla GTIN tai osanumero), gtin (vain Luhn-validoitu 8/12/13/14, tai null), mpn (osanumero kun ean ≠ gtin)
availability_status: "in_stock" | "supplier_stock" | "out_of_stock"
available_for_order (bool), estimated_delivery_min_days / _max_days
availability: nested-objekti {status, available_for_order, stock_own, stock_supplier, estimated_delivery:{min_days, max_days, unit}}
package_qty: minimitilausmäärä (MOQ) — tilaus pyöristetään monikertoihin
weight_kg, unit, image_url, product_url
updated_at, created_at: ISO-8601 aikaleimat inkrementaalisynkkaan

Palvelun löydettävyys

Kun endpoint-URL https://rakentajaoutlet.fi/mcp on lisätty MCP-clientiin (Claude Desktop, ChatGPT Developer Mode, Cursor, jne.), client löytää tarjolla olevat työkalut automaattisesti tools/list-kutsulla. Shopify-yhteensopivat työkalunimet (search_catalog, get_product_details jne.) helpottavat agenttien ymmärrystä työkaluista, mutta eivät itsessään auta MCP-clientia löytämään endpointtia — URL täytyy antaa käyttäjän tai integraation toimesta.

AI-agentit ja LLM:t voivat kuitenkin löytää palvelun automaattisesti näistä discovery-signaaleista:

llms.txt — kertoo MCP-endpointin, työkalut ja tämän ohjeen
/.well-known/mcp.json — MCP-manifest (Anthropicin vakiintumassa oleva discovery-polku)
/.well-known/mcp/server-card.json — vaihtoehtoinen alias (SEP-2127 -tyyppinen)
/api/v1/ — REST API v1 -meta ja endpoint-katsaus (provider, shop, endpoints)

Turvallisuusperiaatteet

Read-only: rajapinta ei muokkaa kaupan tilaa käyttäjän puolesta. Kaikki tilamuutokset (ostoskori, tilaus) tapahtuvat selaimessa käyttäjän hyväksyminä.
Rate-limit: 30 pyyntöä/minuutti per IP (MCP), 60 pyyntöä/minuutti per IP (REST API v1)
Tietosuoja: hakusanat lokitetaan IP-osoitteen /24-anonymisoituna, retentio 90 päivää. Ei profilointia. Lisätiedot tietosuojaselosteessa.

Suunnitteilla

get_cart (V2): ostoskorin lukeminen cart_token:illa (stateless MCP:llä ei ole identiteettiä anonyymin sessiokorin lukemiseen — vaatii cart_token-arkkitehtuurin)
OAuth 2.1 + update_cart (V2): käyttäjän valtuutus mutatoiviin operaatioihin
list_categories-työkalu: helpottaa agentteja löytämään category_id:t
MySQL FULLTEXT-indeksi + typo-tolerantti fuzzy-haku: parempi hakulaatu monimutkaisiin kyselyihin
Webhookit (V2): push-notifikaatiot integraatioille (product.updated, price.changed, stock.changed) — poistaa pollaustarpeen
Feed/bulk-export: /api/v1/products/export?format=jsonl&gzip=1 koko katalogi yhtenä virtana markkinapaikoille

Alustan tarjoaja

MCP-palvelu, REST API v1 ja tekninen alusta: Miamo Intelligence Oy (support@miamo.fi). Sama alustaperiaate on käytössä myös verkkokaupassa okunkoneosa.fi — integraattori tunnistaa saman alustan X-API-Provider-headerista ja voi käyttää samaa integraatiokoodia molempien kanssa.

Palaute ja bug-raportit

Osoitteeseen info@rakentajaoutlet.fi. Tekninen ylläpito ja alustan kehitys: support@miamo.fi.