# MCP node tasks 05 - sampling

Dette projekt er femte del af vores praktiske introduktion til Model Context Protocol, forkortet MCP.

I de tidligere dele har vi arbejdet med:

- Del 1: Arkitektur og begreber
- Del 2: MCP-server med resource, tool og prompt
- Del 3: Custom MCP-client
- Del 4: Samlet workflow med tools, resources og prompts
- Del 5: Sampling

I denne del ser vi på sampling.

Sampling betyder, at en MCP-server kan bede clientens LLM om hjælp midt i et workflow.

## Vigtig pointe

I de første dele gik flowet primært denne vej:

```text
Client -> server
```

Med sampling kan serveren også spørge tilbage:

```text
Server -> clientens LLM -> server
```

Det betyder, at serveren kan bruge modelhjælp uden selv at have en LLM API-nøgle.

## Formål

Efter denne del skal du kunne forklare:

- Hvad sampling er
- Hvorfor sampling kræver client-support
- Hvordan sampling adskiller sig fra almindelige tool calls
- Hvordan en server kan bede clienten om modelhjælp
- Hvordan en client-side sampling handler fungerer
- Hvorfor fallback og fejlhåndtering er vigtigt
- Hvorfor sampling kan give sikkerheds- og privatlivsproblemer

## Projektstruktur

```text
mcp-node-tasks-05-sampling/
├── data/
│   ├── project-guide.md
│   └── tasks.json
├── docs/
│   └── images/
│       ├── image-26.png
│       ├── image-28.png
│       └── image-29.png
├── src/
│   ├── server.js
│   ├── samplingClient.js
│   └── taskStore.js
├── package.json
└── README.md
```

```

## Hvad er sampling?

Sampling er en MCP-mekanisme, hvor serveren kan bede clienten om en LLM-completion.

Eksempel:

1. Clienten kalder et tool på serveren.
2. Serveren læser data.
3. Serveren har brug for en AI-formuleret analyse.
4. Serveren sender en sampling request til clienten.
5. Clienten bruger sin LLM eller sampling handler.
6. Serveren modtager svaret.
7. Serveren returnerer det endelige tool-resultat.

## Hvorfor bruger vi en custom client?

Claude Desktop og Cursor kan være gode til tools, men sampling afhænger af, om hosten understøtter MCP sampling.

Derfor tester vi sampling med en custom client:

```text
src/samplingClient.js
```

Den starter serveren og registrerer en sampling handler.

## Hvad er en sampling handler?

En sampling handler er en funktion på client-siden.

Den kaldes, når serveren sender en sampling request.

I et rigtigt setup kan handleren kalde en LLM.

I dette undervisningseksempel bruger vi en simpel lokal handler uden API-nøgle.

Det gør flowet lettere at forstå.

## Serverens capabilities

Serveren udstiller både tidligere capabilities og et nyt sampling-tool.

| Type | Navn | Funktion |
|---|---|---|
| Resource | `tasks://all` | Læser alle tasks |
| Resource | `tasks://open` | Læser kun åbne tasks |
| Resource | `project://guide` | Læser projektets prioriteringsguide |
| Tool | `add_task` | Opretter en ny task |
| Tool | `complete_task` | Markerer en task som færdig |
| Tool | `sample_next_work_session` | Bruger sampling til at foreslå næste arbejdssession |

## Samlet sampling-flow


```mermaid
flowchart TD
    A["npm run sampling"]
    B["src/samplingClient.js<br>Custom MCP client"]
    C["Sampling handler<br>Simuleret LLM-svar"]
    D["src/server.js<br>MCP-server"]
    E["Tool<br>sample_next_work_session"]
    F["Resource data<br>project-guide + open tasks"]
    G["sampling/createMessage<br>Server spørger clienten"]
    H["Tool-resultat<br>Plan for næste session"]
    I["data/project-guide.md"]
    J["data/tasks.json"]

    A --> B
    B --> D
    B --> C
    B --> E
    E --> D
    D --> F
    F --> I
    F --> J
    D --> G
    G --> C
    C --> D
    D --> H
    H --> B
```

## Almindeligt tool call vs sampling

| Flow | Hvad sker der? |
|---|---|
| Almindeligt tool call | Clienten kalder serveren, og serveren returnerer resultat |
| Sampling tool call | Clienten kalder serveren, serveren spørger clientens LLM, og serveren returnerer derefter resultat |

Kort sagt:

```text
Almindeligt tool:
Client -> server -> resultat

Sampling:
Client -> server -> clientens LLM -> server -> resultat
```

## Installation

Kør:

```bash
npm install
```

## Kør serveren alene

Du kan køre serveren alene:

```bash
npm start
```

Serveren bruger stdio og kan se ud som om, den ikke gør noget.

Det er normalt.

Den venter på en MCP-client.

## Test med MCP Inspector

Kør:

```bash
npm run inspect
```

Test især dette tool:

```text
sample_next_work_session
```

Vigtig pointe:

Hvis MCP Inspector eller hosten ikke understøtter sampling, bruger serveren fallback-logik og returnerer en simpel regelbaseret plan.

## Kør sampling-client

Sampling testes bedst med den custom client:

```bash
npm run sampling
```

`samplingClient.js` gør dette:

1. Starter MCP-serveren
2. Registrerer en sampling handler
3. Laver discovery
4. Kalder `sample_next_work_session`
5. Modtager sampling request fra serveren
6. Returnerer et simuleret LLM-svar
7. Viser serverens endelige resultat

## Claude Desktop

Denne del er primært lavet til custom client.

Claude Desktop kan stadig bruges til almindelige tools, men sampling afhænger af, om Claude Desktop understøtter sampling i den aktuelle version.

Brug derfor Claude til de almindelige tools fra del 4:

```text
prepare_next_work_session
prepare_status_report
add_task
complete_task
```

Brug custom client til sampling:

```bash
npm run sampling
```

## Claude-konfiguration

Hvis du vil koble serveren til Claude Desktop, kan du bruge:

```json
{
  "mcpServers": {
    "mcp-node-tasks-05": {
      "command": "node",
      "args": [
        "C:\\Users\\mikc\\WebstormProjects\\mcp-node-tasks-05-sampling\\src\\server.js"
      ]
    }
  }
}
```

Ret stien, så den passer til din computer.

På Windows kan du også bruge forward slashes:

```text
C:/Users/mikc/WebstormProjects/mcp-node-tasks-05-sampling/src/server.js
```

## Forslag til test i Claude

Hvis serveren er koblet på Claude, kan du prøve:

```text
Vis hvilke tools denne MCP-server stiller til rådighed.
```

```text
Brug tool’et sample_next_work_session med fokus på MCP-undervisning.
```

Hvis Claude eller hosten ikke understøtter sampling, bør serveren bruge fallback og stadig give et svar.

## Sikkerhed og fallback

Sampling kan sende data fra serveren til clientens LLM.

Det kan være fint i et lokalt undervisningsprojekt, men i rigtige systemer skal man være opmærksom på:

- følsomme data
- prompt injection
- for store prompts
- rate limiting
- brugeraccept
- fejl i clientens sampling handler
- om clienten understøtter sampling

I dette projekt bruger vi derfor fallback.

Hvis sampling fejler, returnerer serveren en simpel regelbaseret prioritering.

## Miniøvelse

Åbn `src/server.js`.

Find tool’et:

```text
sample_next_work_session
```

Svar på:

1. Hvilke data læser tool’et?
2. Hvor sendes sampling requesten?
3. Hvad sker der, hvis sampling fejler?
4. Hvorfor bør der være fallback?
5. Hvilke data ville være problematiske at sende til en ekstern LLM?

## Ekstra øvelse

Udvid sampling handleren i `src/samplingClient.js`, så den svarer forskelligt afhængigt af fokus.

Eksempel:

```text
fokus: dokumentation
```

bør give et andet svar end:

```text
fokus: demo
```

## Næste trin

Næste naturlige skridt er testing og security.

Her bliver spørgsmålene:

- Hvordan tester vi MCP tools?
- Hvordan tester vi fallback?
- Hvordan undgår vi farlige tools?
- Hvordan logger vi tool calls?
- Hvordan beskytter vi følsomme data?