skillmds 0.1.0

package/bin/skillmd-mcp.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// SkillMD MCP server (stdio). Wraps the public SkillMD API so any MCP-capable agent
+// can search, fetch, install, and discover Agent Skills by name or task.
+//
+//   claude mcp add skillmd -- npx -y skillmds
+//
+// Env:
+//   SKILLMD_API   override API base (default https://skillmd-api.vinoor.workers.dev)
+//   SKILLMD_TOKEN  personal access token (enables skillmd_list_saved / personalized recommend)
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+const API = process.env.SKILLMD_API || "https://skillmd-api.vinoor.workers.dev";
+const TOKEN = process.env.SKILLMD_TOKEN || "";
+
+async function api(path, init = {}) {
+  const headers = { accept: "application/json", ...(init.headers || {}) };
+  if (TOKEN) headers.authorization = `Bearer ${TOKEN}`;
+  const res = await fetch(API + path, { ...init, headers });
+  if (!res.ok) throw new Error(`SkillMD API ${res.status} on ${path}: ${await res.text().catch(() => "")}`);
+  return res.json();
+}
+const text = (obj) => ({ content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }] });
+
+const TOOLS = [
+  {
+    name: "skillmd_search",
+    description: "Search SkillMD for Agent Skills by name, description, or task. Returns matching skills with ratings and install snippets.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Natural-language query or keywords" },
+        category: { type: "string", description: "Filter by category slug (e.g. devops, data, security)" },
+        verified_only: { type: "boolean", description: "Only verified skills" },
+        type: { type: "string", enum: ["single", "pack"], description: "single file or pack" },
+        min_rating: { type: "number", description: "Minimum average rating 0-5" },
+        limit: { type: "number", description: "Max results (default 20)" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "skillmd_get",
+    description: "Fetch a single skill by slug (owner/name), including its SKILL.md body, provenance, license and security flags.",
+    inputSchema: { type: "object", properties: { slug: { type: "string", description: "owner/name, e.g. anthropic/pdf" } }, required: ["slug"] },
+  },
+  {
+    name: "skillmd_install",
+    description: "Install a skill by slug: writes its SKILL.md into the agent's skills directory. Never executes any scripts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: "owner/name, e.g. anthropic/pdf" },
+        dest: { type: "string", description: "Target skills dir. Default ~/.claude/skills" },
+      },
+      required: ["slug"],
+    },
+  },
+  {
+    name: "skillmd_trending",
+    description: "Top skills on the SkillMD leaderboard. range: '30d' or 'all'.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        range: { type: "string", enum: ["30d", "all"], description: "Time window (default all)" },
+        category: { type: "string", description: "Optional category slug" },
+        limit: { type: "number", description: "Max results (default 20)" },
+      },
+    },
+  },
+  {
+    name: "skillmd_recommend",
+    description: "Recommend skills. If based_on is given, suggests skills similar to it (same category); otherwise returns trending.",
+    inputSchema: {
+      type: "object",
+      properties: { based_on: { type: "string", description: "A slug to base recommendations on" }, limit: { type: "number" } },
+    },
+  },
+  {
+    name: "skillmd_list_saved",
+    description: "List the signed-in user's saved skills. Requires SKILLMD_TOKEN to be set.",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+function reconstructSkillMd(skill) {
+  const fm = ["---", `name: ${skill.slug.split("/")[1] || skill.title}`, `description: ${String(skill.description).replace(/\n/g, " ")}`];
+  if (skill.license) fm.push(`license: ${skill.license}`);
+  fm.push("---", "");
+  return fm.join("\n") + (skill.body_md || "");
+}
+
+async function handleCall(name, args) {
+  switch (name) {
+    case "skillmd_search": {
+      const p = new URLSearchParams({ q: args.query, limit: String(args.limit ?? 20) });
+      if (args.category) p.set("category", args.category);
+      if (args.verified_only) p.set("verified", "true");
+      if (args.type) p.set("type", args.type);
+      if (args.min_rating != null) p.set("min_rating", String(args.min_rating));
+      const r = await api(`/api/search?${p}`);
+      return text(r.items ?? []);
+    }
+    case "skillmd_get": {
+      const [owner, slugName] = String(args.slug).split("/");
+      const r = await api(`/api/skills/${owner}/${slugName}`);
+      return text(r);
+    }
+    case "skillmd_trending": {
+      const p = new URLSearchParams({ range: args.range ?? "all", limit: String(args.limit ?? 20) });
+      if (args.category) p.set("category", args.category);
+      const r = await api(`/api/leaderboard?${p}`);
+      return text(r.items ?? []);
+    }
+    case "skillmd_recommend": {
+      if (args.based_on) {
+        const [owner, slugName] = String(args.based_on).split("/");
+        const base = await api(`/api/skills/${owner}/${slugName}`).catch(() => null);
+        if (base?.category_slug) {
+          const r = await api(`/api/leaderboard?range=all&limit=${args.limit ?? 10}&category=${base.category_slug}`);
+          return text((r.items ?? []).filter((s) => s.slug !== args.based_on));
+        }
+      }
+      const r = await api(`/api/leaderboard?range=30d&limit=${args.limit ?? 10}`);
+      return text(r.items ?? []);
+    }
+    case "skillmd_list_saved": {
+      if (!TOKEN) return text("Set SKILLMD_TOKEN (a SkillMD personal access token) to list your saved skills.");
+      const r = await api(`/api/favorites`);
+      return text(r.items ?? []);
+    }
+    case "skillmd_install": {
+      const [owner, slugName] = String(args.slug).split("/");
+      const skill = await api(`/api/skills/${owner}/${slugName}`);
+      const baseDir = args.dest ? resolve(args.dest) : join(homedir(), ".claude", "skills");
+      const dir = join(baseDir, slugName);
+      await mkdir(dir, { recursive: true });
+      const file = join(dir, "SKILL.md");
+      await writeFile(file, reconstructSkillMd(skill), "utf8");
+      api(`/api/skills/${owner}/${slugName}/install`, { method: "POST", body: JSON.stringify({ via: "mcp" }) }).catch(() => {});
+      const note = skill.type === "pack"
+        ? " (pack assets are not bundled yet — only SKILL.md was written)"
+        : "";
+      return text(`Installed ${args.slug} → ${file}${note}`);
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+const server = new Server({ name: "skillmd", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  try {
+    return await handleCall(req.params.name, req.params.arguments ?? {});
+  } catch (e) {
+    return { isError: true, content: [{ type: "text", text: String(e?.message || e) }] };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("skillmd MCP server running (stdio)");

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "skillmds",
+  "version": "0.1.0",
+  "description": "SkillMD MCP server — search, fetch and install Agent Skills from SkillMD.com",
+  "type": "module",
+  "bin": {
+    "skillmds": "bin/skillmd-mcp.mjs"
+  },
+  "keywords": ["mcp", "agent-skills", "skillmd", "claude", "ai"],
+  "homepage": "https://skillmd.com",
+  "files": ["bin"],
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.13.0"
+  }
+}