addressed review-library.md

Author: zho

.env.example

@@ -13,5 +13,22 @@ PINECONE_RERANK_MODEL=bge-reranker-v2-m3
 PINECONE_TOP_K=10
 
 # Optional: Logging level (default: INFO)
-# Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
+# Options: DEBUG, INFO, WARN, ERROR
 PINECONE_READ_ONLY_MCP_LOG_LEVEL=INFO
+
+# Optional: Logging format (default: text)
+# Options: text, json
+PINECONE_READ_ONLY_MCP_LOG_FORMAT=text
+
+# Optional: Sparse index name (default: ${PINECONE_INDEX_NAME}-sparse)
+# PINECONE_SPARSE_INDEX_NAME=rag-hybrid-sparse
+
+# Optional: Namespace + suggestion-flow cache TTL in seconds (default: 1800 = 30min)
+# PINECONE_CACHE_TTL_SECONDS=1800
+
+# Optional: Disable the suggest_query_params flow gate (default: false).
+# WARNING: turning this on bypasses the safety guard. A WARN log fires at startup.
+# PINECONE_DISABLE_SUGGEST_FLOW=false
+
+# Optional: Request timeout for Pinecone calls, in milliseconds (default: 15000)
+# PINECONE_REQUEST_TIMEOUT_MS=15000

.github/dependabot.yml

@@ -10,6 +10,21 @@ updates:
     labels:
       - "dependencies"
       - "automated"
+    groups:
+      vitest:
+        patterns:
+          - "vitest"
+          - "@vitest/*"
+      typescript-eslint:
+        patterns:
+          - "typescript-eslint"
+          - "@typescript-eslint/*"
+      eslint-prettier:
+        patterns:
+          - "eslint"
+          - "@eslint/*"
+          - "prettier"
+          - "eslint-config-prettier"
 
   - package-ecosystem: "github-actions"
     directory: "/"

.github/workflows/ci.yml

@@ -5,13 +5,15 @@ on:
     branches: [main]
   push:
     branches: [main]
-  workflow_call: # Allow this workflow to be called by other workflows
+  workflow_call:
 
 jobs:
   build-and-test:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
         node-version: [18.x, 20.x, 22.x]
 
     steps:
@@ -41,9 +43,32 @@ jobs:
       - name: Smoke test CLI
         run: node dist/index.js --help
 
-      - name: Run tests
+      - name: Run tests with coverage
+        if: matrix.os == 'ubuntu-latest' && matrix.node-version == '20.x'
+        run: npm run test:coverage
+
+      - name: Run tests (no coverage)
+        if: "!(matrix.os == 'ubuntu-latest' && matrix.node-version == '20.x')"
         run: npm test
 
+      - name: Generate CycloneDX SBOM (lockfile-based)
+        if: matrix.os == 'ubuntu-latest' && matrix.node-version == '20.x'
+        run: npx --yes @cyclonedx/cyclonedx-npm --package-lock-only --output-file sbom.cdx.json
+
+      - name: Upload SBOM artifact
+        if: matrix.os == 'ubuntu-latest' && matrix.node-version == '20.x'
+        uses: actions/upload-artifact@v4
+        with:
+          name: sbom-cyclonedx
+          path: sbom.cdx.json
+
+      - name: Upload coverage to Codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.node-version == '20.x'
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage/lcov.info
+          fail_ci_if_error: false
+
   quality:
     runs-on: ubuntu-latest
     steps:

.npmignore

@@ -32,6 +32,7 @@ node_modules/
 .vscode/
 .idea/
 dist/
+docs/
 
 # Testing
 coverage/

CHANGELOG.md

@@ -4,38 +4,43 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Future releases are managed automatically by [release-please](https://github.com/googleapis/release-please).
 
 ## [Unreleased]
 
 ### Added
 
-- `list_namespaces` tool: discovers all namespaces with record counts and sampled metadata fields
-- `namespace_router` tool: ranks namespaces by relevance to a natural-language query
-- `suggest_query_params` tool: mandatory flow gate that recommends fields and tool variant before queries
-- `count` tool: counts unique documents matching a query, with `truncated` flag when results exceed `COUNT_TOP_K`
-- `query_fast` tool: lightweight chunk-level search with minimal field set
-- `query_detailed` tool: chunk-level search with optional semantic reranking
-- `query` tool: unified query entry-point supporting `query_fast` and `query_detailed` modes
-- `guided_query` tool: single-call orchestrator that runs routing → suggestion → execution, returning a `decision_trace`
-- `generate_urls` tool: synthesizes URLs for records whose metadata lacks a `url` field
-- `query_documents` tool: reassembles full documents from chunks grouped by document identifier
-- Centralized structured logger (`src/logger.ts`) with level-gated stderr output and stack-trace capture
-- Dockerfile for containerised deployment
-- `About.md` project documentation covering architecture, tools, and operating principles
+- `SERVER_VERSION` is now read from `package.json` at runtime so MCP `serverInfo` always matches the published package version.
+- `--version` CLI flag prints the package version and exits.
+- `list_namespaces` response now includes `expires_at_iso` so clients see the cache expiry as an ISO-8601 timestamp without converting `cache_ttl_seconds`.
+- `docs/` handbook: `TOOLS.md`, `CONFIGURATION.md`, `FAQ.md`, `MIGRATION.md`, `CI_CD.md`, and `docs/README.md` index; root `RELEASING.md` stub points to `docs/RELEASING.md`.
+- `SECURITY.md`, `CONTRIBUTING.md`, and `CODE_OF_CONDUCT.md` for OSS hygiene.
+- `examples/README.md` describing the library embedding sample.
+- GitHub Actions: **multi-OS** CI matrix (Ubuntu, Windows, macOS × Node 18/20/22), **Codecov** upload (Ubuntu + Node 20), **CycloneDX SBOM** artifact, **Release Please**, and **Docker** multi-arch publish to **GHCR**.
+- `src/config.test.ts` and `npm run test:coverage` with Vitest coverage thresholds (see `vitest.config.ts`).
+- `@vitest/coverage-v8` devDependency for coverage reports (`lcov`, `json-summary`, HTML).
 
 ### Changed
 
-- Modularised server into focused files under `src/server/` (tools, caches, formatters, suggestion flow)
-- CI workflow updated: multi-node matrix (`18.x`, `20.x`, `22.x`), separate quality job with `continue-on-error`
-- Replaced all `console.error` calls in `pinecone-client.ts` with typed `logInfo` / `logDebug` / `logError`
+- `.env.example` log-level options corrected to the four levels actually supported (`DEBUG`, `INFO`, `WARN`, `ERROR`); the stale `WARNING`/`CRITICAL` values are gone.
+- README Slack URL example now matches the generator output (`https://app.slack.com/client/{team_id}/{channel_id}/p{messageId}`).
+- README "Comparison with Python Version" no longer claims an identical API interface; the new TypeScript-only tools (`guided_query`, `query_documents`, `keyword_search`, `namespace_router`, `suggest_query_params`, `count`, `generate_urls`) are listed explicitly.
+- `npm run ci` now runs `test:coverage` so merges are gated on coverage thresholds.
+- Dependabot groups related **vitest**, **typescript-eslint**, and **eslint/prettier** updates.
 
-### Fixed
 
-- Timestamp-based metadata filter now correctly handles numeric epoch values
+### Removed
+
+- Dead `test:mcp` npm script (referenced a `test-mcp-server.js` file that has never existed).
 
-### Security
+## [0.1.6] - 2026-04-24
 
-- N/A
+Historical 0.1.x releases (0.1.0 → 0.1.6) shipped the full tool surface
+(`list_namespaces`, `namespace_router`, `suggest_query_params`, `count`,
+`query`, `query_fast`, `query_detailed`, `keyword_search`, `query_documents`,
+`guided_query`, `generate_urls`), the structured `src/logger.ts`, the
+`Dockerfile`, and the modularised `src/server/` layout. See git history for
+details — going forward, all changes are tracked here by release-please.
 
 ## [0.1.1] - 2026-01-27
 
@@ -69,6 +74,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Environment variable support
 - Full documentation and examples
 
-[Unreleased]: https://github.com/CppDigest/pinecone-read-only-mcp-typescript/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/CppDigest/pinecone-read-only-mcp-typescript/compare/v0.1.6...HEAD
+[0.1.6]: https://github.com/CppDigest/pinecone-read-only-mcp-typescript/compare/v0.1.1...v0.1.6
 [0.1.1]: https://github.com/CppDigest/pinecone-read-only-mcp-typescript/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/CppDigest/pinecone-read-only-mcp-typescript/releases/tag/v0.1.0

README.md

@@ -7,6 +7,20 @@
 
 A Model Context Protocol (MCP) server that provides semantic search over Pinecone vector databases using hybrid search (dense + sparse) with reranking.
 
+## Documentation
+
+| Doc | Description |
+|-----|---------------|
+| [docs/README.md](docs/README.md) | Index of all guides |
+| [docs/TOOLS.md](docs/TOOLS.md) | Tool catalog & flows |
+| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Env vars, CLI flags, library config |
+| [docs/FAQ.md](docs/FAQ.md) | Common questions |
+| [docs/MIGRATION.md](docs/MIGRATION.md) | Deprecations & breaking changes |
+| [docs/CI_CD.md](docs/CI_CD.md) | GitHub Actions, SBOM, Docker, releases |
+| [RELEASING.md](RELEASING.md) | Pointer to the full release guide in `docs/` |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |
+| [SECURITY.md](SECURITY.md) | Vulnerability reporting |
+
 ## Features
 
 - **Hybrid Search**: Combines dense and sparse embeddings for superior recall
@@ -54,16 +68,19 @@ npm run build
 
 ## Configuration
 
-The server requires a Pinecone API key and supports the following configuration options:
+You need a **Pinecone API key** and (by default) a **dense** index plus matching **sparse** index; see [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for every environment variable and CLI flag.
+
+Quick reference:
 
-### Environment Variables
+| Variable | Required | Default |
+| -------- | -------- | ------- |
+| `PINECONE_API_KEY` | Yes (for live Pinecone) | — |
+| `PINECONE_INDEX_NAME` | No | `rag-hybrid` |
+| `PINECONE_SPARSE_INDEX_NAME` | No | `{index}-sparse` |
+| `PINECONE_READ_ONLY_MCP_LOG_LEVEL` | No | `INFO` (`DEBUG`–`ERROR`) |
+| `PINECONE_READ_ONLY_MCP_LOG_FORMAT` | No | `text` (`json` for log pipelines) |
 
-| Variable                           | Required | Default                | Description                                      |
-| ---------------------------------- | -------- | ---------------------- | ------------------------------------------------ |
-| `PINECONE_API_KEY`                 | Yes      | -                      | Your Pinecone API key                            |
-| `PINECONE_INDEX_NAME`              | No       | `rag-hybrid`           | Pinecone index name (dense + sparse for hybrid)   |
-| `PINECONE_RERANK_MODEL`            | No       | `bge-reranker-v2-m3`   | Reranking model                                  |
-| `PINECONE_READ_ONLY_MCP_LOG_LEVEL` | No       | `INFO`                 | Logging level                                    |
+Run `pinecone-read-only-mcp --help` for CLI equivalents (`--cache-ttl-seconds`, `--request-timeout-ms`, `--disable-suggest-flow`, etc.).
 
 ### Claude Desktop Configuration
 
@@ -301,7 +318,7 @@ Rules:
   Format: `https://lists.boost.org/archives/list/{doc_id_or_thread_id}/`
 - **`slack-Cpplang`**: prefer `source` directly if present; otherwise use `team_id`, `channel_id`, and `doc_id`  
   `message_id = doc_id.replace('.', '')`  
-  Format: `https://app.slack.com/{team_id}/{channel_id}/p{message_id}`
+  Format: `https://app.slack.com/client/{team_id}/{channel_id}/p{message_id}`
 
 **Parameters:**
 
@@ -577,13 +594,20 @@ npm run dev -- --api-key YOUR_API_KEY
 
 ## Comparison with Python Version
 
-This TypeScript implementation provides the same functionality as the [Python version](https://github.com/CppDigest/pinecone-read-only-mcp) with the following benefits:
+This TypeScript implementation grew out of the [Python version](https://github.com/CppDigest/pinecone-read-only-mcp) and now exposes a strict superset of its tool surface, including:
+
+- `guided_query` (single-call orchestrator with decision trace)
+- `query_documents` (full-document reassembly from chunks)
+- `keyword_search` (sparse-index-only retrieval)
+- `namespace_router` and `suggest_query_params` (flow guidance)
+- `count` and `generate_urls`
+
+Other benefits:
 
 - Native Node.js integration
 - Better npm ecosystem integration
 - TypeScript type safety
 - Similar performance characteristics
-- Same API interface
 
 ## Troubleshooting