chore(release): v0.2.0 — changelog, migration, npm alignment

Author: zho

CHANGELOG.md

@@ -8,6 +8,8 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-29
+
 ### Changed
 
 - Package root export is the generic **core** layer (`setupCoreServer`); full CLI parity uses `@will-cppa/pinecone-read-only-mcp/alliance` (`setupAllianceServer`, built-in URL generators). `resolveConfig` uses env when set, else defaults: index **`rag-hybrid`**, rerank **`bge-reranker-v2-m3`** (constants `DEFAULT_INDEX_NAME` / `DEFAULT_RERANK_MODEL` in `src/core/config.ts`).
@@ -99,7 +101,8 @@ details. Newer shipped changes are recorded in this changelog by version.
 - Environment variable support
 - Full documentation and examples
 
-[Unreleased]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.1.6...HEAD
+[Unreleased]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.1.6...v0.2.0
 [0.1.6]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.1.1...v0.1.6
 [0.1.1]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/releases/tag/v0.1.0

README.md

@@ -7,6 +7,12 @@
 
 A Model Context Protocol (MCP) server that provides semantic search over Pinecone vector databases using hybrid search (dense + sparse) with reranking.
 
+**Current version: 0.2.0** (npm `latest` after publish). Pin `@0.2.0` in install and MCP config for reproducible upgrades.
+
+## Upgrading from 0.1.x
+
+Version **0.2.0** includes breaking MCP and type changes. See [docs/MIGRATION.md](docs/MIGRATION.md) for before/after examples and the [CHANGELOG](CHANGELOG.md#020---2026-05-29) **Changed** section for the full list.
+
 ## Documentation
 
 | Doc                                            | Description                            |
@@ -44,7 +50,7 @@ For successful `query`, `query_documents`, and `guided_query` payloads, **rerank
 - **Dynamic Namespace Discovery**: Automatically discovers available namespaces in your Pinecone index
 - **Metadata Filtering**: Supports optional metadata filters for refined searches
 - **Fast presets**: Lazy initialization, connection pooling, and efficient result merging; use the `query` tool `preset=fast | detailed | full` to trade latency vs quality (no published benchmarks yet — treat descriptions as qualitative).
-- **Production-oriented defaults**: Input validation, error handling, and configurable logging (semantic versioning is pre-1.0 — review CHANGELOG before upgrading).
+- **Production-oriented defaults**: Input validation, error handling, and configurable logging; upgrading from **0.1.x** — see [MIGRATION.md](docs/MIGRATION.md).
 - **TypeScript Support**: Full TypeScript support with type definitions
 
 ## Installation
@@ -54,25 +60,25 @@ For successful `query`, `query_documents`, and `guided_query` payloads, **rerank
 ### As a Package
 
 ```bash
-npm install @will-cppa/pinecone-read-only-mcp
+npm install @will-cppa/pinecone-read-only-mcp@0.2.0
 ```
 
 Or using yarn:
 
 ```bash
-yarn add @will-cppa/pinecone-read-only-mcp
+yarn add @will-cppa/pinecone-read-only-mcp@0.2.0
 ```
 
 Or using pnpm:
 
 ```bash
-pnpm add @will-cppa/pinecone-read-only-mcp
+pnpm add @will-cppa/pinecone-read-only-mcp@0.2.0
 ```
 
 ### Global Installation
 
 ```bash
-npm install -g @will-cppa/pinecone-read-only-mcp
+npm install -g @will-cppa/pinecone-read-only-mcp@0.2.0
 ```
 
 ### From Source
@@ -182,7 +188,7 @@ Add to your `claude_desktop_config.json`:
   "mcpServers": {
     "pinecone-search": {
       "command": "npx",
-      "args": ["-y", "@will-cppa/pinecone-read-only-mcp"],
+      "args": ["-y", "@will-cppa/pinecone-read-only-mcp@0.2.0"],
       "env": {
         "PINECONE_API_KEY": "your-api-key-here",
         "PINECONE_INDEX_NAME": "your-index-name",
@@ -202,7 +208,7 @@ Or with explicit options:
       "command": "npx",
       "args": [
         "-y",
-        "@will-cppa/pinecone-read-only-mcp",
+        "@will-cppa/pinecone-read-only-mcp@0.2.0",
         "--api-key",
         "your-api-key-here",
         "--index-name",
@@ -235,7 +241,7 @@ For a global installation:
 Run the server using npx (no installation required):
 
 ```bash
-npx @will-cppa/pinecone-read-only-mcp --api-key YOUR_API_KEY
+npx @will-cppa/pinecone-read-only-mcp@0.2.0 --api-key YOUR_API_KEY
 ```
 
 Or if installed globally:
@@ -275,10 +281,10 @@ Run `pinecone-read-only-mcp --help` for the full option list.
 
 ```bash
 # install
-npm i @will-cppa/pinecone-read-only-mcp
+npm i @will-cppa/pinecone-read-only-mcp@0.2.0
 
 # run
-npx @will-cppa/pinecone-read-only-mcp --api-key YOUR_API_KEY
+npx @will-cppa/pinecone-read-only-mcp@0.2.0 --api-key YOUR_API_KEY
 ```
 
 ### Deploy with Docker

docs/MIGRATION.md

@@ -1,8 +1,10 @@
 # Migration guide
 
-This guide is for **library and MCP client authors** upgrading from earlier **0.1.x** lines. The `[Unreleased]` section of [`CHANGELOG.md`](../CHANGELOG.md) is the authoritative list of changes; this document shows **how** to migrate.
+This guide is for **library and MCP client authors** upgrading from earlier **0.1.x** lines. The **[0.2.0]** section of [`CHANGELOG.md`](../CHANGELOG.md) is the authoritative list of changes; this document shows **how** to migrate.
 
-## Migrating to v0.2.0 (upcoming)
+Under [semver 0.y.z](https://semver.org/spec/v2.0.0.html#spec-item-4), **0.1.x → 0.2.0 is a breaking minor** — pin `@0.2.0` only after reading this guide.
+
+## Migrating to v0.2.0
 
 ### Namespace trimming and suggest-flow
 
@@ -120,10 +122,23 @@ await callTool('query', {
 
 ---
 
+### 5. Node.js >= 20.12.0
+
+**Rationale:** `engines.node` is now **>=20.12.0**. Vitest **4** (bundled **rolldown**) imports `util.styleText` from `node:util` (added in Node **20.12**), and **`@vitest/coverage-v8`** uses `node:inspector/promises`. CI tests **20.x** and **22.x** only.
+
+**Migration steps:**
+
+1. Upgrade local Node to **20.12+** (or **22.x**).
+2. Update CI images / `actions/setup-node` to **20.12+** if you pin an older 20.x patch.
+3. Re-run your MCP client or library tests after upgrading.
+
+---
+
 ## Summary checklist
 
 - [ ] Normalize and reuse namespace strings across suggest + gated tools.
 - [ ] Adopt `ToolError` parsing for all tool failures.
 - [ ] Remove reliance on in-body `status: 'error'` for query responses.
 - [ ] Update `recommended_tool` handling to `count` \| `fast` \| `detailed` \| `full`.
 - [ ] Map legacy fast/detailed tool calls to `query` + `preset`.
+- [ ] Run on Node.js **>=20.12.0**.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@will-cppa/pinecone-read-only-mcp",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "A Model Context Protocol (MCP) server that provides semantic search over Pinecone vector databases using hybrid search (dense + sparse) with reranking.",
   "type": "module",
   "main": "dist/core/index.js",