@heyclaude/mcp 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @heyclaude/mcp Changelog
 
+## 0.2.0 - Discovery and Submission Drafting
+
+- Add read-only discovery tools for server metadata, paginated category
+  browsing, recent updates, and related entries.
+- Add copyable asset, entry comparison, registry stats, and client setup tools
+  for richer MCP client workflows.
+- Add read-only MCP resources and workflow prompts for discovery, submission
+  drafting, pre-issue review, and safe install guidance.
+- Add submission helper tools for examples, canonical issue drafts, duplicate
+  review, and maintainer checklist guidance.
+- Document the public no-key access model and the dedicated MCP rate-limit
+  policy.
+
 ## 0.1.2 - Repository Rename
 
 - Update package metadata, README links, and release provenance for the

package/README.md

@@ -11,7 +11,7 @@
   <a href="https://github.com/JSONbored/awesome-claude">GitHub</a> •
   <a href="https://www.npmjs.com/package/@heyclaude/mcp">npm</a> •
   <a href="https://heyclau.de/api/mcp">MCP endpoint</a> •
-  <a href="https://github.com/JSONbored/awesome-claude/releases/tag/mcp-v0.1.2">v0.1.2 release</a>
+  <a href="https://github.com/JSONbored/awesome-claude/releases/tag/mcp-v0.2.0">v0.2.0 release</a>
 </p>
 
 Read-only Model Context Protocol server for the HeyClaude registry.
@@ -22,11 +22,32 @@ adapters, feed discovery, and safe submission-draft helpers. It does not create
 GitHub issues, open pull requests, write local files, publish content, or manage
 accounts.
 
+No API key is required for the public endpoint. Abuse controls are handled with
+strict request validation, a 64 KiB body limit, and a dedicated Cloudflare
+`API_MCP_RATE_LIMIT` binding capped at 60 requests/minute/IP in production.
+
 ## Tools
 
 - `search_registry` - search public registry entries by query, category, and
   platform.
+- `server_info` - fetch package version, registry generation, tool list, public
+  access policy, and rate-limit metadata.
+- `list_category_entries` - browse entries with bounded pagination and optional
+  category, platform, tag, and query filters.
+- `get_recent_updates` - list recently added or upstream-updated entries from
+  generated registry metadata, optionally filtered with `since`.
+- `get_related_entries` - find related entries based on category, tags,
+  platforms, keywords, and source metadata.
 - `get_entry_detail` - fetch an entry detail payload by category and slug.
+- `get_copyable_asset` - fetch the category-aware copy/install asset for an
+  entry, such as full prompt text, config snippets, commands, scripts, or
+  collection items.
+- `compare_entries` - compare 2-5 entries by fit, category, platform support,
+  install complexity, and source metadata.
+- `get_registry_stats` - fetch aggregate counts, freshness metadata, and real
+  source-signal coverage without implying popularity when stats are absent.
+- `get_client_setup` - fetch tested setup snippets for Codex, Claude Desktop,
+  Cursor, Windsurf, and raw Streamable HTTP clients.
 - `get_compatibility` - fetch skill platform compatibility metadata.
 - `get_install_guidance` - fetch install commands, config, package, and platform
   guidance.
@@ -43,6 +64,27 @@ accounts.
   URLs for human review.
 - `get_category_submission_guidance` - fetch category-specific contribution
   guidance and required fields.
+- `prepare_submission_draft` - normalize and validate fields, then return a
+  canonical issue title/body plus prefilled URLs.
+- `get_submission_examples` - fetch category-specific example fields and
+  templates for more complete submissions.
+- `review_submission_draft` - review schema errors, duplicate risk, and
+  maintainer checklist items before a submission issue is opened.
+
+## Resources and Prompts
+
+The server also exposes read-only MCP resources:
+
+- `heyclaude://feeds/directory`
+- `heyclaude://category/{category}`
+- `heyclaude://entry/{category}/{slug}`
+
+Workflow prompts are available for common client flows:
+
+- `find_best_asset`
+- `prepare_submission`
+- `review_submission_before_issue`
+- `install_asset_safely`
 
 ## Local Stdio
 
@@ -123,8 +165,11 @@ checks the HTTP guards used by the remote route.
 - Submission helpers generate URLs and validation reports only.
 - No GitHub OAuth, tokens, issue creation, PR creation, or repo writes.
 - No local project-file writes or config mutations.
-- Remote endpoint uses route-level rate limits and Cloudflare rate-limit bindings
-  when available.
+- Remote endpoint requires JSON POST bodies, rejects payloads above 64 KiB, and
+  uses the dedicated `API_MCP_RATE_LIMIT` Cloudflare binding at
+  60 requests/minute/IP in production.
+- Submission tools prepare review drafts only; HeyClaude does not auto-publish
+  MCP-submitted content.
 
 ## npm Release Prep
 
@@ -139,7 +184,7 @@ Do not publish until the web branch has shipped, the production endpoint has
 been verified, and the package smoke test passes. The release checklist is:
 
 ```bash
-pnpm validate:mcp-endpoint -- --url https://heyclau.de/api/mcp
+pnpm validate:mcp-endpoint -- --url https://heyclau.de/api/mcp --strict-tools
 pnpm --filter @heyclaude/mcp test
 pnpm --filter @heyclaude/mcp pack --dry-run
 MCP_PACKAGE_REMOTE_SMOKE_URL=https://heyclau.de/api/mcp pnpm validate:mcp-package

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyclaude/mcp",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "description": "Read-only MCP server for the HeyClaude registry.",
   "license": "MIT",

package/scripts/validate-endpoint.mjs

@@ -6,12 +6,30 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { normalizeEndpointUrl } from "../src/endpoint-url.js";
 import { READ_ONLY_TOOL_NAMES } from "../src/registry.js";
 
+const baselineToolNames = [
+  "search_registry",
+  "get_entry_detail",
+  "get_compatibility",
+  "get_install_guidance",
+  "get_platform_adapter",
+  "list_distribution_feeds",
+  "get_submission_schema",
+  "validate_submission_draft",
+  "search_duplicate_entries",
+  "build_submission_urls",
+  "get_category_submission_guidance",
+];
+
 function parseArgs(argv) {
   const args = new Map();
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index];
     if (value === "--") continue;
     if (!value.startsWith("--")) continue;
+    if (value === "--strict-tools") {
+      args.set("strict-tools", "1");
+      continue;
+    }
     args.set(value.slice(2), argv[index + 1] ?? "");
     index += 1;
   }
@@ -75,7 +93,24 @@ async function validateHttpGuards(endpointUrl) {
   );
 }
 
-async function validateMcpTools(endpointUrl) {
+function validateToolList(toolNames, strictTools) {
+  if (strictTools) {
+    assert(
+      JSON.stringify(toolNames) === JSON.stringify(READ_ONLY_TOOL_NAMES),
+      `Unexpected tool list: ${toolNames.join(", ")}`,
+    );
+    return;
+  }
+
+  for (const toolName of baselineToolNames) {
+    assert(
+      toolNames.includes(toolName),
+      `Deployed MCP endpoint is missing baseline tool: ${toolName}`,
+    );
+  }
+}
+
+async function validateMcpTools(endpointUrl, options = {}) {
   const client = new Client({
     name: "heyclaude-endpoint-validator",
     version: "0.1.0",
@@ -87,10 +122,49 @@ async function validateMcpTools(endpointUrl) {
 
     const tools = await client.listTools();
     const toolNames = tools.tools.map((tool) => tool.name);
-    assert(
-      JSON.stringify(toolNames) === JSON.stringify(READ_ONLY_TOOL_NAMES),
-      `Unexpected tool list: ${toolNames.join(", ")}`,
-    );
+    validateToolList(toolNames, options.strictTools);
+    const hasVersionTwoSurface = toolNames.includes("get_registry_stats");
+    if (hasVersionTwoSurface) {
+      assert(
+        tools.tools.every((tool) => tool.annotations?.readOnlyHint === true),
+        "All HeyClaude MCP tools must advertise read-only annotations.",
+      );
+      assert(
+        tools.tools.every((tool) => tool.outputSchema?.type === "object"),
+        "All HeyClaude MCP tools must expose object output schemas.",
+      );
+
+      const resources = await client.listResources();
+      assert(
+        resources.resources.some(
+          (resource) => resource.uri === "heyclaude://feeds/directory",
+        ),
+        "MCP resources did not expose the directory feed resource.",
+      );
+      const directoryResource = await client.readResource({
+        uri: "heyclaude://feeds/directory",
+      });
+      assert(
+        directoryResource.contents?.[0]?.mimeType === "application/json",
+        "Directory resource did not return JSON content.",
+      );
+
+      const prompts = await client.listPrompts();
+      assert(
+        prompts.prompts.some((prompt) => prompt.name === "find_best_asset"),
+        "MCP prompts did not expose find_best_asset.",
+      );
+      const installPrompt = await client.getPrompt({
+        name: "install_asset_safely",
+        arguments: { category: "mcp", slug: "example", platform: "Codex" },
+      });
+      assert(
+        installPrompt.messages?.[0]?.content?.text?.includes(
+          "get_install_guidance",
+        ),
+        "install_asset_safely prompt did not mention install guidance.",
+      );
+    }
 
     const search = parseToolResult(
       await client.callTool({
@@ -104,6 +178,52 @@ async function validateMcpTools(endpointUrl) {
       "search_registry did not return entries.",
     );
 
+    if (toolNames.includes("server_info")) {
+      const info = parseToolResult(
+        await client.callTool({
+          name: "server_info",
+          arguments: {},
+        }),
+      );
+      assert(info.ok === true, "server_info did not return ok.");
+      assert(
+        info.endpoint?.auth === "none",
+        "server_info did not expose the public no-key access model.",
+      );
+      assert(
+        info.endpoint?.rateLimit?.binding === "API_MCP_RATE_LIMIT",
+        "server_info did not expose the MCP rate-limit binding.",
+      );
+    }
+
+    if (toolNames.includes("list_category_entries")) {
+      const listed = parseToolResult(
+        await client.callTool({
+          name: "list_category_entries",
+          arguments: { category: "mcp", limit: 2 },
+        }),
+      );
+      assert(listed.ok === true, "list_category_entries did not return ok.");
+      assert(
+        Array.isArray(listed.entries) && listed.entries.length > 0,
+        "list_category_entries did not return entries.",
+      );
+    }
+
+    if (toolNames.includes("get_registry_stats")) {
+      const stats = parseToolResult(
+        await client.callTool({
+          name: "get_registry_stats",
+          arguments: {},
+        }),
+      );
+      assert(stats.ok === true, "get_registry_stats did not return ok.");
+      assert(
+        stats.policy?.readOnly === true,
+        "get_registry_stats did not expose the no-write policy.",
+      );
+    }
+
     const first = search.entries[0];
     const detail = parseToolResult(
       await client.callTool({
@@ -117,6 +237,20 @@ async function validateMcpTools(endpointUrl) {
       "get_entry_detail returned the wrong entry.",
     );
 
+    if (toolNames.includes("get_copyable_asset")) {
+      const asset = parseToolResult(
+        await client.callTool({
+          name: "get_copyable_asset",
+          arguments: { category: first.category, slug: first.slug },
+        }),
+      );
+      assert(asset.ok === true, "get_copyable_asset did not return ok.");
+      assert(
+        asset.primaryAsset || asset.assets?.length,
+        "get_copyable_asset did not return any copyable asset.",
+      );
+    }
+
     const feeds = parseToolResult(
       await client.callTool({
         name: "list_distribution_feeds",
@@ -163,6 +297,35 @@ async function validateMcpTools(endpointUrl) {
       "build_submission_urls did not return an MCP issue URL.",
     );
 
+    if (toolNames.includes("prepare_submission_draft")) {
+      const prepared = parseToolResult(
+        await client.callTool({
+          name: "prepare_submission_draft",
+          arguments: {
+            fields: {
+              category: "mcp",
+              name: "Endpoint Validation MCP",
+              docs_url: "https://example.com/docs",
+              description:
+                "Endpoint validation draft for the HeyClaude MCP submission helpers.",
+              install_command: "npx -y endpoint-validation-mcp",
+              usage_snippet: "Use this draft to validate MCP route behavior.",
+            },
+          },
+        }),
+      );
+      assert(
+        prepared.issueDraft?.body,
+        "prepare_submission_draft did not return a canonical issue body.",
+      );
+      assert(
+        String(prepared.submissionPolicy || "").includes(
+          "does not auto-publish",
+        ),
+        "prepare_submission_draft did not expose the maintainer-reviewed policy.",
+      );
+    }
+
     const invalid = parseToolResult(
       await client.callTool({
         name: "search_registry",
@@ -182,6 +345,9 @@ async function validateMcpTools(endpointUrl) {
 const args = parseArgs(process.argv.slice(2));
 const endpointUrlRaw = args.get("url") || process.env.MCP_ENDPOINT_URL;
 const endpointUrl = endpointUrlRaw ? normalizeEndpointUrl(endpointUrlRaw) : "";
+const strictTools =
+  args.get("strict-tools") === "1" ||
+  process.env.MCP_ENDPOINT_STRICT_TOOLS === "1";
 
 if (!endpointUrl) {
   console.error(
@@ -192,7 +358,7 @@ if (!endpointUrl) {
 
 try {
   await validateHttpGuards(endpointUrl);
-  await validateMcpTools(endpointUrl);
+  await validateMcpTools(endpointUrl, { strictTools });
   console.log(`Validated HeyClaude MCP endpoint at ${endpointUrl.toString()}`);
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error));

package/src/registry.d.ts

@@ -14,18 +14,82 @@ export const TOOL_DEFINITIONS: Array<{
   name: string;
   description: string;
   inputSchema: Record<string, unknown>;
+  outputSchema: Record<string, unknown>;
+  annotations: Record<string, unknown>;
 }>;
 
+export const MCP_PUBLIC_POLICY: Record<string, unknown>;
+export const RESOURCE_TEMPLATES: Array<Record<string, unknown>>;
+export const PROMPT_DEFINITIONS: Array<Record<string, unknown>>;
+
 export function searchRegistry(
   args?: Record<string, unknown>,
   options?: RegistryArtifactLoaders,
 ): Promise<RegistryToolResult>;
 
+export function getServerInfo(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
+export function listCategoryEntries(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
+export function getRecentUpdates(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
+export function getRelatedEntries(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
 export function getEntryDetail(
   args?: Record<string, unknown>,
   options?: RegistryArtifactLoaders,
 ): Promise<RegistryToolResult>;
 
+export function getCopyableAsset(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
+export function compareEntries(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
+export function getRegistryStats(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
+export function getClientSetup(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
+export function listRegistryResources(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<Record<string, unknown>>;
+
+export function listRegistryResourceTemplates(): Record<string, unknown>;
+
+export function readRegistryResource(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<Record<string, unknown>>;
+
+export function listRegistryPrompts(): Record<string, unknown>;
+
+export function getRegistryPrompt(
+  args?: Record<string, unknown>,
+): Record<string, unknown>;
+
 export function getCompatibility(
   args?: Record<string, unknown>,
   options?: RegistryArtifactLoaders,
@@ -71,6 +135,21 @@ export function getCategorySubmissionGuidance(
   options?: RegistryArtifactLoaders,
 ): Promise<RegistryToolResult>;
 
+export function prepareSubmissionDraft(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
+export function getSubmissionExamples(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
+export function reviewSubmissionDraft(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
 export function callRegistryTool(
   name: string,
   args?: Record<string, unknown>,
@@ -79,7 +158,15 @@ export function callRegistryTool(
 
 export {
   SearchRegistryInputSchema,
+  ServerInfoInputSchema,
+  ListCategoryEntriesInputSchema,
+  RecentUpdatesInputSchema,
+  RelatedEntriesInputSchema,
   EntryDetailInputSchema,
+  CopyableAssetInputSchema,
+  CompareEntriesInputSchema,
+  RegistryStatsInputSchema,
+  ClientSetupInputSchema,
   CompatibilityInputSchema,
   InstallGuidanceInputSchema,
   PlatformAdapterInputSchema,
@@ -90,8 +177,12 @@ export {
   SearchDuplicateEntriesInputSchema,
   BuildSubmissionUrlsInputSchema,
   CategorySubmissionGuidanceInputSchema,
+  PrepareSubmissionDraftInputSchema,
+  GetSubmissionExamplesInputSchema,
+  ReviewSubmissionDraftInputSchema,
   TOOL_INPUT_SCHEMAS,
   jsonSchemaForTool,
+  jsonSchemaForToolOutput,
   parseToolArguments,
   formatZodError,
 } from "./schemas.js";