[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456
[circleci-url]: https://circleci.com/gh/nestjs/nest
A progressive Node.js framework for building efficient and scalable server-side applications.
## Description
[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
## Project setup
```bash
$ npm install
```
## Compile and run the project
```bash
# development
$ npm run start
# watch mode
$ npm run start:dev
# production mode
$ npm run start:prod
```
## Mistral assistant
The in-app assistant calls the Mistral Conversations API from the API server. Configure the key and optional model in the API environment, never in the Angular client:
```bash
MISTRAL_API_KEY=your-mistral-api-key
MISTRAL_MODEL=mistral-large-latest
MCP_ACCESS_TOKEN=shared-secret-for-the-listify-mcp-connector
```
The authenticated frontend calls `POST /api/assistant/chat`; the API forwards the conversation to `POST /v1/conversations` with the `listify` connector enabled and returns the assistant text. The MCP connector token authenticates only the connector. The assistant passes the authenticated Listify `userId` into every connector tool call, so each logged-in user sees and modifies only their own lists.
Configure the external MCP connector with `Authorization: Bearer $MCP_ACCESS_TOKEN`. If your connector supports dynamic headers, it may also send `x-listify-user-id`; otherwise the MCP tools require a `userId` argument.
Every Mistral response is stored in `assistant_chat_logs`. The table includes the sanitized provider request, the full raw provider response, the extracted assistant text sent back to the UI, response status and timing metadata.
## SSO mit OIDC
Listify nutzt OpenID Connect mit Authorization Code Flow und PKCE (`S256`). Die Discovery-URL wird automatisch aus dem Issuer gebildet:
```text
{OIDC_ISSUER}/.well-known/openid-configuration
```
### LDAP-Portal Client
1. Im LDAP-Portal unter `/admin/oidc-clients` einen Client fuer Listify registrieren.
2. Authorization Code Flow mit PKCE aktivieren. Dynamic Client Registration wird nicht verwendet.
3. Scopes `openid profile email groups` erlauben. Fuer Refresh Tokens optional `offline_access` ergaenzen.
4. Der Client muss `sub`, `preferred_username`, `email`, `name`, `given_name`, `family_name` und bei Scope `groups` den Claim `groups` erhalten.
5. Redirect URI registrieren:
```text
http://localhost:4200/auth/sso/callback
```
Bei Docker/Reverse Proxy:
```text
http://localhost:8080/auth/sso/callback
```
In Produktion muss hier die oeffentlich erreichbare Listify-URL stehen, z. B. `https://listify.example.com/auth/sso/callback`.
6. Post-Logout Redirect URI registrieren:
```text
http://localhost:4200/auth/sso/logout-callback
```
Bei Docker/Reverse Proxy:
```text
http://localhost:8080/auth/sso/logout-callback
```
Für das produktive Listify-Deployment muss im OIDC-Client exakt diese Logout Redirect URI hinterlegt sein:
```text
https://listify.forgecore.work/auth/sso/logout-callback
```
### Listify Environment
```bash
OIDC_ISSUER=https://id.example.com
OIDC_CLIENT_ID=
OIDC_CLIENT_SECRET=
OIDC_SCOPES=openid profile email groups
OIDC_REDIRECT_URI=http://localhost:4200/auth/sso/callback
OIDC_POST_LOGOUT_REDIRECT_URI=http://localhost:4200/auth/sso/logout-callback
CLIENT_URL=http://localhost:4200
```
Das ID Token wird per JWKS validiert. Das Access Token des LDAP-Portals ist opaque; Listify validiert es ueber `/oidc/token/introspection` und ruft danach `/oidc/me` mit `Authorization: Bearer ` fuer UserInfo auf.
Wenn die Introspection-Antwort eine andere Access-Token-Audience als die Client-ID enthaelt, kann sie explizit gesetzt werden:
```bash
OIDC_ACCESS_TOKEN_AUDIENCE=
```
Gruppen werden aus dem Claim `groups` gelesen und lokal auf App-Rollen gemappt. Das Mapping ist zentral in `oidc_group_role_mappings` konfigurierbar, z. B.:
```sql
INSERT INTO oidc_group_role_mappings (id, groupPath, role, enabled)
VALUES (UUID(), '/teams/admins', 'app_admin', 1);
```
## Run tests
```bash
# unit tests
$ npm run test
# e2e tests
$ npm run test:e2e
# test coverage
$ npm run test:cov
```
## MCP-Agent anbinden
Die API enthaelt einen Remote-MCP-Server unter `/mcp`. Er nutzt den bestehenden JWT-Login der REST-API. Ein Agent oder MCP-Client darf deshalb nur mit einem gueltigen Access Token eines verifizierten Users auf die Tools zugreifen.
### Ablauf
1. User ueber die normale Auth-API anmelden, z. B. `POST /auth/login`.
2. `accessToken` aus der Login-Antwort speichern.
3. MCP-Client auf den Streamable-HTTP-Endpunkt konfigurieren:
```text
http://localhost:3000/mcp
```
4. Bei jedem MCP-Request diesen Header senden:
```http
Authorization: Bearer
```
Der Server erzeugt beim MCP-Initialize eine Session. Folge-Requests muessen den vom Server gelieferten `mcp-session-id` Header mitsenden. Die Session ist an den User aus dem JWT gebunden; ein Token eines anderen Users kann dieselbe MCP-Session nicht weiterverwenden.
### Verfuegbare Tools
- `list_existing_lists`
- Liest die Listen des angemeldeten Users.
- Input: optional `{ "status": "open" | "completed" | "all", "includeItems": true | false }`
- Ohne `status` werden nur offene Listen geliefert. Erledigte/geschlossene Listen werden nur mit `"status": "completed"` oder explizit alle Listen mit `"status": "all"` geliefert.
- Schreibt keine Daten.
- `list_templates`
- Liest die Listenvorlagen des angemeldeten Users.
- Input: optional `{ "kind": "packing" | "shopping" | "todo" | "custom" }`
- Schreibt keine Daten.
- `suggest_lists`
- Erzeugt strukturierte Vorschlaege fuer neue Listen.
- Input:
```json
{
"goal": "Sommerurlaub mit Handgepaeck",
"kind": "packing",
"constraints": ["Nur Handgepaeck", "Reisedokumente nicht vergessen"]
}
```
- Output enthaelt `suggestions` mit `name`, `description`, `kind`, `items`, optionalem Template-Bezug und `rationale`.
- Schreibt keine Daten und legt keine Liste an.
- `create_list`
- Erstellt eine neue Liste fuer den angemeldeten User.
- Input:
```json
{
"name": "Sommerurlaub",
"description": "Packliste fuer die Reise",
"kind": "packing",
"items": [
{ "title": "Pass", "required": true },
{ "title": "Tickets", "notes": "Digital und offline sichern" }
]
}
```
- `items` ist optional. Wenn Items angegeben sind, werden sie nach dem Erstellen der Liste in Reihenfolge hinzugefuegt.
- Output enthaelt `list` mit der erstellten Liste inklusive Items.
- `add_list_item`
- Fuegt ein Item zu einer bestehenden Liste hinzu, auf die der angemeldete User Zugriff hat.
- Input:
```json
{
"listId": "list-id",
"title": "Milch",
"quantity": 2,
"required": true
}
```
- Output enthaelt `list` mit der aktualisierten Liste.
- `create_template`
- Erstellt ein neues Template fuer den angemeldeten User.
- Input:
```json
{
"name": "Sommerurlaub",
"description": "Wiederverwendbare Packvorlage",
"kind": "packing",
"items": [
{ "title": "Pass", "required": true },
{ "title": "Tickets", "notes": "Digital und offline sichern" }
]
}
```
- Output enthaelt `template` mit dem erstellten Template inklusive Items.
- `add_template_item`
- Fuegt ein Item zu einem bestehenden Template hinzu, das dem angemeldeten User gehoert.
- Input:
```json
{
"templateId": "template-id",
"title": "Sonnencreme",
"required": false
}
```
- Output enthaelt `template` mit dem aktualisierten Template.
### Minimaler MCP-Request
Ein MCP-Client uebernimmt normalerweise Initialize, Session-Header und Tool-Calls selbst. Fuer eigene Tests sieht ein Tool-Call nach erfolgreicher Initialisierung sinngemaess so aus:
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "suggest_lists",
"arguments": {
"goal": "Sommerurlaub mit Handgepaeck",
"kind": "packing",
"constraints": ["Nur Handgepaeck"]
}
}
}
```
Wichtig: Der aktuelle Ausbau erlaubt Erstellen von Listen und Templates sowie Hinzufuegen von Items. Aendern, Abhaken, Loeschen und Teilen ist ueber MCP noch nicht freigegeben.
## Deployment
When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information.
If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps:
```bash
$ npm install -g @nestjs/mau
$ mau deploy
```
With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.
## Resources
Check out a few resources that may come in handy when working with NestJS:
- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework.
- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy).
- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/).
- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks.
- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com).
- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com).
- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs).
- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com).
## Support
Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
## Stay in touch
- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
- Website - [https://nestjs.com](https://nestjs.com/)
- Twitter - [@nestframework](https://twitter.com/nestframework)
## License
Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).