findskills-mcp 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# findskills-mcp
+
+MCP Server for [FindSkills](https://findskills.org) — search and discover 15,000+ AI Agent Skills via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Quick Start
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "findskills": {
+      "command": "npx",
+      "args": ["-y", "findskills-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add findskills -- npx -y findskills-mcp
+```
+
+### Other MCP Clients
+
+```bash
+npx findskills-mcp
+```
+
+The server communicates over stdio using the MCP protocol.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_skills` | Search by keyword, ranked by relevance |
+| `list_skills` | Browse/filter by category, source, safety, quality |
+| `get_skill` | Full details for a specific skill |
+| `get_stats` | Dataset overview (total count, distributions) |
+| `list_tags` | All tags with usage counts |
+
+### search_skills
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | yes | Search keyword |
+| `limit` | number | no | Max results (default 20, max 100) |
+
+### list_skills
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `category` | enum | no | One of: search, coding, data, communication, media, automation, security, ai-ml, devops, finance, productivity, integration, other |
+| `source` | enum | no | clawhub, github, manual |
+| `auth_type` | enum | no | none, api_key, oauth2, bearer |
+| `sort` | enum | no | updated, added, stars, quality, safety, name |
+| `min_quality` | number | no | Minimum quality score (0-100) |
+| `min_safety` | number | no | Minimum safety score (0-100) |
+| `limit` | number | no | Results per page (default 20) |
+| `offset` | number | no | Pagination offset |
+
+### get_skill
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Skill ID |
+
+### get_stats
+
+No parameters.
+
+### list_tags
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `limit` | number | no | Max tags (default 50) |
+
+## Requirements
+
+- Node.js >= 20.0.0
+
+## License
+
+MIT

package/api.js

@@ -0,0 +1,36 @@
+const BASE = 'https://findskills.org/api/v1';
+
+async function request(path) {
+  const res = await fetch(`${BASE}${path}`, { redirect: 'follow' });
+  if (!res.ok) throw new Error(`FindSkills API error: ${res.status} ${res.statusText}`);
+  return res.json();
+}
+
+export async function searchSkills(query, limit = 20) {
+  return request(`/search?q=${encodeURIComponent(query)}&limit=${limit}`);
+}
+
+export async function listSkills({ category, source, auth_type, sort, min_quality, min_safety, limit = 20, offset = 0 } = {}) {
+  const params = new URLSearchParams();
+  params.set('limit', String(limit));
+  params.set('offset', String(offset));
+  if (category) params.set('category', category);
+  if (source) params.set('source', source);
+  if (auth_type) params.set('auth_type', auth_type);
+  if (sort) params.set('sort', sort);
+  if (min_quality != null) params.set('min_quality', String(min_quality));
+  if (min_safety != null) params.set('min_safety', String(min_safety));
+  return request(`/skills?${params}`);
+}
+
+export async function getSkill(id) {
+  return request(`/skills/${encodeURIComponent(id)}`);
+}
+
+export async function getStats() {
+  return request('/stats');
+}
+
+export async function listTags(limit = 50) {
+  return request(`/tags?limit=${limit}`);
+}

package/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { startServer } from './server.js';
+startServer();

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "findskills-mcp",
+  "version": "0.1.0",
+  "description": "MCP Server for FindSkills — search and discover 15,000+ AI Agent Skills",
+  "type": "module",
+  "bin": {
+    "findskills-mcp": "bin.js"
+  },
+  "files": [
+    "bin.js",
+    "server.js",
+    "api.js"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "ai",
+    "agent",
+    "skills",
+    "findskills",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shintemy/findskills.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^3.24.0"
+  }
+}

package/server.js

@@ -0,0 +1,82 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { searchSkills, listSkills, getSkill, getStats, listTags } from './api.js';
+
+function text(content) {
+  return { content: [{ type: 'text', text: typeof content === 'string' ? content : JSON.stringify(content, null, 2) }] };
+}
+
+export function createServer() {
+  const server = new McpServer({ name: 'findskills', version: '0.1.0' });
+
+  server.registerTool('search_skills', {
+    title: 'Search Skills',
+    description: 'Search FindSkills directory by keyword. Returns skills ranked by relevance.',
+    inputSchema: {
+      query: z.string().describe('Search keyword (e.g. "web scraping", "slack", "database")'),
+      limit: z.number().int().min(1).max(100).default(20).describe('Max results (default 20)'),
+    },
+  }, async ({ query, limit }) => {
+    const data = await searchSkills(query, limit);
+    return text(data);
+  });
+
+  server.registerTool('list_skills', {
+    title: 'List Skills',
+    description: 'Browse and filter skills by category, source, safety tier, and more. Supports pagination.',
+    inputSchema: {
+      category: z.enum(['search', 'coding', 'data', 'communication', 'media', 'automation', 'security', 'ai-ml', 'devops', 'finance', 'productivity', 'integration', 'other']).optional().describe('Filter by category'),
+      source: z.enum(['clawhub', 'github', 'manual']).optional().describe('Filter by data source'),
+      auth_type: z.enum(['none', 'api_key', 'oauth2', 'bearer']).optional().describe('Filter by auth requirement'),
+      sort: z.enum(['updated', 'added', 'stars', 'quality', 'safety', 'name']).default('updated').describe('Sort order'),
+      min_quality: z.number().int().min(0).max(100).optional().describe('Minimum quality score (0-100)'),
+      min_safety: z.number().int().min(0).max(100).optional().describe('Minimum safety score (0-100)'),
+      limit: z.number().int().min(1).max(100).default(20).describe('Results per page'),
+      offset: z.number().int().min(0).default(0).describe('Pagination offset'),
+    },
+  }, async (params) => {
+    const data = await listSkills(params);
+    return text(data);
+  });
+
+  server.registerTool('get_skill', {
+    title: 'Get Skill Details',
+    description: 'Get full details for a specific skill including auth requirements, safety signals, and quality signals.',
+    inputSchema: {
+      id: z.string().describe('Skill ID (e.g. "clawhub-web-search")'),
+    },
+  }, async ({ id }) => {
+    const data = await getSkill(id);
+    return text(data);
+  });
+
+  server.registerTool('get_stats', {
+    title: 'Get Dataset Stats',
+    description: 'Get FindSkills dataset overview: total skill count, category/source/auth breakdowns, quality and safety distributions. Call this first to understand the dataset.',
+    inputSchema: {},
+  }, async () => {
+    const data = await getStats();
+    return text(data);
+  });
+
+  server.registerTool('list_tags', {
+    title: 'List Tags',
+    description: 'List all skill tags with usage counts, sorted by popularity.',
+    inputSchema: {
+      limit: z.number().int().min(1).max(500).default(50).describe('Max tags to return'),
+    },
+  }, async ({ limit }) => {
+    const data = await listTags(limit);
+    return text(data);
+  });
+
+  return server;
+}
+
+export async function startServer() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('FindSkills MCP Server running on stdio');
+}