Guides
  1. releases

MCP Server

MCP Server v0.0.1-beta.12

Release target: replacement for withdrawn 0.0.1-beta.11, with the npm/npx binary startup fix, refreshed knowledge/vector package, and the internal staging/dev auth foundations from beta.11.

Why beta.12

0.0.1-beta.11 was published and then withdrawn after Claude failed to start the server through the npm package binary path (npx -y @convertcom/mcp-server@latest). npm package versions are immutable after publish/unpublish, so the replacement release must use a new version: 0.0.1-beta.12.

Highlights

  • Fixed npm package binary startup by resolving real paths before deciding whether src/index.ts is the main entrypoint.
  • Extended package smoke to launch the installed package binary (node_modules/.bin/convert-mcp, or convert-mcp.cmd on Windows), matching the npx/Claude failure mode instead of only testing node build/index.js.
  • Added durable operator notes for npm immutability, rollback/dist-tag handling, and binary-shim startup testing.
  • Refreshed packages/server/data/convert-kb.json from the canonical assistant HubSpot export.
  • Rebuilt the semantic vector store for 5,797 knowledge chunks.
  • Preserved required empty Zvec segment directories with tracked .gitkeep files so git/npm packaging keeps the vector store openable.
  • Tightened yarn test:vectors and package smoke so missing packaged vector segment directories fail release validation instead of shipping a broken search index.
  • Retains beta.11's internal CONVERT_BASE_URL support, typed auth-context plumbing, private remote runtime scaffolding, and public npm package boundary.

Release Readiness Evidence

Run before tagging:

yarn install --immutable
yarn build
yarn workspace @convertcom/mcp-server test --runInBand
yarn test:smoke
yarn test:conformance
yarn test:package
yarn test:vectors
CONVERT_DISABLE_SEMANTIC_KB=1 yarn test:release
yarn test:real
CONVERT_BASE_URL=https://api.app-staging.convert.com/api/v2 yarn test:real

Manual pre-release check must use the npm-style binary path that failed in beta.11:

  1. Pack and install the local tarball into a temporary project.
  2. Launch node_modules/.bin/convert-mcp or Windows convert-mcp.cmd.
  3. Verify MCP initialize, tools/list, docs search / fetch, and accounts.list with Convert credentials.

Release Plan

  1. Keep npm latest on 0.0.1-beta.10 until all validation and manual package-bin testing pass.
  2. Commit beta.12 version metadata, release docs, binary fix, and refreshed knowledge/vector artifacts to main.
  3. Wait for the GitHub Release Gate push workflow to pass on main.
  4. Create and push the annotated tag: 
    git tag -a v0.0.1-beta.12 -m "v0.0.1-beta.12"
git push origin v0.0.1-beta.12
  5. Create a normal GitHub Release for v0.0.1-beta.12 using these notes. Do not mark it as draft or prerelease.
  6. The Publish Package to npmjs workflow will run on release publication, validate the tag/version match, run yarn test:release, and publish @convertcom/[email protected] to npm with the latest tag.
  7. Verify after publish: 
    npm view @convertcom/mcp-server dist-tags versions --json

MCP Server v0.0.1-beta.10

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.

MCP Server v0.0.1-beta.9

Highlights

  • Fix namespace tool argument normalization for Claude Code and other MCP clients that flatten or stringify path/body fields.
  • Harden npm publish to install immutably from the committed yarn.lock.
  • Pin axios to 1.13.5 to avoid dependency drift during release builds.
  • Sync release and workspace docs with the actual publish flow.

MCP Server v0.0.1-beta.8

Beta 8 release for Convert MCP server.

Changes:

  • MCP robustness and cross-client compatibility improvements
  • Better validation and actionable error responses for LLM self-correction
  • Safety guardrails and improved tool schemas for all namespaces

Validation:

  • yarn workspace @convertcom/mcp-server test
  • yarn test:smoke
  • yarn test:real
  • yarn test:conformance

MCP Server v0.0.1-beta.7

What's New

AI Agent Usability Overhaul

  • Auto-extracted body schema hints — agents now see valid enums and required fields for every write endpoint, extracted automatically from the OpenAPI spec
  • Hand-curated ACTION_NOTES — working examples, gotcha warnings, and required field hints for the trickiest endpoints (experiences, locations, audiences, hypotheses, etc.)
  • Error response hints — when an action fails, the error now includes contextual guidance so agents self-correct on retry

Tool Discoverability Fix

  • Rewrote SERVER_INSTRUCTIONS so MCP clients (Claude Desktop, ChatGPT, etc.) correctly reach for the 13 namespace API tools instead of only using search_knowledge_base
  • All namespace descriptions now clearly indicate direct API access to the user's Convert.com account

Embedded Knowledge Base (Hybrid Search)

  • MiniSearch (BM25 keyword) + Zvec (semantic vector store) with Reciprocal Rank Fusion
  • The server can now answer Convert platform questions and guide users through concepts without external docs

Shutdown Crash Fix

  • Fixed SIGABRT on shutdown when semantic search init partially loads native modules but falls back to keyword-only mode
  • Smoke tests now validate clean shutdown (catch abnormal exits)

Other

  • Dynamic account ID discovery in real API smoke test (no more hardcoded IDs)
  • MCP spec-compliant tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
  • Updated OpenAPI spec and dependency refresh

Test Evidence

  • 123 unit tests passing (action-notes, annotations, RRF fusion)
  • Stdio smoke test passing (14 tools, clean shutdown)
  • Live API smoke test passing (accounts → projects → experiences chain)

MCP Server v0.0.1-beta.6

What's Changed

  • 🔒 Removed repository links from package.json (private repository)
  • npm page will no longer show GitHub repository/homepage links

This is a metadata-only update. All features from v0.0.1-beta.5 remain unchanged.

Installation

Configure in your MCP client:

{
  "mcpServers": {
    "convert": {
      "command": "npx",
      "args": ["-y", "@convertcom/mcp-server@latest"],
      "env": {
        "CONVERT_API_KEY": "your_application_id",
        "CONVERT_API_SECRET": "your_secret_key",
        "TOOLS_FOR_CLIENT": "reporting"
      }
    }
  }
}

MCP Server v0.0.1-beta.5

What's Changed

  • 📝 Simplified README - Removed installation options section (users only interact via MCP clients)
  • 🎨 Removed logo - Logos don't display on npm, cleaner presentation
  • 📚 Streamlined documentation - Focus on client integration and usage

This is a documentation-only update. All features from v0.0.1-beta.4 remain unchanged.

Installation

Configure in your MCP client:

{
  "mcpServers": {
    "convert": {
      "command": "npx",
      "args": ["-y", "@convertcom/mcp-server@latest"],
      "env": {
        "CONVERT_API_KEY": "your_application_id",
        "CONVERT_API_SECRET": "your_secret_key",
        "TOOLS_FOR_CLIENT": "reporting"
      }
    }
  }
}

See the README for full documentation.

MCP Server v0.0.1-beta.4

What's New

  • ✨ Beautiful new README with logos, badges, and professional formatting
  • 📚 Enhanced documentation with model recommendations (Claude Sonnet 4.5, GPT-5)
  • 🔍 Built-in knowledge base with 5,279+ indexed chunks from Convert support docs
  • 🛡️ Improved security best practices and clear access level guidance
  • 🎯 Updated example prompts showing real-world use cases organized by category
  • 🔧 GitHub Actions workflow for automated npm publishing
  • 📖 Comprehensive API coverage section highlighting all capabilities
  • 🚀 Release process documentation for maintainers

Installation

npx -y @convertcom/mcp-server@latest

Documentation

See the README for full documentation, including:

  • Quick start guide
  • Client integration (Claude Desktop, Cursor, and more)
  • Detailed namespace documentation with all available actions
  • Example prompts for common tasks
  • Troubleshooting tips

Note: This replaces the outdated 0.0.1-beta.3 documentation with a completely redesigned README.

MCP Server v0.0.1-beta.3

What's New

  • ✨ Beautiful new README with logos and badges
  • 📚 Enhanced documentation with model recommendations (Claude Sonnet 4.5, GPT-5)
  • 🔍 Built-in knowledge base with 5,279+ indexed chunks from Convert support docs
  • 🛡️ Improved security best practices
  • 🎯 Updated example prompts showing real-world use cases
  • 🔧 GitHub Actions workflow for automated npm publishing
  • 🐛 Fixed GitHub Actions workflow authentication and build process

Installation

npx -y @convertcom/mcp-server@latest

See the README for full documentation.

MCP Server v0.0.1-beta.2

What's New

  • ✨ Beautiful new README with logos and badges
  • 📚 Enhanced documentation with model recommendations (Claude Sonnet 4.5, GPT-5)
  • 🔍 Built-in knowledge base with 5,279+ indexed chunks from Convert support docs
  • 🛡️ Improved security best practices
  • 🎯 Updated example prompts showing real-world use cases
  • 🔧 GitHub Actions workflow for automated npm publishing

Installation

npx -y @convertcom/mcp-server@latest

See the README for full documentation.

Updated about 19 hours ago