MCP-palvelin

Hobin MCP-palvelin (Model Context Protocol) antaa tekoälyavustimen tehdä samoja seuran ylläpitotehtäviä, joita teet hallintapaneelissa. Avustaja kirjautuu sinun Hob-tunnuksellasi ja näkee vain ne seurat ja toiminnot, joihin sinulla on jo oikeus.

MCP ei ole erillinen moduuli eikä sitä oteta käyttöön seuran moduulivalinnassa. Yhteys on yksi osoite koko Hobissa; seura valitaan vasta kirjautumisen jälkeen.

Tämä sivu kuvaa käytännön käyttöä, ei teknistä API-dokumentaatiota.

Kenelle sopii?

• Ylläpitäjille, jotka haluavat pyytää avustinta luomaan kausia (viikkotunnit tai joukkueurheilu), tunteja, joukkueita, yleisiä tapahtumia, coneja, kilpailuja tai profiileja
• Seuroille, joissa hallintatyötä tehdään keskustelemalla avustimen kanssa, ei pelkästään lomakkeita täyttämällä
• Tilanteisiin, joissa avustin tarvitsee lukea seuran tietoja (profiilit, jäsenyydet, ohjelma, palautteet) ennen muutosta

MCP ei korvaa Hobin käyttöliittymää. Profiilin ilmoittautuminen, maksaminen ja muut profiilin toiminnot hoidetaan edelleen Hobissa.

Yhdistäminen

Palvelin käyttää streamable HTTP -yhteyttä. Osoite tuotannossa:

https://hob.fi/mcp/

Käytä osoitetta kauttaviivalla lopussa. Polku ei ole seuran alla (ei muotoa /ex_seura/mcp/).

1. Lisää MCP-asiakkaaseen (esimerkiksi Claude Desktop, Cursor tai MCP Inspector) streamable HTTP -palvelin, jonka URL on https://hob.fi/mcp/.
2. Jätä asiakastunnus ja salaisuus tyhjiksi, jos asiakas osaa rekisteröityä itse (dynaaminen asiakasrekisteröinti). Hob tarjoaa rekisteröinnin OAuth-palvelimellaan.
3. Ensimmäisellä työkalukutsulla asiakas avaa selaimen. Kirjaudu sisään omalla Hob-tunnuksellasi.
4. Tämän jälkeen avustin kutsuu työkaluja Bearer-tunnuksella. Kirjautumaton käyttäjä ei pääse palvelimeen.

Seuran valinta

Yhdellä yhteydellä näet kaikki seurat, joihin tunnuksesi kuuluu. Avustimen kannattaa ensin listata seurat ja vasta sitten tehdä seuran sisäisiä toimintoja.

Jokaisesta seurasta näkyy nimi, tekninen tunnus, aikavyöhyke ja käytössä olevat moduulit. Aika ilman aikavyöhykettä tulkitaan seuran paikallisena aikana (conissa conin omalla vyöhykkeellä, jos se on asetettu). Vastauksissa ajat palautetaan ISO 8601 -muodossa offsetin kanssa.

Kun seura on valittu, avustin voi kysyä, mitkä ylläpitotyökalut ja hakukokoelmat ovat käytössä juuri tuossa seurassa ja millä oikeuksilla. Työkalu, jota et saa kutsua, jää listalle merkinnällä, ettei se ole käytettävissä — avustin voi kertoa, mikä oikeus puuttuu, sen sijaan että ominaisuus piilotettaisiin.

Profiilien haku ja luonti on käytössä kaikissa seuroissa. Jäsenkausien ja jäsenluokkien työkalut näkyvät vain, kun jäsenrekisteri on seuran käytössä. Älä pyydä avustinta kutsumaan työkaluja seuran käyttämättömään moduuliin: kutsu voidaan estää.

Muutokset, oikeudet ja jäljitys

Lukutyökalut hakevat tietoja. Kirjoittavat työkalut muuttavat seuran dataa (luonti, päivitys, julkaisu, poisto).

Jokainen kirjoittava kutsu vaatii lyhyen perustelun (miksi muutos tehdään) ja merkinnän, mikä avustin muutoksen teki. Muutos tallennetaan Hobin versiohistoriaan sinun käyttäjätunnuksellasi.

Oikeudet ovat samat kuin hallintapaneelissa. Jos et saa luoda profiileja tai coneja käyttöliittymässä, et saa tehdä sitä MCP:n kautta. Pyydä tarvittaessa seuran pääkäyttäjää myöntämään vastaava rooli.

Yksityisyys

Työkalujen vastauksissa henkilötiedot (sähköposti, puhelin, sukunimi) lyhennetään oletuksena. Luonti ja haku voivat silti käyttää täyttä sähköpostia tai nimeä suodattimena.

Täydet henkilötiedot vastauksissa edellyttävät seuran palvelinasetusta. Tätä ei kytketä päälle MCP-kutsulla.

Mitä kunkin moduulin kautta voi tehdä

MCP ei julkaise kaikkea Hobin toiminnallisuutta. Alla on se, mitä avustin voi tällä hetkellä hoitaa. Jos moduulia ei ole listattu, sille ei ole MCP-työkaluja.

Yleiset työkalut

Kaikille kirjautuneille:

• testata, että yhteys toimii
• listata seurat, joihin tunnuksella on pääsy
• listata seuran moduulien työkalut ja hakukokoelmat
• hakea tietoja seuran kokoelmista (profiilit, jäsenyydet, tunnit, yleiset tapahtumat, conit, kilpailut, kilpailujen ilmoittautumiset, varausten säännöt, aikataulut ja varaukset ja niin edelleen), jos oikeudet riittävät
• luoda monta kohdetta kerralla niille toimille, jotka sen tukevat (esimerkiksi monta profiilia, varausta tai tapahtumaa) ja tarkistaa, milloin työ on valmis. Kerralla enintään 200. Kaikki kirjoittavat toimet eivät tue tätä.

Yleiset tapahtumat

Yleiset tapahtumat ovat käytössä kaikissa seuroissa. Tekninen tunniste on generic. Ne eivät ole viikkotunnin yksittäisiä tuntikertoja eivätkä coneja.

Avustin voi:

• hakea seuran yleisiä tapahtumia
• luoda tapahtuman (nimi, alku- ja loppuaika, valinnainen sijainti, hinta, osallistujaraja ja ilmoittautumisen rajoitus)
• päivittää tapahtuman tietoja
• korvata ilmoittautumislomakkeen kokonaan (uusi lomake ei yhdisty vanhaan)
• hakea tapahtumien ilmoittautumisia (myös jonon)
• ilmoittaa profiilin tapahtumaan (ylläpitäjän ilmoittautuminen)
• päivittää olemassa olevan ilmoittautumisen (yhdistää lisälomakkeen vastaukset; saldo lasketaan uudelleen, ellei sitä ole muokattu käsin)
• vahvistaa jonossa olevan ilmoittautumisen (päästää osallistujan, vaikka tapahtuma olisi täynnä)
• perua ilmoittautumisen (täydessä tapahtumassa vapauttaa jonopaikan)

Pakolliset lisälomakkeen kentät pätevät ilmoittautumisessa, myös kenttä joka on pakollinen vain kun toinen vastaus täyttää ehdon. Samaa profiilia ei voi ilmoittaa kahdesti. Lapsiprofiili voi muodostaa ryhmän huoltajan kanssa. Profiilin oma ilmoittautuminen ei ole MCP-työkalu. Viikkotunnille ilmoittautuminen ei ole edelleenkään MCP:ssä.

Kuka saa ilmoittautua on yksi asetus: anonyymit, kirjautuneet profiilit, varsinaiset jäsenet, maksaneet jäsenet tai muu ehto (esimerkiksi täsmäävä jäsenyyden tila). Avustin voi asettaa tämän. Ylläpitäjän ilmoittautuminen MCP:n kautta onnistuu silti, vaikka ehto estäisi profiilin oman ilmoittautumisen.

Ilmoittautumislomakkeeseen voi lisätä syntymävuosi-kentän (kalenterivuosi) tai syntymäpäivä-kentän (kalenteripäivä). Tapahtuman hintaan voi liittää alennuksia johdetun iän perusteella. Tämä ei ole valmis lapsialennussääntö.

Anonyymi ilmoittautuminen ei luo seuran profiilia. Muokkaus ja peruutus jäävät kirjautuneille profiileille.

Tapahtuman hintaan voi liittää alennuksia, jotka täsmäävät hakijan jäsenyyden tilaan (odottaa tai hyväksytty). Peruttu jäsenyys tai jäsenyyden puuttuminen ei saa tätä alennusta. Tämä ei ole valmis jäsenalennussääntö.

Ilmoittautumisen alku- ja päättymishetken voi jättää pois, jolloin ilmoittautuminen pysyy kiinni kunnes ajat asetetaan. Tapahtuman alun pitää olla ennen loppua (tai sama hetki).

Jäsenrekisteri

Katso myös jäsenrekisteri.

Profiilien haku ja luonti ei edellytä jäsenrekisteri-moduulia. Kausi- ja luokkatyökalut edellyttävät.

Avustin voi:

• hakea profiileja (henkilöitä ja organisaatioita) ja luoda uuden profiilin — henkilö tai organisaatio, ei jäsenyyttä — käytössä kaikissa seuroissa
• hakea jäsenyyksiä (profiili, kausi, luokka ja tila), kun jäsenrekisteri-moduuli on käytössä — tämä ei ole sama kuin profiilien haku. Ilmoittautumislomakkeen arkaluonteiset vastaukset lyhennetään oletuksena
• hakea jäsenkausia ja jäsenluokkia, kun jäsenrekisteri-moduuli on käytössä
• luoda, päivittää ja kopioida jäsenkauden (kopiointi tuo lomakkeen ja jäsenluokat)
• luoda ja päivittää jäsenluokan (hinta, kuvaus, säännöt). Hinta ja liittymismaksu voivat sisältää alennuksia hakijan tai hakemuslomakkeen tietojen perusteella.

Jäsenyyden hyväksyntä tai hylkäys ei ole vielä MCP:ssä. Profiili on henkilö tai organisaatio; jäsenyys on kausi- ja luokkakohtainen ilmoittautuminen. Organisaatioprofiililla on näyttönimi, vapaaehtoinen sähköposti ja puhelin, eikä sille luoda kirjautumistiliä. CSV-tuonti luo yhä vain henkilöprofiileja.

Maksut

Katso myös maksutavat. Tekninen tunniste on payments.

Avustin voi:

• lisätä profiilille manuaalisen tilitapahtuman (veloitus negatiivisena, hyvitys positiivisena, kuten hallintapaneelissa)

Avustin ei hae tilitapahtumia eikä korjaa summaa. Käteismaksun kirjaaminen ja summan korjaus ovat hallintapaneelissa.

Viikkotunnit

Katso myös viikkotunti-moduuli. Tekninen tunniste on danceclub.

Avustin voi:

• hakea kausia, tunteja (aktiviteetteja), tapahtumia, kausikortteja ja tapahtumien ilmoittautumisia (myös jonon)
• luoda ja päivittää kauden
• luoda ja päivittää tunnin (kertakäynti, kurssi tai molemmat)
• poistaa tyhjän tunnin ja sen tapahtumat (poisto epäonnistuu, jos tunnilla on ilmoittautumisia)
• deaktivoida tunnin, jolla on ilmoittautumisia (tunti merkitään ei-aktiiviseksi; tulevat tapahtumat ja tulevat osallistumiset poistetaan)
• luoda ja päivittää kausikortin ja kytkeä sen tunteihin
• luoda yksittäisiä tapahtumia tai generoida toistuvat tapahtumat viikkovälillä (esimerkiksi tiistaisin kauden loppuun, valitut päivät pois)
• päivittää tai poistaa tapahtuman (poisto epäonnistuu, jos tapahtumaan on ilmoittautumisia)
• perua profiilin kurssi-ilmoittautumisen (poistaa tulevat osallistumiset ja kurssin yksin kattavan kortin, kuten hallintapaneeli)

Tyypillinen järjestys: kausi → tunnit → tapahtumat (tai generointi) → kausikortit → tarvittaessa tunnin päivitys, jotta suositeltu kortti kytkeytyy. Ilmoittautumisia voi hakea (vahvistettu, odottaa tai jonossa). Avustin ei ilmoita profiilia tunnille eikä vahvista jonoa.

Kun tunti luodaan ilman kautta, käytetään aikaisinta tänään voimassa olevaa kautta, tai aikaisinta tulevaa kautta jos yhtään ei ole käynnissä. Anna kausi, kun käynnissä olevia kausia on useita.

Joukkueurheilu

Erillistä joukkueurheilun ohjesivua ei vielä ole. Tekninen tunniste on teamsports.

Avustin voi:

• luoda kauden (nimi, alku ja loppu)
• luoda joukkueen (nimi, kausi)
• asettaa profiilin joukkueen vastuuhenkilöksi (rooli, kuten hallintapaneelissa)
• lisätä profiilin joukkueen rosteriin (kuten hallintapaneelissa)

Avustin ei vielä hae kausia, joukkueita tai tapahtumia. Pelaajan lisätietojen muokkaus tai pelaajan poisto ei ole MCP:ssä.

Conit

Katso myös coni-moduuli.

Avustin voi:

• hakea coneja, ohjelmanumeroita ja ohjelmaehdotuksia sekä ohjelmaan osallistujia ja coniin ilmoittautuneita
• luoda conin (luonti ei julkaise sitä); sijainnin (kaupunki tai paikka) ja kuka saa ilmoittautua (anonyymit, kirjautuneet, varsinaiset jäsenet, maksaneet jäsenet tai muu ehto) voi antaa luonnissa
• päivittää conin asetuksia, aikoja, sijaintia, tiloja, lomakkeita ja sitä kuka saa ilmoittautua
• julkaista conin (erillinen toimenpide)
• luoda ja päivittää ohjelmanumeron, myös merkitä sen perutuksi
• hyväksyä ohjelmaehdotuksen ohjelmaksi tai hylätä ehdotuksen viestillä
• päivittää coniin ilmoittautumista: vahvistaa odottavan tai jonossa olevan ilmoittautumisen, vaihtaa nimimerkin tai merkitä majoitushuoneen
• perua coniin ilmoittautumisen (poistaa osallistumisen; täydessä conissa vapauttaa jonopaikan)

Vaatiiko ilmoittautuminen henkilökunnan hyväksynnän asetetaan hallintapaneelissa, ei MCP:ssä. Profiilin oma ilmoittautuminen, ohjelmanumeroon liittyminen tai majoituksen varaaminen profiilina ei ole MCP-työkalu. Avustin ei lisää uutta osallistujaa coniin, vaan käsittelee olemassa olevia ilmoittautumisia. Ohjelmarivi ei sisällä osallistujia — osallistujat haetaan erikseen.

Kilpailut

Katso myös kilpailu-moduuli. Tekninen tunniste on competition.

Avustin voi:

• hakea seuran kilpailuja ja joukkueiden ilmoittautumisia (hyväksytty, odottaa tai jonossa)
• luoda kilpailun (nimi; valinnainen slug, ajat, ilmoittautumisikkuna, ilmoittautumistapa, joukkuekohtainen osallistumismaksu, ilmoittautumisen lisäkentät, rosterilomake ja vapaamuotoiset kilpailun lisätiedot kuten tyyppi, tyyli tai taso — ei ilmoittautumis- tai rosterilomakkeen kenttiä)
• päivittää näitä tietoja
• korvata kilpailun rosterilomakkeen kokonaan (uusi lomake ei yhdisty vanhaan)
• korvata ilmoittautumisen lisäkentät kokonaan (uusi lomake ei yhdisty vanhaan)
• hyväksyä odottavan ilmoittautumisen (veloittaa joukkuekohtaisen osallistumismaksun, jos se on määritelty)
• hylätä odottavan ilmoittautumisen (ilmoittautuminen poistetaan)
• poistaa kilpailun, jolla ei ole ilmoittautumisia

Pelkällä nimellä luotu kilpailu on ilmoittautumiselle auki, kunnes ikkuna asetetaan. Jos alku annetaan, myös loppu tarvitaan, ja alun pitää olla ennen loppua (tai sama hetki). Sama pätee ilmoittautumisikkunaan. Avustin ei luo kilpailujoukkuetta eikä ilmoita joukkuetta kilpailuun.

Palautekyselyt

Katso myös palautemoduuli.

Avustin voi:

• hakea palautekyselyitä ja annettuja vastauksia
• luoda ja päivittää kyselyn (slug, intro, lomake, päättymishetki)
• julkaista kyselyn, jotta vastauksia otetaan vastaan

Vastauksen lähettäminen profiilina ei ole MCP-työkalu. Julkaisematon kysely ei ole avoinna vastaajille.

Varaukset

Katso myös varausmoduuli. Tekninen tunniste on lending.

Avustin voi:

• hakea lainattavia resursseja, varauksia (resurssin teknisellä nimellä ja/tai profiililla), varaussääntöjä, aikatauluja, sitä, mitkä aikataulut on kytketty mihinkin sääntöön, ja estettyjen aikojen ulkoisia kalenterilinkkejä
• luoda lainattavan resurssin (tila tai väline)
• päivittää resurssia (nimi, esittely, varauksen tyyppi, määrä, aktiivisuus)
• lisätä resurssille varauslogiikan (säännön)
• päivittää varaussääntöä (nimi, varaustapa, kenelle se koskee, järjestys resurssilla ja rajoitusasetukset; virheelliset arvot hylätään). Säännön asetuksissa voi lykätä veloituksen varauksen päättymiseen; oletus on veloitus vahvistuksessa. Sama asetus on hallintapaneelin varaussäännössä.
• poistaa varaussäännön resurssilta
• luoda ja päivittää nimetyn aikataulun (toistuvat ajat, kapasiteetti, iCalendar-osoite tai viikkotunnin tapahtumat täsmäävässä paikassa)
• kytkeä iCalendar-osoitteen aikatauluun (valinnainen suodatin kalenterin tapahtumille)
• kytkeä nimetyn aikataulun varauslogiikkaan tai irrottaa sen
• kytkeä nimetyn aikataulun estetyiksi ajoiksi aikavarausresurssille (ulkoinen kalenteri tai viikkotunnin tapahtumat). Tämä ei ole varaussäännön kytkentä.
• luoda, päivittää ja poistaa varauksen ylläpitäjänä (resurssi teknisellä nimellä, lainaaja profiilina)

Ylläpitäjän varaus MCP:n kautta ei noudata kapasiteetti- eikä aikataulurajoja. Jos säännössä on pakollinen lisälomake, sen kentät pitää silti täyttää. Käytä tätä harkiten. Lainaajaa tai resurssia ei vaihdeta päivityksellä — luo tarvittaessa uusi varaus. Estetyt ajat aikavarausresurssilla estävät päällekkäiset varaukset; ne eivät aseta varaussäännön hintaa.

Viestintä

Hallintapaneelissa osio on Viestintä. Tekninen tunniste on messaging.

Avustin voi:

• hakea uutiskirjeitä (luonnokset ja julkaistut)
• luoda luonnosuutiskirjeen, joka on sidottu lähteeseen (esimerkiksi coni tai kausi)
• päivittää tai poistaa julkaisemattoman luonnoksen
• luoda ja päivittää viestipohjan (kertaluonteinen kirje valituille profiileille hallintapaneelista; pohjan tallennus ei lähetä postia)
• poistaa viestipohjan, jota ei käytetä. Poisto estetään, jos pohjaa käyttää odottava ajastettu lähetys, jäsenluokan automaatio tai conin kuittauspohja. Pelkät toimitetut lähetykset eivät estä poistoa.

Uutiskirjeen lähettäminen tai julkaisu ei ole MCP:ssä. Viestipohjan lähettäminen ei ole MCP:ssä. Julkaistua kirjettä ei voi muokata eikä poistaa tämän kautta.

Käytännön vinkkejä

• Kerro avustimelle ensin seura (nimi tai tekninen tunnus) ja mitä haluat saada aikaan, esimerkiksi “luo syyskauden viikkotunnit”.
• Pyydä avustinta listaamaan seuran työkalut, jos jokin toiminto ei onnistu — kyse voi olla puuttuvasta oikeudesta tai siitä, ettei moduuli ole käytössä.
• Anna kirjoittaville toimille selkeä syy (“kausi 2026 avataan”).
• Älä oleta, että avustin voi hyväksyä jäsenyyksiä, ilmoittaa profiileja viikkotunneille, ilmoittaa kilpailujoukkuetta tai lähettää uutiskirjeitä tai viestipohjia — nämä eivät ole MCP:ssä. Ylläpitäjä voi ilmoittaa profiilin yleiseen tapahtumaan; se ei ole profiilin oma ilmoittautuminen. Kilpailun voi luoda MCP:llä, ja odottavan ilmoittautumisen voi hyväksyä tai hylätä; joukkueen ilmoittaminen ei ole MCP:ssä.
• Tarkista tulos hallintapaneelista, jos muutos on julkinen (conin julkaisu, palautekyselyn avaus).