> For the complete documentation index, see [llms.txt](https://mcp.conserver.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mcp.conserver.io/reference/changelog.md).

# Changelog

All notable changes to the vCon MCP Server will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## \[Unreleased]

### Migrations

* `20261109163739_revoke_anon_read_paths.sql` closes the paths that let the `anon` role read vCon rows past row-level security. Idempotent; apply with `supabase db push`.
  * `anon` can no longer read the `vcons_legacy` and `vcon_field_usage` views or the `vcon_tags_mv` materialized view, and `PUBLIC` loses `vcon_tags_mv`. `authenticated` keeps `vcon_tags_mv` because the tag search RPCs read it
  * `anon`, `authenticated` and `PUBLIC` can no longer execute `exec_sql`, `explain_query`, `set_tenant_context`, `clear_tenant_context`, `get_connection_metrics`, `get_index_health`, `get_performance_metrics` or `get_storage_efficiency`. `service_role` keeps them
  * `vcons_legacy` and `vcon_field_usage` run with the caller's privileges (`security_invoker`, PostgreSQL 15 or later), so an `authenticated` caller sees only the rows its tenant policy allows. On older servers the views are left unchanged
  * `anon` loses every table and function in `public`, and tables and functions that `postgres` creates there later grant it nothing. Functions that belong to an extension installed in `public` are left alone. Where `authenticated` or `service_role` could execute a function only through the default `PUBLIC` grant, the migration grants it to them explicitly
  * PostgreSQL grants `EXECUTE` on every new function to `PUBLIC`, and a per-schema default cannot remove that. A migration that adds a function should end with `REVOKE EXECUTE ON FUNCTION ... FROM PUBLIC, anon`; `supabase/tests/anon_lockdown.sql` fails if one is missed
  * Applies to `public` only. Per-group schemas made earlier with `scripts/bootstrap-schema.sh` keep their old grants until the same revokes are applied in that schema
* `20261112120000_keep_stored_tenant.sql` changes `save_vcon_batch` for every deployment: a re-post of a stored uuid no longer changes its `tenant_id`. Before, a service-key re-post with no tenant moved a stamped vCon and all its children to NULL, and a re-post stamped for another tenant moved them there. A vCon stored with a NULL tenant still takes the re-post's tenant. Everything else in a re-post is written as before. Deployments that never set a tenant see no change. A direct `UPDATE vcons SET tenant_id` still works
  * Adds `release_vcon_from_quarantine(uuid, tenant, reason, evidence, released_by)` and the append-only table `tenant_quarantine_releases`, both `service_role` only. Nothing calls them unless `TENANT_MODE=writer` has stored a vCon under `_quarantine`
* `20261112120100_fix_tenant_backfill.sql`
  * `backfill_tenant_id_batch('s3_sync_tracking', n)` no longer fails with `column s3.id does not exist`. The function is now `service_role` only; `authenticated` loses `EXECUTE`
  * Adds `backfill_vcon_tenant_ids(batch_size, writer_rule)` and `vcon_tenant_stamp(vcon_id, strict)`, `service_role` only. They correct what `20251202180000_backfill_tenant_ids.sql` did once: read `purpose` as well as `type`, and skip a body that is not JSON instead of aborting. They are called by an operator; applying the migration changes no stored tenant

### Security

* Deployments that run the server with `SUPABASE_ANON_KEY` instead of `SUPABASE_SERVICE_ROLE_KEY` lose the `exec_sql` and `explain_query` routes: analytics, tag and schema discovery, database inspection, query plans and health metrics. Tables already returned no rows to `anon`, so switch to the service role key
* The table and function revokes cover the whole `public` schema. If `public` also holds another application's objects that rely on `anon`, review them before applying. Other database roles that called `public` functions only through the default `PUBLIC` grant need an explicit `GRANT EXECUTE`
* `scripts/bootstrap-schema.sh` no longer grants anything to `anon` in a new schema (it granted `ALL` on tables, sequences and functions, plus matching default privileges), revokes the default `PUBLIC` execute grant there, and leaves the `SECURITY DEFINER` helpers to `service_role`

### Added

* `scripts/test-anon-lockdown.sh` applies the migration chain to a throwaway Postgres behind a real PostgREST and checks that `anon` is refused on each closed path, before and after the migration and on a re-run, that `service_role` and `authenticated` see what they saw before, and that a schema cloned by `bootstrap-schema.sh` gives `anon` nothing. Needs PostgreSQL 15+ server binaries; downloads PostgREST once
* `supabase/tests/anon_lockdown.sql` runs the same grants as catalog and `SET ROLE` checks against any migrated database
* `TENANT_MODE` environment variable: `off` (default when unset), `writer` or `lane`. An unknown value stops startup; unset keeps today's behaviour
* `TENANT_MODE=writer`: needs `SUPABASE_SERVICE_ROLE_KEY` and the Supabase backend. Reads the tenant stamp on every vCon it stores whatever `RLS_ENABLED` says, stores a missing, malformed or conflicting stamp under `_quarantine` (where `RLS_ENABLED=true` kept the first of two ids silently), and refreshes `vcon_tags_mv` at start and every `TAGS_MV_REFRESH_INTERVAL_MS` (default 60000). See `docs/guide/rls-multi-tenant.md`
  * Refuses to start with `CURRENT_TENANT_ID` set: the writer serves every tenant, and the session tenant it sets outlives a request on a pooled connection and reaches other callers. With `TENANT_MODE` unset, `CURRENT_TENANT_ID` works as before
  * Refuses to start with `TENANT_ATTACHMENT_TYPE` or `TENANT_JSON_PATH` set to anything but `tenant` and `id`, so the TypeScript rule and the SQL backfill cannot differ
  * Refuses to start unless `save_vcon_batch` and `20261112120000_keep_stored_tenant.sql` are in the store; the probe writes nothing. Never takes the non-atomic per-table fallback, whose plain upsert overwrites a stored tenant: if `save_vcon_batch` is missing at write time the write fails with an error
  * Logs a warning (uuid, stored tenant, stamped tenant) when a re-post kept a stored tenant different from its stamp. One read per batch, after the commit
* `scripts/test-tenant-writer.sh` proves both migrations on a throwaway Postgres: re-posts keep the stored tenant, the release function and its log, both backfills, a re-run, and the anon lockdown checks. `VCON_SQL_TESTS=1` runs it from vitest
* `TENANT_MODE=lane` serves many tenants of a row-level store from one process that holds no store key. See `docs/guide/tenant-lane.md`
  * refuses to start with `SUPABASE_SERVICE_ROLE_KEY` or `SUPABASE_ANON_KEY` set, on stdio, or without `MCP_HTTP_STATELESS=true`
  * each request must carry `Authorization: Bearer <jwt>` with `role: authenticated` and a `tenant_id` claim. A request without one gets 401 before any store call. The lane builds a store client per request and sends that token, and nothing else, as `apikey` and `Authorization` to its own PostgREST, which verifies it
  * serves `search_vcons`, `search_vcons_content`, `search_vcons_semantic`, `get_vcon` and `delete_vcon`. Every other tool, every resource and prompt, and every REST route but health are refused. Plugins and the Redis cache are off, and the tag view is never refreshed through a lane: the writer's timer keeps it current
  * `delete_vcon` reports not found when the delete removed no row
  * a token its PostgREST refuses with HTTP 401 (expired, bad signature, no anonymous access) gives the tool error `Unauthorized: the store refused this request's token (HTTP 401)`, which never holds the token or the store's text
  * `search_vcons_semantic` with query text needs `EMBEDDING_PROVIDER=openai` in a lane, since the default provider calls its edge function with the service key
  * logs the token's `tenant_id`, never the bearer
* `supabase/strict/`, the strict tenant pack: opt-in SQL that makes row-level security fail closed for multi-tenant deployments. `supabase db push` does not apply it. Run `supabase/strict/apply.sh`, which applies it and a catalog guard in one transaction, refuses while any tenant table holds a row with no tenant or a child whose tenant differs from its vCon's, and changes nothing on a second run. Re-run it after every upgrade; `apply.sh --check` runs the guard alone. See `docs/guide/strict-tenant-pack.md`
  * one policy per tenant table, for `authenticated`, with no NULL branch; RLS forced
  * tenant roles read and delete only: `authenticated` keeps `SELECT` and `DELETE` on the tenant tables and `SELECT` on views, and executes no `VOLATILE` function (`save_vcon_batch`, `remove_vcon_child_and_compact` and the other write RPCs, plus three read-only helpers declared `VOLATILE`: `get_vcon_embeddings`, `get_unsynced_vcons`, `check_vcon_embeddings_complete`). `PUBLIC`, `anon` and `authenticated` lose `TRUNCATE`, `TRIGGER`, `REFERENCES` and `MAINTAIN` on every table and view, also by default for tables `postgres` creates later. `child_refresh_conversation_start()` runs as its owner so a tenant's delete still refreshes `conversation_start`: `SECURITY DEFINER`, `search_path` pinned to `public, pg_temp`, an owner with `BYPASSRLS`, no `EXECUTE` for tenant roles. The guard checks all four
  * `get_current_tenant_id()` reads the JWT `tenant_id` claim only; no claim, an empty claim and `_quarantine` mean no tenant, and the `app.current_tenant_id` fallback is gone
  * `vcon_tags_scoped`, a tenant-filtered view over `vcon_tags_mv`; `authenticated` loses `vcon_tags_mv` and the refresh functions, and the twelve search and tag RPCs read the scoped view with no NULL branch. `search_vcons_by_tags_and_date` and its count gain a tenant predicate, so the service role gets rows from them only with a tenant claim
  * `tenant_id` `NOT NULL` and never empty on all ten tenant tables
  * composite keys: each child references its parent by `(id, tenant_id)`
  * `authenticated` loses `vkong.vcons`; the always-false `embedding_queue` policy is dropped
  * functions meant for `service_role` only (`exec_sql`, the tag refresh, the tenant backfills, `vcon_tenant_stamp`, `release_vcon_from_quarantine` and others) are taken back from `anon` and `authenticated` if a later grant reopened one
  * with the pack applied, a write whose `vcons` row has no `tenant_id` fails with a not-null error, a `save_vcon_batch` re-post included; `TENANT_MODE=writer` always stamps one
  * the catalog guard also fails on those privileges, on a reachable `VOLATILE` function, and on a NULL-tolerant tenant test in a reachable function: `IS NULL`, `IS [NOT] DISTINCT FROM`, `COALESCE` or `NULLIF` around the tenant, or a comparison with `''`. It pins the owner of `vcon_tags_scoped`
  * with the service key and no `tenant_id` claim, every rewritten search RPC returns nothing: `search_vcons_content`, `search_vcons_semantic`, `search_vcons_hybrid`, `search_by_tags`, `search_vcons` with tags or a dealer filter, `vcon_search`, `vcon_aggregate` and the matching REST routes. The guide lists each
  * the first apply scans every tenant table under `ACCESS EXCLUSIVE` locks in one transaction; apply it in a maintenance window
  * `apply.sh` takes the connection string from `DATABASE_URL` or `--url-file`, not from its arguments, and hands the password to `psql` in `PGPASSWORD`
* `tests/tenant-isolation/`: a REST-level tenant isolation harness on a throwaway PostgreSQL 17 with pgvector and PostgREST 16.2 in Docker, with signed JWTs and a canary per tenant. `npm run test:tenant` (strict pack), `npm run test:tenant:baseline` (unmodified schema, asserts the known leaks) and `npm run test:tenant:guard` (apply script and catalog guard). The `Tenant isolation` workflow runs all three on pull requests. `startRest('lane')` serves PostgREST as the tenant lane needs it: authenticated only, no anon role
* `tests/tenant-isolation/mcp-shape.ts`: the MCP shape. Runs the server as a tenant lane (`TENANT_MODE=lane`, no key) against the lane's PostgREST through a proxy that strips `/rest/v1`, with a real MCP client, real supabase-js and real pgvector. One tenant's token against the other tenant's uuid and text through all five tools, its own canary through each (markers looked for in every field of an answer), `delete_vcon` across tenants, of its own vCon with every child, and of its own vCon when a policy refuses the delete, quarantine, missing-claim, wrong-signature, `service_role` and expired tokens, every other tool, and the start refusals. `npm run test:tenant:mcp` and `npm run test:tenant:mcp:baseline` (fails unless the unmodified schema leaks through the lane). The `Tenant isolation` workflow runs both, and now runs on pull requests whatever their base branch

### Changed

* `IVConQueries.deleteVCon` may resolve to the number of vCons it removed. `VConService.delete` treats 0 as not found. The Supabase and MongoDB implementations used by `TENANT_MODE=off` do not report a count, so their behaviour is unchanged
* `VConService.delete` reports not found only when the vCon does not exist. A store error on the read that checks it exists (a refused key, a 5xx, a network failure) used to be reported as not found. It now surfaces as an error, in every mode: `delete_vcon` returns a tool error instead of "not found", and `DELETE /api/v1/vcons/:uuid` answers 500 instead of 404. Nothing is deleted
* An unknown `TENANT_MODE` value stops the server at start in every mode, `off` included. Unset or blank keeps today's behaviour
* `npm run test:tenant` runs the new REST shape. `scripts/test-tenant-isolation.ts` now starts it; the old script's "authenticated" client used the service role key and could not see a leak

### Fixed

* `docs/guide/debugging-tenant-rls.md` described the service role key as tenant-scoped, named migrations and functions that do not exist, and treated rows with no tenant as shared. It now describes what each setting does, with and without the strict pack
* Comments in `src/db/tenant-context.ts` and `src/config/tenant-config.ts` no longer claim that the session variable scopes service-key reads or that a database trigger reads the tenant attachment

***

## \[1.11.0] - 2026-10-20

### Migrations

Apply with `supabase db push` (or your migration runner) before or after deploying; the code works either way until a caller sends `date_field: "conversation"`.

* `20261019171238_add_conversation_start.sql` adds `vcons.conversation_start`, the triggers that keep it current, a backfill and an index. The rule ignores NULL starts and starts before 1990-01-01 (placeholders such as 1970 epoch defaults): the earliest dialog `start` if any dialog has one; otherwise the earliest attachment `start` capped at `created_at` (`LEAST(min attachment start, created_at)`), because some libraries stamp attachment `start` with the write time; otherwise `created_at`. `supabase/tests/conversation_start.sql` checks the triggers and backfill against a migrated database. It replaces `search_vcons_keyword`, `search_vcons_by_tags_and_date`, `search_vcons_by_tags_and_date_count`, `aggregate_vcons_by_dealer_stats`, `count_vcons_for_dealer_filter` and `count_vcons_tags_and_dealer` with versions that take an optional trailing `date_field` (default `'created'`); the old overloads are dropped. Default calls send the same payload as before, so the server runs against an unmigrated database until a caller asks for `date_field: "conversation"`. Created in `public` only; per-group schemas need it applied there

### Added

* `date_field` (`created` default, `conversation`) on every date filter: `search_vcons`, `search_vcons_content`, `vcon_search` `filters`, `vcon_aggregate` `filters`, `get_content_analytics`, and REST `GET /vcons`, `GET /vcons/search/content`, `GET /analytics/content`. `conversation` filters on when the conversation happened, which is what a date range means for imported historical conversations whose `created_at` is the import time. Invalid values return InvalidParams, `INVALID_ARGUMENT`, or REST 400. The MongoDB backend rejects `conversation`
* `conversation_start` in `search_vcons` and REST `GET /vcons` metadata rows and in the `core` group of `vcon_fetch` / `vcon_search` items, computed from the loaded vCon with the same rule
* `vcon_capabilities` `search.date_fields` and `search.default_date_field`

### Security

* Caller input placed into SQL run through the `exec_sql` RPC is now validated at the query builder. `exec_sql` only substitutes `:vcon_id` and `:limit`, so these values were previously interpolated as-is:
  * `get_content_analytics` / `GET /analytics/content`: `start_date` and `end_date` are parsed and emitted as canonical ISO 8601 timestamps
  * `get_database_stats` / `GET /database/stats`: `table_name` must be a plain lowercase identifier (`^[a-z_][a-z0-9_]*$`)
  * `months_back`, `top_n_types`, `top_n_keys`, `min_usage_count` and the tag and discovery `min_count` must be integers within bounds
  * Rejected values return MCP `InvalidParams` and REST 400 instead of reaching the database

***

## \[1.10.0] - 2026-10-19

### Migrations

Apply with `supabase db push` (or your migration runner) before or after deploying; the code works either way.

* `20260925000000_preserve_extra_fields.sql` adds the `extra` jsonb columns (#95)
* `20261019120000_remove_vcon_child_compact.sql` adds `remove_vcon_child_and_compact`. Until it exists, removals fall back to the old non-atomic path and log a warning once. It is created in `public`; per-group schemas bootstrapped earlier need it created there (#111)
* `20261019130000_restore_legacy_session_id.sql` restores dialog `session_id` values that the 2025-11 data migration rewrote as `{local: <old>, remote: "nil"}`. Only rows still holding exactly that object change; `session_id_legacy` is kept (#110)

### Added

* Create responses (`create_vcon`, `create_vcon_from_template`, `POST /vcons`, each batch item) carry `warnings: string[]`, which flags a missing or incomplete `lawful_basis` attachment. Nothing is defaulted or invented (#112)
* `resources/templates/list`: parameterised resource URIs are served as templates; `resources/list` now returns only concrete URIs (#109)
* `response_format` (`metadata`, `ids_only`, `full`) on `search_vcons_semantic` and `search_vcons_hybrid` (#108)
* `embed-vcons` accepts `?analysis_types=` to restrict which analyses are embedded (#97)

### Changed

* REST returns 400 for invalid query params (`limit`, `min_count`, `top_n`, `months_back`, `threshold`, `semantic_weight`, `embedding`) instead of silently using the default (#107)
* REST child writes (dialog, analysis, attachments, parties) run the same semantic validation as the MCP tools and return 400 when it fails (#107)
* Unauthenticated `GET /health` returns status only; database connection details need a valid API key (#107)
* MCP tools report bad input as `InvalidParams` instead of `InternalError` (#108)
* `update_vcon` declares `critical`; `must_support` is still accepted as an alias. REST create maps `must_support`, `appended` and `mimetype` to their 0.4.0 names (#108)
* Removed unused tool parameters: `create_vcon_from_template.metadata`, `get_schema.version`, and `include_count` on semantic and hybrid search (#108)
* Ids-resource `next_cursor` is now `<created_at>,<uuid>`; bare timestamps still work (#109)
* `get_examples` attachments use `purpose` and `mediatype`; `full_featured` carries a synthetic lawful\_basis attachment (#112)
* The `party_history` table is no longer written; dialog `party_history` round-trips through `extra` (#111)
* API reference, resources, prompts, env var and CLAUDE.md docs rewritten against the code; 56 broken relative links fixed (#113, #114)
* Postgres tuning guide for large corpora in `docs/deployment/production.md` (#96)

### Fixed

* A missing vCon returns 404, not 500, on REST child, index and tag routes (#107)
* Non-SELECT `POST /database/analyze` returns 400, not 500 (#107)
* `update_vcon` could not set `critical` when following its own schema (#108)
* `threshold: 0` and `semantic_weight: 0` were replaced by their defaults (#108)
* `vcon://v1/vcons/ids/{n}/after/{cursor}` returned the first page again; it now pages older rows with a uuid tie-break on both Supabase and MongoDB (#109)
* Dialog `session_id` accepts the core-02 `{local, remote}` object or an array of them; legacy strings are still accepted (#110)
* Removing an analysis or attachment could lose later rows if the reinsert failed; it is now one transaction (#111)
* `GET /vcons` `has_more` could be wrong when a plugin filtered results (#111)
* Storing a vCon dropped fields outside each table's columns and changed some body types on read; they now round-trip through `extra` (CON-1047, #95)
* A tenant attachment with `purpose: "tenant"` and no `type` left `tenant_id` NULL on the vCon and its children (#99)
* `add_analysis`/`add_dialog`/`add_attachment` (MCP tools and their REST equivalents: `POST`/`PATCH /vcons/:uuid/{analysis,dialog,attachments}`) now accept a JSON `body` (object, array, number, boolean, or null) when `encoding: "json"`, per draft-ietf-vcon-vcon-core-04 Section 2.3.2. Previously only whole-vCon creation (`create_vcon`, `POST /vcons`, `/vcons/batch`) accepted a non-string body; the per-item add/update paths rejected it with a 400/tool error. A string body is still accepted unchanged regardless of encoding. The Postgres/Supabase and MongoDB storage layers already round-tripped JSON bodies correctly (CON-1047); this closes the validation gap in front of them (CON-1113)

***

## \[1.9.2] - 2026-09-23

### Fixed

* Metadata `vcon_search` no longer fails past offset \~900. Each page used to load every vCon from row 0 up to the cursor, all at once, until the Supabase client gave out with `SEARCH_FAILED`. It now fetches one page (#93)
* Growth, size, content-volume and temporal analytics no longer multiply counts through a combined LEFT JOIN of dialog, analysis and attachments. Each child table is aggregated first, and joins target `vcons.uuid`, which the child foreign keys reference (#93)
* Attachment analytics group on `purpose`, falling back to the legacy `type`, so 0.4.0 attachments no longer report as `type: null` (#93)
* Tag analytics, `get_unique_tags` and taxonomy coverage refresh `vcon_tags_mv` when it is stale. Deployments without pg\_cron kept the view empty and reported no tags on a tagged corpus. Requires migration `20260923210000_refresh_vcon_tags_mv_if_stale.sql` (#93)
* PostgREST errors report their message instead of `[object Object]` in tool responses and batch-writer logs (#93)

***

## \[1.9.1] - 2026-09-23

### Changed

* OAuth consent page redesigned: a card with the server host, a standard Google button, and a consent step that names the signed-in account and states whether access is read-only. Buttons disable while a request is in flight. Follows the system light or dark theme and fits phone widths (#91)

### Fixed

* A request carrying a valid OAuth token no longer logs "Invalid MCP auth token attempted". The static-key check stays quiet when OAuth is enabled, and the warning is logged only when both checks reject the token (#91)

***

## \[1.9.0] - 2026-09-23

### Added

* OAuth 2.1 on the MCP HTTP endpoint so the server can be added as a custom connector in claude.ai and Claude Desktop, which only sign in with OAuth. vcon-mcp acts as the resource server: it serves protected-resource metadata (RFC 9728) at `/.well-known/oauth-protected-resource` and the resource-path variant without auth, redirects `/.well-known/oauth-authorization-server` to the issuer, answers 401 with `WWW-Authenticate: Bearer resource_metadata="..."`, and verifies JWT access tokens on every request (JWKS signature, issuer, expiry, audience equal to `OAUTH_RESOURCE`). An optional consent page at `/oauth/consent` completes the Supabase OAuth Server flow. Off unless `OAUTH_ISSUER` is set; static `API_KEYS` / `API_KEYS_READONLY` tokens are checked first and keep working. OAuth sessions are read-only unless `OAUTH_READONLY=false`. The consent page signs in by emailed code or through a Supabase external provider such as Google (`OAUTH_CONSENT_PROVIDERS`) (#89)

***

## \[1.8.0] - 2026-09-20

### Added

* `API_ANONYMOUS_READONLY=true` treats a request with no token as a read-only session: `GET`/`HEAD`/`OPTIONS` on REST, read tools over MCP. Tokens in `API_KEYS` keep full access and a wrong token is still rejected. Lets a public dataset be reached from MCP clients that cannot send a bearer header (claude.ai and ChatGPT connectors) without `API_AUTH_REQUIRED=false`, which also opens writes (#84)
* `MCP_SERVER_INSTRUCTIONS` is returned in the `instructions` field of the MCP `initialize` result, so a hosted dataset can tell a connecting agent what the corpus is, how its vCons are shaped and which tools to start with (#85)

## \[1.7.0] - 2026-09-20

### Added

* `MCP_TOOLS_PROFILE=public` for hosted, read-only datasets. A context-free agent connecting to a public corpus previously saw 28 tools on a read-only session, about half of them operator tooling (`get_database_stats`, `analyze_query`, health and growth analytics). The `public` profile keeps the read and search tools, `get_schema`, `get_examples`, and tag discovery, and hides database internals, analytics, and the two deployment-shaped tools `vcon_aggregate` and `vcon_taxonomy`. `MCP_DISABLED_TOOLS` now merges with a profile's own disabled list instead of replacing it (VCON-1716)
* Prompts carry a `category` and are filtered by the same profile and category rules as tools, in both `prompts/list` and `prompts/get`. `daily_activity_report` is `analytics`; every other prompt is `read` (VCON-1716)

### Changed

* Shared tool descriptions no longer carry one deployment's vocabulary. `vcon_aggregate`, `vcon_search`, `vcon_fetch`, and `vcon_taxonomy` describe tag filters, include groups, and the `strolid_dealer` attachment in neutral terms ("where a deployment stores one") instead of "top dealers by portal-tag rate" and `tags.portal` examples. Field names and the API contract are unchanged (VCON-1716)
* The `find_by_customer` prompt is renamed `find_by_party`, with the customer wording removed from its description and from `daily_activity_report`. Clients that request the old name get `Unknown prompt` (VCON-1716)
* `has_more` on `GET /vcons` is computed from a probe row (`limit + 1` requested, extra row withheld) instead of `vcons.length === limit`, which reported `true` on any exactly-full page and cost the client a request for an empty one. Same probe the `vcon://v1/vcons/ids` resource already used (CON-792)
* The redundant post-hoc party filter in `searchVCons` is gone; that path was already constrained by the candidate set, so it was resolving the same party lookup twice per request (CON-792)
* `vitest.config.ts` excludes `.claude/**`, so a git worktree under `.claude/worktrees` no longer doubles the local suite or drags its `tests/e2e` copies into `npm test`

### Fixed

* REST pagination honors `?offset`. `parsePagination()` parsed and validated it and the envelope reported it back, but the list handler never put it into the search filters, and neither `IVConQueries.searchVCons` nor the Supabase/Mongo implementations declared or read it — so `GET /vcons?limit=10&offset=10` returned rows 1-10 while reporting `offset: 10`. Offset now threads route -> interface -> both backends: Supabase's plain path uses `.range()`, the party-filter and tag-ordered paths slice from the offset, and Mongo uses `.skip()`. Deep paging in the tag-ordered path remains capped at `TAG_ORDERED_FETCH_CAP` (100,000 rows) (CON-790)
* Dealer-filtered metadata search returns full pages. `searchVCons` resolved `dealerMatchUuidSet()` *after* the page had been fetched and bounded, then dropped non-matching rows from it — so a dealer holding 1 in 10 of the corpus got pages of roughly one row, while `searchVConsCount` correctly reported the full total. The dealer predicate now constrains the query before the page is cut, the way the party filter already did. Reached through the `vcon_search` MCP tool (`filters.dealer_id` / `filters.dealer_name`); REST exposes no dealer parameters and was unaffected (CON-792)

***

## \[1.6.1] - 2026-08-27

### Fixed

* Declared `@opentelemetry/core`, `@opentelemetry/resources` and `@opentelemetry/sdk-metrics` as dependencies. `dist/observability/config.js` imports all three at startup, but they were never declared; they only resolved in the dev repo because npm hoisted them as transitive deps of `@opentelemetry/sdk-node`. On a clean install with a different hoisting layout the server died immediately with `ERR_MODULE_NOT_FOUND: Cannot find package '@opentelemetry/resources'`, which an MCP client surfaces only as `CONNECTION_CLOSED`. Found installing the vCon plugin, whose `.mcp.json` launches the server with `npx -y vcon-mcp` (PR #74)

***

## \[1.6.0] - 2026-08-27

### Added

* `bin` entry (`vcon-mcp` -> `dist/index.js`), so the server runs with `npx -y vcon-mcp`. `package.json` declared `main` and `exports` but no `bin`, so npm installed the package without an executable and every adopter had to clone the repo, build it, and point their MCP client at an absolute `dist/index.js` path. The entry file already carried the shebang; only the wiring was missing (PR #73)

### Changed

* README MCP client configuration examples use `npx -y vcon-mcp` instead of a hard-coded `dist/index.js` path, in both the Claude Desktop and read-only deployment samples
* `PUBLISHING_GUIDE.md` documents the tag-push release flow instead of walking a maintainer through `npm login` and `npm publish` by hand. Publishing by hand is what left v1.4.0 tagged and unpublished for three days; the guide now ends with `npm view vcon-mcp version` as the verification step, since the tag, the changelog and the registry drift apart independently

***

## \[1.5.0] - 2026-08-21

### Added

* Read-only API keys (`API_KEYS_READONLY`). `API_KEYS` was a flat list where every token granted full read, write and delete over the REST API, so there was no safe credential to hand an external consumer of a hosted dataset. Read-only tokens authenticate but are limited to `GET`/`HEAD`/`OPTIONS` on REST (403 otherwise) and to non-write MCP tools, reusing the existing `MCP_TOOLS_PROFILE` category metadata rather than a second classification. `API_KEYS` keeps full access for backward compatibility; the server warns at startup when no read-only keys are configured, a token listed in both variables is read-only (deny wins), an MCP session is pinned to the scope of the key that opened it, and plugin tools (which carry no category) are dropped from read-only sessions (PR #69)

### Fixed

* Attachment `purpose='tags'` is now treated as equivalent to `type='tags'`. vCon 0.4.0 classifies attachments with `purpose`, so tags arriving inside a spec-correct document were written with `type` NULL and were invisible to every tag read path and to `vcon_tags_mv` — silently, with no error. A `BEFORE INSERT OR UPDATE` trigger on `attachments` mirrors `tags` across both columns (with a backfill), and `vcon_tags_mv` keys on `coalesce(type, purpose)`. Tags written by the server now also carry the spec `purpose` field (PR #66)
* MongoDB backend tag paths (`getTags`, `saveTags`, `searchByTags`, unique-tag discovery) and `extractTags` recognize either spelling via a shared `isTagsAttachment()` predicate (PR #66)

### Migration

normalizing trigger and backfills existing tag attachments. It deliberately does not rebuild `vcon_tags_mv`, so it is safe to apply out of order

### Notes

* 1.4.0 was tagged but never published to npm; its CHANGELOG entry was clobbered by the #66 merge and is restored below. Installing 1.5.0 from npm brings everything since 1.3.0

## \[1.4.0] - 2026-08-18

> Tagged but never published to npm; superseded by 1.5.0.

### Added

* Supabase-native `gte-small` embeddings, so a hosted dataset needs no third-party embedding key: `embedSupabase()` runs inside the Supabase project at the native 384 dims, `embed-vcons` accepts `supabase` as a provider (and falls back to it instead of erroring on a missing `OPENAI_API_KEY`), and a new `embed-query` edge function embeds query strings with the same model as the corpus. `EMBEDDING_PROVIDER` forces a specific choice (PR #65)

### Fixed

* **MCP over HTTP was unusable after one request.** `startHttpServer` built a single `StreamableHTTPServerTransport` at startup and reused it for every request; in stateless mode the SDK rejects a reused transport, and because `setupHttpMiddleware` never awaited `handleRequest` the rejection surfaced as an empty-body HTTP 500 — so a hosted server accepted exactly one `initialize` per container start. Each request now reuses the transport for its `Mcp-Session-Id` or gets a fresh transport and MCP Server (PR #68)
* Port resolution used `config.port || ...`, so port 0 (bind any free port) fell through to the default (PR #68)
* Tags stored as a flat JSON object body (`{"source": "gmail", ...}`, produced by external ingest) read back as no tags at all, because every read path required the `["key:value", ...]` array form. `vcon_tags_mv` and a new shared `parseTagsBody()` now accept both shapes; writes still emit the array form (PR #67)
* Query-time embedding was hardcoded to `api.openai.com` with no override, so a locally embedded corpus could not be searched at all; the query path now uses the configured provider and rejects a wrong-dimension response instead of passing it into the vector comparison (PR #65)
* `vcon_embeddings` upserts were not idempotent for subject-level rows: `content_reference` is NULL there and Postgres treats NULLs as distinct in a unique constraint, so each backfill pass inserted another full 384-dim copy with no error (PR #65)

### Migration

* `20260817120000_vcon_tags_mv_object_body.sql` — rebuilds `vcon_tags_mv` on `coalesce(type, purpose)` with support for both tag body shapes
* `20260817210000_vcon_embeddings_unique_nulls_not_distinct.sql` — makes the `vcon_embeddings` unique constraint `NULLS NOT DISTINCT`

***

## \[1.3.0] - 2026-06-10

### Added

* Per-group Supabase isolation: an instance is scoped by `SUPABASE_DB_SCHEMA` (default `public`), enabling one MCP server per group via a separate Supabase project (project isolation) or a separate Postgres schema in a shared project (schema isolation) (PR #58)
* `ENV_FILE` support so each instance can load its own `.env.<group>` file
* `VCON_INSTANCE_LABEL` surfaced in startup logs and `GET /api/v1/health` (alongside the active `schema`)
* `start` / `start:group` npm scripts and `scripts/start-group.sh` launcher
* `scripts/bootstrap-schema.sh` (clone `public` into a new schema, with pg version fallback, extension-type preservation, and role grants) and `scripts/migrate-all-groups.sh` (migration fan-out across groups)
* Multi-Supabase Isolation guide; group-isolation env vars documented in installation/configuration/README

### Changed

* MCP server advertises its real package version (was hardcoded `1.0.0`); now sourced from `package.json`
* The Supabase client applies `db.schema` from `SUPABASE_DB_SCHEMA`

***

## \[1.2.0] - 2026-04-15

### Added

* REST API parity with MCP tool surface — full HTTP/JSON access at `/api/v1` (PR #46)
* Predictable vCon contract tools: `vcon_fetch`, `vcon_search`, `vcon_capabilities`, `vcon_taxonomy`, `describe_response_shape`
* HTTP transport (`MCP_TRANSPORT=http`) with Streamable HTTP and SSE
* API-key authentication for REST and MCP HTTP endpoints (`API_KEYS`, `API_KEY_HEADER`, `API_AUTH_REQUIRED`)
* Tool profiles and category controls (`MCP_TOOLS_PROFILE`, `MCP_ENABLED_CATEGORIES`, `MCP_DISABLED_CATEGORIES`, `MCP_DISABLED_TOOLS`)
* Docker image published to `public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp` with `main-<sha>`, `latest`, and semver tags
* Build provenance exposed via `X-Version`, `X-Git-Commit`, `X-Build-Time` response headers
* Pino structured JSON logging (stderr); OpenTelemetry instrumentation with OTLP exporter option
* DNS rebinding protection options for HTTP transport (`MCP_HTTP_DNS_PROTECTION`, allowed hosts/origins)
* Discovery surfaces and internal knowledge graph

### Changed

* Tool catalog grew from 30 to 35 (5 new contract tools)
* vCon version handling relaxed to accept any string or missing value
* Dialog disposition validation relaxed to accept any string
* Bearer token extraction tolerates leading whitespace in headers

### Fixed

* Upsert vCon on duplicate UUID submission instead of erroring
* Correct body serialization/deserialization for analysis and attachments (CON-352)
* `getTags` no longer crashes on non-array attachment bodies

***

## \[1.0.1] - 2025-12 (approximate)

> Date precise to the month only — the npm-published 1.0.1 pre-dated the current main lineage and its exact release date isn't in this repo.

### Added

* Comprehensive database documentation for LLMs (architecture, quickstart, schema visual)
* Row Level Security (RLS) support for multi-tenant isolation
* Enhanced database status and analytics scripts
* S3 sync functionality and backfill scripts
* Tenant debugging support
* Versioned resource URIs (vcon://v1/...)
* Backup and restore functionality
* Enhanced embedding generation with backfill options
* Improved database inspection tools

### Changed

* Updated package dependencies
* Enhanced embedding scripts with continuous and backfill modes
* Improved database status reporting with time-ago formatting
* Enhanced dialog, attachment, and analysis type distribution logging

### Fixed

* Removed obsolete test scripts and temporary files
* Improved environment variable management in scripts

***

## \[1.0.0] - 2025-10-14

### Added

#### Core Features

* Full CRUD operations for vCons (create, read, update, delete)
* Component management (parties, dialog, attachments, analysis)
* Advanced search capabilities (metadata, content, semantic, hybrid)
* Tag management system with key-value pairs
* Template-based vCon creation
* Batch operations (import, export, bulk updates)
* Validation and data quality checks
* MCP resources for URI-based access
* MCP prompts for query templates
* Plugin system for extensibility

#### Search & Query

* Metadata search with filters (subject, party, date range)
* Full-text content search with PostgreSQL trigrams
* Semantic search with vector embeddings (pgvector)
* Hybrid search combining keyword and semantic
* Tag-based search and filtering
* Aggregation and statistics

#### Database

* Normalized PostgreSQL schema for vCons
* Full IETF spec compliance (draft-ietf-vcon-vcon-core-00)
* Materialized views for tag queries
* HNSW indexes for vector search
* GIN indexes for full-text search
* Foreign key constraints and referential integrity

#### Developer Features

* TypeScript with full type safety
* Zod schemas for validation
* Comprehensive test suite (Vitest)
* Plugin development framework
* Example plugins and code
* MCP Inspector compatibility

#### Documentation

* Complete user guides
* API reference documentation
* Developer guides (architecture, testing, plugins)
* IETF vCon specification reference
* Database schema documentation
* Migration guides and quick references

### Fixed

#### Specification Compliance

* ✅ Analysis uses `schema` not `schema_version` (Section 4.5.6)
* ✅ Analysis `vendor` is required, not optional (Section 4.5.5)
* ✅ Analysis `body` is string type, not object (Section 4.5.7)
* ✅ Party object includes `uuid` field (Section 4.2.12)
* ✅ Party object includes `did` field (Section 4.2.6)
* ✅ Dialog includes `session_id`, `application`, `message_id` fields
* ✅ No default values for `encoding` fields
* ✅ Dialog `type` has proper CHECK constraint
* ✅ vCon includes `extensions` and `must_support` arrays

### Technical Details

#### Dependencies

* `@modelcontextprotocol/sdk` ^0.4.0
* `@supabase/supabase-js` ^2.39.0
* `zod` ^3.22.4
* `typescript` ^5.3.3
* `vitest` ^1.2.0

#### Requirements

* Node.js 18.x or higher
* PostgreSQL 15.x or higher
* Supabase (local or cloud)

#### Database Schema Version

* Version: 1.0.0
* vCon spec compliance: 0.3.0 (draft-ietf-vcon-vcon-core-00)

***

## \[0.9.0] - 2025-10-07 (Beta)

### Added

* Initial beta release
* Basic CRUD operations
* Search functionality
* Tag system implementation
* Database schema design

### Known Issues

* Documentation incomplete
* Some edge cases in search not handled
* Performance optimization needed

***

## Development Timeline

### Phase 1: Core Implementation (Completed)

* ✅ Database schema with spec corrections
* ✅ CRUD operations with validation
* ✅ Basic search functionality
* ✅ Tag management system
* ✅ MCP protocol integration

### Phase 2: Advanced Features (Completed)

* ✅ Semantic search with embeddings
* ✅ Hybrid search
* ✅ Plugin system
* ✅ Batch operations
* ✅ Template system

### Phase 3: Documentation (Completed)

* ✅ User guides
* ✅ API documentation
* ✅ Developer guides
* ✅ Reference documentation
* ✅ VitePress site

### Phase 4: Production & Distribution (Completed in 1.2.0)

* ✅ REST API parity with MCP surface
* ✅ HTTP transport with API-key auth
* ✅ Docker image pipeline to ECR
* ✅ Pino structured logging + OpenTelemetry
* ✅ Multi-tenant RLS

### Phase 5: Predictability & Discovery (Completed in 1.2.0)

* ✅ Contract tools: `vcon_fetch`, `vcon_search`, `vcon_capabilities`, `vcon_taxonomy`, `describe_response_shape`
* ✅ Discovery surfaces and internal knowledge graph

### Phase 6: Future Work (Planned)

* ⏳ Privacy Suite plugin (consent, redaction, PII detection)
* ⏳ Compliance tooling hooks (GDPR, CCPA, HIPAA)
* ⏳ Performance hardening on large corpora

***

## Migration Guides

### Migrating to 1.0.0

If you're upgrading from a pre-1.0 version or another vCon implementation:

1. **Read the Migration Guide:** [MIGRATION\_GUIDE.md](https://mcp.conserver.io/reference/migration_guide.md)
2. **Check Field Names:** [QUICK\_REFERENCE.md](https://mcp.conserver.io/reference/quick_reference.md)
3. **Update Database:** [CORRECTED\_SCHEMA.md](https://mcp.conserver.io/reference/corrected_schema.md)
4. **Run Tests:** Ensure compliance tests pass

**Critical Changes:**

* Analysis uses `schema` not `schema_version`
* Analysis `vendor` is now required
* Analysis `body` is string, not object
* Party includes `uuid` field
* Dialog includes new fields (`session_id`, `application`, `message_id`)

***

## Version Numbering

We follow [Semantic Versioning](https://semver.org/):

* **Major (X.0.0)**: Breaking changes, incompatible API changes
* **Minor (0.X.0)**: New features, backward compatible
* **Patch (0.0.X)**: Bug fixes, backward compatible

### What Triggers Version Bumps

**Major (Breaking):**

* Database schema changes requiring migration
* API changes incompatible with previous versions
* Required configuration changes

**Minor (Features):**

* New tools, resources, or prompts
* New optional features
* Performance improvements
* Documentation enhancements

**Patch (Fixes):**

* Bug fixes
* Security patches
* Documentation corrections
* Performance optimizations without API changes

***

## Release Notes

### v1.0.0 Release Highlights

This first major release represents a production-ready, fully spec-compliant vCon MCP Server with:

* **100% IETF Spec Compliance** - All known specification issues corrected
* **Production-Ready Database** - Normalized schema with proper constraints and indexes
* **Advanced Search** - Keyword, semantic, and hybrid search capabilities
* **Extensible Architecture** - Plugin system for custom functionality
* **Complete Documentation** - User guides, API reference, developer guides
* **Professional Quality** - TypeScript, comprehensive tests, proper error handling

**Perfect for:**

* Production conversation data management
* AI-powered conversation intelligence
* Compliance and archival systems
* Development and research

**Not Included (Proprietary):**

* Privacy Suite (consent management, PII detection)
* Compliance tools (GDPR, CCPA, HIPAA automation)
* Enterprise support

***

## Future Roadmap

The roadmap below reflects work not yet started or in early planning. Concrete shipped versions live in the dated entries above.

### Near-term (post-1.2.0)

* Privacy Suite plugin (consent management, PII detection, redaction)
* Compliance tooling hooks (GDPR, CCPA, HIPAA support patterns)
* Performance hardening on large corpora (cold-start full-text search)

### Longer-term

* Cloud-native deployment patterns and horizontal scaling guidance
* Additional storage backends

***

## Contributing

See [CONTRIBUTING.md](https://mcp.conserver.io/development/contributing.md) for how to contribute to this project.

***

## License

### Open Source Core

The vCon MCP Server is released under the MIT License.

### Proprietary Features

Privacy Suite and enterprise features are available under commercial license.

***

## Support

* **Documentation:** <https://vcon-dev.github.io/vcon-mcp/>
* **Issues:** <https://github.com/vcon-dev/vcon-mcp/issues>
* **Discussions:** <https://github.com/vcon-dev/vcon-mcp/discussions>
* **IETF Working Group:** <https://datatracker.ietf.org/wg/vcon/>

***

**Note:** This changelog reflects the development history. Earlier versions (pre-1.0) were development/beta releases not intended for production use.

***

*Last Updated: May 18, 2026*
