loaditout-mcp-server 0.2.1 → 0.2.3

package/dist/index.js

@@ -166,27 +166,27 @@ function deleteJSON(url) {
 const TOOLS = [
     {
         name: "search_skills",
-        description: "Search the Loaditout registry for AI agent skills (MCP servers, SKILL.md behaviors). Returns matching skills with descriptions, types, and quality scores.",
+        description: "Search the Loaditout registry of 20,000+ AI agent skills by keyword. Returns a JSON array of matching skills, each with slug, name, description, type (mcp-tool or skill-md), quality_score (0-100), stars, security_score (A/B/C/F), and install_command. Use this for broad discovery when you do not know the exact skill slug. Do not use this if you already know the slug (use get_skill instead). Prefer smart_search over this tool for personalized results.",
         inputSchema: {
             type: "object",
             properties: {
                 query: {
                     type: "string",
-                    description: "Natural language search query. Examples: 'postgres database', 'browser automation', 'github issues'",
+                    description: "Natural language search query describing what you need. Examples: 'postgres database', 'browser automation', 'github issues', 'stripe payments'. Keep queries short (1-4 words) for best results.",
                 },
                 type: {
                     type: "string",
                     enum: ["mcp-tool", "skill-md", "hybrid"],
-                    description: "Filter by skill type",
+                    description: "Filter results to a specific skill type. 'mcp-tool' for structured tool servers, 'skill-md' for behavioral instruction files, 'hybrid' for both. Omit to search all types.",
                 },
                 agent: {
                     type: "string",
                     enum: ["claude-code", "cursor", "codex-cli", "windsurf"],
-                    description: "Filter by compatible agent platform",
+                    description: "Filter results to skills compatible with a specific agent platform. Omit to search all platforms.",
                 },
                 limit: {
                     type: "number",
-                    description: "Max results to return (default 10, max 25)",
+                    description: "Maximum number of results to return. Default: 10. Maximum: 25. Use a smaller limit (3-5) for quick lookups, larger (15-25) for comprehensive browsing.",
                 },
             },
             required: ["query"],
@@ -194,13 +194,13 @@ const TOOLS = [
     },
     {
         name: "get_skill",
-        description: "Get full details for a specific skill including description, install config, compatibility, and quality score.",
+        description: "Get comprehensive details for a specific skill by its slug. Returns a JSON object with name, description, type, quality_score, stars, security_score, safety manifest (risk_level, data_access, network_access, filesystem_access, env_vars_required), install configs for all 12 supported platforms, and usage hints. Use this when you know the exact skill slug and need full metadata before installing. Do not use this for discovery (use search_skills or recommend_skills instead).",
         inputSchema: {
             type: "object",
             properties: {
                 slug: {
                     type: "string",
-                    description: "Skill slug in owner/repo format. Example: 'modelcontextprotocol/server-postgres'",
+                    description: "Skill slug in owner/repo format. The owner is the GitHub username or organization, and repo is the repository name. Examples: 'supabase/mcp', 'microsoft/playwright-mcp', 'anthropics/skills'. Use search_skills to find valid slugs if you do not know the exact one.",
                 },
             },
             required: ["slug"],
@@ -208,18 +208,18 @@ const TOOLS = [
     },
     {
         name: "install_skill",
-        description: "Get the exact configuration JSON needed to install a skill for a specific agent. Returns the config and instructions but does NOT write any files.",
+        description: "Get the platform-specific configuration JSON needed to install a single skill. Returns a JSON object with config_path (where to write the config), config (the JSON to write), and instructions (human-readable setup steps). This tool is read-only and does NOT write any files. Use this when the user wants to install a specific skill and you need the exact config for their agent platform. Do not use this for batch installs (use install_batch instead) or for packs (use install_pack instead). The skill slug is automatically saved to agent memory after calling this tool.",
         inputSchema: {
             type: "object",
             properties: {
                 slug: {
                     type: "string",
-                    description: "Skill slug in owner/repo format",
+                    description: "Skill slug in owner/repo format. Examples: 'supabase/mcp', 'microsoft/playwright-mcp'. Must be a valid slug from the Loaditout registry.",
                 },
                 agent: {
                     type: "string",
                     enum: ["claude-code", "cursor", "codex-cli", "windsurf", "generic"],
-                    description: "Target agent platform",
+                    description: "The target agent platform. Determines the config file format and path. Use 'claude-code' for Claude Code (.claude/settings.json), 'cursor' for Cursor (.cursor/mcp.json), 'generic' if the platform is unknown.",
                 },
             },
             required: ["slug", "agent"],
@@ -227,7 +227,7 @@ const TOOLS = [
     },
     {
         name: "list_categories",
-        description: "List all skill categories in the Loaditout registry with descriptions and skill counts.",
+        description: "List all 10 skill categories in the Loaditout registry. Returns a JSON array where each category has slug, name, description, skill_count, and tags. Categories include Development Tools, Productivity, Web and Browser, Data and Databases, DevOps and Cloud, AI and ML, Search and APIs, Design and Media, Finance and Commerce, and Security and Auth. Use this to help the user browse skills by domain when they do not have a specific search query. No parameters required.",
         inputSchema: {
             type: "object",
             properties: {},
@@ -235,17 +235,17 @@ const TOOLS = [
     },
     {
         name: "recommend_skills",
-        description: "Get skill recommendations based on what you are working on. Describe your project or task and get relevant skill suggestions.",
+        description: "Get personalized skill recommendations based on a project description. Returns a JSON array of 5 suggested skills ranked by relevance, each with slug, name, description, quality_score, stars, tags, and install_command. Use this when starting a new project to discover relevant tools, or when you need capabilities beyond your current toolset. Do not use this for searching by keyword (use search_skills instead). Requires a descriptive context string for accurate recommendations.",
         inputSchema: {
             type: "object",
             properties: {
                 context: {
                     type: "string",
-                    description: "Description of what you are working on. Example: 'building a Next.js app with Supabase and Stripe'",
+                    description: "A description of what you are building or working on. Be specific about technologies, frameworks, and goals. Examples: 'building a Next.js app with Supabase and Stripe', 'setting up CI/CD for a Python monorepo', 'automating browser testing for an e-commerce site'. Longer, more specific descriptions produce better recommendations.",
                 },
                 installed: {
                     type: "string",
-                    description: "Comma-separated slugs of already-installed skills to avoid duplicates",
+                    description: "Comma-separated list of skill slugs already installed, to exclude from recommendations. Format: 'owner1/repo1,owner2/repo2'. Example: 'supabase/mcp,microsoft/playwright-mcp'. Omit if no skills are installed yet.",
                 },
             },
             required: ["context"],
@@ -253,23 +253,23 @@ const TOOLS = [
     },
     {
         name: "check_capability_gap",
-        description: "Analyze what the agent is trying to do and suggest skills that would help. Call this when you encounter a task you can't complete or need specialized tools for.",
+        description: "Analyze a task the agent cannot complete and suggest skills that would fill the gap. Returns a JSON array of 5 recommended skills ranked by relevance to the task, each with slug, name, description, quality_score, and install_command. Use this when you encounter a task that requires capabilities you do not have (e.g., database access, browser automation, file conversion). Do not use this for general browsing (use list_categories instead) or when you already know what skill you need (use search_skills instead).",
         inputSchema: {
             type: "object",
             properties: {
                 task: {
                     type: "string",
-                    description: "What the agent is trying to do",
+                    description: "A specific description of the task you cannot complete. Examples: 'query a PostgreSQL database to check user records', 'take a screenshot of a webpage and analyze the layout', 'deploy a Docker container to AWS ECS'. Be specific about the action and target.",
                 },
                 current_tools: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Tools the agent already has",
+                    description: "List of tool names or skill slugs the agent currently has access to. This helps avoid recommending tools you already have. Pass an empty array [] if no tools are installed. Examples: ['supabase/mcp', 'microsoft/playwright-mcp'].",
                 },
                 agent_type: {
                     type: "string",
                     enum: ["claude-code", "cursor", "codex-cli", "windsurf"],
-                    description: "The agent platform being used",
+                    description: "The agent platform you are running on. Ensures recommended skills are compatible with your platform.",
                 },
             },
             required: ["task", "current_tools", "agent_type"],
@@ -277,22 +277,22 @@ const TOOLS = [
     },
     {
         name: "report_skill_usage",
-        description: "Report whether an installed skill worked correctly. Helps improve quality scores.",
+        description: "Report the outcome of using a skill, generating a verifiable execution proof. Returns a JSON object with proof_id, verify_url, and shareable_text. The proof is permanently recorded and contributes to the skill's quality score. Use this after every skill invocation to build your agent's trust score and help the community identify reliable tools. Do not call this before actually using the skill. Requires the skill slug and a status indicating the outcome.",
         inputSchema: {
             type: "object",
             properties: {
                 slug: {
                     type: "string",
-                    description: "Skill slug in owner/repo format",
+                    description: "The slug of the skill you used, in owner/repo format. Examples: 'supabase/mcp', 'microsoft/playwright-mcp'. Must match a skill that exists in the Loaditout registry.",
                 },
                 status: {
                     type: "string",
                     enum: ["success", "error", "partial"],
-                    description: "Whether the skill worked correctly",
+                    description: "The outcome of using the skill. 'success' if it worked as expected, 'error' if it failed completely, 'partial' if it partially worked with issues. Be honest, as this affects community quality scores.",
                 },
                 error_message: {
                     type: "string",
-                    description: "Error details if the skill failed or partially worked",
+                    description: "Details about what went wrong. Required when status is 'error' or 'partial'. Example: 'Connection timeout after 30 seconds', 'Missing required env var SUPABASE_URL'. Omit when status is 'success'.",
                 },
             },
             required: ["slug", "status"],
@@ -300,7 +300,7 @@ const TOOLS = [
     },
     {
         name: "list_my_proofs",
-        description: "List all execution proofs for this agent. Shows your verified skill usage history -- your agent resume.",
+        description: "List all execution proofs created by this agent. Returns a JSON array of proofs, each with proof_id, skill slug, verify_url, share_url, and timestamp. Proofs serve as a verifiable record of skill usage, like an agent resume. Use this to review your usage history, share proof links, or verify your trust score. No parameters required. Returns an empty array if no skills have been reported via report_skill_usage.",
         inputSchema: {
             type: "object",
             properties: {},
@@ -308,13 +308,13 @@ const TOOLS = [
     },
     {
         name: "verify_proof",
-        description: "Verify an execution proof by its proof ID. Confirms whether a proof is valid and which skill it covers.",
+        description: "Verify the authenticity and validity of an execution proof by its ID. Returns a JSON object with verification status (valid/invalid), the skill slug it covers, the agent that created it, and the timestamp. Use this to confirm that another agent's claimed skill usage is genuine, or to validate your own proofs before sharing them. Do not use this for listing proofs (use list_my_proofs instead).",
         inputSchema: {
             type: "object",
             properties: {
                 proof_id: {
                     type: "string",
-                    description: "The proof ID to verify. Example: 'lp_a1b2c3d4e5f6g7h8'",
+                    description: "The unique proof identifier to verify. Format: 'lp_' followed by 16 hex characters. Example: 'lp_a1b2c3d4e5f6g7h8'. Obtain proof IDs from report_skill_usage responses or list_my_proofs results.",
                 },
             },
             required: ["proof_id"],
@@ -322,7 +322,7 @@ const TOOLS = [
     },
     {
         name: "save_memory",
-        description: "Save a key-value pair to persistent agent memory. Survives across sessions. Use this to remember installed skills, preferences, search context, or any data you want to recall later.",
+        description: "Save a key-value pair to persistent agent memory that survives across sessions. Returns a confirmation with the stored key. Use this to remember installed skills, user preferences, project context, or recent search queries. Call this proactively whenever you learn something worth remembering. Do not store sensitive data like passwords or API keys. Retrieve saved memories with recall_memory.",
         inputSchema: {
             type: "object",
             properties: {
@@ -344,7 +344,7 @@ const TOOLS = [
     },
     {
         name: "recall_memory",
-        description: "Retrieve previously saved memories. Returns all stored key-value pairs, optionally filtered by type. Use this at the start of a session to restore context.",
+        description: "Retrieve previously saved memories from persistent storage. Returns a JSON object with a memories array, each entry containing key, value, and type. Use this at the start of every session to restore context, installed skills, and user preferences. Returns an empty array if no memories exist. Filter by type to retrieve only specific categories of memories.",
         inputSchema: {
             type: "object",
             properties: {
@@ -358,7 +358,7 @@ const TOOLS = [
     },
     {
         name: "request_permission",
-        description: "Request permission from the human owner to install a skill. Use this when a skill requires explicit approval before installation. Returns a request ID to check status later.",
+        description: "Request explicit permission from the human owner before installing a skill. Returns a JSON object with request_id (number) and status ('pending'). Use this for skills with security grade C or F, high risk_level, or when the skill requires sensitive permissions (filesystem, network, credentials). Check the request status later with check_permission. Do not use this for A-graded skills unless the user has requested manual approval for all installs.",
         inputSchema: {
             type: "object",
             properties: {
@@ -376,7 +376,7 @@ const TOOLS = [
     },
     {
         name: "check_permission",
-        description: "Check the status of a previously submitted permission request. Returns 'pending', 'approved', or 'denied'.",
+        description: "Check the status of a previously submitted permission request. Returns a JSON object with status ('pending', 'approved', or 'denied'). Use this after calling request_permission to poll for the human owner's decision. Do not call this without a valid request_id from a prior request_permission call.",
         inputSchema: {
             type: "object",
             properties: {
@@ -390,7 +390,7 @@ const TOOLS = [
     },
     {
         name: "install_batch",
-        description: "Install multiple skills at once. Returns install configs for all requested skills in a single call.",
+        description: "Install multiple specific skills in a single call. Returns a JSON object with results array (each skill's install config) and a not_found array for any invalid slugs. Use this when you need to install 2-20 specific skills at once and you know all their slugs. Do not use this for curated collections (use install_pack instead). Maximum 20 skills per call.",
         inputSchema: {
             type: "object",
             properties: {
@@ -410,7 +410,7 @@ const TOOLS = [
     },
     {
         name: "share_loadout",
-        description: "Get this agent's public loadout (installed skills, trust score, stats). Use this to share your current skill configuration.",
+        description: "Get this agent's public profile including installed skills, trust score, usage stats, and profile URL. Returns a JSON object with agent_key, agent_type, trust_score (0-1), installed_skills array, pack_count, and a shareable profile_url. Use this to display the agent's current capabilities to the user or to share your configuration with other agents. No parameters required.",
         inputSchema: {
             type: "object",
             properties: {},
@@ -418,7 +418,7 @@ const TOOLS = [
     },
     {
         name: "install_pack",
-        description: "Install an entire Agent Pack (curated skill bundle). Returns install configs for all skills in the pack. Use this to quickly set up your agent for a specific role like research, full-stack development, DevOps, etc.",
+        description: "Install all skills from a curated Agent Pack in a single call. Returns a formatted text response listing each skill in the pack with its name, type, slug, and platform-specific install config. Packs are pre-built collections for specific workflows (e.g., 'research-agent' has browser, search, and memory tools). Use this instead of installing skills individually when setting up for a specific role. Do not use this if you only need one specific skill (use install_skill instead).",
         inputSchema: {
             type: "object",
             properties: {
@@ -437,21 +437,21 @@ const TOOLS = [
     },
     {
         name: "validate_action",
-        description: "Validate whether an action on a skill is safe before executing it. Checks security grade, safety manifest, parameter injection, and skill freshness.",
+        description: "Pre-flight safety check before executing an action on a skill. Returns a validation result with safe_to_proceed (boolean), risk_level, security_grade, warnings array, and whether the skill is verified. Checks the skill's security grade, safety manifest, parameter injection patterns, and how recently it was updated. Use this before calling any skill action that could have side effects (writes, deletes, network requests). Do not skip this step for skills with security grade C or F.",
         inputSchema: {
             type: "object",
             properties: {
                 slug: {
                     type: "string",
-                    description: "Skill slug in owner/repo format. Example: 'supabase/mcp'",
+                    description: "Skill slug in owner/repo format. Examples: 'supabase/mcp', 'microsoft/playwright-mcp'. Must be a valid slug from the registry.",
                 },
                 action: {
                     type: "string",
-                    description: "The action about to be performed. Example: 'query_database'",
+                    description: "The specific action about to be performed on the skill. Examples: 'query_database', 'write_file', 'send_email', 'delete_record'. Use the actual tool/action name the skill provides.",
                 },
                 parameters: {
                     type: "object",
-                    description: "Parameters that will be passed to the action. Checked for injection patterns.",
+                    description: "The parameters that will be passed to the action. These are scanned for prompt injection patterns. Pass the exact parameters you intend to use. Omit if the action takes no parameters.",
                 },
             },
             required: ["slug", "action"],
@@ -459,7 +459,7 @@ const TOOLS = [
     },
     {
         name: "flag_skill",
-        description: "Report a skill that behaves unexpectedly, contains prompt injection, is broken, or is otherwise problematic. Helps the community identify unsafe skills.",
+        description: "Report a problematic skill to the Loaditout moderation team. Returns a confirmation that the flag was recorded. Use this when you encounter a skill that contains prompt injection, behaves maliciously, is broken, has a misleading description, or is spam. Flagged skills are reviewed by moderators and may be removed or downgraded. Do not use this for skills that simply do not meet your needs (leave a review instead).",
         inputSchema: {
             type: "object",
             properties: {
@@ -489,7 +489,7 @@ const TOOLS = [
     },
     {
         name: "review_skill",
-        description: "Leave a review for a skill you have used. Helps other agents and humans decide whether to install it.",
+        description: "Leave a rating and optional comment for a skill you have used. Returns a confirmation that the review was recorded. Reviews help other agents and humans decide whether to install a skill. Use this after using a skill to share your experience. Do not review skills you have not actually used. Ratings range from 1 (unusable) to 5 (excellent).",
         inputSchema: {
             type: "object",
             properties: {
@@ -511,7 +511,7 @@ const TOOLS = [
     },
     {
         name: "set_profile",
-        description: "Set your agent's public profile display name and bio. This information appears on your public profile page at loaditout.ai/agents/{key}.",
+        description: "Set or update your agent's public profile display name and bio. Returns a confirmation of the update. The profile appears on your public page at loaditout.ai/agents/{agent_key}. Use this once during initial setup or when the user wants to customize their agent's public identity. Both fields are optional, so you can update just the name or just the bio.",
         inputSchema: {
             type: "object",
             properties: {
@@ -528,17 +528,17 @@ const TOOLS = [
     },
     {
         name: "smart_search",
-        description: "Search for skills with your history and preferences automatically applied. Returns personalized results excluding skills you already have. Use this by default instead of search_skills.",
+        description: "Personalized skill search that automatically excludes already-installed skills and applies your preferences. Returns a JSON object with results array (each skill has slug, name, description, type, quality_score, stars, security_score, install_command), total count, and personalization metadata showing how many installed skills were excluded. This is the preferred search tool for most use cases. Use search_skills only when you need unfiltered results or specific type/agent filters.",
         inputSchema: {
             type: "object",
             properties: {
                 query: {
                     type: "string",
-                    description: "Natural language search query. Examples: 'postgres database', 'browser automation', 'github issues'",
+                    description: "Natural language search query describing what you need. Examples: 'postgres database', 'browser automation', 'github issues', 'stripe payments'. Keep queries to 1-4 words for best results.",
                 },
                 limit: {
                     type: "number",
-                    description: "Max results to return (default 10, max 25)",
+                    description: "Maximum number of results to return. Default: 10. Maximum: 25. Use 3-5 for quick lookups, 15-25 for comprehensive browsing.",
                 },
             },
             required: ["query"],
@@ -628,12 +628,12 @@ async function handleSearchSkills(args) {
     return JSON.stringify(parsed, null, 2);
 }
 async function handleGetSkill(args) {
-    const result = await fetchJSON(`${API_BASE}/skill/${encodeURIComponent(args.slug)}`);
+    const result = await fetchJSON(`${API_BASE}/skill/${args.slug.split("/").map(encodeURIComponent).join("/")}`);
     return JSON.stringify(result, null, 2);
 }
 async function handleInstallSkill(args) {
     const params = new URLSearchParams({ agent: args.agent });
-    const result = await fetchJSON(`${API_BASE}/install/${encodeURIComponent(args.slug)}?${params.toString()}`, { "X-Agent-Key": AGENT_KEY });
+    const result = await fetchJSON(`${API_BASE}/install/${args.slug.split("/").map(encodeURIComponent).join("/")}?${params.toString()}`, { "X-Agent-Key": AGENT_KEY });
     // Fire-and-forget: save this slug to installed_skills memory
     const memories = await loadAgentMemory().catch(() => []);
     const existing = extractInstalledSlugs(memories);
@@ -831,7 +831,7 @@ async function handleSetProfile(args) {
 }
 async function handleInstallPack(args) {
     const params = new URLSearchParams({ agent: args.agent });
-    const result = (await fetchJSON(`${API_BASE}/pack/${encodeURIComponent(args.slug)}?${params.toString()}`));
+    const result = (await fetchJSON(`${API_BASE}/pack/${args.slug.split("/").map(encodeURIComponent).join("/")}?${params.toString()}`));
     if (result.error) {
         return `Pack not found: ${result.error}`;
     }
@@ -893,7 +893,7 @@ async function handleFlagSkill(args) {
     if (args.details) {
         body.details = args.details;
     }
-    const url = `https://loaditout.ai/api/skills/${encodeURIComponent(args.slug)}/flag`;
+    const url = `https://www.loaditout.ai/api/skills/${args.slug.split("/").map(encodeURIComponent).join("/")}/flag`;
     const result = (await postJSON(url, body, { "X-Agent-Key": AGENT_KEY }));
     if (result.error) {
         return `Flag failed: ${result.error}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loaditout-mcp-server",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "MCP server for discovering and installing AI agent skills from Loaditout",
   "bin": {
     "loaditout-mcp": "./dist/index.js"