Superpowers MCP Server

Instructions

Implementation Reference

• superpowers-mcp.js:220-254 (handler)

  The handler for the 'find_skills' tool within the CallToolRequestSchema request handler. It discovers skills in personal and superpowers directories using findSkillsInDir, formats a list, and returns it as text content.

  if (name === 'find_skills') {
    const personalSkills = findSkillsInDir(personalSkillsDir, 'personal', 3);
    const superpowersSkills = findSkillsInDir(superpowersSkillsDir, 'superpowers', 3);
  
    const allSkills = [...personalSkills, ...superpowersSkills];
  
    if (allSkills.length === 0) {
      return {
        content: [{
          type: 'text',
          text: 'No skills found. Install superpowers skills to ~/.augment/superpowers/skills/ or add personal skills to ~/.augment/skills/'
        }]
      };
    }
  
    let output = 'Available skills:\n\n';
  
    for (const skill of allSkills) {
      const namespace = skill.sourceType === 'personal' ? '' : 'superpowers:';
      const skillName = skill.name || path.basename(skill.path);
  
      output += `${namespace}${skillName}\n`;
      if (skill.description) {
        output += `  ${skill.description}\n`;
      }
      output += `  Directory: ${skill.path}\n\n`;
    }
  
    return {
      content: [{
        type: 'text',
        text: output
      }]
    };
  }

• superpowers-mcp.js:188-196 (registration)

  Registration of the 'find_skills' tool in the tools list returned by ListToolsRequestSchema handler, including its description and input schema (no parameters required).

  {
    name: 'find_skills',
    description: 'List all available skills in the personal and superpowers skill libraries.',
    inputSchema: {
      type: 'object',
      properties: {},
      required: []
    }
  },

• superpowers-mcp.js:95-129 (helper)

  Helper function used by the 'find_skills' handler to recursively scan directories for SKILL.md files, extract frontmatter metadata, and collect skill information.

  function findSkillsInDir(dir, sourceType, maxDepth = 3) {
    const skills = [];
  
    if (!fs.existsSync(dir)) return skills;
  
    function recurse(currentDir, depth) {
      if (depth > maxDepth) return;
  
      const entries = fs.readdirSync(currentDir, { withFileTypes: true });
  
      for (const entry of entries) {
        const fullPath = path.join(currentDir, entry.name);
  
        if (entry.isDirectory()) {
          const skillFile = path.join(fullPath, 'SKILL.md');
          if (fs.existsSync(skillFile)) {
            const { name, description } = extractFrontmatter(skillFile);
            skills.push({
              path: fullPath,
              skillFile: skillFile,
              name: name || entry.name,
              description: description || '',
              sourceType: sourceType,
              dirName: entry.name
            });
          }
  
          recurse(fullPath, depth + 1);
        }
      }
    }
  
    recurse(dir, 0);
    return skills;
  }