skillsmp-mcp-lite 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SkillsMP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# SkillsMP MCP Server
+
+An MCP (Model Context Protocol) server that enables AI assistants to search for skills from [SkillsMP](https://skillsmp.com) marketplace before starting any task.
+
+## Features
+
+- **Keyword Search**: Search skills using specific keywords like "PDF", "web scraper", "SEO"
+- **AI Semantic Search**: Find skills using natural language descriptions powered by Cloudflare AI
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable           | Required | Description           |
+| ------------------ | -------- | --------------------- |
+| `SKILLSMP_API_KEY` | Yes      | Your SkillsMP API key |
+
+Get your API key from: https://skillsmp.com/docs/api
+
+### VS Code / Cursor Setup
+
+Add to your `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "skillsmp": {
+        "command": "node",
+        "args": ["path/to/skillsmp-mcp-server/dist/index.js"],
+        "env": {
+          "SKILLSMP_API_KEY": "sk_live_skillsmp_YOUR_API_KEY"
+        }
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop Setup
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "skillsmp": {
+      "command": "node",
+      "args": ["/absolute/path/to/skillsmp-mcp-server/dist/index.js"],
+      "env": {
+        "SKILLSMP_API_KEY": "sk_live_skillsmp_YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `skillsmp_search_skills`
+
+Search for skills using keywords.
+
+**Parameters:**
+
+- `query` (string, required): Search keywords
+- `page` (number, optional): Page number (default: 1)
+- `limit` (number, optional): Items per page (default: 20, max: 100)
+- `sortBy` (string, optional): Sort by "stars" or "recent"
+
+**Example:**
+
+```
+Search for "PDF manipulation" skills
+```
+
+### `skillsmp_ai_search_skills`
+
+AI semantic search for skills using natural language.
+
+**Parameters:**
+
+- `query` (string, required): Natural language description of what you want to accomplish
+
+**Example:**
+
+```
+Find skills for "How to create a web scraper that extracts product data"
+```
+
+## Usage Workflow
+
+The recommended workflow is:
+
+1. **Before starting any task**, search for relevant skills
+2. If a matching skill is found, use `npx openskills read <skill-name>` to load it
+3. Follow the skill's instructions to complete the task
+
+## API Reference
+
+This server uses the SkillsMP REST API:
+
+- `GET /api/v1/skills/search` - Keyword search
+- `GET /api/v1/skills/ai-search` - AI semantic search
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,80 @@
+/**
+ * SkillsMP API Client and Types
+ */
+export declare const SKILLSMP_API_BASE = "https://skillsmp.com/api/v1";
+export interface Skill {
+    id: string;
+    name: string;
+    description: string;
+    author?: string;
+    stars?: number;
+    updatedAt?: number;
+    tags?: string[];
+    githubUrl?: string;
+    skillUrl?: string;
+}
+export interface Pagination {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+export interface SearchResponse {
+    success: boolean;
+    data: {
+        skills: Skill[];
+        pagination: Pagination;
+        filters?: {
+            search: string;
+            sortBy: string;
+        };
+    };
+    meta?: {
+        requestId: string;
+        responseTimeMs: number;
+    };
+}
+export interface AISearchResponse {
+    success: boolean;
+    data: {
+        object: string;
+        search_query: string;
+        data: Array<{
+            file_id: string;
+            filename: string;
+            score: number;
+            skill?: Skill;
+        }>;
+        has_more: boolean;
+        next_page: string | null;
+    };
+    meta?: {
+        requestId: string;
+        responseTimeMs: number;
+    };
+}
+export interface ApiError {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+export declare function makeApiRequest<T>(endpoint: string, apiKey: string, params?: Record<string, string | number>): Promise<T>;
+/**
+ * Validate search response structure
+ */
+export declare function validateSearchResponse(data: unknown): asserts data is SearchResponse;
+/**
+ * Validate AI search response structure
+ */
+export declare function validateAISearchResponse(data: unknown): asserts data is AISearchResponse;
+/**
+ * Custom error for API structure changes
+ */
+export declare class ApiStructureError extends Error {
+    constructor(message: string);
+}
+export declare function handleApiError(error: unknown): string;

package/dist/api.js

@@ -0,0 +1,95 @@
+/**
+ * SkillsMP API Client and Types
+ */
+// API Configuration
+export const SKILLSMP_API_BASE = "https://skillsmp.com/api/v1";
+// API Client
+export async function makeApiRequest(endpoint, apiKey, params) {
+    const url = new URL(`${SKILLSMP_API_BASE}/${endpoint}`);
+    if (params) {
+        Object.entries(params).forEach(([key, value]) => {
+            if (value !== undefined && value !== null) {
+                url.searchParams.append(key, String(value));
+            }
+        });
+    }
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: {
+            "Authorization": `Bearer ${apiKey}`,
+            "Content-Type": "application/json"
+        }
+    });
+    if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new Error(errorData.error?.message ||
+            `API request failed with status ${response.status}`);
+    }
+    return response.json();
+}
+/**
+ * Validate base response structure (shared logic)
+ */
+function validateBaseResponse(data) {
+    if (!data || typeof data !== 'object') {
+        throw new ApiStructureError('Invalid response: expected object');
+    }
+    const response = data;
+    if (typeof response.success !== 'boolean') {
+        throw new ApiStructureError('Invalid response: missing "success" field');
+    }
+    if (!response.success) {
+        throw new ApiStructureError(`API returned failure: ${JSON.stringify(response)}`);
+    }
+    if (!response.data || typeof response.data !== 'object') {
+        throw new ApiStructureError('Invalid response: missing "data" object');
+    }
+    return response.data;
+}
+/**
+ * Validate search response structure
+ */
+export function validateSearchResponse(data) {
+    const responseData = validateBaseResponse(data);
+    if (!Array.isArray(responseData.skills)) {
+        throw new ApiStructureError('Invalid response structure: expected "data.skills" array. ' +
+            `Got: ${JSON.stringify(Object.keys(responseData))}. ` +
+            'The SkillsMP API structure may have changed.');
+    }
+}
+/**
+ * Validate AI search response structure
+ */
+export function validateAISearchResponse(data) {
+    const responseData = validateBaseResponse(data);
+    if (!Array.isArray(responseData.data)) {
+        throw new ApiStructureError('Invalid AI search response structure: expected "data.data" array. ' +
+            `Got: ${JSON.stringify(Object.keys(responseData))}. ` +
+            'The SkillsMP API structure may have changed.');
+    }
+}
+/**
+ * Custom error for API structure changes
+ */
+export class ApiStructureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ApiStructureError';
+    }
+}
+// Error Handler
+export function handleApiError(error) {
+    if (error instanceof ApiStructureError) {
+        return `⚠️ API Structure Error: ${error.message}\n\nThis likely means the SkillsMP API has changed. Please report this issue.`;
+    }
+    if (error instanceof Error) {
+        if (error.message.includes("401")) {
+            return "Error: Invalid or missing API key. Please check your SKILLSMP_API_KEY environment variable.";
+        }
+        if (error.message.includes("429")) {
+            return "Error: Rate limit exceeded. Please wait before making more requests.";
+        }
+        return `Error: ${error.message}`;
+    }
+    return "Error: An unexpected error occurred";
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerSkillsTools } from "./tools/skills.js";
+/**
+ * SkillsMP MCP Server
+ *
+ * This server provides tools to search for AI skills from SkillsMP marketplace
+ * before starting any task. It supports both keyword search and AI semantic search.
+ *
+ * Environment Variables:
+ *   SKILLSMP_API_KEY - Your SkillsMP API key (required)
+ */
+const API_KEY = process.env.SKILLSMP_API_KEY;
+if (!API_KEY) {
+    console.error("Error: SKILLSMP_API_KEY environment variable is required");
+    console.error("Get your API key from: https://skillsmp.com/docs/api");
+    process.exit(1);
+}
+// Initialize MCP Server
+const server = new McpServer({
+    name: "skillsmp-mcp-server",
+    version: "1.0.0"
+});
+// Register skills search tools
+registerSkillsTools(server, API_KEY);
+// Start server with stdio transport
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("SkillsMP MCP Server started");
+    console.error("Available tools:");
+    console.error("  - skillsmp_search_skills: Keyword search for skills");
+    console.error("  - skillsmp_ai_search_skills: AI semantic search for skills");
+}
+main().catch((error) => {
+    console.error("Failed to start server:", error);
+    process.exit(1);
+});

package/dist/schemas.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+/**
+ * Zod Schemas for SkillsMP Tools
+ */
+export declare enum SortBy {
+    STARS = "stars",
+    RECENT = "recent"
+}
+export declare const KeywordSearchSchema: z.ZodObject<{
+    query: z.ZodString;
+    page: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    sortBy: z.ZodOptional<z.ZodNativeEnum<typeof SortBy>>;
+}, "strict", z.ZodTypeAny, {
+    query: string;
+    page: number;
+    limit: number;
+    sortBy?: SortBy | undefined;
+}, {
+    query: string;
+    page?: number | undefined;
+    limit?: number | undefined;
+    sortBy?: SortBy | undefined;
+}>;
+export type KeywordSearchInput = z.infer<typeof KeywordSearchSchema>;
+export declare const AISearchSchema: z.ZodObject<{
+    query: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    query: string;
+}, {
+    query: string;
+}>;
+export type AISearchInput = z.infer<typeof AISearchSchema>;

package/dist/schemas.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+/**
+ * Zod Schemas for SkillsMP Tools
+ */
+// Sort options enum
+export var SortBy;
+(function (SortBy) {
+    SortBy["STARS"] = "stars";
+    SortBy["RECENT"] = "recent";
+})(SortBy || (SortBy = {}));
+// Keyword Search Schema
+export const KeywordSearchSchema = z.object({
+    query: z.string()
+        .min(1, "Query is required")
+        .max(200, "Query must not exceed 200 characters")
+        .describe("Search keywords for finding skills"),
+    page: z.number()
+        .int()
+        .min(1)
+        .default(1)
+        .describe("Page number (default: 1)"),
+    limit: z.number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(20)
+        .describe("Items per page (default: 20, max: 100)"),
+    sortBy: z.nativeEnum(SortBy)
+        .optional()
+        .describe("Sort by: 'stars' or 'recent'")
+}).strict();
+// AI Semantic Search Schema
+export const AISearchSchema = z.object({
+    query: z.string()
+        .min(1, "Query is required")
+        .max(500, "Query must not exceed 500 characters")
+        .describe("Natural language description of what you want to accomplish")
+}).strict();

package/dist/tools/skills.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register SkillsMP tools on the MCP server
+ */
+export declare function registerSkillsTools(server: McpServer, apiKey: string): void;

package/dist/tools/skills.js

@@ -0,0 +1,210 @@
+import { makeApiRequest, handleApiError, validateSearchResponse, validateAISearchResponse } from "../api.js";
+import { KeywordSearchSchema, AISearchSchema } from "../schemas.js";
+/**
+ * Register SkillsMP tools on the MCP server
+ */
+export function registerSkillsTools(server, apiKey) {
+    // Tool 1: Keyword Search
+    server.registerTool("skillsmp_search_skills", {
+        title: "Search SkillsMP Skills",
+        description: `Search for AI skills using keywords from SkillsMP marketplace.
+
+Use this tool to find skills by specific terms like 'SEO', 'web scraper', 'PDF', 'data analysis', etc.
+
+**IMPORTANT**: Before starting any task, use this tool to check if there's an existing skill that can help complete the task more effectively.
+
+Args:
+  - query (string, required): Search keywords
+  - page (number, optional): Page number (default: 1)
+  - limit (number, optional): Items per page (default: 20, max: 100)
+  - sortBy (string, optional): Sort by 'stars' or 'recent'
+
+Returns:
+  List of matching skills with name, description, author, and star count.
+
+Examples:
+  - "PDF manipulation" -> Find skills for working with PDFs
+  - "web scraper" -> Find web scraping skills
+  - "SEO optimization" -> Find SEO-related skills`,
+        inputSchema: KeywordSearchSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            const queryParams = {
+                q: params.query
+            };
+            if (params.page)
+                queryParams.page = params.page;
+            if (params.limit)
+                queryParams.limit = params.limit;
+            if (params.sortBy)
+                queryParams.sortBy = params.sortBy;
+            const rawData = await makeApiRequest("skills/search", apiKey, queryParams);
+            // Validate API response structure before processing
+            validateSearchResponse(rawData);
+            const skills = rawData.data?.skills || [];
+            const pagination = rawData.data?.pagination;
+            if (!skills.length) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `No skills found matching '${params.query}'. Try different keywords or use AI semantic search for natural language queries.`
+                        }]
+                };
+            }
+            const output = formatSkillsResponse(skills, params.query, pagination);
+            return {
+                content: [{ type: "text", text: output }],
+                structuredContent: {
+                    query: params.query,
+                    count: skills.length,
+                    skills: skills,
+                    pagination: pagination
+                }
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: "text",
+                        text: handleApiError(error)
+                    }]
+            };
+        }
+    });
+    // Tool 2: AI Semantic Search
+    server.registerTool("skillsmp_ai_search_skills", {
+        title: "AI Search SkillsMP Skills",
+        description: `AI semantic search for skills using natural language descriptions.
+
+Use this when you need to find skills based on what you want to accomplish rather than specific keywords.
+
+**IMPORTANT**: Before starting any complex task, use this tool to discover relevant skills that can help.
+
+Args:
+  - query (string, required): Natural language description of what you want to accomplish
+
+Returns:
+  List of semantically relevant skills that match your intent.
+
+Examples:
+  - "How to create a web scraper" -> Find skills for web scraping
+  - "Build a dashboard with charts" -> Find data visualization skills
+  - "Generate PDF reports from data" -> Find PDF generation skills
+  - "Automate social media posting" -> Find social media automation skills`,
+        inputSchema: AISearchSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            const rawData = await makeApiRequest("skills/ai-search", apiKey, { q: params.query });
+            // Validate API response structure before processing
+            validateAISearchResponse(rawData);
+            // AI search returns results in data.data array with skill objects
+            const results = rawData.data?.data || [];
+            const skills = results
+                .filter(item => item.skill) // Only include items with skill data
+                .map(item => ({
+                ...item.skill,
+                score: item.score
+            }));
+            if (!skills.length) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `No skills found for: "${params.query}". Try rephrasing your query or use keyword search for specific terms.`
+                        }]
+                };
+            }
+            const output = formatAISearchResponse(skills, params.query);
+            return {
+                content: [{ type: "text", text: output }],
+                structuredContent: {
+                    query: params.query,
+                    count: skills.length,
+                    skills: skills
+                }
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: "text",
+                        text: handleApiError(error)
+                    }]
+            };
+        }
+    });
+}
+/**
+ * Render a single skill as markdown lines
+ */
+function renderSkill(skill, index) {
+    const lines = [];
+    // Header
+    const header = index !== undefined ? `## ${index + 1}. ${skill.name}` : `## ${skill.name}`;
+    lines.push(header);
+    // Meta info
+    const meta = [];
+    if (skill.stars !== undefined)
+        meta.push(`⭐ ${skill.stars} stars`);
+    if (skill.score !== undefined)
+        meta.push(`📊 Score: ${(skill.score * 100).toFixed(1)}%`);
+    if (meta.length)
+        lines.push(meta.join(" | "));
+    lines.push("");
+    lines.push(skill.description || "No description available");
+    if (skill.author) {
+        lines.push("");
+        lines.push(`**Author**: ${skill.author}`);
+    }
+    if (skill.skillUrl) {
+        lines.push(`**URL**: ${skill.skillUrl}`);
+    }
+    if (skill.tags?.length) {
+        lines.push(`**Tags**: ${skill.tags.join(", ")}`);
+    }
+    lines.push("", "---", "");
+    return lines;
+}
+/**
+ * Format skills search response as markdown
+ */
+function formatSkillsResponse(skills, query, pagination) {
+    const lines = [
+        `# 🔍 Skills Search Results: "${query}"`,
+        "",
+        `Found ${pagination?.total || skills.length} skill(s) (showing ${skills.length})`,
+        ""
+    ];
+    skills.forEach(skill => lines.push(...renderSkill(skill)));
+    if (pagination?.hasNext) {
+        lines.push(`*More results available. Call this tool again with \`page: ${pagination.page + 1}\` to see more.*`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Format AI search response as markdown
+ */
+function formatAISearchResponse(skills, query) {
+    const lines = [
+        `# 🤖 AI Semantic Search Results`,
+        "",
+        `**Query**: "${query}"`,
+        "",
+        `Found ${skills.length} relevant skill(s)`,
+        ""
+    ];
+    skills.forEach((skill, i) => lines.push(...renderSkill(skill, i)));
+    lines.push("💡 **Tip**: Use `npx openskills read <skill-name>` to load a skill's detailed instructions.");
+    return lines.join("\n");
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "skillsmp-mcp-lite",
+  "version": "1.0.0",
+  "description": "Lightweight MCP server for searching AI skills from SkillsMP before starting any task",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "skillsmp-mcp-lite": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "skills",
+    "ai",
+    "skillsmp",
+    "ai-skills",
+    "marketplace"
+  ],
+  "author": "clancylllin <poerevan9@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/boyonglin/skillsmp-mcp-lite.git"
+  },
+  "homepage": "https://github.com/boyonglin/skillsmp-mcp-lite#readme",
+  "bugs": {
+    "url": "https://github.com/boyonglin/skillsmp-mcp-lite/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}