@heyclaude/mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @heyclaude/mcp Changelog
+
+## 0.1.0 - Initial Public Package
+
+- Add remote-first stdio bridge for the public HeyClaude MCP endpoint.
+- Keep explicit local artifact mode for development and release validation.
+- Expose read-only registry search, detail, compatibility, install guidance,
+  feed discovery, and submission-draft helper tools.
+- Add package smoke validation for packed npm installs.

package/README.md

@@ -0,0 +1,132 @@
+# HeyClaude MCP Server
+
+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.
+
+## Tools
+
+- `search_registry` - search public registry entries by query, category, and
+  platform.
+- `get_entry_detail` - fetch an entry detail payload by category and slug.
+- `get_compatibility` - fetch skill platform compatibility metadata.
+- `get_install_guidance` - fetch install commands, config, package, and platform
+  guidance.
+- `get_platform_adapter` - fetch generated adapter content, currently Cursor
+  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.
+- `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.
+- `get_category_submission_guidance` - fetch category-specific contribution
+  guidance and required fields.
+
+## Local Stdio
+
+The published package defaults to the live HeyClaude MCP endpoint:
+
+```json
+{
+  "mcpServers": {
+    "heyclaude": {
+      "command": "npx",
+      "args": ["-y", "@heyclaude/mcp"]
+    }
+  }
+}
+```
+
+Use a custom endpoint when testing a preview/dev deployment:
+
+```json
+{
+  "mcpServers": {
+    "heyclaude": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@heyclaude/mcp",
+        "--url",
+        "https://heyclaude-dev.zeronode.workers.dev/api/mcp"
+      ]
+    }
+  }
+}
+```
+
+Local artifact mode is explicit and intended for development:
+
+```bash
+pnpm --filter @heyclaude/mcp start:local
+```
+
+Set `HEYCLAUDE_DATA_DIR=/absolute/path/to/data`, or pass
+`--local --data-dir /absolute/path/to/data`, to point at a generated data
+directory.
+
+Example local MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "heyclaude": {
+      "command": "pnpm",
+      "args": ["--filter", "@heyclaude/mcp", "start:local"]
+    }
+  }
+}
+```
+
+## Remote HTTP
+
+The web app also exposes a Streamable HTTP endpoint:
+
+- production: `https://heyclau.de/api/mcp`
+- dev: `https://heyclaude-dev.zeronode.workers.dev/api/mcp`
+
+Validate a deployed endpoint with the SDK-level contract check:
+
+```bash
+MCP_ENDPOINT_URL=https://heyclaude-dev.zeronode.workers.dev/api/mcp pnpm validate:mcp-endpoint
+```
+
+This check connects with an MCP client, lists tools, calls representative
+registry and submission-helper tools, verifies strict argument validation, and
+checks the HTTP guards used by the remote route.
+
+## Security Boundary
+
+- Read-only registry artifacts only.
+- 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.
+
+## npm Release Prep
+
+MCP releases are package-scoped. Website/catalog changes do not create repo-wide
+semver releases. The initial public package version is `0.1.0`, and GitHub
+release tags use `mcp-vX.Y.Z`.
+
+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 --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
+```
+
+Publishing should happen through the manual `Publish MCP Package` GitHub
+workflow with npm trusted publishing/provenance enabled for `@heyclaude/mcp`.

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@heyclaude/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Read-only MCP server for the HeyClaude registry.",
+  "license": "MIT",
+  "main": "./src/registry.js",
+  "types": "./src/registry.d.ts",
+  "homepage": "https://heyclau.de",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JSONbored/claudepro-directory.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/JSONbored/claudepro-directory/issues"
+  },
+  "keywords": [
+    "heyclaude",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ai-registry",
+    "agents",
+    "skills"
+  ],
+  "files": [
+    "CHANGELOG.md",
+    "README.md",
+    "scripts/**/*.mjs",
+    "src/**/*.d.ts",
+    "src/**/*.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/registry.d.ts",
+      "default": "./src/registry.js"
+    },
+    "./registry": {
+      "types": "./src/registry.d.ts",
+      "default": "./src/registry.js"
+    },
+    "./server": {
+      "types": "./src/server.d.ts",
+      "default": "./src/server.js"
+    },
+    "./remote-proxy": {
+      "types": "./src/remote-proxy.d.ts",
+      "default": "./src/remote-proxy.js"
+    },
+    "./platforms": {
+      "types": "./src/platforms.d.ts",
+      "default": "./src/platforms.js"
+    },
+    "./schemas": {
+      "types": "./src/schemas.d.ts",
+      "default": "./src/schemas.js"
+    },
+    "./submissions": {
+      "types": "./src/submissions.d.ts",
+      "default": "./src/submissions.js"
+    }
+  },
+  "bin": {
+    "heyclaude-mcp": "src/cli.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node src/cli.js",
+    "start:local": "node src/cli.js --local --data-dir ../../apps/web/public/data",
+    "validate:endpoint": "node scripts/validate-endpoint.mjs",
+    "validate:package": "node ../../scripts/validate-mcp-package.mjs",
+    "test": "pnpm --dir ../.. exec vitest run tests/mcp-server.test.ts tests/mcp-cli.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "4.4.3"
+  }
+}

package/scripts/validate-endpoint.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+import { normalizeEndpointUrl } from "../src/endpoint-url.js";
+import { READ_ONLY_TOOL_NAMES } from "../src/registry.js";
+
+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;
+    args.set(value.slice(2), argv[index + 1] ?? "");
+    index += 1;
+  }
+  return args;
+}
+
+function parseToolResult(result) {
+  const text = result?.content?.find((item) => item?.type === "text")?.text;
+  if (!text) throw new Error("MCP tool response did not include text content.");
+  return JSON.parse(text);
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+async function validateHttpGuards(endpointUrl) {
+  const options = await fetch(endpointUrl, { method: "OPTIONS" });
+  assert(options.status === 204, `OPTIONS returned ${options.status}`);
+  assert(
+    String(options.headers.get("access-control-allow-methods") || "").includes(
+      "POST",
+    ),
+    "OPTIONS did not expose POST in access-control-allow-methods.",
+  );
+  assert(
+    options.headers.get("cache-control") === "no-store",
+    "OPTIONS did not return cache-control: no-store.",
+  );
+
+  const invalidContentType = await fetch(endpointUrl, {
+    method: "POST",
+    headers: {
+      accept: "application/json, text/event-stream",
+      "content-type": "text/plain",
+    },
+    body: "{}",
+  });
+  assert(
+    invalidContentType.status === 415 || invalidContentType.status === 403,
+    `text/plain POST returned ${invalidContentType.status}`,
+  );
+
+  const forbiddenOrigin = await fetch(endpointUrl, {
+    method: "POST",
+    headers: {
+      accept: "application/json, text/event-stream",
+      "content-type": "application/json",
+      origin: "https://example.invalid",
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: "forbidden-origin",
+      method: "tools/list",
+      params: {},
+    }),
+  });
+  assert(
+    forbiddenOrigin.status === 403,
+    `forbidden origin POST returned ${forbiddenOrigin.status}`,
+  );
+}
+
+async function validateMcpTools(endpointUrl) {
+  const client = new Client({
+    name: "heyclaude-endpoint-validator",
+    version: "0.1.0",
+  });
+  const transport = new StreamableHTTPClientTransport(endpointUrl);
+
+  try {
+    await client.connect(transport);
+
+    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(", ")}`,
+    );
+
+    const search = parseToolResult(
+      await client.callTool({
+        name: "search_registry",
+        arguments: { query: "mcp", limit: 2 },
+      }),
+    );
+    assert(search.ok === true, "search_registry did not return ok: true.");
+    assert(
+      Array.isArray(search.entries) && search.entries.length > 0,
+      "search_registry did not return entries.",
+    );
+
+    const first = search.entries[0];
+    const detail = parseToolResult(
+      await client.callTool({
+        name: "get_entry_detail",
+        arguments: { category: first.category, slug: first.slug },
+      }),
+    );
+    assert(detail.ok === true, "get_entry_detail did not return ok: true.");
+    assert(
+      detail.key === `${first.category}:${first.slug}`,
+      "get_entry_detail returned the wrong entry.",
+    );
+
+    const feeds = parseToolResult(
+      await client.callTool({
+        name: "list_distribution_feeds",
+        arguments: {},
+      }),
+    );
+    assert(feeds.ok === true, "list_distribution_feeds did not return ok.");
+    assert(
+      feeds.artifacts?.directory === "/data/directory-index.json",
+      "list_distribution_feeds did not expose the directory artifact.",
+    );
+
+    const schema = parseToolResult(
+      await client.callTool({
+        name: "get_submission_schema",
+        arguments: { category: "mcp" },
+      }),
+    );
+    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.",
+    );
+
+    const urls = parseToolResult(
+      await client.callTool({
+        name: "build_submission_urls",
+        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(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.",
+    );
+
+    const invalid = parseToolResult(
+      await client.callTool({
+        name: "search_registry",
+        arguments: { limit: 100, unexpected: true },
+      }),
+    );
+    assert(invalid.ok === false, "Invalid search_registry call did not fail.");
+    assert(
+      invalid.error?.code === "invalid_request",
+      "Invalid search_registry call did not return invalid_request.",
+    );
+  } finally {
+    await client.close();
+  }
+}
+
+const args = parseArgs(process.argv.slice(2));
+const endpointUrlRaw = args.get("url") || process.env.MCP_ENDPOINT_URL;
+const endpointUrl = endpointUrlRaw ? normalizeEndpointUrl(endpointUrlRaw) : "";
+
+if (!endpointUrl) {
+  console.error(
+    "Missing --url or MCP_ENDPOINT_URL for MCP endpoint validation.",
+  );
+  process.exit(1);
+}
+
+try {
+  await validateHttpGuards(endpointUrl);
+  await validateMcpTools(endpointUrl);
+  console.log(`Validated HeyClaude MCP endpoint at ${endpointUrl.toString()}`);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/src/cli-options.js

@@ -0,0 +1,103 @@
+import {
+  DEFAULT_REMOTE_MCP_URL,
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  normalizeEndpointUrl,
+  normalizeTimeoutMs,
+} from "./endpoint-url.js";
+import { packageName, packageVersion } from "./package-metadata.js";
+
+const helpText = `${packageName} ${packageVersion}
+
+Read-only stdio MCP bridge for the HeyClaude registry.
+
+Usage:
+  heyclaude-mcp [--url <endpoint>] [--timeout-ms <ms>]
+  heyclaude-mcp --local --data-dir <path>
+
+Options:
+  --url <endpoint>       Remote Streamable HTTP MCP endpoint.
+                         Defaults to ${DEFAULT_REMOTE_MCP_URL}
+  --local                Run the local artifact-backed MCP server.
+  --data-dir <path>      Generated registry data directory for local mode.
+  --timeout-ms <ms>      Remote request timeout. Default ${DEFAULT_REQUEST_TIMEOUT_MS}.
+  --version, -v          Print package version.
+  --help, -h             Print this help text.
+
+Environment:
+  HEYCLAUDE_MCP_URL          Remote MCP endpoint override.
+  HEYCLAUDE_MCP_TIMEOUT_MS   Remote request timeout override.
+  HEYCLAUDE_DATA_DIR         Local data directory; enables local mode.
+`;
+
+function readFlagValue(argv, index, flag) {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("-")) {
+    throw new Error(`${flag} requires a value.`);
+  }
+  return value;
+}
+
+export function renderHelp() {
+  return helpText;
+}
+
+export function parseCliArgs(argv = [], env = process.env) {
+  const options = {
+    mode: "remote",
+    url: env.HEYCLAUDE_MCP_URL || DEFAULT_REMOTE_MCP_URL,
+    dataDir: env.HEYCLAUDE_DATA_DIR || "",
+    timeoutMs: normalizeTimeoutMs(env.HEYCLAUDE_MCP_TIMEOUT_MS),
+    help: false,
+    version: false,
+  };
+
+  if (options.dataDir) {
+    options.mode = "local";
+  }
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--") continue;
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "--version" || arg === "-v") {
+      options.version = true;
+      continue;
+    }
+    if (arg === "--local") {
+      options.mode = "local";
+      continue;
+    }
+    if (arg === "--url") {
+      options.url = readFlagValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--data-dir") {
+      options.dataDir = readFlagValue(argv, index, arg);
+      options.mode = "local";
+      index += 1;
+      continue;
+    }
+    if (arg === "--timeout-ms") {
+      options.timeoutMs = normalizeTimeoutMs(readFlagValue(argv, index, arg));
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (options.help || options.version) return options;
+
+  if (options.mode === "local") {
+    if (!options.dataDir) {
+      throw new Error("Local mode requires --data-dir or HEYCLAUDE_DATA_DIR.");
+    }
+    return options;
+  }
+
+  options.url = normalizeEndpointUrl(options.url);
+  return options;
+}

package/src/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { parseCliArgs, renderHelp } from "./cli-options.js";
+import { packageVersion } from "./package-metadata.js";
+import { runRemoteStdioProxy } from "./remote-proxy.js";
+import { runStdioServer } from "./server.js";
+
+async function main() {
+  const options = parseCliArgs(process.argv.slice(2), process.env);
+  if (options.help) {
+    console.log(renderHelp());
+    return;
+  }
+  if (options.version) {
+    console.log(packageVersion);
+    return;
+  }
+  if (options.mode === "local") {
+    await runStdioServer({ dataDir: options.dataDir });
+    return;
+  }
+  await runRemoteStdioProxy({
+    url: options.url,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

package/src/endpoint-url.js

@@ -0,0 +1,32 @@
+export const DEFAULT_REMOTE_MCP_URL = "https://heyclau.de/api/mcp";
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+
+const localHosts = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+
+export function normalizeEndpointUrl(value = DEFAULT_REMOTE_MCP_URL) {
+  const raw = String(value || "").trim();
+  if (!raw) throw new Error("MCP endpoint URL is required.");
+
+  const url = new URL(raw);
+  if (url.protocol !== "https:" && !localHosts.has(url.hostname)) {
+    throw new Error("MCP endpoint URL must use HTTPS outside localhost.");
+  }
+
+  if (url.pathname === "/" || url.pathname === "") {
+    url.pathname = "/api/mcp";
+  }
+
+  return url;
+}
+
+export function normalizeTimeoutMs(
+  value,
+  fallback = DEFAULT_REQUEST_TIMEOUT_MS,
+) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric < 1000 || numeric > 300000) {
+    throw new Error("Timeout must be between 1000 and 300000 milliseconds.");
+  }
+  return Math.trunc(numeric);
+}

package/src/package-metadata.js

@@ -0,0 +1,7 @@
+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");

package/src/platforms.d.ts

@@ -0,0 +1,9 @@
+export const SITE_URL: "https://heyclau.de";
+
+export function platformFeedSlug(platform: string): string;
+
+export function buildSkillPlatformCompatibility(entry: {
+  category?: string;
+  slug?: string;
+  platformCompatibility?: unknown[];
+}): unknown[];

package/src/platforms.js

@@ -0,0 +1,86 @@
+export const SITE_URL = "https://heyclau.de";
+
+function slugPart(value, options = {}) {
+  const text = String(value || "")
+    .trim()
+    .toLowerCase();
+  let output = "";
+  let lastWasSeparator = false;
+
+  for (const char of text) {
+    const isAlphaNumeric =
+      (char >= "a" && char <= "z") || (char >= "0" && char <= "9");
+    if (isAlphaNumeric) {
+      output += char;
+      lastWasSeparator = false;
+      continue;
+    }
+    if (char === "&" && options.expandAmpersand) {
+      if (output && !lastWasSeparator) output += "-";
+      output += "and";
+      lastWasSeparator = false;
+      continue;
+    }
+    if (output && !lastWasSeparator) {
+      output += "-";
+      lastWasSeparator = true;
+    }
+  }
+
+  return lastWasSeparator ? output.slice(0, -1) : output;
+}
+
+export function platformFeedSlug(platform) {
+  return slugPart(platform, { expandAmpersand: true });
+}
+
+export function buildSkillPlatformCompatibility(entry) {
+  if (entry?.category !== "skills") return [];
+  if (Array.isArray(entry.platformCompatibility)) {
+    return entry.platformCompatibility;
+  }
+
+  const slug = String(entry?.slug || "").trim();
+  return [
+    {
+      platform: "Claude",
+      support: "native-skill",
+      artifact: "SKILL.md package",
+      installHint: "Install the skill package into your Claude skills folder.",
+    },
+    {
+      platform: "Codex",
+      support: "native-skill",
+      artifact: "SKILL.md package",
+      installHint: "Install the skill package into your Codex skills folder.",
+    },
+    {
+      platform: "Windsurf",
+      support: "native-skill",
+      artifact: "SKILL.md package",
+      installHint: "Install the skill under .windsurf/skills/<skill-name>/.",
+    },
+    {
+      platform: "Gemini",
+      support: "native-skill",
+      artifact: "SKILL.md package",
+      installHint:
+        "Use the skill package with Gemini CLI extension skill support.",
+    },
+    {
+      platform: "Cursor",
+      support: "adapter",
+      artifact: `.cursor/rules/${slug}.mdc`,
+      adapterUrl: `/data/skill-adapters/cursor/${slug}.mdc`,
+      installHint:
+        "Use the generated Cursor rule adapter because Cursor rules are the supported reusable instruction surface.",
+    },
+    {
+      platform: "Generic AGENTS",
+      support: "manual-context",
+      artifact: "SKILL.md package",
+      installHint:
+        "Use SKILL.md as reusable agent context or convert it into the target tool's instruction file.",
+    },
+  ];
+}