skillsmp-mcp-lite 1.0.0 → 1.0.2

package/README.md

@@ -1,114 +1,143 @@
-# SkillsMP MCP Server
+# SkillsMP MCP Server (Lite)
 
-An MCP (Model Context Protocol) server that enables AI assistants to search for skills from [SkillsMP](https://skillsmp.com) marketplace before starting any task.
+A lightweight MCP 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
+## Quick Setup
 
-```bash
-npm install
-npm run build
-```
-
-## Configuration
+No installation required! Just add the config to your AI client.
 
-### Environment Variables
+### VS Code / GitHub Copilot
 
-| Variable           | Required | Description           |
-| ------------------ | -------- | --------------------- |
-| `SKILLSMP_API_KEY` | Yes      | Your SkillsMP API key |
+Add to your VS Code `mcp.json` (open with: `Ctrl+Shift+P` → "MCP: Open User Configuration"):
 
-Get your API key from: https://skillsmp.com/docs/api
+```json
+{
+  "servers": {
+    "skillsmp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "skillsmp-mcp-lite"],
+      "env": {
+        "SKILLSMP_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
 
-### VS Code / Cursor Setup
+### Cursor
 
-Add to your `settings.json`:
+Add to `~/.cursor/mcp.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"
-        }
+  "mcpServers": {
+    "skillsmp": {
+      "command": "npx",
+      "args": ["-y", "skillsmp-mcp-lite"],
+      "env": {
+        "SKILLSMP_API_KEY": "YOUR_API_KEY"
       }
     }
   }
 }
 ```
 
-### Claude Desktop Setup
+### Claude Desktop
 
 Add to your `claude_desktop_config.json`:
 
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
 ```json
 {
   "mcpServers": {
     "skillsmp": {
-      "command": "node",
-      "args": ["/absolute/path/to/skillsmp-mcp-server/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "skillsmp-mcp-lite"],
       "env": {
-        "SKILLSMP_API_KEY": "sk_live_skillsmp_YOUR_API_KEY"
+        "SKILLSMP_API_KEY": "YOUR_API_KEY"
       }
     }
   }
 }
 ```
 
+### Claude Code
+
+```bash
+claude mcp add skillsmp -- npx -y skillsmp-mcp-lite --env SKILLSMP_API_KEY=YOUR_API_KEY
+```
+
+## Get Your API Key
+
+Get your API key from: https://skillsmp.com/docs/api
+
+> **Note**: The API key is optional. Without it, you may encounter rate limits.
+
 ## Available Tools
 
 ### `skillsmp_search_skills`
 
 Search for skills using keywords.
 
-**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | Search keywords |
+| `page` | number | No | Page number (default: 1) |
+| `limit` | number | No | Items per page (default: 20, max: 100) |
+| `sortBy` | string | No | Sort by "stars" or "recent" |
 
-- `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"
+### `skillsmp_ai_search_skills`
 
-**Example:**
+AI semantic search for skills using natural language.
 
-```
-Search for "PDF manipulation" skills
-```
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | Natural language description |
 
-### `skillsmp_ai_search_skills`
+### `skillsmp_install_and_read_skill`
 
-AI semantic search for skills using natural language.
+Install a skill from GitHub and immediately read its content.
 
-**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `repo` | string | Yes | GitHub repository in 'owner/repo' format |
+| `skillName` | string | Yes | Name of the skill to read after installation |
+| `global` | boolean | No | Install globally to ~/.claude/skills/ (default: false) |
+| `universal` | boolean | No | Install to .agent/skills/ for universal usage (default: false) |
 
-- `query` (string, required): Natural language description of what you want to accomplish
+## Usage Examples
 
-**Example:**
+Ask your AI assistant:
 
-```
-Find skills for "How to create a web scraper that extracts product data"
-```
+- "Search for PDF manipulation skills"
+- "Find skills for building a web scraper"
+- "What skills can help me with SEO optimization?"
+- "Install and load the python-code-review skill from existential-birds/beagle"
 
-## Usage Workflow
+## AGENTS.md Integration
 
-The recommended workflow is:
+To enable automatic skill discovery, copy the content from [`AGENTS.example.md`](./AGENTS.example.md) and paste it at the top of your `AGENTS.md` file.
 
-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
+### How It Works
 
-## API Reference
+1. AI receives a complex task
+2. AI searches SkillsMP for relevant skills using `skillsmp_search_skills`
+3. If keyword search is insufficient, AI tries `skillsmp_ai_search_skills`
+4. If a relevant skill is found, AI installs and reads it with `skillsmp_install_and_read_skill`
+5. AI follows the skill's instructions to complete the task
 
-This server uses the SkillsMP REST API:
+### Search Tips
 
-- `GET /api/v1/skills/search` - Keyword search
-- `GET /api/v1/skills/ai-search` - AI semantic search
+- **Keyword search**: Keep queries short (1-3 words). Example: `"code review"`, `"typescript"`, `"pdf"`
+- **Semantic search**: Use natural language. Example: `"how to build a landing page with React"`
 
 ## License
 

package/dist/schemas.d.ts

@@ -31,3 +31,20 @@ export declare const AISearchSchema: z.ZodObject<{
     query: string;
 }>;
 export type AISearchInput = z.infer<typeof AISearchSchema>;
+export declare const InstallAndReadSchema: z.ZodObject<{
+    repo: z.ZodString;
+    skillName: z.ZodString;
+    global: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    universal: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strict", z.ZodTypeAny, {
+    repo: string;
+    skillName: string;
+    global: boolean;
+    universal: boolean;
+}, {
+    repo: string;
+    skillName: string;
+    global?: boolean | undefined;
+    universal?: boolean | undefined;
+}>;
+export type InstallAndReadInput = z.infer<typeof InstallAndReadSchema>;

package/dist/schemas.js

@@ -36,3 +36,21 @@ export const AISearchSchema = z.object({
         .max(500, "Query must not exceed 500 characters")
         .describe("Natural language description of what you want to accomplish")
 }).strict();
+// Install and Read Skill Schema
+export const InstallAndReadSchema = z.object({
+    repo: z.string()
+        .min(1, "Repository is required")
+        .regex(/^[^/]+\/[^/]+$/, "Repository must be in 'owner/repo' format")
+        .describe("GitHub repository in 'owner/repo' format (e.g., 'existential-birds/beagle')"),
+    skillName: z.string()
+        .min(1, "Skill name is required")
+        .describe("Name of the skill to read after installation"),
+    global: z.boolean()
+        .optional()
+        .default(false)
+        .describe("Install globally to ~/.claude/skills/ (default: false, installs to project)"),
+    universal: z.boolean()
+        .optional()
+        .default(false)
+        .describe("Install to .agent/skills/ for universal AGENTS.md usage (default: false)")
+}).strict();

package/dist/tools/skills.js

@@ -1,5 +1,8 @@
+import { exec } from "child_process";
+import { promisify } from "util";
 import { makeApiRequest, handleApiError, validateSearchResponse, validateAISearchResponse } from "../api.js";
-import { KeywordSearchSchema, AISearchSchema } from "../schemas.js";
+import { KeywordSearchSchema, AISearchSchema, InstallAndReadSchema } from "../schemas.js";
+const execAsync = promisify(exec);
 /**
  * Register SkillsMP tools on the MCP server
  */
@@ -144,6 +147,115 @@ Examples:
             };
         }
     });
+    // Tool 3: Install and Read Skill
+    server.registerTool("skillsmp_install_and_read_skill", {
+        title: "Install and Read Skill",
+        description: `Install a skill from GitHub and immediately read its content.
+
+This tool first checks if the skill is already installed locally. If found, it skips installation and directly reads the content (faster). If not found, it installs from GitHub first.
+
+**IMPORTANT**: Use this to quickly load skill instructions without manual steps.
+
+Args:
+  - repo (string, required): GitHub repository in 'owner/repo' format
+  - skillName (string, required): Name of the skill to read after installation
+  - global (boolean, optional): Install globally to ~/.claude/skills/ (default: false)
+  - universal (boolean, optional): Install to .agent/skills/ for universal usage (default: false)
+
+Returns:
+  The full content of the skill's instructions (SKILL.md).
+
+Examples:
+  - repo: "existential-birds/beagle", skillName: "python-code-review"
+  - repo: "LA3D/skillhelper", skillName: "code-reviewer"`,
+        inputSchema: InstallAndReadSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            const readCmd = `npx -y openskills read ${params.skillName}`;
+            // Step 1: Check if skill already exists locally
+            let skillExists = false;
+            try {
+                const { stdout } = await execAsync(readCmd, { timeout: 30000 });
+                if (stdout && !stdout.includes("not found") && !stdout.includes("Error")) {
+                    skillExists = true;
+                    const output = formatInstallAndReadResponse(params.repo, params.skillName, stdout, true);
+                    return {
+                        content: [{ type: "text", text: output }],
+                        structuredContent: {
+                            repo: params.repo,
+                            skillName: params.skillName,
+                            skillContent: stdout,
+                            wasAlreadyInstalled: true
+                        }
+                    };
+                }
+            }
+            catch {
+                // Skill not found locally, proceed with installation
+                skillExists = false;
+            }
+            // Step 2: Install if not exists
+            const installFlags = ["-y"];
+            if (params.global)
+                installFlags.push("--global");
+            if (params.universal)
+                installFlags.push("--universal");
+            const installCmd = `npx -y openskills install ${params.repo} ${installFlags.join(" ")}`;
+            let installOutput;
+            try {
+                const { stdout, stderr } = await execAsync(installCmd, { timeout: 120000 });
+                installOutput = stdout || stderr;
+            }
+            catch (installError) {
+                const error = installError;
+                return {
+                    content: [{
+                            type: "text",
+                            text: `❌ **Installation Failed**\n\nRepository: ${params.repo}\n\nError:\n${error.stderr || error.message || "Unknown error"}`
+                        }]
+                };
+            }
+            // Step 3: Read the skill after installation
+            let readOutput;
+            try {
+                const { stdout, stderr } = await execAsync(readCmd, { timeout: 30000 });
+                readOutput = stdout || stderr;
+            }
+            catch (readError) {
+                const error = readError;
+                return {
+                    content: [{
+                            type: "text",
+                            text: `✅ **Installation Succeeded** but **Read Failed**\n\nRepository: ${params.repo}\nSkill: ${params.skillName}\n\n**Install Output:**\n${installOutput}\n\n**Read Error:**\n${error.stderr || error.message || "Skill not found"}\n\n💡 **Tip**: Check if the skill name is correct. Use \`npx openskills list\` to see installed skills.`
+                        }]
+                };
+            }
+            const output = formatInstallAndReadResponse(params.repo, params.skillName, readOutput, false);
+            return {
+                content: [{ type: "text", text: output }],
+                structuredContent: {
+                    repo: params.repo,
+                    skillName: params.skillName,
+                    skillContent: readOutput,
+                    wasAlreadyInstalled: false
+                }
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `❌ **Error**: ${error instanceof Error ? error.message : "An unexpected error occurred"}`
+                    }]
+            };
+        }
+    });
 }
 /**
  * Render a single skill as markdown lines
@@ -205,6 +317,24 @@ function formatAISearchResponse(skills, query) {
         ""
     ];
     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.");
+    lines.push("💡 **Tip**: Use `skillsmp_install_and_read_skill` to install and load a skill's instructions.");
+    return lines.join("\n");
+}
+/**
+ * Format install and read response as markdown
+ */
+function formatInstallAndReadResponse(repo, skillName, skillContent, wasAlreadyInstalled) {
+    const statusIcon = wasAlreadyInstalled ? "📖" : "📦";
+    const statusText = wasAlreadyInstalled ? "Skill Loaded (already installed)" : "Skill Installed & Loaded";
+    const lines = [
+        `# ${statusIcon} ${statusText}: ${skillName}`,
+        "",
+        `**Repository**: ${repo}`,
+        wasAlreadyInstalled ? "**Status**: ⚡ Loaded from local cache (skipped installation)" : "**Status**: ✅ Freshly installed",
+        "",
+        "---",
+        "",
+        skillContent
+    ];
     return lines.join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillsmp-mcp-lite",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Lightweight MCP server for searching AI skills from SkillsMP before starting any task",
   "type": "module",
   "main": "dist/index.js",