refactor: trim MCP instructions and fix Alliance appendix numbering

[jonathanMLDev]

Description

Trim operator/install/deploy content from default MCP instructions strings and restructure the Alliance appendix for clarity. No runtime behavior change — setupCoreServer / setupAllianceServer defaults, config resolvers, and the instructions override are unchanged.

Addresses instruction review concerns C2 (operator token cost), C3 (duplicate Alliance step numbering), and C6 (suggest-flow escape clause).

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code quality improvement
• Performance improvement

Changes Made

src/constants.ts

• Removed env-var setup, misconfiguration note, Alliance CLI index/rerank defaults, and stderr logging config from instruction strings
• Reranking feature bullet is mechanism-only (no PINECONE_RERANK_MODEL framing)
• Replaced colliding Alliance appendix steps 4–5 with unnumbered "Manual Alliance flow" bullets
• Added PINECONE_DISABLE_SUGGEST_FLOW=true escape clause to the manual-flow bullet

src/constants.test.ts

• Added guards: no operator/deploy content, no duplicate step numbering, escape clause present
• Removed rag-hybrid assertion from appendix test

docs/CONFIGURATION.md

• Extended startup-throw bullet with "not as an MCP tool error" contrast

CHANGELOG.md

• [Unreleased] > Changed entry for instruction trim

Token reduction

String	Before	After	Delta
CORE_SERVER_INSTRUCTIONS	1,494	1,283	−211
ALLIANCE_INSTRUCTIONS_APPENDIX	761	492	−269
ALLIANCE_SERVER_INSTRUCTIONS	2,255	1,775	−480

Testing

• All existing tests pass (npm run ci — 339 tests)
• Added new tests for changes
• Manual testing performed

Related issues

• Close Trim install/deploy documentation from runtime MCP instructions #193
• Close De-duplicate Alliance usage section numbering in MCP instructions #194
• Close Add suggest-flow escape clause to Alliance appendix step 4 #196

Additional Notes

No API, tool surface, or config default changes. Stripped operator content was already documented in docs/CONFIGURATION.md and README.md; the only doc addition is clarifying that missing config throws at startup, not as an MCP tool error.

Summary by CodeRabbit

• Documentation

  • Clarified how startup failures are reported when required settings (such as apiKey or indexName) are missing in single-key mode.
  • Updated configuration/changelog guidance to reflect streamlined instruction text and revised manual alliance flow steps, including an escape clause for suggest-flow behavior.

• Tests

  • Expanded assertions to verify the updated instruction wording, manual flow formatting, and presence of the suggest-flow escape clause.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 26bb8359-514a-4121-9a09-8214099540d8

📥 Commits

Reviewing files that changed from the base of the PR and between 5285254 and 3a3b532.

📒 Files selected for processing (2)

• src/constants.test.ts
• src/constants.ts

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

• src/constants.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/constants.test.ts

---

📝 Walkthrough

Walkthrough

This PR trims operator/install/deploy content from the core and Alliance instruction strings, rewrites the Alliance manual flow into unnumbered bullets with a suggest-flow escape clause, and updates tests plus supporting changelog and configuration notes.

Changes

Instruction content and Alliance flow updates

Layer / File(s)	Summary
Trim core instruction content src/constants.ts, docs/CONFIGURATION.md	Updates reranking and result-row guidance in the core instruction text, removes the stderr logging note, and clarifies that the missing-after-trim apiKey/indexName error occurs at server startup.
Revise Alliance manual flow src/constants.ts	Replaces the Alliance appendix deployment/default text with unnumbered manual flow bullets that keep the mandatory suggest gate wording and include PINECONE_DISABLE_SUGGEST_FLOW=true.
Extend tests and update docs src/constants.test.ts, CHANGELOG.md	Adds assertions for removed operator/deploy strings, appendix structure, the single Usage: occurrence, and the suggest-flow escape clause, and updates the unreleased changelog entry.

Estimated code review effort: 2 (Simple) | ~12 minutes

Possibly related PRs

• cppalliance/pinecone-read-only-mcp-typescript#125: Updates the same instruction constants and tests around core/alliance prompt text and suggest-flow wording.
• cppalliance/pinecone-read-only-mcp-typescript#167: Also edits the exported instruction strings and related tests for guided_query and disableSuggestFlow messaging.

Suggested reviewers: wpak-ai, leostar0412

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: trimming MCP instructions and fixing Alliance appendix numbering.
Linked Issues check	✅ Passed	The changes align with issues #193, #194, and #196 by trimming runtime instructions, de-duplicating Alliance flow numbering, and preserving the escape clause.
Out of Scope Changes check	✅ Passed	No clear out-of-scope changes are present; the changelog, docs, and tests all support the stated instruction-cleanup goals.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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.}

[codecov]

Codecov Report

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

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #197   +/-   ##
=======================================
  Coverage        ?   83.86%           
=======================================
  Files           ?       45           
  Lines           ?     2306           
  Branches        ?      779           
=======================================
  Hits            ?     1934           
  Misses          ?      372           
  Partials        ?        0           

☔ View full report in Codecov by Harness.
📢 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.

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@src/constants.test.ts`:
- Around line 40-45: The duplicate-numbering guard in the
ALLIANCE_INSTRUCTIONS_APPENDIX test only checks for a numbered 4. step, so it
can miss a future 5. step appearing alone. Update the assertion in
src/constants.test.ts around ALLIANCE_INSTRUCTIONS_APPENDIX to cover both step-4
and step-5 numbering patterns, using the same test block that currently
references ALLIANCE_SERVER_INSTRUCTIONS and ALLIANCE_INSTRUCTIONS_APPENDIX, so
the guard detects either duplicate numbering case.

In `@src/constants.ts`:
- Around line 66-72: The Alliance appendix in ALLIANCE_INSTRUCTIONS_APPENDIX
repeats the suggest-flow gate in two places and should be consolidated into a
single guidance statement. Update the appended text so the mandatory gate around
suggest_query_params is stated once, and ensure that gate explicitly applies to
query, count, and query_documents in the unified instruction. Keep the wording
aligned with the existing manual flow guidance while removing the duplicated
bullet/paragraph redundancy.

🪄 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: d5edfc4d-9eda-4800-99ed-bf21b5d76af0

📥 Commits

Reviewing files that changed from the base of the PR and between 680929e and 5285254.

📒 Files selected for processing (4)

• CHANGELOG.md
• docs/CONFIGURATION.md
• src/constants.test.ts
• src/constants.ts

[leostar0412]

LGTM!