docs(mcp): document output schemas and read-only annotations in README

[Kikobeats]

What

The README's "Response shape" section predates the 2.4.0 protocol work. This adds:

• Every tool declares an MCP outputSchema for structuredContent.data, mirroring the library's TypeScript types (Asset, Metadata, Embed, FunctionResult, ...); error results are exempt from output validation; legitimately absent fields are nullable (logo with no detected brand logo, markdown with no selector match, ...).
• Tools are annotated readOnlyHint: true (they only fetch/transform public URLs), except microlink_function, which executes user-supplied code.
• PRO parameters now say so in their own schema descriptions, not only in the external docs.

Docs only, no code changes.

---

Note

Low Risk
Documentation-only README edits with no runtime or API behavior changes.

Overview
Updates the Response shape section in packages/mcp/README.md so it matches the 2.4.0 MCP protocol behavior.

It now documents that each tool exposes an MCP outputSchema for structuredContent.data (aligned with library types like Asset, Metadata, Embed, FunctionResult), with errors exempt from output validation and optional fields marked nullable. It also notes readOnlyHint: true on fetch/transform tools, with microlink_function excluded because it runs user-supplied code.

PRO paid-plan parameters are described as labeled in per-parameter schema descriptions (not only in external Microlink docs). The failure-response bullet is unchanged in substance; it sits after the new bullets in the list.

^{Reviewed by Cursor Bugbot for commit ea3f82d. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Documentation
  • Documented MCP tool response schemas for structured data, including nullable fields and error handling.
  • Documented read-only annotations for tools, with the exception of microlink_function.
  • Clarified that paid-plan parameters are labeled PRO in their schema descriptions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 2525cff3-43f2-4771-9a80-3bd72a6fdfe7

📥 Commits

Reviewing files that changed from the base of the PR and between f2d20e6 and ea3f82d.

📒 Files selected for processing (1)

• packages/mcp/README.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The MCP README now documents tool output schemas, read-only annotations, and the labeling of parameters that require a paid plan.

Changes

MCP README updates

Layer / File(s)	Summary
Response shape and tool metadata packages/mcp/README.md	Documents MCP outputSchema declarations, readOnlyHint annotations, the microlink_function exception, and PRO labels in schema descriptions.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to ea3f8

This PR only documents existing MCP behavior and introduces no runtime changes or merge-blocking risk.

🚥 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 clearly and concisely describes the README documentation changes for output schemas and read-only annotations, which are the main changes in the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/mcp-readme-2-4-0

---

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

[github-actions]

Coverage Report for CI Build 34701993503

Warning

No base build found for commit f2d20e6 on master.
Coverage changes can't be calculated without a base build.
If a base build is processing, this comment will update automatically when it completes.

Coverage: 79.358%

Details

• Patch coverage: No coverable lines changed in this PR.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

Requires a base build to compare against. How to fix this →

---

Coverage Stats

Relevant Lines:	5152
Covered Lines:	4098
Line Coverage:	79.54%
Relevant Branches:	865
Covered Branches:	677
Branch Coverage:	78.27%
Branches in Coverage %:	Yes
Coverage Strength:	25.06 hits per line

---

💛 - Coveralls

[Kikobeats]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.