Skip to content

feat(server): named views per source, and a layout for create_link and draft_schedule - #643

Open
eizedev wants to merge 7 commits into
mainfrom
feat/named-views
Open

eizedev wants to merge 7 commits into
mainfrom
feat/named-views

Conversation

@eizedev

@eizedev eizedev commented Nov 19, 2026

Copy link
Copy Markdown
Owner

Fixes #616
Fixes #469

An operator can publish named views per source. render_view, create_link and draft_schedule take a view's name as view. create_link and draft_schedule also take a layout, as render_view does.

Named views (#616)

  • sources.<id>.views maps a name to a view file's path or to a view written in place.
  • sources.<id>.viewsDir is a folder of view files. A file the browser downloads (by-region.pivotkit.json) works as it is and becomes the view by-region.
  • The files are read on every request, the way print templates are. A request for one view reads only that file.
  • list_sources and describe_source (MCP and REST) list each view's name, title and description.
  • validate_view and describe_view take the view itself, not a name.
  • The start and check-config read every view. A file that is no view stops the start, as a broken template does. A missing file or folder starts the server with a PROBLEM.
  • check-config has a "Named views" section with the fields each view needs. For a file source it warns about a field the data does not have.
  • At most 100 views per source and 256 KiB per file.

What a caller learns follows the policy:

  • A view that uses a field hidden from the caller is not listed. Its name answers like a name that does not exist, and "did you mean" never offers it.
  • A link and a draft carry the view. A view that holds values of a field the caller sees at summary gets no link or draft (NOT_ALLOWED). Values are filter items, a custom sort order, collapsed groups, and hidden series or series colours of the chart. That check runs after the data is read, so a field at values counts as listed.
  • render_view makes the report as a file, as for any view.

The issue asked whether describe_source's example views could carry this. They cannot. list_sources reads no data, while the examples are built per call from the loaded fields. They also have no stable name to pass back. So the views get their own views key.

The rows route part of the #616 comment needs the records route of #635. findNamedView in views.js is the lookup that route can call. I wrote that part up for a follow-up issue.

A layout in create_link and draft_schedule (#469)

  • Both operations take exactly one of view or layout, through the existing viewOrLayout.
  • NO_LINK and NOT_SCHEDULABLE still come first.
  • The MCP placeholder layout that refused every layout is gone, and with it VIEW_ONLY.
  • The MCP protocol test that asserted the refusal tested the old behaviour. It now checks that a layout with groups works and that neither or both are refused.

MCP tool schemas and descriptions changed, so the upgrading page says to reconnect MCP clients.

Tests

  • New: packages/pivotkit-server/test/named-views.test.js (10 tests), one operations test in pivotkit-report, and two MCP protocol tests. They failed before the code.
  • Local runs on macOS: npm run lint, npm run types, pivotkit-server (779), pivotkit-mcp (100), pivotkit-report (110), the repository tests (110), npm run pack:check, zensical build --strict.
  • Linux, Windows, the browser suite and the container image run only in CI.

Docs checked: I searched docs/, the package READMEs, the skill and the AGENTS files for create_link, draft_schedule, layout, list_sources, describe_source and print templates. Changed: reference/sources.md (new "Named views" section), reference/mcp.md, reference/rest.md, reference/report.md, concepts/limits.md, features.md, model-data.md, privacy.md, security.md, the upgrading page, docs/openapi.json, the skill and MCP instructions, the server README, the server and MCP AGENTS files, and the changelogs of pivotkit-server, pivotkit-mcp and pivotkit-report.

Merge order

This uses the upgrading heading "From 0.8.2 to the next release", like #635 and #640, so it expects the 0.8.2 release (#634) first. It overlaps with #635 and #640 in present.js, registry.js, config.js, the upgrading page, the reference pages, the server changelog and docs/openapi.json. The later one to merge needs a merge of main and node scripts/openapi.js.

🤖 Generated with Claude Code

eizedev and others added 6 commits November 19, 2026 04:18
Sources take views (a name to a view file or a view) and viewsDir (a folder
of view files). list_sources and describe_source name them; render_view,
create_link and draft_schedule take a view by its name. create_link and
draft_schedule take a layout as render_view does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nce, clearer names

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e run, count chart colours

A link or draft of a named view is checked with the policy bound to the
data's statistics, so a field at values counts as listed. Series colours
of a chart count as values. Views over the limit are left out instead of
stopping the start. Docs name named views in security and privacy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

server: operator-published named views per source MCP: accept layout in create_link and draft_schedule

1 participant