docs(mcp): add troubleshooting guidance and missing env vars

[erraggy]

Summary

• ✨ Add 4 missing env vars (OASTOOLS_ALLOW_PRIVATE_IPS, OASTOOLS_MAX_INLINE_SIZE, OASTOOLS_MAX_LIMIT, OASTOOLS_MAX_JOIN_SPECS) to both the MCP protocol-level serverInstructions and plugin/CLAUDE.md config table
• 🔧 Add troubleshooting sections to both files covering SSRF blocks (initial request + redirect variant), inline content size limits, and env var restart requirements
• Error message text matches actual code output (verified against safeclient.go and input.go)
• SSRF scope correctly documented as private/loopback/link-local (matching isBlockedIP())

Motivation

When an LLM agent uses spec.url to fetch a spec from a private/internal host, the SSRF protection blocks it with "blocked request to private/loopback IP: <host> (<ip>)". Without guidance, agents fall back to workarounds like curl — bypassing the MCP tools entirely. The troubleshooting sections explicitly guide agents to the proper env var fix.

Test plan

• go build ./cmd/oastools — compiles clean
• make check — all 8498 tests pass, 0 lint errors, 0 markdown lint errors
• MCP initialize response verified: built from source, sent JSON-RPC initialize request over stdio, confirmed instructions field contains the new env vars and troubleshooting section
• Error message text verified against safeclient.go:36,58 and input.go:202
• Env var defaults verified against config.go:59-62
• Cross-file consistency confirmed between server.go, plugin/CLAUDE.md, and docs/mcp-server.md

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@erraggy has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 9 minutes and 11 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

Added four environment variable options to server instructions and docs (OASTOOLS_ALLOW_PRIVATE_IPS, OASTOOLS_MAX_INLINE_SIZE, OASTOOLS_MAX_LIMIT, OASTOOLS_MAX_JOIN_SPECS), expanded troubleshooting guidance, and appended an allow-hint to error messages that block private/loopback IPs during safe client requests.

Changes

Cohort / File(s)	Summary
Server instructions / internal docs internal/mcpserver/server.go	Added four new environment variables with defaults and descriptions; expanded Troubleshooting with guidance on private IP blocking, inline content size limits, and restart requirement for env var changes.
User-facing documentation plugin/CLAUDE.md	Documented the same four env vars, defaults, usage notes, and troubleshooting; added example MCP config snippet.
Safe client behavior internal/mcpserver/safeclient.go	Updated error messages that block requests or redirects to private/loopback IPs to include guidance text: “; set OASTOOLS_ALLOW_PRIVATE_IPS=true to allow”. Control flow unchanged.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs(mcp): add troubleshooting guidance and missing env vars' accurately summarizes the main changes: adding documentation with troubleshooting guidance and missing environment variables to the MCP server.
Description check	✅ Passed	The description comprehensively covers the changeset, detailing the four new environment variables, troubleshooting sections, and verification work performed including test results and cross-file consistency checks.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/mcp-troubleshooting-guidance

---

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

❌ Patch coverage is 83.33333% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.78%. Comparing base (aad19f1) to head (94e93f2).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/mcpserver/safeclient.go	0.00%	2 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #346   +/-   ##
=======================================
  Coverage   84.78%   84.78%           
=======================================
  Files         193      193           
  Lines       27249    27255    +6     
=======================================
+ Hits        23102    23108    +6     
  Misses       2828     2828           
  Partials     1319     1319           

Files with missing lines	Coverage Δ
internal/mcpserver/config.go	100.00% <100.00%> (ø)
internal/mcpserver/input.go	81.60% <100.00%> (ø)
internal/mcpserver/server.go	91.85% <ø> (ø)
internal/mcpserver/tools_join.go	91.42% <100.00%> (ø)
internal/mcpserver/safeclient.go	22.58% <0.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@internal/mcpserver/server.go`:
- Around line 36-41: Update the ambiguous inline-size error message in the
Troubleshooting text so the two numeric placeholders are distinct (e.g., replace
the duplicated "<N>" placeholders in "inline content size <N> bytes exceeds
maximum <N> bytes" with "<actual>" and "<limit>" or similar), ensuring the
message unambiguously shows the actual size and the configured limit; modify the
string in internal/mcpserver/server.go where that troubleshooting text is
declared so any validation or verification scripts that match the
plugin/CLAUDE.md wording continue to work.

In `@plugin/CLAUDE.md`:
- Line 191: Update the inline-size error template so the two placeholders are
distinct and unambiguous: replace the duplicated "<N>" placeholders in the
string "inline content size <N> bytes exceeds maximum <N> bytes" with clearly
named placeholders (e.g., "<ACTUAL_BYTES>" and "<MAX_BYTES>" or "{actual}" and
"{max}") and update any documentation examples to use the new placeholders and a
concrete example like "inline content size 15000000 bytes exceeds maximum
10485760 bytes" so readers can immediately map values to their meaning.