@heyclaude/mcp 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @heyclaude/mcp Changelog
 
+## 0.3.0 - Safety Metadata and Submission Policy
+
+- Expose registry `safetyNotes` and `privacyNotes` in MCP search, detail,
+  copyable asset, comparison, and install guidance responses.
+- Accept `safety_notes` and `privacy_notes` in submission draft helpers with
+  the same short-note limits used by HeyClaude intake.
+- Support source-backed and copyable-content skill submissions without requiring
+  community ZIP/MCPB package hosting.
+- Reflect the review-gated import policy: submission helpers can prepare issues
+  and local checks, but never create issues, open PRs, merge, publish, or mirror
+  package artifacts.
+
 ## 0.2.0 - Discovery and Submission Drafting
 
 - Add read-only discovery tools for server metadata, paginated category

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.2.0">v0.2.0 release</a>
+  <a href="https://github.com/JSONbored/awesome-claude/releases/tag/mcp-v0.3.0">v0.3.0 release</a>
 </p>
 
 Read-only Model Context Protocol server for the HeyClaude registry.
@@ -19,8 +19,8 @@ Read-only Model Context Protocol server for the HeyClaude registry.
 It exposes the same public registry surface used by the website and Raycast:
 search, entry details, platform compatibility, install guidance, generated
 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.
+GitHub issues, open pull requests, write local files, publish content, host
+packages, 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
@@ -55,21 +55,30 @@ strict request validation, a 64 KiB body limit, and a dedicated Cloudflare
   rule adapters for skill packages.
 - `list_distribution_feeds` - discover public JSON, RSS, Atom, and platform
   feeds.
-- `get_submission_schema` - fetch category submission fields and issue template
-  metadata.
+- `get_submission_schema` - fetch category submission fields for PR-first
+  intake.
 - `validate_submission_draft` - validate a content submission draft locally.
 - `search_duplicate_entries` - check generated registry artifacts for likely
   duplicates before opening a submission.
-- `build_submission_urls` - build prefilled HeyClaude submit and GitHub issue
-  URLs for human review.
+- `build_submission_urls` - build prefilled HeyClaude submit and review 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.
+  canonical PR draft plus prefilled submit URL.
 - `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.
+  maintainer checklist items before a submission PR is opened.
+- `get_submission_policy` - fetch the read-only submission, artifact, import,
+  and maintainer-review policy.
+- `explain_entry_trust` - explain source, package, safety, privacy, and review
+  metadata signals for one entry. This is a metadata review only and does not
+  provide malware scanning, automatic safety guarantees, or installation approval.
+- `review_entry_safety` - compare 1-5 entries for source, package, safety, and
+  privacy metadata fit before install or recommendation. This is a metadata review
+  only and does not provide malware scanning, automatic safety guarantees, or
+  installation approval.
 
 ## Resources and Prompts
 
@@ -83,7 +92,7 @@ Workflow prompts are available for common client flows:
 
 - `find_best_asset`
 - `prepare_submission`
-- `review_submission_before_issue`
+- `review_submission_before_pr`
 - `install_asset_safely`
 
 ## Local Stdio
@@ -168,8 +177,14 @@ checks the HTTP guards used by the remote route.
 - 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.
+- Submission tools prepare review drafts only; the MCP server does not perform
+  GitHub writes or publish submitted content.
+- Source-backed, content-only PRs may be merged automatically after content
+  validation, Superagent, and private maintainer-agent review pass. Platform,
+  workflow, package, and generated-artifact changes are never auto-merged by
+  this path.
+- Community ZIP/MCPB artifacts are review/quarantine material only. Public
+  HeyClaude-hosted downloads are maintainer-built package artifacts.
 
 ## npm Release Prep
 
@@ -184,10 +199,10 @@ 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 --strict-tools
+MCP_ENDPOINT_REQUIRE_SAFETY_METADATA=1 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
+MCP_PACKAGE_REQUIRE_SAFETY_METADATA=1 MCP_PACKAGE_REMOTE_SMOKE_URL=https://heyclau.de/api/mcp pnpm validate:mcp-package
 ```
 
 Publishing should happen through the manual `Publish MCP Package` GitHub

package/package.json

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

package/scripts/validate-endpoint.mjs

@@ -30,6 +30,10 @@ function parseArgs(argv) {
       args.set("strict-tools", "1");
       continue;
     }
+    if (value === "--require-safety-metadata") {
+      args.set("require-safety-metadata", "1");
+      continue;
+    }
     args.set(value.slice(2), argv[index + 1] ?? "");
     index += 1;
   }
@@ -46,6 +50,40 @@ function assert(condition, message) {
   if (!condition) throw new Error(message);
 }
 
+function assertSubmitUrl(value) {
+  let url;
+  try {
+    url = new URL(String(value || ""));
+  } catch {
+    throw new Error(
+      "build_submission_urls did not return an absolute submit URL.",
+    );
+  }
+  assert(
+    url.protocol === "https:",
+    "build_submission_urls submit URL must use HTTPS.",
+  );
+  assert(
+    url.origin === "https://heyclau.de",
+    "build_submission_urls submit URL used the wrong origin.",
+  );
+  assert(
+    url.pathname === "/submit",
+    "build_submission_urls did not return the submit URL.",
+  );
+}
+
+function assertSafetyMetadataShape(payload, label) {
+  assert(
+    Array.isArray(payload?.safetyNotes),
+    `${label} did not expose safetyNotes as an array.`,
+  );
+  assert(
+    Array.isArray(payload?.privacyNotes),
+    `${label} did not expose privacyNotes as an array.`,
+  );
+}
+
 async function validateHttpGuards(endpointUrl) {
   const options = await fetch(endpointUrl, { method: "OPTIONS" });
   assert(options.status === 204, `OPTIONS returned ${options.status}`);
@@ -177,6 +215,12 @@ async function validateMcpTools(endpointUrl, options = {}) {
       Array.isArray(search.entries) && search.entries.length > 0,
       "search_registry did not return entries.",
     );
+    if (options.requireSafetyMetadata) {
+      assertSafetyMetadataShape(
+        search.entries[0],
+        "search_registry first entry",
+      );
+    }
 
     if (toolNames.includes("server_info")) {
       const info = parseToolResult(
@@ -236,6 +280,9 @@ async function validateMcpTools(endpointUrl, options = {}) {
       detail.key === `${first.category}:${first.slug}`,
       "get_entry_detail returned the wrong entry.",
     );
+    if (options.requireSafetyMetadata) {
+      assertSafetyMetadataShape(detail.entry, "get_entry_detail entry");
+    }
 
     if (toolNames.includes("get_copyable_asset")) {
       const asset = parseToolResult(
@@ -271,9 +318,20 @@ async function validateMcpTools(endpointUrl, options = {}) {
     );
     assert(schema.ok === true, "get_submission_schema did not return ok.");
     assert(
-      schema.issueTemplate?.template === "submit-mcp.yml",
-      "get_submission_schema did not return the MCP issue template.",
+      schema.prIntake?.mode === "github_app_user_fork_pr",
+      "get_submission_schema did not return PR-first intake metadata.",
     );
+    if (options.requireSafetyMetadata) {
+      const fieldIds = schema.schema?.fields?.map((field) => field.id) || [];
+      assert(
+        fieldIds.includes("safety_notes"),
+        "get_submission_schema did not expose safety_notes.",
+      );
+      assert(
+        fieldIds.includes("privacy_notes"),
+        "get_submission_schema did not expose privacy_notes.",
+      );
+    }
 
     const urls = parseToolResult(
       await client.callTool({
@@ -292,10 +350,7 @@ async function validateMcpTools(endpointUrl, options = {}) {
       }),
     );
     assert(urls.ok === true, "build_submission_urls did not return ok.");
-    assert(
-      String(urls.githubIssueUrl || "").includes("template=submit-mcp.yml"),
-      "build_submission_urls did not return an MCP issue URL.",
-    );
+    assertSubmitUrl(urls.submitUrl);
 
     if (toolNames.includes("prepare_submission_draft")) {
       const prepared = parseToolResult(
@@ -315,12 +370,12 @@ async function validateMcpTools(endpointUrl, options = {}) {
         }),
       );
       assert(
-        prepared.issueDraft?.body,
-        "prepare_submission_draft did not return a canonical issue body.",
+        prepared.prDraft?.body,
+        "prepare_submission_draft did not return a canonical PR draft body.",
       );
       assert(
         String(prepared.submissionPolicy || "").includes(
-          "does not auto-publish",
+          "may be merged automatically",
         ),
         "prepare_submission_draft did not expose the maintainer-reviewed policy.",
       );
@@ -348,6 +403,9 @@ const endpointUrl = endpointUrlRaw ? normalizeEndpointUrl(endpointUrlRaw) : "";
 const strictTools =
   args.get("strict-tools") === "1" ||
   process.env.MCP_ENDPOINT_STRICT_TOOLS === "1";
+const requireSafetyMetadata =
+  args.get("require-safety-metadata") === "1" ||
+  process.env.MCP_ENDPOINT_REQUIRE_SAFETY_METADATA === "1";
 
 if (!endpointUrl) {
   console.error(
@@ -358,7 +416,7 @@ if (!endpointUrl) {
 
 try {
   await validateHttpGuards(endpointUrl);
-  await validateMcpTools(endpointUrl, { strictTools });
+  await validateMcpTools(endpointUrl, { strictTools, requireSafetyMetadata });
   console.log(`Validated HeyClaude MCP endpoint at ${endpointUrl.toString()}`);
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error));

package/src/package-metadata.js

@@ -1,7 +1,4 @@
-import { createRequire } from "node:module";
-
-const require = createRequire(import.meta.url);
-const packageJson = require("../package.json");
-
-export const packageName = String(packageJson.name || "@heyclaude/mcp");
-export const packageVersion = String(packageJson.version || "0.0.0");
+// Keep this Worker-safe: Cloudflare's bundle loader rejects runtime
+// package.json specifiers inside the SSR/MCP route bundle.
+export const packageName = "@heyclaude/mcp";
+export const packageVersion = "0.3.0";

package/src/registry.d.ts

@@ -27,6 +27,11 @@ export function searchRegistry(
   options?: RegistryArtifactLoaders,
 ): Promise<RegistryToolResult>;
 
+export function planWorkflowToolbox(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
 export function getServerInfo(
   args?: Record<string, unknown>,
   options?: RegistryArtifactLoaders,
@@ -81,7 +86,10 @@ export function listRegistryResourceTemplates(): Record<string, unknown>;
 
 export function readRegistryResource(
   args?: Record<string, unknown>,
-  options?: RegistryArtifactLoaders,
+  options?: RegistryArtifactLoaders & {
+    publicApiBaseUrl?: string;
+    fetchPublicApi?: (apiPath: string) => Promise<unknown>;
+  },
 ): Promise<Record<string, unknown>>;
 
 export function listRegistryPrompts(): Record<string, unknown>;
@@ -150,6 +158,42 @@ export function reviewSubmissionDraft(
   options?: RegistryArtifactLoaders,
 ): Promise<RegistryToolResult>;
 
+export function getSubmissionPolicy(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
+export function explainEntryTrust(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
+export function reviewEntrySafety(
+  args?: Record<string, unknown>,
+  options?: RegistryArtifactLoaders,
+): Promise<RegistryToolResult>;
+
+export function listRegistryRecent(
+  options?: RegistryArtifactLoaders & {
+    publicApiBaseUrl?: string;
+    fetchPublicApi?: (apiPath: string) => Promise<unknown>;
+  },
+): Promise<RegistryToolResult>;
+
+export function listRegistryTrending(
+  options?: RegistryArtifactLoaders & {
+    publicApiBaseUrl?: string;
+    fetchPublicApi?: (apiPath: string) => Promise<unknown>;
+  },
+): Promise<RegistryToolResult>;
+
+export function listJobsActive(
+  options?: RegistryArtifactLoaders & {
+    publicApiBaseUrl?: string;
+    fetchPublicApi?: (apiPath: string) => Promise<unknown>;
+  },
+): Promise<RegistryToolResult>;
+
 export function callRegistryTool(
   name: string,
   args?: Record<string, unknown>,
@@ -158,6 +202,7 @@ export function callRegistryTool(
 
 export {
   SearchRegistryInputSchema,
+  PlanWorkflowToolboxInputSchema,
   ServerInfoInputSchema,
   ListCategoryEntriesInputSchema,
   RecentUpdatesInputSchema,
@@ -180,6 +225,9 @@ export {
   PrepareSubmissionDraftInputSchema,
   GetSubmissionExamplesInputSchema,
   ReviewSubmissionDraftInputSchema,
+  SubmissionPolicyInputSchema,
+  ExplainEntryTrustInputSchema,
+  ReviewEntrySafetyInputSchema,
   TOOL_INPUT_SCHEMAS,
   jsonSchemaForTool,
   jsonSchemaForToolOutput,