# Nxtly MCP

Bruk Nxtly fra MCP-klienter som Claude, ChatGPT, Claude Code, Cursor og VS Code.
Assistenten kan lese dagsoversikten, finne, opprette, endre og fullføre oppgaver,
og lese eller skrive notater.

Det finnes to servere:

| | Ekstern server (anbefalt) | stdio (`mcp/server.mjs`) |
|---|---|---|
| Adresse | `https://api.nxtly.app/v1/mcp`, innebygd i API-et | Kjører lokalt med Node |
| Innlogging | OAuth via Nxtlys innloggingsside, brukertoken eller API-nøkkel | API-nøkkel eller brukertoken i miljøvariabel |
| Tilgang | Personlig arbeidsområde, delte prosjekter og notater. API-nøkkel: ett arbeidsområde, ingen notater | Ett prosjekt per nøkkel |
| Verktøy | Oppgaver, lister, arbeidsområder og notater | Prosjekter, medlemmer, invitasjoner og oppgaver |

## Ekstern server

Serveren bruker Streamable HTTP med tilstandsløse JSON-svar og støtter
protokollversjonene 2024-11-05 til 2025-11-25. Hvert verktøy kjører det tilsvarende
REST-kallet med brukerens egen autentisering. Roller, synlighet og API-rettigheter
er dermed de samme som på nett og i Apple-appen.

### Koble til en assistent

**Klienter med OAuth:** legg til `https://api.nxtly.app/v1/mcp` som egendefinert
MCP-tilkobling. Klienten registrerer seg og åpner Nxtlys godkjenningsside.
Logg inn med Nxtly-passordet ditt og godkjenn tilgangen. Kontoer med aktivert
tofaktorautentisering kan ikke kobles til ennå. Passordendring kobler fra alle
klienter. På nettsiden kan du se og fjerne tilkoblinger under **Konto → MCP-tilkoblinger**.
API-et tilbyr `GET /v1/me/connections` og `DELETE /v1/me/connections/{uuid}`.

**Claude Code:**

```bash
claude mcp add --transport http nxtly https://api.nxtly.app/v1/mcp
```

**Klienter med fast autentiseringsheader:** opprett en API-nøkkel for
arbeidsområdet og send den som Bearer-token. Nøkkelen gir tilgang til ett
arbeidsområde, uten notater. Se [API-referansen](../docs/api.md).

```json
{
  "mcpServers": {
    "nxtly": {
      "type": "http",
      "url": "https://api.nxtly.app/v1/mcp",
      "headers": { "Authorization": "Bearer nxtly_..." }
    }
  }
}
```

Forespørsler fra nettleser må komme fra et opphav i `MCP_ALLOWED_ORIGINS`
(standard: `CORS_ALLOWED_ORIGINS`). Klienter som kjører på server, sender normalt
ikke `Origin`-header.

### Verktøy

| Verktøy | Funksjon |
|---|---|
| `list_workspaces` | Hente personlig arbeidsområde og delte prosjekter med egen rolle |
| `list_lists` | Hente oppgavelister, valgfritt i ett arbeidsområde |
| `list_todos` | Velge `view`: `today` (inkludert forfalte), `overdue`, `upcoming` (7 dager), `open`, `done` eller `all`; valgfritt arbeidsområde og liste |
| `search_todos` | Finne oppgaver som inneholder alle ordene i søket |
| `get_todo` | Hente én oppgave med beskrivelse, etiketter, ansvarlige og gjentakelse |
| `create_todo` | Opprette oppgave med tittel, beskrivelse, frist, påminnelse, prioritet, arbeidsområde eller liste, eksisterende etiketter, gjentakelse og sted |
| `update_todo` | Endre de samme feltene; `null` tømmer et felt |
| `complete_todo` | Fullføre oppgave; gjentakende oppgaver flyttes til neste gjentakelse |
| `delete_todo` / `restore_todo` | Flytte til papirkurven og gjenopprette |
| `list_notes`, `search_notes`, `get_note` | Lese notater med brukerøkt |
| `create_note`, `append_to_note` | Skrive notater som ren tekst med brukerøkt |

Tidspunkter returneres i brukerens tidssone. Dato og klokkeslett uten angitt
UTC-forskyvning tolkes i denne tidssonen. En dato uten klokkeslett betyr kl. 09:00.

### Lokal testing

```bash
make serve-api
NXTLY_TEST_BASE_URL=http://127.0.0.1:8501/v1 node api/tests/mcp-oauth.cjs
```

Testen oppretter nye testkontoer i en isolert database der migreringene er kjørt.
Den kontrollerer verktøy, nøkkelrettigheter og hele OAuth-flyten: registrering,
godkjenning, PKCE, tokenrotasjon, oppdagelse av gjenbruk og frakobling.

## Lokal stdio-server

stdio-serveren gir MCP-klienter tilgang til prosjekter, prosjektmedlemmer og
delte oppgaver. Den bruker samme REST API og tilgangskontroll som nett- og
Apple-klientene.

Installer låste avhengigheter én gang fra repoets rot med `npm ci`.

### Autentisering

Bruk en nøkkel bundet til arbeidsområdet for en varig integrasjon:

```bash
export NXTLY_API_KEY=nxtly_...
export NXTLY_PROJECT_ID=prosjektets-uuid
npm run mcp
```

Opprett nøkkelen under **Innstillinger → Integrasjoner → API-nøkler** i den
oppdaterte Apple-appen, eller **Konto → Integrasjoner og API-nøkler** på nett.
Du kan også bruke `POST /v1/api-keys` med brukertoken, `X-Workspace` for
arbeidsområdet og disse rettighetene:

```json
{
  "name": "Min MCP-klient",
  "scopes": ["tasks:read", "tasks:write", "projects:read", "members:manage"]
}
```

Hele nøkkelen returneres bare én gang. Brukertoken støttes også gjennom
`NXTLY_ACCESS_TOKEN`. `NXTLY_REFRESH_TOKEN` aktiverer tokenrotasjon i prosessen.

Ved lokal utvikling kan du sette `NXTLY_API_URL=http://127.0.0.1:8501/v1`.
Eksterne API-adresser må bruke HTTPS.

### Klientoppsett

```json
{
  "mcpServers": {
    "nxtly": {
      "command": "node",
      "args": ["/absolutt/sti/til/nxtly/mcp/server.mjs"],
      "env": {
        "NXTLY_API_KEY": "nxtly_...",
        "NXTLY_PROJECT_ID": "prosjektets-uuid"
      }
    }
  }
}
```

De 20 verktøyene dekker oppretting, lesing, endring og sletting av prosjekter;
medlemmer; invitasjoner; samt søk, oppretting, endring, fullføring, sletting og
gjenoppretting av oppgaver. Kjør `npm run test:mcp` for en protokolltest som
ikke kontakter REST API-et.