MCP Server for Markly.cloud - watermark images via AI agents
Markly MCP server has explicit tool registration with Zod schemas and descriptions visible in src/index.ts. All 4 tools are registered with names, descriptions, and input parameter schemas. However, there are significant gaps in output schema documentation, error handling recovery guidance, and parameter constraint enforcement. Naming is reasonable (verb_noun pattern used consistently). Descriptions are present but brief (69-167 chars), below the optimal 50-200 char baseline for LLM optimization. Parameters have type declarations and basic descriptions, but lack detailed constraints (ranges, format specifications) and dependency documentation. Error handling returns generic error messages without recovery guidance or actionable next steps. The server lacks tool annotations (readOnlyHint, destructiveHint, idempotentHint) for the three write tools.
Watermark multiple images at once. Upload image URLs, apply text watermark, get a ZIP. Supports up to 20 images.
Check your Markly API usage and quota. Shows plan, daily requests, limits, and total images processed.
Add a logo/image watermark to an image. Provide image and logo URLs. Returns a download URL (valid 30 min).
Add a text watermark to an image. Provide an image URL and watermark text. Returns a download URL (valid 30 min).
Output schemas not documented. No structured definition of what fields are returned (e.g., for markly_watermark_text, is it {download_url: string, expires_at: string} or plain text?). LLMs cannot plan downstream operations or extract data without knowing response structure.
Error handling returns generic error messages ('Error: <message>') without recovery guidance. Examples: 'API error 401' does not tell the LLM to check MARKLY_API_KEY; 'Invalid image URL' does not suggest calling with a different URL. Per pattern:recovery-guide, errors must include actionable next steps.
Parameter constraints not fully specified. Example: 'size' in markly_watermark_text is described as '12-200, default 48' but no min/max validation constraints are declared in schema. 'color' requires hex format '#ffffff' but no pattern constraint enforces it. 'text' has max 200 chars but no maxLength in schema. LLMs cannot reliably infer bounds from descriptions alone.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 55 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 15 | - | v1 |
No tool annotations. The three write tools (markly_watermark_text, markly_watermark_logo, markly_batch_watermark) lack destructiveHint or idempotentHint annotations. markly_check_usage lacks readOnlyHint. These annotations are part of the current 2026-07-28 spec and enable agents to reason about side effects.
No confirmation or dry-run support for destructive/irreversible operations. The three watermarking tools generate download URLs valid for 30 minutes. There is no dry-run mode, no preview option, and no confirmation step. Per pattern:confirmation-request, agents should have a chance to verify before committing irreversible actions.
API key exposure risk mitigated by environment variable, but no documentation of required env var setup. The MarklyClient constructor reads MARKLY_API_KEY from process.env, but the README or inline comments should explicitly state: 'Set MARKLY_API_KEY=<your-key> before starting.' Agents or users launching this server without the env var will fail silently.
Parameter descriptions lack dependency hints. Example: image_urls in markly_batch_watermark says 'max 20' but does not document: what happens if you pass 21? What does the error message say? Are any images watermarked before the API rejects the batch? No guidance on partial failure handling or retry strategy.
Tool descriptions do not state when to use each tool vs. alternatives. Example: markly_watermark_text and markly_watermark_logo both add watermarks, but the descriptions do not explain when to choose one over the other ('Use text watermark for copyright notices, logo watermark for branding'). This forces LLM reasoning overhead.