diff --git a/client/src/components/Assistant/cards/collection/collectionLook.ts b/client/src/components/Assistant/cards/collection/collectionLook.ts index ffb6f598a..4fe7770ff 100644 --- a/client/src/components/Assistant/cards/collection/collectionLook.ts +++ b/client/src/components/Assistant/cards/collection/collectionLook.ts @@ -37,6 +37,7 @@ export const COLLECTION_LOOK = { steps: { get_collection: { stepKey: 'assistant.step.readingList' }, get_collection_items: { stepKey: 'assistant.step.readingList' }, + list_collection_places: { stepKey: 'assistant.step.readingList' }, list_collections: { stepKey: 'assistant.step.lookingAtLists' }, available_collection_users: { stepKey: 'assistant.step.lookingAtLists' }, find_place_in_collections: { stepKey: 'assistant.step.checkingLists' }, diff --git a/server/src/db/repositories/Collections.repository.ts b/server/src/db/repositories/Collections.repository.ts index 1b22f49b1..d86a074f0 100644 --- a/server/src/db/repositories/Collections.repository.ts +++ b/server/src/db/repositories/Collections.repository.ts @@ -84,6 +84,42 @@ type CollectionPlacesWriteKyselyDB = Pick; type CollectionPlaceLabelsKyselyDB = Pick; +type CollectionPlacesPageKyselyDB = Pick; + +/** Which of a list's places a page holds (list_collection_places, #2647); every filter left out matches all. */ +interface CollectionPlacePageFilter { + status?: string; + labelId?: number; + unlabeled?: boolean; +} + +/** + * A place's position in its list: the keys both a page and getCollection order + * by, in that order. A missing sort_order reads as the column default and a + * missing created_at as the earliest, so the order is total on every engine and + * a page can go on after any place. + */ +export interface CollectionPlacePosition { + sortOrder: number; + createdAt: string; + id: number; +} + +/** A saved place as a page names it: the fields an agent finds it by, plus its position. */ +export interface CollectionPlacePageRow { + id: number; + name: string; + status: string; + address: string | null; + lat: number | null; + lng: number | null; + google_place_id: string | null; + website: string | null; + phone: string | null; + sort_key: number; + created_key: string; +} + /** * `collections` — the root of the collections cluster (Plan 3h Task 1, part * A). Owns every CL1-CL36 statement not moved to `CollectionMembersRepository`/ @@ -344,7 +380,9 @@ export class CollectionsRepository extends TrekRepository { * CL16/CL17 (`getCollection`/`exportCollection`'s dup-text pair, collapsed * onto ONE repository method as the brief directs) — the same * `cp.*`/category-alias select as {@link findPlaceRowById}, scoped by - * `cp.collection_id` and ordered by `cp.sort_order, cp.created_at`. + * `cp.collection_id` and ordered by the place's position: `sort_order`, + * `created_at`, then `id`, so two places saved in the same second keep one + * order, the one list_collection_places pages through (#2647). */ async listPlaceRows(collectionId: number): Promise { return await this.placesReadDb() @@ -382,8 +420,99 @@ export class CollectionsRepository extends TrekRepository { 'c.icon as category_icon', ]) .where('cp.collection_id', '=', collectionId) - .orderBy('cp.sort_order') - .orderBy('cp.created_at') + .orderBy((eb) => eb.fn.coalesce('cp.sort_order', eb.val(0))) + .orderBy((eb) => eb.fn.coalesce('cp.created_at', eb.val(''))) + .orderBy('cp.id') + .execute(); + } + + /** The places of a list the filter matches, before any paging. */ + private filteredPlaces(collectionId: number, filter: CollectionPlacePageFilter) { + const { status, labelId, unlabeled } = filter; + let query = this.kysely() + .selectFrom('collection_places as cp') + .where('cp.collection_id', '=', collectionId); + if (status !== undefined) query = query.where('cp.status', '=', status); + if (labelId !== undefined) { + query = query.where((eb) => + eb.exists( + eb + .selectFrom('collection_place_labels as cpl') + .select('cpl.label_id') + .whereRef('cpl.collection_place_id', '=', 'cp.id') + .where('cpl.label_id', '=', labelId), + ), + ); + } + if (unlabeled) { + query = query.where((eb) => + eb.not( + eb.exists( + eb + .selectFrom('collection_place_labels as cpl') + .select('cpl.label_id') + .whereRef('cpl.collection_place_id', '=', 'cp.id'), + ), + ), + ); + } + return query; + } + + /** How many places of a list the filter matches (list_collection_places' total). */ + async countPlacePage(collectionId: number, filter: CollectionPlacePageFilter): Promise { + const row = await this.filteredPlaces(collectionId, filter) + .select((eb) => eb.fn.countAll().as('n')) + .executeTakeFirstOrThrow(); + return Number(row.n); + } + + /** + * Up to `limit` places of a list the filter matches, in the list's order + * (listPlaceRows'), starting after the position `after` names: a keyset, so + * a place that stops matching between two pages moves none of the others. + */ + async listPlacePage( + collectionId: number, + filter: CollectionPlacePageFilter, + after: CollectionPlacePosition | null, + limit: number, + ): Promise { + let query = this.filteredPlaces(collectionId, filter); + if (after) { + query = query.where((eb) => { + const sortKey = eb.fn.coalesce('cp.sort_order', eb.val(0)); + const createdKey = eb.fn.coalesce('cp.created_at', eb.val('')); + return eb.or([ + eb(sortKey, '>', after.sortOrder), + eb.and([ + eb(sortKey, '=', after.sortOrder), + eb.or([ + eb(createdKey, '>', after.createdAt), + eb.and([eb(createdKey, '=', after.createdAt), eb('cp.id', '>', after.id)]), + ]), + ]), + ]); + }); + } + return await query + .select((eb) => [ + 'cp.id', + 'cp.name', + 'cp.status', + 'cp.address', + 'cp.lat', + 'cp.lng', + 'cp.google_place_id', + 'cp.website', + 'cp.phone', + eb.fn.coalesce('cp.sort_order', eb.val(0)).as('sort_key'), + eb.fn.coalesce('cp.created_at', eb.val('')).as('created_key'), + ]) + .orderBy('sort_key') + .orderBy('created_key') + .orderBy('cp.id') + .limit(limit) .execute(); } diff --git a/server/src/nest-mcp/helpers.ts b/server/src/nest-mcp/helpers.ts index 5a5917125..4b169149e 100644 --- a/server/src/nest-mcp/helpers.ts +++ b/server/src/nest-mcp/helpers.ts @@ -15,6 +15,11 @@ export function ok(data: unknown): McpTextResult { return { content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }] }; } +/** Success result: `data` as one line of JSON, for an answer whose size matters more than how it reads (a page of a long list). */ +export function okCompact(data: unknown): McpTextResult { + return { content: [{ type: 'text' as const, text: JSON.stringify(data) }] }; +} + /** Error result with a verbatim message (no formatting, no prefix). */ export function errorResult(text: string): McpTextResult { return { content: [{ type: 'text' as const, text }], isError: true }; diff --git a/server/src/nest-mcp/index.ts b/server/src/nest-mcp/index.ts index 5a6d6f817..e2882f5b9 100644 --- a/server/src/nest-mcp/index.ts +++ b/server/src/nest-mcp/index.ts @@ -3,6 +3,7 @@ export { demoDenied, errorResult, ok, + okCompact, TOOL_ANNOTATIONS_DELETE, TOOL_ANNOTATIONS_NON_IDEMPOTENT, TOOL_ANNOTATIONS_OPEN_WORLD_NON_IDEMPOTENT, diff --git a/server/src/nest/collections/collections-places-page.service.ts b/server/src/nest/collections/collections-places-page.service.ts new file mode 100644 index 000000000..cb1f576d6 --- /dev/null +++ b/server/src/nest/collections/collections-places-page.service.ts @@ -0,0 +1,131 @@ +import { CollectionLabels } from '../../db/entities/CollectionLabels.entity'; +import { Collections } from '../../db/entities/Collections.entity'; +import { CollectionLabelsRepository } from '../../db/repositories/CollectionLabels.repository'; +import { + CollectionsRepository, + type CollectionPlacePageRow, + type CollectionPlacePosition, +} from '../../db/repositories/Collections.repository'; +import { DomainError } from '../common/domain-error'; +import { decodePlacesCursor, encodePlacesCursor } from './collections.helpers'; +import { CollectionsService } from './collections.service'; +import { InjectRepository } from '@mikro-orm/nestjs'; +import { Injectable } from '@nestjs/common'; +import { COLLECTION_PLACES_PAGE_DEFAULT, type CollectionPlacesPageRequest } from '@trek/shared'; + +/** + * How long the places of one page may run as JSON. The in-app assistant cuts a + * tool answer at 40,000 characters, and a page cut there would leave its last + * places unread while next_cursor goes on after them. So a page ends early, + * before that cut, and next_cursor goes on after the last place it holds. + */ +const PAGE_CHARS = 30_000; + +/** The fields a page carries only where a place has them, so an empty one costs nothing. */ +const FIELDS_WHEN_SET = ['address', 'lat', 'lng', 'google_place_id', 'website', 'phone'] as const; + +/** A saved place as a page lists it: id, name, status, its labels and the fields it has. */ +type CompactPlace = Record; + +/** One page of a list's places, next to what the list is and how far the filter reaches. */ +interface CollectionPlacesPage { + collection: { id: number; name: string }; + labels: Array<{ id: number; name: string; color: string | null }>; + /** Places of the list the filter matches, on every page. */ + total: number; + places: CompactPlace[]; + next_cursor: string | null; +} + +function compactPlace(row: CollectionPlacePageRow, labelIds: number[]): CompactPlace { + const place: CompactPlace = { id: row.id, name: row.name, status: row.status }; + if (labelIds.length > 0) place.label_ids = labelIds; + for (const field of FIELDS_WHEN_SET) { + const value = row[field]; + if (value !== null && value !== '') place[field] = value; + } + return place; +} + +/** The places of a page in order until their JSON would pass PAGE_CHARS; always at least one. */ +function fillPage(rows: CollectionPlacePageRow[], labelIds: Map): CompactPlace[] { + const page: CompactPlace[] = []; + let chars = 0; + for (const row of rows) { + const place = compactPlace(row, labelIds.get(row.id) ?? []); + chars += JSON.stringify(place).length + 1; + if (page.length > 0 && chars > PAGE_CHARS) break; + page.push(place); + } + return page; +} + +function positionOf(row: CollectionPlacePageRow): CollectionPlacePosition { + return { sortOrder: row.sort_key, createdAt: row.created_key, id: row.id }; +} + +/** + * A long list a page at a time (the list_collection_places tool, #2647). + * get_collection answers a list whole, every place with its full row, tags and + * every member's vote, which an MCP client cuts down to its first and last + * places on a long list. A page is the list's own order, compact, and goes on + * from a cursor: the position of its last place, so places that stop matching + * the filter in between (labelled while paging through the unlabelled ones) + * move none of the others. Read through the collections service's own access + * check, like get_collection. + */ +@Injectable() +export class CollectionsPlacesPageService { + constructor( + private readonly collections: CollectionsService, + @InjectRepository(Collections) private readonly collectionsRepo: CollectionsRepository, + @InjectRepository(CollectionLabels) private readonly labels: CollectionLabelsRepository, + ) {} + + async listPlaces(userId: number, request: CollectionPlacesPageRequest): Promise { + const { collectionId, status, labelId, unlabeled } = request; + await this.collections.assertAccess(userId, collectionId); + if (labelId !== undefined && unlabeled) { + throw new DomainError(400, 'Pass either labelId or unlabeled, not both'); + } + const after = this.positionAfter(request.cursor); + const labels = await this.labels.listByCollection(collectionId); + if (labelId !== undefined && !labels.some((label) => label.id === labelId)) { + throw new DomainError(404, 'Label not found in this list'); + } + + const filter = { status, labelId, unlabeled }; + const limit = request.limit ?? COLLECTION_PLACES_PAGE_DEFAULT; + const total = await this.collectionsRepo.countPlacePage(collectionId, filter); + // One place more than the page holds says whether another page follows. + const rows = await this.collectionsRepo.listPlacePage(collectionId, filter, after, limit + 1); + const candidates = rows.slice(0, limit); + const places = fillPage(candidates, await this.labelIdsOf(candidates.map((row) => row.id))); + const last = rows[places.length - 1]; + const collection = await this.collectionsRepo.findRow(collectionId); + return { + collection: { id: collectionId, name: collection?.name ?? '' }, + labels: labels.map(({ id, name, color }) => ({ id, name, color })), + total, + places, + next_cursor: places.length < rows.length && last ? encodePlacesCursor(positionOf(last)) : null, + }; + } + + /** Where a page starts: after the place the cursor names, or at the top without one. */ + private positionAfter(cursor: string | undefined): CollectionPlacePosition | null { + if (cursor === undefined) return null; + const position = decodePlacesCursor(cursor); + if (!position) throw new DomainError(400, 'Invalid cursor: pass the next_cursor of the page before'); + return position; + } + + /** Each place's label ids, in one read for the whole page. */ + private async labelIdsOf(placeIds: number[]): Promise> { + const byPlace = new Map(); + for (const { pid, label_id } of await this.collectionsRepo.loadLabelIdsByPlaceIds(placeIds)) { + byPlace.set(pid, [...(byPlace.get(pid) ?? []), label_id]); + } + return byPlace; + } +} diff --git a/server/src/nest/collections/collections.helpers.ts b/server/src/nest/collections/collections.helpers.ts index e8a0447b8..021df149c 100644 --- a/server/src/nest/collections/collections.helpers.ts +++ b/server/src/nest/collections/collections.helpers.ts @@ -1,5 +1,8 @@ +import type { CollectionPlacePosition } from '../../db/repositories/Collections.repository'; import type { CollectionLink, CollectionPlaceUpdateRequest } from '@trek/shared'; +import { z } from 'zod'; + /** * Pure helpers of the collections domain, moved verbatim out of * collections.service.ts. Nothing here touches the DB, so they stay plain @@ -48,3 +51,29 @@ export function listingWriteOf(body: CollectionPlaceUpdateRequest): ListingWrite if (body.currency !== undefined) write.currency = body.currency ?? null; return write; } + +/** A cursor as list_collection_places hands it out: the position of the last place of a page. */ +const placesCursorSchema = z.tuple([z.number().int(), z.string().max(40), z.number().int().positive()]); + +/** + * The cursor of the page after a place (#2647): its position in the list, so + * the next page starts right after it whatever changed in between. Opaque to + * the client, which passes it back as it came. + */ +export function encodePlacesCursor(position: CollectionPlacePosition): string { + return Buffer.from(JSON.stringify([position.sortOrder, position.createdAt, position.id])).toString('base64url'); +} + +/** The position a cursor names; null for anything encodePlacesCursor did not write. */ +export function decodePlacesCursor(cursor: string): CollectionPlacePosition | null { + let value: unknown; + try { + value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')); + } catch { + return null; + } + const parsed = placesCursorSchema.safeParse(value); + if (!parsed.success) return null; + const [sortOrder, createdAt, id] = parsed.data; + return { sortOrder, createdAt, id }; +} diff --git a/server/src/nest/collections/collections.mcp.ts b/server/src/nest/collections/collections.mcp.ts index c4a5acc52..58ce7ec68 100644 --- a/server/src/nest/collections/collections.mcp.ts +++ b/server/src/nest/collections/collections.mcp.ts @@ -10,11 +10,13 @@ import { TOOL_ANNOTATIONS_DELETE, TOOL_ANNOTATIONS_NON_IDEMPOTENT, ok, + okCompact, } from '../../nest-mcp'; import { addonGate } from '../addons/addon-gate'; import { AddonsService } from '../addons/addons.service'; import { McpToolGuardsService } from '../mcp-shared/mcp-tool-guards.service'; import { CollectionsItemsService } from './collections-items.service'; +import { CollectionsPlacesPageService } from './collections-places-page.service'; import { CollectionsService } from './collections.service'; import { InjectRepository } from '@mikro-orm/nestjs'; import { @@ -29,7 +31,10 @@ import { collectionInviteRequestSchema, collectionSetStatusFromTripRequestSchema, collectionItemsRequestSchema, + collectionPlacesPageRequestSchema, collectionLinkSchema, + COLLECTION_PLACES_PAGE_DEFAULT, + COLLECTION_PLACES_PAGE_MAX, COLLECTION_STATUSES, COLLECTION_ROLES, idSchema, @@ -46,6 +51,7 @@ import type { CollectionLabelAssignRequest, CollectionSetStatusFromTripRequest, CollectionItemsRequest, + CollectionPlacesPageRequest, CollectionStatus, CollectionRole, } from '@trek/shared'; @@ -90,6 +96,7 @@ export class CollectionsMcp { readonly addons: AddonsService, private readonly guards: McpToolGuardsService, private readonly items: CollectionsItemsService, + private readonly placesPage: CollectionsPlacesPageService, ) {} // ── Read ────────────────────────────────────────────────────────────── @@ -114,7 +121,7 @@ export class CollectionsMcp { @Tool({ name: 'get_collection', description: - 'Get one collection with its members, labels, and all saved places. Each place includes rating_avg / rating_count and the per-member ratings (#1435) so you can plan around highly-rated spots.', + 'Get one collection with its members, labels, and all saved places. Each place includes rating_avg / rating_count and the per-member ratings (#1435) so you can plan around highly-rated spots. For a long list, page through it with list_collection_places instead.', inputSchema: { collectionId: idSchema }, annotations: TOOL_ANNOTATIONS_READONLY, when: collectionsAddonOn, @@ -128,6 +135,23 @@ export class CollectionsMcp { } } + @Tool({ + name: 'list_collection_places', + description: `Page through one list's saved places in the list's own order (the order get_collection uses), ${COLLECTION_PLACES_PAGE_DEFAULT} at a time unless limit says otherwise (at most ${COLLECTION_PLACES_PAGE_MAX}). Each place as a compact row: id, name, status and label_ids, plus address, lat, lng, google_place_id, website and phone, every one left out when empty. Filter by status, by labelId (a label of this list) or with unlabeled: true for the places without any label. Next to the page: the list's labels, total (the places the filter matches) and next_cursor; pass it back as cursor for the next page, null on the last. A page of long rows can end before limit, so always go on at next_cursor. Labelling the places of a page while paging through unlabeled ones skips none. Pairs with assign_collection_labels and update_collection_place; get_collection_items reads a place in full.`, + inputSchema: collectionPlacesPageRequestSchema.shape, + annotations: TOOL_ANNOTATIONS_READONLY, + when: collectionsAddonOn, + access: { group: 'collections', mode: 'read' }, + }) + async listCollectionPlaces(request: CollectionPlacesPageRequest, ctx: McpContext) { + try { + // One line of JSON: the size of a long list is what this tool exists for (#2647). + return okCompact(await this.placesPage.listPlaces(ctx.userId, request)); + } catch (err) { + return fail(err); + } + } + @Tool({ name: 'available_collection_users', description: diff --git a/server/src/nest/collections/collections.module.ts b/server/src/nest/collections/collections.module.ts index 835b1fabf..4e8511155 100644 --- a/server/src/nest/collections/collections.module.ts +++ b/server/src/nest/collections/collections.module.ts @@ -22,6 +22,7 @@ import { buildStorageUploadOptions } from '../storage/storage-upload.factory'; import { StorageModule } from '../storage/storage.module'; import { StorageService } from '../storage/storage.service'; import { CollectionsItemsService } from './collections-items.service'; +import { CollectionsPlacesPageService } from './collections-places-page.service'; import { CollectionsStorageRefsService } from './collections-storage-refs.service'; import { CollectionsController } from './collections.controller'; import { MAX_COVER_SIZE } from './collections.controller'; @@ -81,6 +82,7 @@ import { MulterModule } from '@nestjs/platform-express'; providers: [ CollectionsService, CollectionsItemsService, + CollectionsPlacesPageService, CollectionsMcp, CollectionsRpc, CollectionsStorageRefsService, diff --git a/server/tests/unit/db/repositories/Collections.repository.test.ts b/server/tests/unit/db/repositories/Collections.repository.test.ts new file mode 100644 index 000000000..22f919063 --- /dev/null +++ b/server/tests/unit/db/repositories/Collections.repository.test.ts @@ -0,0 +1,150 @@ +/** + * `CollectionsRepository`: the order of a list's places and the pages + * list_collection_places reads it in (#2647). getCollection (listPlaceRows) + * and a page order the same way, sort_order, then created_at, then id, so two + * places saved in the same second keep one order; a page filters by status, + * label or "no label" and goes on after a position, not an offset. + * COLL-REPO-001 to COLL-REPO-005. + */ +import { CollectionLabels } from '../../../../src/db/entities/CollectionLabels.entity'; +import type { CollectionPlaces } from '../../../../src/db/entities/CollectionPlaces.entity'; +import { Collections } from '../../../../src/db/entities/Collections.entity'; +import type { + CollectionPlacePageRow, + CollectionsRepository, +} from '../../../../src/db/repositories/Collections.repository'; +import { createSnapshotTestDb } from '../../../helpers/db-mock'; +import { labelCollectionPlace, makeCollection, makeCollectionPlace } from '../../../helpers/factories/collections'; +import { createRow } from '../../../helpers/factories/rows'; +import { makeUser } from '../../../helpers/factories/users'; +import { resetTestDb } from '../../../helpers/test-db'; +import { createTestOrm, type TestOrm } from '../../../helpers/test-orm'; +import type { EntityData } from '@mikro-orm/core'; + +import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest'; + +const testDb = createSnapshotTestDb(); +let t: TestOrm; +let repo: CollectionsRepository; + +beforeAll(async () => { + t = await createTestOrm(testDb); + repo = t.repo(Collections); +}); +beforeEach(() => { + resetTestDb(testDb); + t.clear(); +}); +afterAll(async () => { + await t.close(); + testDb.close(); +}); + +const SAME_SECOND = '2026-05-01 10:00:00'; + +/** + * A list of five places: two saved in the same second at position 0, one saved + * earlier at position 0, one at position 1 and one whose position was never + * written (it reads as 0, after the earlier one by its created_at). + */ +async function seedList() { + const { user } = await makeUser(t); + const list = await makeCollection(t, user.id, { name: 'Paris' }); + const place = (name: string, overrides: EntityData) => + makeCollectionPlace(t, list.id, user.id, { name, ...overrides }); + const later = await place('Later', { sort_order: 1, created_at: '2026-04-01 09:00:00' }); + const tieA = await place('Tie A', { sort_order: 0, created_at: SAME_SECOND, status: 'want' }); + const tieB = await place('Tie B', { sort_order: 0, created_at: SAME_SECOND }); + const early = await place('Early', { sort_order: 0, created_at: '2026-03-01 08:00:00', status: 'want' }); + const unplaced = await place('Unplaced', { sort_order: null, created_at: '2026-03-15 08:00:00' }); + return { user, list, ids: { later: later.id, tieA: tieA.id, tieB: tieB.id, early: early.id, unplaced: unplaced.id } }; +} + +const names = (rows: Array>) => rows.map((row) => row.name); + +describe('CollectionsRepository: the order of a list', () => { + it('COLL-REPO-001: getCollection orders by position, then saving time, then id', async () => { + const { list } = await seedList(); + const rows = await repo.listPlaceRows(list.id); + expect(names(rows)).toEqual(['Early', 'Unplaced', 'Tie A', 'Tie B', 'Later']); + }); +}); + +describe('CollectionsRepository: a page of a list (#2647)', () => { + it('COLL-REPO-002: a page holds the list in that same order and goes on after the position it names', async () => { + const { list, ids } = await seedList(); + const first = await repo.listPlacePage(list.id, {}, null, 3); + expect(names(first)).toEqual(['Early', 'Unplaced', 'Tie A']); + // The position a page goes on from: the missing sort_order reads as 0. + expect(first[1]).toMatchObject({ id: ids.unplaced, sort_key: 0, created_key: '2026-03-15 08:00:00' }); + + const tieA = first[2]; + const rest = await repo.listPlacePage( + list.id, + {}, + { sortOrder: tieA.sort_key, createdAt: tieA.created_key, id: tieA.id }, + 3, + ); + expect(names(rest)).toEqual(['Tie B', 'Later']); + expect(await repo.countPlacePage(list.id, {})).toBe(5); + }); + + it('COLL-REPO-003: a page carries the fields an agent names a place by', async () => { + const { user } = await makeUser(t); + const list = await makeCollection(t, user.id); + await makeCollectionPlace(t, list.id, user.id, { + name: 'Septime', + address: '80 Rue de Charonne', + google_place_id: 'ChIJseptime', + website: 'https://septime-charonne.fr', + phone: '+33 1 43 67 38 29', + }); + const [row] = await repo.listPlacePage(list.id, {}, null, 10); + expect(row).toMatchObject({ + name: 'Septime', + status: 'idea', + address: '80 Rue de Charonne', + lat: 48.8566, + lng: 2.3522, + google_place_id: 'ChIJseptime', + website: 'https://septime-charonne.fr', + phone: '+33 1 43 67 38 29', + }); + }); + + it('COLL-REPO-004: filters by status and by label, and counts what the filter matches', async () => { + const { list, ids } = await seedList(); + const label = await createRow(t, CollectionLabels, { collection: list.id, name: 'Food' }); + await labelCollectionPlace(t, ids.tieB, label.id); + await labelCollectionPlace(t, ids.later, label.id); + + expect(names(await repo.listPlacePage(list.id, { status: 'want' }, null, 10))).toEqual(['Early', 'Tie A']); + expect(await repo.countPlacePage(list.id, { status: 'want' })).toBe(2); + expect(names(await repo.listPlacePage(list.id, { labelId: label.id }, null, 10))).toEqual(['Tie B', 'Later']); + expect(await repo.countPlacePage(list.id, { labelId: label.id })).toBe(2); + expect(names(await repo.listPlacePage(list.id, { unlabeled: true }, null, 10))).toEqual([ + 'Early', + 'Unplaced', + 'Tie A', + ]); + expect(await repo.countPlacePage(list.id, { unlabeled: true, status: 'want' })).toBe(2); + }); + + it('COLL-REPO-005: a place labelled after its page was read does not move the next page of unlabelled ones', async () => { + const { list, ids } = await seedList(); + const label = await createRow(t, CollectionLabels, { collection: list.id, name: 'Done' }); + const first = await repo.listPlacePage(list.id, { unlabeled: true }, null, 2); + expect(names(first)).toEqual(['Early', 'Unplaced']); + await labelCollectionPlace(t, ids.early, label.id); + await labelCollectionPlace(t, ids.unplaced, label.id); + + const last = first[1]; + const next = await repo.listPlacePage( + list.id, + { unlabeled: true }, + { sortOrder: last.sort_key, createdAt: last.created_key, id: last.id }, + 2, + ); + expect(names(next)).toEqual(['Tie A', 'Tie B']); + }); +}); diff --git a/server/tests/unit/mcp/tools-collections.test.ts b/server/tests/unit/mcp/tools-collections.test.ts index ec708fbe2..b923bad68 100644 --- a/server/tests/unit/mcp/tools-collections.test.ts +++ b/server/tests/unit/mcp/tools-collections.test.ts @@ -994,6 +994,140 @@ describe('Sharing tools', () => { }); }); +// --------------------------------------------------------------------------- +// list_collection_places (#2647): a long list a compact page at a time, going +// on from a cursor rather than an offset. +// --------------------------------------------------------------------------- + +describe('Tool: list_collection_places', () => { + interface Page { + collection: { id: number; name: string }; + labels: { id: number; name: string; color: string | null }[]; + total: number; + places: Record[]; + next_cursor: string | null; + } + + async function listPage(h: McpHarness, args: Record): Promise { + const result = await h.client.callTool({ name: 'list_collection_places', arguments: args }); + expect(result.isError).toBeFalsy(); + // Compact on purpose: one line of JSON, however long the page. + expect(errorText(result)).not.toContain('\n'); + return parseToolResult(result) as Page; + } + + async function seedPlaces(colId: number, ownerId: number, count: number): Promise { + const ids: number[] = []; + for (let i = 1; i <= count; i++) ids.push(await seedPlace(colId, ownerId, `Spot ${i}`)); + return ids; + } + + it('MCP-COLL-PAGE-001: pages through a list in its order, compact rows leaving out what a place lacks', async () => { + const { user } = createUser(testDb); + const col = await seedCollection(user.id, 'Paris'); + await seedPlaces(col, user.id, 4); + await seedPlace(col, user.id, 'Septime', { lat: 48.85, lng: 2.38, status: 'want', google_place_id: 'ChIJseptime' }); + const food = await insertRow(orm, CollectionLabels, { collection: col, name: 'Food', color: '#e11d48' }); + + await withHarness(user.id, async (h) => { + const first = await listPage(h, { collectionId: col, limit: 2 }); + expect(first.collection).toEqual({ id: col, name: 'Paris' }); + expect(first.labels).toEqual([{ id: food, name: 'Food', color: '#e11d48' }]); + expect(first.total).toBe(5); + expect(first.places).toEqual([ + { id: expect.any(Number), name: 'Spot 1', status: 'idea' }, + { id: expect.any(Number), name: 'Spot 2', status: 'idea' }, + ]); + expect(first.next_cursor).toEqual(expect.any(String)); + + const second = await listPage(h, { collectionId: col, limit: 2, cursor: first.next_cursor }); + expect(second.places.map((p) => p.name)).toEqual(['Spot 3', 'Spot 4']); + + const last = await listPage(h, { collectionId: col, limit: 2, cursor: second.next_cursor }); + expect(last.places).toEqual([ + { + id: expect.any(Number), + name: 'Septime', + status: 'want', + lat: 48.85, + lng: 2.38, + google_place_id: 'ChIJseptime', + }, + ]); + expect(last.next_cursor).toBeNull(); + }); + }); + + it('MCP-COLL-PAGE-002: labelling each page while paging through the unlabeled places skips none', async () => { + const { user } = createUser(testDb); + const col = await seedCollection(user.id, 'Long list'); + const ids = await seedPlaces(col, user.id, 6); + const done = await insertRow(orm, CollectionLabels, { collection: col, name: 'Done' }); + + await withHarness(user.id, async (h) => { + const seen: unknown[] = []; + const totals: number[] = []; + let cursor: string | null = null; + do { + const page = await listPage(h, { collectionId: col, limit: 2, unlabeled: true, ...(cursor ? { cursor } : {}) }); + totals.push(page.total); + seen.push(...page.places.map((p) => p.id)); + const labelled = await h.client.callTool({ + name: 'assign_collection_labels', + arguments: { label_ids: [done], place_ids: page.places.map((p) => p.id) }, + }); + expect(labelled.isError).toBeFalsy(); + cursor = page.next_cursor; + } while (cursor); + // An offset would have jumped from the second place straight to the fifth. + expect(seen).toEqual(ids); + expect(totals).toEqual([6, 4, 2]); + + const labelled = await listPage(h, { collectionId: col, labelId: done }); + expect(labelled.total).toBe(6); + expect(labelled.places.every((p) => (p.label_ids as number[]).includes(done))).toBe(true); + }); + }); + + it('MCP-COLL-PAGE-003: filters by status, and refuses a foreign label, both label filters at once and a made-up cursor', async () => { + const { user } = createUser(testDb); + const { user: other } = createUser(testDb); + const col = await seedCollection(user.id, 'Paris'); + const elsewhere = await seedCollection(other.id, 'Theirs'); + await seedPlace(col, user.id, 'Louvre', { status: 'visited' }); + await seedPlace(col, user.id, 'Orsay', { status: 'revisit' }); + const theirs = await insertRow(orm, CollectionLabels, { collection: elsewhere, name: 'Theirs' }); + const mine = await insertRow(orm, CollectionLabels, { collection: col, name: 'Mine' }); + + await withHarness(user.id, async (h) => { + const revisit = await listPage(h, { collectionId: col, status: 'revisit' }); + expect(revisit.total).toBe(1); + expect(revisit.places.map((p) => p.name)).toEqual(['Orsay']); + + const call = (args: Record) => + h.client.callTool({ name: 'list_collection_places', arguments: { collectionId: col, ...args } }); + const foreign = await call({ labelId: theirs }); + expect(foreign.isError).toBe(true); + expect(errorText(foreign)).toBe('Label not found in this list'); + expect(errorText(await call({ labelId: mine, unlabeled: true }))).toBe( + 'Pass either labelId or unlabeled, not both', + ); + expect(errorText(await call({ cursor: 'not-a-cursor' }))).toBe( + 'Invalid cursor: pass the next_cursor of the page before', + ); + expect((await call({ limit: 501 })).isError).toBe(true); + + // A list the caller cannot see answers as if it did not exist. + const hidden = await h.client.callTool({ + name: 'list_collection_places', + arguments: { collectionId: elsewhere }, + }); + expect(hidden.isError).toBe(true); + expect(errorText(hidden)).toBe('Collection not found'); + }); + }); +}); + // --------------------------------------------------------------------------- // Scope gating (collections read/write, registration-time) // --------------------------------------------------------------------------- @@ -1001,6 +1135,7 @@ describe('Sharing tools', () => { const READ_TOOLS = [ 'list_collections', 'get_collection', + 'list_collection_places', 'get_collection_items', 'available_collection_users', 'find_place_in_collections', @@ -1041,7 +1176,7 @@ describe('Collection tools — scope gating', () => { } } - it('registers all 28 tools with null scopes (full access)', async () => { + it('registers all 29 tools with null scopes (full access)', async () => { const { user } = createUser(testDb); const names = await listToolNames(user.id, null); for (const tool of [...READ_TOOLS, ...WRITE_TOOLS]) expect(names).toContain(tool); diff --git a/server/tests/unit/nest-mcp/helpers.test.ts b/server/tests/unit/nest-mcp/helpers.test.ts index 31c17d4ef..36664cd30 100644 --- a/server/tests/unit/nest-mcp/helpers.test.ts +++ b/server/tests/unit/nest-mcp/helpers.test.ts @@ -2,6 +2,7 @@ import { demoDenied, errorResult, ok, + okCompact, TOOL_ANNOTATIONS_DELETE, TOOL_ANNOTATIONS_NON_IDEMPOTENT, TOOL_ANNOTATIONS_OPEN_WORLD_NON_IDEMPOTENT, @@ -19,6 +20,12 @@ describe('result helpers', () => { expect('isError' in result).toBe(false); }); + it('okCompact() wraps data as one line of JSON, without isError', () => { + const result = okCompact({ a: 1, b: [2, 3] }); + expect(result).toEqual({ content: [{ type: 'text', text: '{"a":1,"b":[2,3]}' }] }); + expect('isError' in result).toBe(false); + }); + it('errorResult() carries the message verbatim with isError', () => { expect(errorResult('Tag not found.')).toEqual({ content: [{ type: 'text', text: 'Tag not found.' }], diff --git a/server/tests/unit/nest/collections.helpers.test.ts b/server/tests/unit/nest/collections.helpers.test.ts index 738d6cbfd..d8f0b9305 100644 --- a/server/tests/unit/nest/collections.helpers.test.ts +++ b/server/tests/unit/nest/collections.helpers.test.ts @@ -1,9 +1,16 @@ /** * The pure helpers of the collections domain: the link helpers, which read and - * write the JSON TEXT column a list or a saved place keeps its links in, and the - * listing fields an update writes. COLLECTIONS-HELPERS-001 to 005. + * write the JSON TEXT column a list or a saved place keeps its links in, the + * listing fields an update writes, and the cursor of a page of places. + * COLLECTIONS-HELPERS-001 to 007. */ -import { listingWriteOf, parseLinks, serializeLinks } from '../../../src/nest/collections/collections.helpers'; +import { + decodePlacesCursor, + encodePlacesCursor, + listingWriteOf, + parseLinks, + serializeLinks, +} from '../../../src/nest/collections/collections.helpers'; import { describe, expect, it } from 'vitest'; @@ -58,3 +65,27 @@ describe('listingWriteOf', () => { expect(listingWriteOf({ website: undefined, phone: '+33 1' })).toEqual({ phone: '+33 1' }); }); }); + +describe('encodePlacesCursor / decodePlacesCursor', () => { + it('COLLECTIONS-HELPERS-006: a cursor gives back the position it was made from', () => { + const position = { sortOrder: 3, createdAt: '2026-05-01 10:00:00', id: 42 }; + const cursor = encodePlacesCursor(position); + expect(cursor).toMatch(/^[A-Za-z0-9_-]+$/); + expect(decodePlacesCursor(cursor)).toEqual(position); + expect(decodePlacesCursor(encodePlacesCursor({ sortOrder: -1, createdAt: '', id: 1 }))).toEqual({ + sortOrder: -1, + createdAt: '', + id: 1, + }); + }); + + it('COLLECTIONS-HELPERS-007: anything else reads as no position', () => { + const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url'); + expect(decodePlacesCursor('not-a-cursor')).toBeNull(); + expect(decodePlacesCursor('')).toBeNull(); + expect(decodePlacesCursor(encode({ id: 1 }))).toBeNull(); + expect(decodePlacesCursor(encode([0, '2026-05-01 10:00:00']))).toBeNull(); + expect(decodePlacesCursor(encode([0.5, '2026-05-01 10:00:00', 1]))).toBeNull(); + expect(decodePlacesCursor(encode([0, '2026-05-01 10:00:00', 0]))).toBeNull(); + }); +}); diff --git a/shared/src/collection/collection.schema.spec.ts b/shared/src/collection/collection.schema.spec.ts index 8bec2b4d2..4c1f78d0c 100644 --- a/shared/src/collection/collection.schema.spec.ts +++ b/shared/src/collection/collection.schema.spec.ts @@ -2,8 +2,10 @@ import { collectionDeleteManyRequestSchema, collectionItemsRequestSchema, collectionMembershipSchema, + collectionPlacesPageRequestSchema, collectionPlaceUpdateRequestSchema, collectionReorderRequestSchema, + COLLECTION_PLACES_PAGE_DEFAULT, collectionSavePlaceRequestSchema, collectionStatusSchema, isVisitedCollectionStatus, @@ -134,3 +136,28 @@ describe('collectionMembershipSchema', () => { expect(collectionMembershipSchema.parse({ saved: true, lists: [list] }).lists[0]?.color).toBeUndefined(); }); }); + +describe('collectionPlacesPageRequestSchema', () => { + // #2647: a page of a list for list_collection_places. + it('takes a list alone, or a cursor, a limit of 1 to 500 and the filters', () => { + expect(collectionPlacesPageRequestSchema.safeParse({ collectionId: 4 }).success).toBe(true); + const full = { + collectionId: 4, + cursor: 'WzAsIiIsMV0', + limit: 500, + status: 'revisit', + labelId: 7, + unlabeled: false, + }; + expect(collectionPlacesPageRequestSchema.parse(full)).toEqual(full); + for (const page of [ + {}, + { collectionId: 4, limit: 0 }, + { collectionId: 4, limit: 501 }, + { collectionId: 4, status: 'gone' }, + ]) { + expect(collectionPlacesPageRequestSchema.safeParse(page).success, JSON.stringify(page)).toBe(false); + } + expect(COLLECTION_PLACES_PAGE_DEFAULT).toBe(100); + }); +}); diff --git a/shared/src/collection/collection.schema.ts b/shared/src/collection/collection.schema.ts index e30106fe3..ac945511f 100644 --- a/shared/src/collection/collection.schema.ts +++ b/shared/src/collection/collection.schema.ts @@ -294,6 +294,38 @@ export const collectionItemsRequestSchema = z.object({ }); export type CollectionItemsRequest = z.infer; +export const COLLECTION_PLACES_PAGE_DEFAULT = 100; +export const COLLECTION_PLACES_PAGE_MAX = 500; + +/** + * One page of a list's places for an MCP client (list_collection_places, #2647): + * get_collection answers a long list as one block a client cuts in the middle. + * Pages follow the list's own order and continue from a cursor rather than an + * offset, so labelling the places of one page while filtering on `unlabeled` + * cannot make the next page skip any. + */ +export const collectionPlacesPageRequestSchema = z.object({ + collectionId: idSchema, + cursor: z + .string() + .max(200) + .optional() + .describe('Where to go on: the next_cursor of the page before. Leave it out for the first page.'), + limit: z + .number() + .int() + .min(1) + .max(COLLECTION_PLACES_PAGE_MAX) + .optional() + .describe( + `How many places at most (default ${COLLECTION_PLACES_PAGE_DEFAULT}, at most ${COLLECTION_PLACES_PAGE_MAX})`, + ), + status: z.enum(COLLECTION_STATUSES).optional().describe('Only places with this status'), + labelId: idSchema.optional().describe('Only places carrying this label of the list'), + unlabeled: z.boolean().optional().describe('true: only places without any label. Not together with labelId.'), +}); +export type CollectionPlacesPageRequest = z.infer; + // Fusion invitations. user_id is NUMERIC ONLY — the UI always sends an id from availableUsers. export const collectionInviteRequestSchema = z.object({ collection_id: z.number(), diff --git a/wiki/MCP-Addon-Tools.md b/wiki/MCP-Addon-Tools.md index 01b30787c..b9e51dcfe 100644 --- a/wiki/MCP-Addon-Tools.md +++ b/wiki/MCP-Addon-Tools.md @@ -102,6 +102,7 @@ Requires `collections:read` or `collections:write` scope. |---|---| | `list_collections` | List the saved-place collections the user owns or has accepted a share for, plus any pending incoming invites. | | `get_collection` | Get one collection with its members, labels, and all saved places, including the average rating and each member's vote. | +| `list_collection_places` | Page through one list's saved places in the list's own order, up to 500 at a time (100 by default), as compact rows: id, name, status and label ids, plus address, coordinates, Google place id, website and phone where set. Filter by `status`, by `labelId` or with `unlabeled: true`. Each page names the list's labels, the total the filter matches and a `next_cursor` to continue with, so labelling the places of a page while paging through the unlabelled ones skips none. | | `available_collection_users` | List users who can still be invited to a collection (excludes current members and guests). | | `find_place_in_collections` | Answer whether a place is already on one of your lists, across the whole library in one call, naming each list and the status the place has there. Identify the place by `google_place_id` / `google_ftid` from `search_place` or by `lat` + `lng`; a name alone is never matched. | | `get_collection_items` | Read saved places and labels by their own ids across every list you can see, without loading whole lists: each place with its status, labels, rating and notes, and the lists they sit in with their colour, size, labels, members (names and roles only) and whether you may delete places from them. Saved place ids are not trip place ids. Ids you cannot see are left out. |