From 82e55b6a7ab4e5fe9346e71bb72293f506803b8b Mon Sep 17 00:00:00 2001 From: zho Date: Tue, 30 Jun 2026 00:34:06 +0800 Subject: [PATCH 1/3] docs: sync README to v0.3.0 and add CODEOWNERS + CONTRIBUTING Update consumer-facing install and MCP config pins to match package.json 0.3.0, add root CONTRIBUTING.md for GitHub onboarding, and route reviews via CODEOWNERS for critical paths. Co-authored-by: Cursor --- .github/CODEOWNERS | 8 ++++ CHANGELOG.md | 3 +- CONTRIBUTING.md | 76 ++++++++++++++++++++++++++++++++++++++ README.md | 35 ++++++++---------- docs/CONTRIBUTING.md | 63 +++---------------------------- docs/deprecation-policy.md | 2 +- 6 files changed, 109 insertions(+), 78 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 CONTRIBUTING.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..73074e7 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,8 @@ +# Default owners +* @wpak-ai @jonathanMLDev + +# Critical paths (explicit for review routing) +/src/ @wpak-ai @jonathanMLDev +/src/alliance/ @wpak-ai @jonathanMLDev +/package.json @wpak-ai @jonathanMLDev +/.github/workflows/ @wpak-ai @jonathanMLDev diff --git a/CHANGELOG.md b/CHANGELOG.md index cee9adc..5a31cb5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -137,7 +137,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.2.0...HEAD +[Unreleased]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.3.0...HEAD +[0.3.0]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.2.0...v0.3.0 [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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5b4ced6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,76 @@ +# Contributing + +Thank you for contributing to `@will-cppa/pinecone-read-only-mcp`. This guide covers local setup, architecture, and pull-request expectations. + +## Prerequisites + +- **Node.js ≥ 20.12** (see `engines` in `package.json` — Vitest 4 / coverage require it). +- **npm** (lockfile is `package-lock.json`). +- **Pinecone API key** (optional for unit tests; required for live integration-style runs and examples that call Pinecone). + +## Dev setup + +```bash +git clone https://github.com/cppalliance/pinecone-read-only-mcp-typescript.git +cd pinecone-read-only-mcp-typescript +npm ci +npm run build +npm test +``` + +For the full local gate before pushing: + +```bash +npm run ci +``` + +| Script | Purpose | +| ------ | ------- | +| `npm run build` | Clean `dist/` and `tsc` compile | +| `npm run typecheck` | `tsc --noEmit` | +| `npm run lint` | ESLint on `src/` | +| `npm run lint:fix` | ESLint with `--fix` | +| `npm run format` | Prettier write (`src/**/*.ts`, config JSON) | +| `npm run format:check` | Prettier check | +| `npm test` | Vitest once | +| `npm run test:coverage` | Vitest + coverage thresholds (`vitest.config.ts`) | +| `npm run ci` | Full local gate (typecheck, lint, format, build, coverage) | +| `npm run docs:link-check` | Validate markdown links in README, CHANGELOG, and `docs/` | + +## Architecture overview + +The codebase is split into two layers. **`src/core/`** is the generic MCP–Pinecone bridge: `PineconeClient`, `resolveConfig`, `setupCoreServer`, and eight MCP tools including `guided_query`. Import from `@will-cppa/pinecone-read-only-mcp` (package root). **`src/alliance/`** is the C++ Alliance app layer: `suggest_query_params`, Boost/Slack URL builtins, and `setupAllianceServer` / `resolveAllianceConfig`. Import from `@will-cppa/pinecone-read-only-mcp/alliance` for the full 14-tool surface (CLI parity). + +Each deployment uses a **`ServerContext`** instance that owns config, the Pinecone client, namespaces cache, URL generator registry, and the suggest-flow gate. Prefer the instance-first pattern: `createServer(config)` → `ctx.setClient(...)` → `setupCoreServer({ context: ctx })` or `setupAllianceServer({ context: ctx })`. Module-level singleton facades (`setPineconeClient`, `getDefaultServerContext`, etc.) are deprecated since 0.3.0. + +The **suggest-flow gate** requires `suggest_query_params` before `query`, `count`, or `query_documents` for a namespace (unless disabled). Alliance defaults keep the gate **on**; core `resolveConfig` defaults `disableSuggestFlow` to **true** so generic embedders can query without Alliance tools. Tool handlers validate inputs with Zod and return structured **`ToolError`** JSON on failure — one of the project's quality standards for MCP consumers. + +Deep reference: [docs/CONFIGURATION.md](docs/CONFIGURATION.md), [docs/TOOLS.md](docs/TOOLS.md), [README.md](README.md#architecture). + +## PR conventions + +- **Branch naming:** `feature/…`, `docs/…`, `bugfix/…`, or `design/…` (short, descriptive slug). +- Run **`npm run ci`** before pushing; CI must pass on the PR. +- Keep changes focused; update **`CHANGELOG.md` `[Unreleased]`** for user-visible behavior. +- Use the [pull request template](.github/PULL_REQUEST_TEMPLATE.md). +- Documentation changes: run `npm run docs:link-check` if you touch many relative links. +- PRs to `main` should receive review from a [CODEOWNERS](.github/CODEOWNERS) maintainer once branch protection is enabled. + +### Deprecations and breaking changes + +Follow [docs/deprecation-policy.md](docs/deprecation-policy.md). Deprecate with CHANGELOG + MIGRATION entries; use labeled `**Breaking (MCP):**` bullets for breaking releases while `0.y.z`. + +### Response field stability + +When changing MCP tool success shapes, put new fields under **`experimental`** unless promoted; update Zod schemas in `src/core/server/response-schemas.ts` and [docs/TOOLS.md](docs/TOOLS.md). See [docs/deprecation-policy.md § Stable vs experimental](docs/deprecation-policy.md#stable-vs-experimental-mcp-response-fields). + +## Code style + +- **TypeScript strict** (`strict`, `noUncheckedIndexedAccess`, etc.) — match surrounding code. +- **ESLint** and **Prettier** — `npm run lint`, `npm run format:check` (configs at repo root). +- **Zod** at MCP tool boundaries; explicit types on exported APIs. +- **No `process.env` reads** in feature code outside `resolveConfig` / CLI — thread `ServerConfig`. +- Tool errors: `jsonErrorResponse` with `ToolError` from `tool-error.ts`. +- Tests beside sources as `*.test.ts`; use Vitest. + +Additional guides live under [`docs/`](docs/README.md) (TOOLS, CONFIGURATION, MIGRATION, CI_CD). diff --git a/README.md b/README.md index ec58832..a49bb02 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,11 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that implements the MCP specification via `@modelcontextprotocol/sdk` v1.25+ and 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. +**Current version: 0.3.0** (npm `latest` after publish). Pin `@0.3.0` in install and MCP config for reproducible upgrades. + +## Upgrading to 0.3.0 + +Version **0.3.0** includes breaking MCP and library changes: experimental response fields nested under `experimental`, branded `CoreServerConfig` / `AllianceServerConfig`, legacy module-facade deprecations, and core `resolveConfig` requiring an index name with suggest-flow off by default. See [docs/MIGRATION.md](docs/MIGRATION.md) for before/after examples and the [CHANGELOG](CHANGELOG.md#030---2026-06-23) **Changed** section for the full list. ## Upgrading from 0.1.x @@ -29,7 +33,7 @@ While the package is **`0.y.z`**, minor releases may include breaking changes ([ | [docs/deprecation-policy.md](docs/deprecation-policy.md) | Release & deprecation policy | | [docs/CI_CD.md](docs/CI_CD.md) | GitHub Actions, SBOM, Docker, releases | | [docs/RELEASING.md](docs/RELEASING.md) | npm publish via GitHub Releases | -| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | How to contribute | +| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute | | [docs/SECURITY.md](docs/SECURITY.md) | Vulnerability reporting | ## Error responses @@ -65,25 +69,25 @@ For successful `query`, `query_documents`, and `guided_query` payloads, **rerank ### As a Package ```bash -npm install @will-cppa/pinecone-read-only-mcp@0.2.0 +npm install @will-cppa/pinecone-read-only-mcp@0.3.0 ``` Or using yarn: ```bash -yarn add @will-cppa/pinecone-read-only-mcp@0.2.0 +yarn add @will-cppa/pinecone-read-only-mcp@0.3.0 ``` Or using pnpm: ```bash -pnpm add @will-cppa/pinecone-read-only-mcp@0.2.0 +pnpm add @will-cppa/pinecone-read-only-mcp@0.3.0 ``` ### Global Installation ```bash -npm install -g @will-cppa/pinecone-read-only-mcp@0.2.0 +npm install -g @will-cppa/pinecone-read-only-mcp@0.3.0 ``` ### From Source @@ -249,7 +253,7 @@ Add to your `claude_desktop_config.json`: "mcpServers": { "pinecone-search": { "command": "npx", - "args": ["-y", "@will-cppa/pinecone-read-only-mcp@0.2.0"], + "args": ["-y", "@will-cppa/pinecone-read-only-mcp@0.3.0"], "env": { "PINECONE_API_KEY": "your-api-key-here", "PINECONE_INDEX_NAME": "your-index-name", @@ -269,7 +273,7 @@ Or with explicit options: "command": "npx", "args": [ "-y", - "@will-cppa/pinecone-read-only-mcp@0.2.0", + "@will-cppa/pinecone-read-only-mcp@0.3.0", "--api-key", "your-api-key-here", "--index-name", @@ -302,7 +306,7 @@ For a global installation: Run the server using npx (no installation required): ```bash -npx @will-cppa/pinecone-read-only-mcp@0.2.0 --api-key YOUR_API_KEY --index-name YOUR_INDEX +npx @will-cppa/pinecone-read-only-mcp@0.3.0 --api-key YOUR_API_KEY --index-name YOUR_INDEX ``` Or if installed globally: @@ -342,10 +346,10 @@ Run `pinecone-read-only-mcp --help` for the full option list. ```bash # install -npm i @will-cppa/pinecone-read-only-mcp@0.2.0 +npm i @will-cppa/pinecone-read-only-mcp@0.3.0 # run -npx @will-cppa/pinecone-read-only-mcp@0.2.0 --api-key YOUR_API_KEY +npx @will-cppa/pinecone-read-only-mcp@0.3.0 --api-key YOUR_API_KEY ``` ### Deploy with Docker @@ -751,14 +755,7 @@ npm run dev -- --api-key YOUR_API_KEY ### Contribution Guidelines -1. Fork the repository -2. Create a feature branch: `git checkout -b feature-name` -3. Make your changes and add tests -4. Ensure all tests pass: `npm test` -5. Ensure code quality checks pass: `npm run lint && npm run format:check && npm run typecheck` -6. Commit your changes: `git commit -am 'Add some feature'` -7. Push to the branch: `git push origin feature-name` -8. Submit a pull request +See [CONTRIBUTING.md](CONTRIBUTING.md) for prerequisites, dev setup, architecture overview, PR conventions, and code style. Run `npm run ci` before opening a pull request. ## Dependencies diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 7325f88..12aa084 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,62 +1,11 @@ # Contributing -## Prerequisites +The canonical contributor guide is at the repository root: **[CONTRIBUTING.md](../CONTRIBUTING.md)**. -- **Node.js ≥ 20.12** (see `engines` in `package.json` — Vitest 4 / coverage require it). -- npm (lockfile is `package-lock.json`). +It covers prerequisites, dev setup, architecture overview, PR conventions, and code style. -## Setup +Topic-specific supplements (also linked from the root guide): -```bash -git clone https://github.com/cppalliance/pinecone-read-only-mcp-typescript.git -cd pinecone-read-only-mcp-typescript -npm ci -``` - -## Commands - -| Script | Purpose | -| ------ | ------- | -| `npm run build` | Clean `dist/` and `tsc` compile | -| `npm run typecheck` | `tsc --noEmit` | -| `npm run lint` | ESLint on `src/` | -| `npm run lint:fix` | ESLint with `--fix` | -| `npm run format` | Prettier write (`src/**/*.ts`, config JSON) | -| `npm run format:check` | Prettier check | -| `npm test` | Vitest once | -| `npm run test:coverage` | Vitest + coverage thresholds (`vitest.config.ts`) | -| `npm run ci` | Full local gate (typecheck, lint, format, build, coverage) | - -## Coding conventions - -- **TypeScript strict** options enabled (`strict`, `noUncheckedIndexedAccess`, etc.). -- Prefer explicit types on exported APIs; use Zod at MCP tool boundaries. -- **No `process.env` reads** in feature code outside `resolveConfig` / CLI — thread `ServerConfig`. -- Tool errors: return `jsonErrorResponse` with `ToolError` shapes from `tool-error.ts`. -- Tests live beside sources as `*.test.ts`; use Vitest. - -## Pull requests - -- Run `npm run ci` before pushing. -- Keep changes focused; update `CHANGELOG.md` `[Unreleased]` for user-visible behavior. -- Documentation changes should keep [README](../README.md) links; run `npm run docs:link-check` locally if you touch many relative links. - -### Deprecations and breaking changes - -Follow [deprecation-policy.md](./deprecation-policy.md). In summary: - -- **Deprecating** an API: add `### Deprecated` in CHANGELOG with a removal target (minimum two minor releases), update [MIGRATION.md](./MIGRATION.md), and use `@deprecated` in types when applicable. -- **Breaking** a release (especially while `0.y.z`): use labeled bullets — `**Breaking (MCP):**`, `**Breaking (types):**`, etc. — each with what changed, who is affected, and a link to a MIGRATION anchor. -- **Removing** deprecated APIs: add `### Removed` only after the deprecation window; keep migration text in MIGRATION.md. - -## Response field stability - -When changing MCP tool **success** response shapes: - -- New fields default to the **`experimental`** nested object unless explicitly promoted (see [deprecation-policy.md § Stable vs experimental](./deprecation-policy.md#stable-vs-experimental-mcp-response-fields)). -- Update Zod schemas in `src/core/server/response-schemas.ts` and export from `src/core/index.ts`. -- Update [TOOLS.md](./TOOLS.md) stable/experimental tables for the affected tool(s). - -## Documentation - -Authoritative reference lives under [`docs/`](./README.md). When adding tools or config knobs, update `docs/TOOLS.md` and `docs/CONFIGURATION.md` in the same PR when possible. +- [deprecation-policy.md](./deprecation-policy.md) — semver, deprecation window, CHANGELOG conventions +- [TOOLS.md](./TOOLS.md) — tool catalog and stable vs experimental response fields +- [CONFIGURATION.md](./CONFIGURATION.md) — env vars, CLI flags, core vs Alliance defaults diff --git a/docs/deprecation-policy.md b/docs/deprecation-policy.md index 3e12c7b..bec3469 100644 --- a/docs/deprecation-policy.md +++ b/docs/deprecation-policy.md @@ -10,7 +10,7 @@ For step-by-step upgrades, see [MIGRATION.md](./MIGRATION.md). For publish mecha ## Semantic versioning while `0.y.z` -This package currently ships as **`0.y.z`**. Under [Semantic Versioning §4](https://semver.org/spec/v2.0.0.html#spec-item-4), **minor releases may include breaking changes** until the first `1.0.0` release. Consumers should **pin an exact version** (for example `@will-cppa/pinecone-read-only-mcp@0.2.0`) in `package.json`, MCP server config, and Docker tags. +This package currently ships as **`0.y.z`**. Under [Semantic Versioning §4](https://semver.org/spec/v2.0.0.html#spec-item-4), **minor releases may include breaking changes** until the first `1.0.0` release. Consumers should **pin an exact version** (for example `@will-cppa/pinecone-read-only-mcp@0.3.0`) in `package.json`, MCP server config, and Docker tags. After **`1.0.0`**, this project intends to follow standard semver: breaking changes land only in **major** releases, and the deprecation window below becomes **binding** for removals that were previously announced as deprecated. From 362892a6d49483c064e56c5f5908c708dc8e22d6 Mon Sep 17 00:00:00 2001 From: zho Date: Tue, 30 Jun 2026 01:23:49 +0800 Subject: [PATCH 2/3] docs: sync README to v0.3.0 and add CODEOWNERS + CONTRIBUTING --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a49bb02..9cea0c3 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that implements the MCP specification via `@modelcontextprotocol/sdk` v1.25+ and provides semantic search over Pinecone vector databases using hybrid search (dense + sparse) with reranking. -**Current version: 0.3.0** (npm `latest` after publish). Pin `@0.3.0` in install and MCP config for reproducible upgrades. +Current version: 0.3.0 (npm `latest` after publish). Pin `@0.3.0` in install and MCP config for reproducible upgrades. ## Upgrading to 0.3.0 From c8e0e4d98710776101da265f20149a8975b0a564 Mon Sep 17 00:00:00 2001 From: zho Date: Tue, 30 Jun 2026 01:39:01 +0800 Subject: [PATCH 3/3] docs: remove docs/CONTRIBUTING.md stub; link to root guide only Single CONTRIBUTING.md at repo root; update docs index and deprecation-policy links. Co-authored-by: Cursor --- docs/CONTRIBUTING.md | 11 ----------- docs/README.md | 2 +- docs/deprecation-policy.md | 4 ++-- 3 files changed, 3 insertions(+), 14 deletions(-) delete mode 100644 docs/CONTRIBUTING.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md deleted file mode 100644 index 12aa084..0000000 --- a/docs/CONTRIBUTING.md +++ /dev/null @@ -1,11 +0,0 @@ -# Contributing - -The canonical contributor guide is at the repository root: **[CONTRIBUTING.md](../CONTRIBUTING.md)**. - -It covers prerequisites, dev setup, architecture overview, PR conventions, and code style. - -Topic-specific supplements (also linked from the root guide): - -- [deprecation-policy.md](./deprecation-policy.md) — semver, deprecation window, CHANGELOG conventions -- [TOOLS.md](./TOOLS.md) — tool catalog and stable vs experimental response fields -- [CONFIGURATION.md](./CONFIGURATION.md) — env vars, CLI flags, core vs Alliance defaults diff --git a/docs/README.md b/docs/README.md index 64ff003..0b183a0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,7 +7,7 @@ Guides for operators, MCP client authors, and library embedders. | [TOOLS.md](./TOOLS.md) | All MCP tools, parameters, success/error shapes, suggest-flow | | [CONFIGURATION.md](./CONFIGURATION.md) | Environment variables, CLI flags, `resolveConfig`, precedence | | [SECURITY.md](./SECURITY.md) | API keys, log redaction, Docker hardening, reporting issues | -| [CONTRIBUTING.md](./CONTRIBUTING.md) | Local dev, tests, lint/format, PR expectations | +| [CONTRIBUTING.md](../CONTRIBUTING.md) | Local dev, tests, lint/format, PR expectations | | [CI_CD.md](./CI_CD.md) | GitHub Actions, CodeQL, SBOM, Codecov, releases | | [FAQ.md](./FAQ.md) | Common questions | | [MIGRATION.md](./MIGRATION.md) | Breaking changes and upgrade paths | diff --git a/docs/deprecation-policy.md b/docs/deprecation-policy.md index bec3469..ae7caa2 100644 --- a/docs/deprecation-policy.md +++ b/docs/deprecation-policy.md @@ -142,7 +142,7 @@ Each breaking bullet should state: - `old_name` on … — use `new_name` instead; removal targeted in **0.4.0** (deprecated **0.2.0**). See [MIGRATION.md](./MIGRATION.md#anchor). ``` -Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md) for PR expectations. +Contributors: see [CONTRIBUTING.md](../CONTRIBUTING.md) for PR expectations. ## Release hygiene @@ -156,6 +156,6 @@ Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md) for PR expectations. | -------- | ---- | | [MIGRATION.md](./MIGRATION.md) | Per-version upgrade how-to | | [CHANGELOG.md](../CHANGELOG.md) | Authoritative change list | -| [CONTRIBUTING.md](./CONTRIBUTING.md) | PR and CHANGELOG expectations | +| [CONTRIBUTING.md](../CONTRIBUTING.md) | PR and CHANGELOG expectations | | [RELEASING.md](./RELEASING.md) | npm publish via GitHub Releases | | [templates/breaking-change-release-notes.md](./templates/breaking-change-release-notes.md) | GitHub Release body template |