# CopyCat MCP API — v1.0.0

Identity: **CopyCat MCP**, version **1.0.0**. Live endpoint:
`https://copycat.tech/mcp`; GET `/mcp/health` reports current availability.
Transport: Streamable HTTP, official SDK v2, stateless compatibility for legacy
2025 MCP clients. POST one JSON-RPC message per request. Use a maintained client
library for protocol negotiation. The server has no auth, sessions, writes, command
execution, old `/sse` endpoint, replay, sampling or pushed notifications. GET/DELETE
on the MCP endpoint return 405 for protocol clients. A browser GET explicitly
accepting HTML redirects to `/mcp-guide` so the public server URL also leads humans
to setup instructions. Public health is GET `/mcp/health`.

All tool results include `trust: "untrusted_reference_data"` and
`execution_performed: false` in structuredContent and equivalent JSON text content.
SDK argument validation can produce an MCP protocol/tool error. Known lookup errors
return `isError: true` with `error.code` and a sanitized `error.message`.

## Tools

| Tool | Required | Optional | Result |
|---|---|---|---|
| `copycat_search` | `query: string` | `platform`, `category`, `product`, `limit` | query, total_matches, ranked result summaries |
| `copycat_get_article` | `article_id: string` | — | full normalized article |
| `copycat_troubleshoot` | `issue: string` | `platform`, `product`, `error_code` | up to three grounded procedures, references, uncertainty notice |
| `copycat_get_commands` | `article_id: string` | `command_language` | exact documented commands, metadata, article warnings/link |
| `copycat_list_categories` | — | `platform` | actual platform/category counts and matching article count |
| `copycat_get_related` | `article_id: string` | `limit` | explicit relationships first, deterministic inferred matches afterward |

Queries/issues: trimmed nonempty, max 512 characters. Filters/language/error_code:
trimmed nonempty max 120. IDs: numeric string, 1–12 digits. Limit: integer 1–20;
defaults search=8, related=5. Filters are exact case-insensitive values. Products
match the primary or explicitly recorded additional products; no product aliases
are invented. Multi-platform counts can overlap. Command language matches recorded
shell/environment/language labels exactly, case-insensitively, without shell guesses.

Search weights: exact identifier 12000, error code 11000, Event ID 10000, title
8000, title phrase 3000, exact product 2500, product phrase 1000, exact category
900, token coverage up to 100. Weights add; ties sort by stable numeric ID.
Relevance carries the numeric score and match reasons, not a probability. A
troubleshoot error_code is searched first; only an empty match falls back to issue.

Full articles also expose derived `manufacturers` and explicit `mcp_topics` used
by website navigation; these do not change the six tools' input schemas.

Search summaries contain article_id, title, excerpt, platforms, product, category,
canonical_url, and relevance. Article records contain documented metadata and
original content; missing metadata is null/empty. Commands include exact command,
environment/language, documented purpose/prerequisites/warnings, risk, safety_level,
admin_required/restart_required when recorded, article ID and canonical URL.

## Resources

| URI | Content |
|---|---|
| `copycat://server` | identity, transport, public read-only policy, guide and instructions |
| `copycat://index` | revision hash, article count, schema and canonical URL metadata |
| `copycat://usage` | human-readable usage instructions |
| `copycat://article/{id}` | untrusted full normalized article with stable identifier |

The article template is discovered through resource template listing, not by
listing thousands of complete article bodies. Article resources do not execute
tools. Unknown resources/IDs fail rather than fetching URLs supplied by callers.

## Errors and HTTP behavior

`ARTICLE_NOT_FOUND`, `DATA_UNAVAILABLE`, and `RESPONSE_TOO_LARGE` are structured tool
errors. Empty search results are successful with total_matches=0. HTTP middleware
errors contain `{ "error": { "code": "..." } }`: HTTPS_REQUIRED (400),
INVALID_JSON/INVALID_REQUEST (400), HOST_NOT_ALLOWED/ORIGIN_NOT_ALLOWED (403),
NOT_FOUND (404), unsupported methods (405), JSON_REQUIRED (415),
REQUEST_TOO_LARGE/RESPONSE_TOO_LARGE (413), RATE_LIMITED (429 + Retry-After),
SERVICE_UNAVAILABLE/RATE_LIMIT_UNAVAILABLE/DATA_UNAVAILABLE (503), REQUEST_TIMEOUT
(504). Clients should handle protocol errors separately from HTTP middleware errors.

Maximum body: 16 KiB; tool data: 96 KiB; complete response: 256 KiB; request deadline:
10 seconds. No partial command truncation. CORS permits only explicit allowed
Origins. CLI clients need not send an Origin.