Skip to content

feat(server): write a source's link parameters into the page's query string - #640

Merged
eizedev merged 6 commits into
mainfrom
feat/link-params-query
Nov 19, 2026
Merged

eizedev merged 6 commits into
mainfrom
feat/link-params-query

Conversation

@eizedev

@eizedev eizedev commented Nov 19, 2026

Copy link
Copy Markdown
Owner

Fixes #619

create_link writes a source's parameters into the page's query string, such as ?customer=acme. The view stays in the fragment. A host application's backend can read the query. Record 0016 is set to accepted.

What changes

  • sources.<id>.linkParams lists the parameters a link may carry, per source. The values go into the query string of sources.<id>.link.
  • With a list, create_link (MCP and POST /views/link) refuses any other parameter with INVALID_INPUT and names the allowed ones. The check runs after the access check, so a source the caller may not use still answers as a missing one.
  • Without a list, create_link works as before: it reads the params and the link carries none.
  • The server does not start with a list that names a claim-bound parameter, an undeclared one, a duplicate, or leaves out a required one. A list also needs link and params. check-config prints the list under the source's link.
  • The values pass the source's parameter rules on every request. The link holds the value the server wrote again, never a claim's value or a default.
  • A query the configured page address holds stays byte for byte. A name the link sets replaces every entry of that name. A hash route keeps its own ?.
  • GET /sources and list_sources name the list as linkParams. The create_link tool description changed, so MCP clients reconnect.
  • The new module is packages/pivotkit-server/src/link-params.js.

Docs

  • concepts/sharing.md#link-params: where parameters travel, a full configuration example, and how the query relates to the fragment's src.params and allowParams. The host page applies "the query wins" and passes on only the listed names. A snippet shows how.
  • security.md#link-params: query values land in access logs, history and the Referer header. List only parameters whose values may show up there. The host page sends Referrer-Policy: same-origin or no-referrer.
  • MCP and REST references, sources, OpenAPI, upgrading page, what reaches a model, features, the PSU getting-started section, changelogs of pivotkit-server, pivotkit-mcp and pivotkit-report, and the server's AGENTS.md.

Docs checked: I searched docs/ and the package READMEs for create_link, views/link, linkKey, allowParams and src.params.

Tests

  • packages/pivotkit-server/test/link-params.test.js (10 tests): an allowed parameter lands in the query; encoding of & # + space ü; an existing query and hash route stay; another, unknown or claim-bound parameter and bad values are refused; a hidden source answers like a missing one; no list keeps today's behaviour; the configuration refusals; GET /sources and REST end to end; check-config.
  • An MCP protocol test runs list_sources and create_link with params over Streamable HTTP.
  • The server tests failed before the code (8 of 9; the "no list" test passed, as intended).
  • Local runs on macOS: npm run lint, npm run types, the tests of pivotkit-server (779), pivotkit-mcp (100), pivotkit-report (109) and the repository tests (110), npm run pack:check, zensical build --strict. Linux, Windows, the browser suite and the container image run only in CI.

Merge order

The upgrading section uses the heading "From 0.8.2 to the next release", the same one the rows route uses. It expects the 0.8.2 release first. This change and the rows route both touch config.js, present.js, docs/openapi.json, the upgrading page, security.md, rest.md, sources.md and the server changelog. The second of the two to merge needs a merge of main and node scripts/openapi.js.

Not in this change

  • A signal when create_link gets params for a source without a list. Today the link carries none, silently.
  • check-config warnings about exposure, such as a listed name that the page address already holds in its query.
  • A helper in pivotkit-core/link that merges the query and the fragment.

🤖 Generated with Claude Code

eizedev and others added 4 commits November 19, 2026 03:39
…string

create_link takes the parameters a source lists in sources.<id>.linkParams
and writes their checked values into the query string of the source's
page. The view stays in the fragment. Any other parameter answers
INVALID_INPUT and names the allowed ones; a claim-bound one never goes into
a link. A query the page address holds stays. GET /sources and
list_sources name the list, check-config prints it. Record 0016 is
accepted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… applies the query rules

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, the REST texts

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
eizedev and others added 2 commits November 19, 2026 08:41
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eizedev
eizedev merged commit e54a5fb into main Nov 19, 2026
21 checks passed
@eizedev
eizedev deleted the feat/link-params-query branch November 19, 2026 08:53
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.

report, mcp: create_link writes source parameters into the page's query string

1 participant