skillsmp-mcp-lite 1.0.1 → 1.0.3

package/README.md

@@ -102,6 +102,17 @@ AI semantic search for skills using natural language.
 |-----------|------|----------|-------------|
 | `query` | string | Yes | Natural language description |
 
+### `skillsmp_install_and_read_skill`
+
+Install a skill from GitHub and immediately read its content.
+
+| 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) |
+
 ## Usage Examples
 
 Ask your AI assistant:
@@ -109,6 +120,24 @@ Ask your AI assistant:
 - "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"
+
+## AGENTS.md Integration
+
+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.
+
+### How It Works
+
+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
+
+### Search Tips
+
+- **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/api.d.ts

@@ -2,6 +2,7 @@
  * SkillsMP API Client and Types
  */
 export declare const SKILLSMP_API_BASE = "https://skillsmp.com/api/v1";
+export declare const API_TIMEOUT_MS = 30000;
 export interface Skill {
     id: string;
     name: string;

package/dist/api.js

@@ -3,6 +3,7 @@
  */
 // API Configuration
 export const SKILLSMP_API_BASE = "https://skillsmp.com/api/v1";
+export const API_TIMEOUT_MS = 30_000;
 // API Client
 export async function makeApiRequest(endpoint, apiKey, params) {
     const url = new URL(`${SKILLSMP_API_BASE}/${endpoint}`);
@@ -13,13 +14,22 @@ export async function makeApiRequest(endpoint, apiKey, params) {
             }
         });
     }
-    const response = await fetch(url.toString(), {
-        method: "GET",
-        headers: {
-            "Authorization": `Bearer ${apiKey}`,
-            "Content-Type": "application/json"
-        }
-    });
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), API_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetch(url.toString(), {
+            method: "GET",
+            headers: {
+                "Authorization": `Bearer ${apiKey}`,
+                "Content-Type": "application/json"
+            },
+            signal: controller.signal
+        });
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
     if (!response.ok) {
         const errorData = await response.json().catch(() => ({}));
         throw new Error(errorData.error?.message ||

package/dist/index.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRequire } from "module";
 import { registerSkillsTools } from "./tools/skills.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
 /**
  * SkillsMP MCP Server
  *
@@ -20,7 +23,7 @@ if (!API_KEY) {
 // Initialize MCP Server
 const server = new McpServer({
     name: "skillsmp-mcp-server",
-    version: "1.0.0"
+    version: version
 });
 // Register skills search tools
 registerSkillsTools(server, API_KEY);

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,33 @@
+import { execFile } 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 execFileAsync = promisify(execFile);
+// Timeout constants (in milliseconds)
+const TIMEOUTS = {
+    READ: 30_000,
+    INSTALL: 120_000
+};
+/**
+ * Safely extract error message from unknown error type
+ */
+function getErrorDetails(error) {
+    if (error instanceof Error) {
+        const execError = error;
+        return {
+            message: execError.message,
+            stderr: execError.stderr
+        };
+    }
+    if (typeof error === 'object' && error !== null) {
+        const e = error;
+        return {
+            message: String(e.message || 'Unknown error'),
+            stderr: typeof e.stderr === 'string' ? e.stderr : undefined
+        };
+    }
+    return { message: String(error) };
+}
 /**
  * Register SkillsMP tools on the MCP server
  */
@@ -144,6 +172,111 @@ 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 readArgs = ["-y", "openskills", "read", params.skillName];
+            // Step 1: Check if skill already exists locally
+            try {
+                const { stdout } = await execFileAsync("npx", readArgs, { timeout: TIMEOUTS.READ });
+                if (stdout && !stdout.includes("not found") && !stdout.includes("Error")) {
+                    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
+            }
+            // Step 2: Install if not exists
+            const installArgs = ["-y", "openskills", "install", params.repo];
+            if (params.global)
+                installArgs.push("--global");
+            if (params.universal)
+                installArgs.push("--universal");
+            let installOutput;
+            try {
+                const { stdout, stderr } = await execFileAsync("npx", installArgs, { timeout: TIMEOUTS.INSTALL });
+                installOutput = stdout || stderr;
+            }
+            catch (installError) {
+                const errorDetails = getErrorDetails(installError);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `❌ **Installation Failed**\n\nRepository: ${params.repo}\n\nError:\n${errorDetails.stderr || errorDetails.message}`
+                        }]
+                };
+            }
+            // Step 3: Read the skill after installation
+            let readOutput;
+            try {
+                const { stdout, stderr } = await execFileAsync("npx", readArgs, { timeout: TIMEOUTS.READ });
+                readOutput = stdout || stderr;
+            }
+            catch (readError) {
+                const errorDetails = getErrorDetails(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${errorDetails.stderr || errorDetails.message}\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 +338,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.1",
+  "version": "1.0.3",
   "description": "Lightweight MCP server for searching AI skills from SkillsMP before starting any task",
   "type": "module",
   "main": "dist/index.js",