MCP Server & Plugin Release Preparation

Prepare an MCP server and plugin release by updating version numbers across all required files and generating a changelog entry. The MCP server version advances independently of the qsv binary version.

Arguments

• version

  (required): The new MCP server version number (e.g., "16.2.0")

• minimum_qsv_version

  (optional): New minimum qsv binary version, if changing

All paths below are relative to

.claude/skills/

.

Version Bump Checklist

Core (must always update)

1. package.json

   : find

   "version":

   field — source of truth;

   version.ts

   reads this at runtime

2. manifest.json

   : find

   "version":

   field near top — must match package.json

3. .claude-plugin/plugin.json

   : find

   "version":

   field

4. ../../.claude-plugin/marketplace.json

   (repo root): find

   "version":

   in both

   metadata

   and

   plugins[0]

   — must match package.json

5. agents/data-analyst.md

   :

   version:

   in YAML frontmatter

6. agents/data-wrangler.md

   :

   version:

   in YAML frontmatter

7. agents/policy-analyst.md

   :

   version:

   in YAML frontmatter

After bumping

package.json

, run

npm install --package-lock-only

to sync

package-lock.json

.

Conditional (only if minimum qsv binary version changes)

8. src/config.ts

   : find

   MINIMUM_QSV_VERSION

   constant — primary runtime enforcement point

9. manifest.json

   : find

   "minimum_qsv_version":

   field — must match config.ts

10. scripts/cowork-setup.cjs

    : find

    MINIMUM_QSV_VERSION

    constant — must match config.ts and manifest.json

Documentation (hardcoded versions to update)

11. README-MCP.md

    : search for

    **Version**: X.Y.Z

    near the bottom

12. docs/desktop/README-MCPB.md

    : search for download URLs and version badge (multiple occurrences)

13. docs/guides/START_HERE.md

    : check for any hardcoded version references

Command count verification

Verify the skill-based command count matches actual files:

ls qsv/qsv-*.json | wc -l

Then check descriptions in these files for stale counts:

• .claude-plugin/plugin.json

  description

• ../../.claude-plugin/marketplace.json

  — both

  metadata.description

  and

  plugins[0].description

• cowork-CLAUDE.md

  — Tool Discovery section

• skills/csv-wrangling/SKILL.md

  — Tool Discovery section

• manifest.json

  —

  _meta.com.dathere.qsv.features

  array

Changelog Entry

Add a new section at the top of

CHANGELOG.md

(in

.claude/skills/

) following this format:

## [X.Y.Z] - YYYY-MM-DD

### Added
- (new features)

### Changed
- (changes to existing features)

### Fixed
- (bug fixes)

Find the last qsv release tag and use it to populate the changelog:

# Find the most recent qsv release tag
LAST_TAG=$(git describe --tags --match '[0-9]*.[0-9]*.[0-9]*' --abbrev=0 2>/dev/null || echo "")

# List relevant commits since that tag (or all commits from repo root if no tag exists)
git log --oneline --no-merges --grep="(mcp)" "${LAST_TAG:-$(git rev-list --max-parents=0 HEAD)}"..HEAD

Only commits with

(mcp)

or

(plugin)

in the title are relevant to MCP server releases.

Verification Steps

After version bumps:

1. npm run build

   — TypeScript compilation succeeds

2. npm test

   — all tests pass

3. npm run mcpb:package

   — generates

   qsv-mcp-server-X.Y.Z.mcpb

4. npm run plugin:package

   — generates

   qsv-data-wrangling-X.Y.Z.plugin

Cowork Plugin

The Cowork plugin (

.plugin

file) is a separate distribution artifact from the Desktop Extension (

.mcpb

). It provides the workflow layer (skills, agents, hooks) without the MCP server itself.

Plugin components (all relative to

.claude/skills/

)

• .claude-plugin/plugin.json

  — plugin manifest (version already bumped in Core step 3)

• scripts/cowork-setup.cjs

  — SessionStart hook that deploys

  cowork-CLAUDE.md

  to the working directory and validates the qsv binary

• cowork-CLAUDE.md

  — workflow template deployed by the hook

• skills/

  — 15 SKILL.md files: 9 user-invocable (csv-query, data-clean, data-convert, data-describe, data-join, data-profile, data-validate, data-viz, infer-ontology) + 6 model-invoked (bls-query, csv-wrangling, data-quality, genai-disclaimer, qsv-performance, reproducible-analysis)

• agents/

  — subagents (data-analyst, data-wrangler, policy-analyst)

Plugin-specific review

When preparing a release, also review:

• cowork-CLAUDE.md

  : check that tool names, workflow steps, and limits are still accurate

• scripts/cowork-setup.cjs

  : if

  minimum_qsv_version

  changed, update the

  MINIMUM_QSV_VERSION

  constant (listed in Conditional step 10)

• skills/

  ,

  agents/

  : check for any hardcoded version references or stale tool names

Important Notes

• MCP server version advances independently of qsv binary version

• minimum_qsv_version

  tracks binary compatibility, not server version — enforced in 3 places:

  src/config.ts

  ,

  manifest.json

  , and

  scripts/cowork-setup.cjs

  (all must stay in sync)
• Skill JSON files (

  qsv/*.json

  ) are auto-generated by the qsv binary (

  qsv --update-mcp-skills

  ), not by this skill — only bump those via

  /release-prep

• version.ts

  reads version from

  package.json

  at runtime — no need to edit

  version.ts

  directly
• The

  .plugin

  package reads its version from

  package.json

  (same source of truth as the

  .mcpb

  )