MCP reference

The Model Context Protocol (MCP) is an open standard that lets AI assistants and coding agents call tools provided by external servers. PageSugar runs a public MCP server so an agent can search the catalogue, inspect a component and retrieve its exact source for Svelte 5 and Tailwind CSS 4. Your coding agent integrates that source into your project.

Endpoint#

https://pagesugar.com/mcp

• Transport: Streamable HTTP. Requests are sent with POST to the single endpoint above.
• Access: anonymous. The catalogue tools are read-only; one tool sends feedback about a component to PageSugar.
• The same URL serves two audiences. An MCP client sends POST requests and gets the protocol. A browser asking for HTML gets the MCP page with setup steps.
• A GET that asks for text/event-stream or JSON returns 405. The server is stateless and offers no server-sent stream, as the transport allows.

Client compatibility#

The MCP page gives setup steps for each client. Those steps follow each client's own documentation and carry the date they were last checked against it.

In general, clients that support remote MCP servers over Streamable HTTP ask for a server URL. Use the endpoint above. Clients that only support local (stdio) servers can connect through a bridge such as mcp-remote. Clients that only support the older SSE transport cannot connect.

What the server can do#

• List categories and browse published components with deterministic filters.
• Search for components that match a natural-language description.
• Return a component's versions, variants, props, usage, dependencies, services, license and integration limits.
• Return the complete file manifest and, when it fits the response budget, the full text of every runtime file.
• Return individual files, or explicit line ranges of large text files.
• Return the ZIP bundle location, its checksum and the distribution receipt URL.
• Pass a user's comment about a component to PageSugar, when the user asks for that or agrees to it.

What it cannot do#

• It does not modify your project, write files, run installers or execute code. Your agent applies changes locally, with your permissions.
• It does not publish, edit or delete components, and it has no authoring operations. Its only write is feedback, which changes nothing in the catalogue directly.
• It does not fetch arbitrary URLs, run shell commands or read anything outside published catalogue artifacts.
• It does not reason about your project. The agent you use does that. Submitted feedback is screened by a classifier model; see Feedback.
• It does not return draft components.

Tools#

Limits and defaults#

Version and variant rules#

• get_component may omit version to inspect the current release. Every response states the exact version it resolved.
• get_component_files, get_component_file and download_component require an exact version.
• The current build serves only each component's current release. Older releases are not yet retained, so they return VERSION_NOT_FOUND once a newer release is published.
• Artifact locations are content-addressed by artifactDigest. A receipt's publishedInRevision is currently the catalogue revision that produced the build, because release history is not yet retained.
• variantId defaults to the release's default variant. The resolved id is always returned. An unknown variant is an error, never a substitution.

What inspection and download return#

get_component includes the component's authored usage guide as usageGuide (Markdown, or null when the component has none) alongside the structured usage, props and customization data. Limitations are reported once, as the top-level limitations; the HTTP API keeps them at docs.usage.limitations. When you pass a version, its detailUrl and markdownUrl keep that version.

Pass detail: "summary" to compare candidates for a fraction of the tokens. A summary keeps identity, versions, variants, compatibility, prop names and types, limitations, the accessibility knownLimitations, dependencies, services, license and links, and leaves out usageGuide, the usage example, prop descriptions, the customization guide, the accessibility notes, per-file lists and fetchCommand. The default is detail: "full".

compatibility.requiresSvelteKit says whether the component needs SvelteKit at all, and compatibility.importNote explains the one difference between SvelteKit majors: examples import from $lib/..., which SvelteKit 3 projects do not define by default.

Copying the source without reading it#

A full get_component lists every file of every variant with its sha256 and a raw sourceUrl, and gives each variant a fetchCommand: one curl that writes all of that variant's files under suggestedDirectory and fails if any file fails, for example

curl -fsSL --fail-early --create-dirs -o src/lib/components/pricing-comparison-table-01/PricingComparisonTable.svelte https://pagesugar.com/artifacts/…/source/PricingComparisonTable.svelte

An agent with a shell runs it and then edits the files on disk, so the source enters its context only when it reads a file to change it. The source URLs are content-addressed and serve the exact bytes the sha256 names. get_component_files returns the same fetchCommand; it and get_component_file are for agents that need the text in the response.

download_component returns locations, not bodies: the bundle URL with its size and SHA-256, and a receiptUrl you fetch to read the receipt. Its markdownUrl and customizationUrl keep the exact version and variant.

Seeing a component#

list_components, search_components and get_component return a thumbnail for each component: an absolute src URL to a screenshot of its default variant (a 1200×750 JPEG), with width, height and alt. It is null when no screenshot has been captured. The screenshot shows the current release, so once older releases are retained, get_component will return thumbnail: null for them; today a superseded version returns VERSION_NOT_FOUND instead. get_component also returns links.previewUrl, the live interactive preview, when the component has one. The server returns URLs, not image data: fetch the thumbnail or open the preview to look at the component.

Completeness#

get_component_files includes file contents by default. When all runtime text fits the budget the result says contentStatus: "complete". When it does not, the result is the complete file manifest with contentStatus: "manifest-only" and a size warning, and the agent should fetch files individually or use the bundle. The server never returns a partial set of files described as complete.

get_component_file reports isPartial: false for whole files. For a line range (startLine and endLine, inclusive and one-based) it reports isPartial: true, the total line count, and a checksum that is labelled as the full file's checksum. Binary files return metadata and download locations, not text.

Search results are best matches and never exhaustive. Use list_components when you need every component that matches a filter.

Errors#

Domain errors use the same codes as the public API:

Feedback#

When a user says something about a component they got from PageSugar (praise, a bug, an accessibility problem, a change they want), their agent can pass it on with submit_component_feedback. The agent should offer to do that, and send it only when the user asks or agrees, or has already said feedback may be shared. A request to change a local copy is not, by itself, permission to send the comment to us.

• What you send: the component id and exact version, the comment, whether it is about the component as downloaded or after local changes, and optionally up to three files from the release it refers to (each a path from the release's file manifest — letters, digits, ., _, - and /, no .. segments and no leading /). Leave out private project code, credentials and personal details.
• Interaction token: get_component, get_component_files, get_component_file and download_component each return a feedback object with an interactionToken for that exact release. The feedback tool requires one. It shows the release came from PageSugar; it expires after 24 hours. An agent without one calls get_component for that version first. The token does not carry a network identifier that could link it to other tokens from the same submitter.
• Retries: send a submissionId UUID generated once per comment. Retrying with the same id returns the original receipt instead of a second submission. Sending the same comment text again under the same interaction token also returns the original receipt, even with a new submissionId; neither case spends any of the limits below.
• What comes back: a receipt id and the same acknowledgement for every stored submission. Whether a comment was judged relevant is not returned.
• Screening: comments are stored first, then screened by TypeSafe's Jev classifier for relevance and abuse. Jev sees the comment, the component's public metadata and source excerpts, whether the comment is about the component as downloaded or after local changes, how the submitter retrieved the component (inspected it, listed its files, read one file, or downloaded the bundle), how many times the submitting network retrieved it in the last hour, and, in a separate request, a few earlier accepted comments on the same component. Clear spam and unrelated text is discarded; anything Jev cannot decide waits for a person.
• What happens next: the maintainers review accepted feedback per component weekly, with the help of an AI assistant. When a component has enough to act on, it becomes an improvement task — a GitHub issue in PageSugar's (private) repository, sometimes with short quotes from the feedback — and the feedback is deleted; niche components may gather feedback for months first. A comment is not a promise of a change.
• Limits: a network can send a small number of comments per minute, per day and per component, and each token can be used a few times; there is also a daily cap on new comments across every network. Over a limit, the tool returns RATE_LIMITED with retryAfterSeconds. Duplicates (see Retries) never count against these limits.

Rate limits#

The catalogue tools are not rate limited yet. When they are, limited requests will return RATE_LIMITED with retry guidance. Agents should still retry with backoff, avoid polling, and prefer the ZIP bundle over fetching many files one by one. Feedback has its own limits, described above.

Privacy#

• Send only what the tools need: a description of the component you want and public compatibility constraints such as "Svelte 5, no extra dependencies".
• Do not send your project's source code, credentials, environment files or personal data. None of the tools need them.
• Treat search queries as data sent to a public service.
• Feedback is stored with the component, version, the comment, the files it names, whether it is about an adapted copy, and the screening results. Your network address is never stored with it or sent to TypeSafe. Your interaction token does not carry an identifier that links it to your other tokens.
• For rate limits and abuse checks, a keyed hash of your network address is kept in daily counters that live for up to about two days, and in a record of which components that network retrieved, which expires an hour after its last entry. Search queries and file contents are not part of that record. A feedback item keeps only counts from it, such as "inspected once, downloaded once".
• Sent to TypeSafe for screening: the comment, the component's public metadata and source excerpts, whether the comment is about an adapted copy, how the component was retrieved, those retrieval counts, and, in a separate request, up to five earlier accepted comments on the same component (shortened).
• Retention: a comment that is never admitted (for example, over a limit) is deleted within 15 minutes. Discarded comments are deleted after seven days, undecided ones 30 days after they were sent, and accepted ones a year after acceptance, or as soon as the maintainers act on them. Acting on feedback means a maintainer reviewing it weekly, with the help of an AI assistant, and summarising what is worth acting on, sometimes with short quotes, in an improvement task in PageSugar's GitHub repository, which is private. That summary is kept as part of the project's history, without names, contact details or project code, and is not covered by the retention periods above. A submission id is remembered for seven days so retries stay safe.

JSON-RPC batch requests (a JSON array of messages) are not supported and are rejected with HTTP 400 and error code -32600; send one message per request.

Requests from web browsers are accepted only from allowed origins; requests without an Origin header, which is typical for desktop and command-line clients, are not subject to that check.

Troubleshooting#

• The client cannot connect. Check that it supports remote servers over Streamable HTTP and that the URL is exactly https://pagesugar.com/mcp. Compare your configuration with the setup steps for your client; the key that holds the URL differs between clients.
• Opening the endpoint in a browser shows a web page. That is expected. Browsers get the MCP page; clients that POST get the protocol.
• A browser-based client is rejected. Its origin is not on the server's allowlist.
• Results look out of date. Results state the exact versions they resolved, and pagination cursors are bound to one catalogue revision. Restart browsing if you see REVISION_EXPIRED.
• Files are missing from a result. Check contentStatus. manifest-only means you need get_component_file or the bundle.

Machine-readable guides#

• Setup steps for every client, as Markdown for your agent: /mcp.md
• This page as Markdown: /docs/mcp.md
• Agent navigation guide: /llms.txt
• The agent workflow describes how an agent should use these tools end to end.