Changelog
Back to All
Improved

MCP Server v0.0.1-beta.10

about 1 month ago by ReadMe API

Release target: Convert MCP server beta hardening for fast-changing Convert API schemas, OpenAI-compatible MCP clients, prompt-first workflow intelligence, and the manual regression blockers found before release.

Highlights

  • Regenerated convert-OA3.yaml from the latest backend MCP OpenAPI build and regenerated packages/server/src/tools.ts.
  • Added curated namespace mappings for latest backend operations: account billing portal and experience heatmap background/overlay.
  • Replaced legacy docs search with OpenAI-compatible search and fetch tools; search_knowledge_base is no longer advertised.
  • Refreshed the packaged Convert support knowledge base from the latest assistant HubSpot export: 5,776 chunks across 500 article URLs.
  • Committed the rebuilt semantic vector index so packaged search starts hybrid, not keyword-only.
  • Added MCP prompt support with 19 curated prompts for Convert experimentation workflows, implementation debugging, and experiment building.
  • Added one compact operator namespace with reporting/audit actions plus verified write workflows.
  • Added cached project defaults inference for goals, audiences, locations, URL patterns, traffic splits, and naming patterns.
  • Kept documentation search hybrid by opening the packaged Zvec index through a temporary runtime copy, avoiding package mutation and keyword-only fallback.
  • Moved the auto-placeholder experience-change schema fix into the generator so generated tools.ts carries discriminated defaultRedirect and richStructure schemas.
  • Fixed runtime schema normalization for audiences.create / audiences.update so non-null nested rules payloads validate and dispatch.
  • Fixed runtime schema normalization for locations.create / locations.update so URL/page targeting rules validate and dispatch.
  • Fixed runtime schema normalization for goals.create / goals.update around real Convert goal types: clicks_element, code_trigger, dom_interaction, scroll_percentage, advanced, ga_import, plus triggering_rule.
  • Fixed runtime schema normalization for features.create / features.update so typed variable defaults such as boolean false and numeric values validate instead of colliding with generated null-only base branches.
  • Added UnsupportedInlineSiteArea guardrail for experiences.create / experiences.update when body.site_area is present, because the API can return success while persisting site_area: null.
  • Added ClicksLinkHrefMustBeString guardrail for clicks_link goals when settings.href is a match object. Convert currently accepts string href values only; agents should use triggering_rule for page scoping or create multiple link goals.
  • Fixed multipart screenshot uploads by preserving multipart/form-data schemas, building real FormData, signing pass-through bodies as Convert expects, and verifying readback when the API reports a post-persistence 500.
  • Added CONVERT_HTTP_HEADER_* passthrough with auth/signing header override protection.
  • Added bounded retry/backoff for 429/503 responses while avoiding unsafe write retries by default.
  • Added flow fixtures for Iqbal custom-code A/B creation, split URL regex settings, variation updates, goals, audiences, locations, project audit, and guardrail payloads.
  • Added registry drift enforcement so new backend operations must be curated or intentionally allowlisted.
  • Added a schema-risk release gate that fails on newly introduced unclassified null-only request-body properties, missing runtime overrides, missing fixtures, or missing guardrails.
  • Extended the mutating live scenario matrix with exact Iqbal custom-code, split URL regex, BeNeLux audience/location, broad namespace, write/readback/rollback, and cleanup flows.
  • Added npm package proof and install-from-tarball smoke to the release gate.
  • Hardened GitHub release automation so the release gate uses the canonical yarn test:release command and the publish workflow checks out the exact release tag before publishing.

Release Readiness Evidence

  • Local yarn test:release: passed.
  • Local CI=true CONVERT_DISABLE_SEMANTIC_KB=1 yarn test:release: passed, matching GitHub runner semantics.
  • Local yarn test:vectors: passed with native read-only Zvec open.
  • Local yarn test:conformance: passed with semantic KB ready, 5,776 chunks loaded.
  • GitHub Release Gate: passing on main before release creation.
  • Unit/fixture suite: 196/196 tests passed.
  • Package proof: 61 files, 19.2 MiB unpacked, install-from-tarball MCP smoke passed.

Required Preflight

cp ../assistant/scripts/kb/hubspot_kb_output/hubspot_kb_part_1.json packages/server/data/convert-kb.json
yarn workspace @convertcom/mcp-server build:vectors
yarn test:vectors
yarn test:release
yarn test:schema-risk
yarn test:real
node scripts/mcp-live-scenario-matrix.mjs
MCP_MATRIX_BROAD_SWEEP=1 node scripts/mcp-live-scenario-matrix.mjs

yarn test:release runs generated-tools drift, build, lint, unit/fixture tests, registry drift, schema-risk, vector-store structure checks, stdio smoke, protocol conformance, npm tarball proof, and install-from-tarball smoke. Local yarn test:vectors also opens the committed semantic vector index natively; CI verifies package structure and skips native Zvec open because the optional native runtime is runner-sensitive. yarn test:real and scripts/mcp-live-scenario-matrix.mjs prefer process env / local .env credentials and honor CONVERT_ACCOUNT_ID / CONVERT_PROJECT_ID target IDs. The matrix creates temporary draft experiences and archives them after verification. Set MCP_MATRIX_BROAD_SWEEP=1 only when intentionally running the broad namespace sweep.