Document teardown, degradation signals, and example mocks

[jonathanMLDev]

Pull Request

README.md

• Documents teardownServer() for re-init in the same process; second setupServer() throws without it.
• Points to degradation fields (degraded, degradation_reason, hybrid_leg_failed) instead of saying they are missing.

docs/TOOLS.md

• QueryResponse success shape includes degradation fields.
• New Rerank and hybrid degradation section with a field table.
• guided_query notes rerank_status and nested degradation fields.

CHANGELOG.md

• [Unreleased] entries for teardownServer, namespace trimming, degradation envelope, setupServer guard, and config-only PineconeClient.

examples/library-embedding-demo.ts

• Comment updated to mention teardownServer() (no unused imports).
  npm run docs:link-check passes, including the new #rerank-and-hybrid-degradation anchor. You can commit when ready.

Related Issue

close #102

Summary by CodeRabbit

• New Features

  • Added teardownServer() to reset process-global state so setupServer() can be re-initialized in the same Node process.
  • Demo/mock Pinecone client and in-memory linked transports available for examples and testing.

• Breaking Changes

  • setupServer() now throws if called twice without teardownServer().
  • Pinecone client configuration now uses explicit client config for index/rerank/top-k.

• Documentation

  • Query/guided_query now document degradation fields: degraded, degradation_reason, hybrid_leg_failed and related behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation updates record the setupServer()/teardownServer lifecycle constraint and add query response degradation envelope fields; examples include a demo Pinecone mock client, in-memory linked MCP transports, and an examples tsconfig.

Changes

Documentation: Lifecycle and Query Degradation Contract

Layer / File(s)	Summary
setupServer/teardownServer lifecycle API CHANGELOG.md, README.md, examples/library-embedding-demo.ts	CHANGELOG and README document that setupServer() throws if called a second time without teardownServer() first; teardownServer() is exported to reset process-global state. The library embedding example notes this constraint for test re-initialization.
Query response contract: degradation envelope docs/TOOLS.md, CHANGELOG.md	TOOLS.md extends the query response schema with degraded, degradation_reason, and hybrid_leg_failed fields and adds a “Rerank and hybrid degradation” section; guided_query decision_trace now includes rerank_status. CHANGELOG records these payload changes.
Documentation reference updates README.md	README link for query/guided_query rerank and hybrid fidelity updated to point to docs/TOOLS.md#rerank-and-hybrid-degradation.
Examples and demo utilities examples/demo-mock-pinecone-client.ts, examples/mcp-linked-transport.ts, examples/tsconfig.json	Adds DemoMockPineconeClient and DEMO_NAMESPACE, in-memory linked MCP Transport pairs for local testing, and an examples/tsconfig.json for example builds.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• cppalliance/pinecone-read-only-mcp-typescript#31: Related to listNamespacesFromKeywordIndex and keyword-index workflows.
• cppalliance/pinecone-read-only-mcp-typescript#86: Overlaps in Pinecone client namespace-listing changes and return semantics.

Suggested labels

enhancement

Suggested reviewers

• wpak-ai
• whisper67265

"From burrows deep I hop to say,
teardown makes testing light as day.
Docs now sing when reranks fail,
mocks and transports blaze the trail.
Hare-hops and cheers — deploy away!"

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	All coding objectives from issue #102 are met: teardownServer() is documented in README and examples, degradation fields are documented in TOOLS.md and README, and CHANGELOG entries are added for teardownServer, namespace trimming, and degradation envelope.
Out of Scope Changes check	✅ Passed	The PR includes appropriate supporting changes (new example files and tsconfig) that align with documenting the library embedding pattern and providing demonstration code related to the lifecycle/degradation features described.
Title check	✅ Passed	The title accurately summarizes the main changes: documentation updates for teardownServer lifecycle, degradation signals in responses, and new example mock/transport utilities.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@00edba7). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #103   +/-   ##
=======================================
  Coverage        ?   80.63%           
=======================================
  Files           ?       34           
  Lines           ?     1265           
  Branches        ?      414           
=======================================
  Hits            ?     1020           
  Misses          ?      243           
  Partials        ?        2           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jonathanMLDev]

@coderabbitai why did you skip? full review again

[coderabbitai]

@jonathanMLDev Apologies for the missed review! I'll kick off a full review of this PR right away.

(´･ω･`) 🐇

✅ Actions performed

Full review triggered.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

examples/tsconfig.json (1)

10-12: 💤 Low value

Consider adding wildcard path mapping for flexibility.

The current path maps the package to a single file (../dist/server.js). This works if server.js exports the entire public API, but won't support subpath imports (e.g., @will-cppa/pinecone-read-only-mcp/utils). For future-proofing, consider:

"paths": {
  "`@will-cppa/pinecone-read-only-mcp`": ["../dist/server.js"],
  "`@will-cppa/pinecone-read-only-mcp/`*": ["../dist/*"]
}

For in-repo examples, the current approach is acceptable.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/tsconfig.json` around lines 10 - 12, The tsconfig "paths" mapping
for the module '`@will-cppa/pinecone-read-only-mcp`' currently points only to
"../dist/server.js" which prevents subpath imports like
"`@will-cppa/pinecone-read-only-mcp/utils`"; update the paths mapping to add a
wildcard entry "`@will-cppa/pinecone-read-only-mcp/`*" that points to the compiled
distribution (e.g., "../dist/*") so both bare and subpath imports resolve;
modify the "paths" object that contains "`@will-cppa/pinecone-read-only-mcp`" to
include the additional wildcard mapping.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/mcp-linked-transport.ts`:
- Around line 19-30: The send methods on the linked transport (the async send
functions on clientTransport and serverTransport) race with close because they
test the closed flag before queueing a microtask; update both send
implementations to perform the closed check inside the queued microtask (i.e.,
when actually about to call serverTransport.onmessage/clientTransport.onmessage)
rather than only before queueMicrotask, so that messages enqueued after close
are dropped; no change to close() behavior other than ensuring it still sets
closed = true and calls onclose handlers.

---

Nitpick comments:
In `@examples/tsconfig.json`:
- Around line 10-12: The tsconfig "paths" mapping for the module
'`@will-cppa/pinecone-read-only-mcp`' currently points only to "../dist/server.js"
which prevents subpath imports like "`@will-cppa/pinecone-read-only-mcp/utils`";
update the paths mapping to add a wildcard entry
"`@will-cppa/pinecone-read-only-mcp/`*" that points to the compiled distribution
(e.g., "../dist/*") so both bare and subpath imports resolve; modify the "paths"
object that contains "`@will-cppa/pinecone-read-only-mcp`" to include the
additional wildcard mapping.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 04be5f79-f8f7-4e29-b836-f3b57edb7893

📥 Commits

Reviewing files that changed from the base of the PR and between ba016c6 and 3f28515.

📒 Files selected for processing (4)

• README.md
• examples/demo-mock-pinecone-client.ts
• examples/mcp-linked-transport.ts
• examples/tsconfig.json

✅ Files skipped from review due to trivial changes (1)

• README.md