Metadata-Version: 2.4
Name: knowledgestep-mcp-labs
Version: 0.1.0
Summary: The lab server of KnowledgeStep's course on the Model Context Protocol
Author: Panu Korpela
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Education
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: annotated-types==0.8.0
Requires-Dist: anyio==4.16.0
Requires-Dist: attrs==26.1.0
Requires-Dist: cffi==2.1.1; platform_python_implementation != "PyPy"
Requires-Dist: click==8.5.1; sys_platform != "emscripten"
Requires-Dist: cryptography==48.0.1; platform_machine == "x86_64" and sys_platform == "darwin"
Requires-Dist: cryptography==50.0.2; platform_machine != "x86_64" or sys_platform != "darwin"
Requires-Dist: h11==0.16.0; sys_platform != "emscripten"
Requires-Dist: httpcore2==2.16.0; sys_platform != "emscripten"
Requires-Dist: httpx2==2.16.0
Requires-Dist: httpx2-jsfetch==1.0; python_full_version >= "3.12" and sys_platform == "emscripten"
Requires-Dist: idna==3.20
Requires-Dist: jsonschema==4.26.0
Requires-Dist: jsonschema-specifications==2025.9.1
Requires-Dist: mcp==2.3.0
Requires-Dist: mcp-types==2.3.0
Requires-Dist: opentelemetry-api==1.45.2
Requires-Dist: pycparser==3.12; implementation_name != "PyPy" and platform_python_implementation != "PyPy"
Requires-Dist: pydantic==2.14.3
Requires-Dist: pydantic-core==2.50.4
Requires-Dist: pyjwt==2.15.1
Requires-Dist: python-multipart==0.0.33
Requires-Dist: pywin32==312; sys_platform == "win32"
Requires-Dist: referencing==0.37.0
Requires-Dist: rpds-py==2026.9.1
Requires-Dist: sse-starlette==3.7.0
Requires-Dist: starlette==1.10.0
Requires-Dist: truststore==0.10.5; sys_platform != "emscripten"
Requires-Dist: typing-extensions==4.16.0
Requires-Dist: typing-inspection==0.4.5
Requires-Dist: uvicorn==0.54.0; sys_platform != "emscripten"
Provides-Extra: test
Requires-Dist: pytest==9.0.1; extra == "test"
Requires-Dist: httpx==0.28.1; extra == "test"
Dynamic: license-file

# KnowledgeStepin MCP-harjoituspalvelin

Pieni MCP-palvelin KnowledgeStepin Model Context Protocol -kurssin
harjoituksiin. Yksi palvelin, jonka harjoitus valitaan käynnistettäessä.
Palvelin ei käsittele oikeita tietoja eikä lähetä mitään minnekään: sen
tiedot ovat keksittyjä, ja työkalut, jotka muuten ilmoittaisivat tai
varaisivat jotain, vain kirjoittavat rivin lokiin (virhetulosteeseen).

Palvelin on tehty virallisella Python-SDK:lla (`mcp` 2.3.0), ja se puhuu
protokollan revisiota 2026-07-28.

## Harjoitukset

- **Työkalut, resurssit ja kehotteet** (osa 1): `--lab primitives`,
  yksi työkalu, yksi resurssi ja yksi kehote
- **Kuka luottaa keneen** (osa 3): `--lab annotations`, vain lukevaksi
  merkitty työkalu, joka kirjoittaa vaarattoman tiedoston
  harjoituskansioon (`--lab-dir`, oletus `~/mcp-lab`)
- **Työkalujen myrkytys** (osa 3): `--lab notes` tallentaa
  muistiinpanoja, ja `--lab shadow` on toinen palvelin, jonka työkalun
  kuvaus käskee vaarattomasti lisäämään muistiinpanoihin sanan
  ”varjostettu”; lisää molemmat
- **Kehoteinjektio** (osa 3): `--lab injection`, tiketti, jossa on
  harmiton upotettu ohje
- **Työkalut mallin käyttöön** (osa 4): `--lab search --variant terse`
  tai `clear`, samat työkalut niukasti ja hyvin kuvattuina
- **Kuljetukset** (osa 5): `--lab transport` ja valitsimet alla
- **Tietojen pyytäminen** (osa 5): `--lab elicitation`, lomake, URL-tila
  ja kielletty avainkysymys

Kuljetusten valitsimet:

- `--transport stdio` (oletus) tai `--transport http`, jolloin palvelin
  kuuntelee osoitetta `--host` (oletus 127.0.0.1) porttia `--port`
  (oletus 8765) polussa `/mcp`
- `--noisy-stdout` kirjoittaa tekstiä vakiotulosteeseen ennen kuin
  palvelin käynnistyy, jolloin teksti sekoittuu ensimmäiseen vastaukseen
- `--no-origin-check` hyväksyy HTTP:ssä minkä tahansa `Origin`-otsakkeen,
  kuten huolimaton palvelin tekisi

## Käyttö uv:llä (suositus)

Tarvitset vain [uv](https://docs.astral.sh/uv/):n, joka hakee myös
Pythonin, jos sitä ei ole. Lisää harjoitus Claude Codeen, esimerkiksi:

```sh
claude mcp add lab-primitives -- uvx --no-build \
  --from knowledgestep-mcp-labs==0.1.0 mcp-lab --lab primitives
```

Komento hakee paketin PyPI:stä ja ajaa sen omassa ympäristössään.
Kolme asiaa rajaa, mitä koneellesi tulee:

- **Tarkka versio:** paketti ja kaikki sen riippuvuudet, SDK:n omat
  mukaan lukien, on lukittu tarkkoihin versioihin (`pyproject.toml`),
  joten uusi julkaisu ei tule mukaan itsestään. PyPI ei salli julkaistun
  version tiedostojen vaihtamista.
- **Vain valmiit paketit:** `--no-build` estää lähdekoodipakettien
  kääntämisen, jolloin asennus ei aja yhdenkään paketin omaa
  asennuskoodia.
- **Viikon viive:** riippuvuudet on valittu vähintään viikon vanhoista
  julkaisuista (`pin.sh`), jotta juuri julkaistu haitallinen versio
  ehditään yleensä havaita ja poistaa ennen kuin se päätyy tänne.

Palvelin toimii silti käyttäjäsi oikeuksin. Jos haluat sen eristettynä
koneestasi, käytä Dockeria.

Tuetut alustat: Windows (x86-64), macOS (Intel ja Apple Silicon) ja
Linux (x86-64 ja ARM), Python 3.11–3.14. Windows ARM:lle
`cryptography`-kirjastosta ei ole valmiita paketteja.

## Käyttö Dockerilla

Rakenna konttikuva tästä hakemistosta:

```sh
docker build -t knowledgestep-mcp-labs .
```

Lisää harjoitus Claude Codeen vakiovirtojen kautta, esimerkiksi:

```sh
claude mcp add lab-search -- docker run -i --rm knowledgestep-mcp-labs \
  --lab search --variant terse
```

Annotaatioiden harjoitus kirjoittaa tiedoston kontin sisälle, joten
liitä harjoituskansio konttiin:

```sh
claude mcp add lab-annotations -- docker run -i --rm \
  -v "$HOME/mcp-lab:/lab" knowledgestep-mcp-labs --lab annotations --lab-dir /lab
```

HTTP:llä palvelin kuuntelee kontissa kaikkia osoitteitaan, ja portti
julkaistaan vain koneen osoitteeseen 127.0.0.1:

```sh
docker run --rm -p 127.0.0.1:8765:8765 knowledgestep-mcp-labs \
  --lab transport --transport http --host 0.0.0.0
claude mcp add --transport http lab-http http://localhost:8765/mcp
```

## Käyttö Pythonilla

Python 3.11 tai uudempi:

```sh
python3 -m venv .venv
.venv/bin/pip install .
claude mcp add lab-search -- "$PWD/.venv/bin/mcp-lab" \
  --lab search --variant terse
```

Windowsissa komento on `.venv\Scripts\mcp-lab.exe`.

## Huomio vakiotulosteesta

Määrittelyn mukaan vakiovirtoja käyttävä palvelin ei saa kirjoittaa
vakiotulosteeseen muuta kuin MCP-viestejä. Python-SDK:n versio 2 ohjaa
vakiotulosteen virhetulosteeseen sillä aikaa, kun palvelin on käynnissä,
joten työkalun sisällä oleva `print` päätyy lokiin eikä riko mitään.
Ennen käynnistymistä kirjoitettu teksti, kuten käynnistysilmoitus tai
kirjasto, joka tulostaa tuotaessa, ei ole suojattu. Valitsin
`--noisy-stdout` näyttää molemmat.

## Kehitys

```sh
.venv/bin/pip install -e ".[test]"
.venv/bin/python -m pytest
```

Testit käyttävät SDK:n omaa asiakasta: työkalut prosessin sisällä,
vakiovirrat aliprosessina ja `Origin`-tarkistuksen HTTP-sovelluksen
kautta.

## Riippuvuuksien päivitys

Suorat riippuvuudet ja poikkeukset perusteluineen ovat tiedostossa
`requirements.in`. `pin.sh` ratkaisee niistä kaikki riippuvuudet viikon
vanhoista julkaisuista ja tarkistaa, että jokaiselle tuetulle alustalle
on valmiit paketit:

```sh
./pin.sh            # tai ./pin.sh 2026-11-14
```

Liitä tulos `pyproject.toml`:n kohtaan `dependencies`, päivitä päivämäärä
kommenttiin, nosta versionumeroa ja aja testit.

## Julkaisu PyPI:hin

1. Luo tili osoitteessa pypi.org ja ota kaksivaiheinen tunnistautuminen
   käyttöön.
2. Rakenna paketti: `uv build`
3. Ensimmäinen julkaisu tehdään koko tilin API-tunnisteella:
   `uv publish`
4. Vaihda sen jälkeen tunniste pelkkään tähän projektiin rajattuun ja
   poista koko tilin tunniste. Kun koodivarasto on julkinen, voi siirtyä
   GitHub Actionsin luotettuun julkaisuun (trusted publishing), jolloin
   tunnistetta ei tarvita lainkaan.
