Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Kikobeats merged 1 commit into from
Sep 13, 2026
+3 −1
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion packages/mcp/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,9 +161,11 @@ Each tool is a thin wrapper over a [`microlink.io`](https://github.com/microlink
### Response shape

- Each tool returns the library's **direct result** under `structuredContent.data` (and the same value as pretty-printed JSON text). For example `microlink_markdown` → `{ data: "# Title\n..." }`, `microlink_screenshot` → `{ data: { url, type, width, height, size } }`, `microlink_links` → `{ data: ["https://...", ...] }`.
- Every tool also declares an MCP `outputSchema` describing its `structuredContent.data`, mirroring the TypeScript types shipped by the library (`Asset`, `Metadata`, `Embed`, `FunctionResult`, ...), so MCP clients get machine-readable result contracts. Error results are exempt from output validation. Fields that can legitimately be absent are nullable (for example `logo` when no brand logo is detected, or `markdown` when the selector matches nothing).
- Tools are annotated `readOnlyHint: true` since they only fetch and transform public URLs. The exception is `microlink_function`, which executes user-supplied code and is not annotated read-only.
- On failure the tool sets MCP `isError` and returns `{ error: { message, code?, status?, statusCode?, url?, more?, details? } }`, where `message` carries the specific cause reported by the API. Capability errors that retrying cannot fix (for example `EPROXYNEEDED` or `EINTEGRATION`) also include machine-readable `reason` (`upgrade_required`), `capability`, an `upgrade` object with the plan and pricing URL, and an agent-facing `hint` with the next step. A `429` includes `reason: "quota_exceeded"` and a free-quota `hint`.

Parameters labeled `PRO` in the official Microlink docs require a paid plan.
Parameters that require a paid plan are labeled `PRO` in their own schema descriptions, mirroring the official Microlink docs.
For compatibility with some MCP clients:
- boolean parameters also accept the strings `"true"` and `"false"` and are normalized before validation.
- parameters that accept objects also accept JSON stringified objects (for example, `screenshot: "{\"overlay\":{\"browser\":\"dark\"}}"`).
Expand Down