superskills-mcp

Una pasarela MCP de propósito general que expone tus habilidades de CLI locales a cualquier asistente de IA. Cualquier cliente MCP (ChatGPT, Claude Desktop, Cursor, etc.) puede conectarse a ella e invocar tus scripts locales como herramientas inteligentes.

read_x_to_markdown({ url })   ← registered automatically from config
my_custom_skill({ ... })      ← just add to skills array, zero code change

1. Inicio rápido (Instalación global)

Instala la herramienta CLI globalmente en tu sistema:

npm install -g .
# Or via pnpm: pnpm link --global

Inicializa tu archivo de configuración (crea ~/.superskills/mcp-config.json):

superskills-mcp init

Inicia el servidor:

superskills-mcp serve
# To run in the background: superskills-mcp serve &

Lista las habilidades registradas:

superskills-mcp list

Detén el servidor:

superskills-mcp stop

Related MCP server: local-skills-mcp

2. Registra tus habilidades

Abre ~/.superskills/mcp-config.json. Para añadir una nueva habilidad, añade un bloque JSON a la matriz skills — no se necesitan cambios en el código.

{
  "server": {
    "name": "superskills-mcp",
    "version": "0.4.0",
    "transport": "http",
    "host": "127.0.0.1",
    "port": 8787
  },
  "defaults": {
    "timeoutMs": 120000,
    "maxOutputBytes": 10485760,
    "runner": {
      "command": "bun",
      "args": ["{serverDir}/scripts/mcp-adapter.ts"]
    }
  },
  "skills": [
    {
      "name": "read_x_to_markdown",
      "description": "Read a given X/Twitter link and return clean Markdown.",
      "skillDir": "/Users/wenli/.baoyu-skills/skills/baoyu-danger-x-to-markdown",
      "input": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "X/Twitter post URL to read"
        }
      },
      "env": {
        "BAOYU_X_TO_MARKDOWN_DOWNLOAD_MEDIA": "true",
        "BAOYU_X_TO_MARKDOWN_KEEP_OUTPUT": "false"
      }
    }
  ]
}

Explicación de los campos de configuración

Añadir una nueva habilidad

1. Añade una nueva entrada a skills[] en ~/.superskills/mcp-config.json

2. Reinicia el servidor (superskills-mcp serve)

3. La nueva herramienta estará disponible automáticamente para todos los clientes MCP conectados

3. Conectar a ChatGPT (Transporte HTTP)

Para ChatGPT o cualquier cliente MCP remoto, el servidor debe estar ejecutándose en modo HTTP (que es el predeterminado).

superskills-mcp serve

Verifica que se esté ejecutando:

curl http://127.0.0.1:8787/health
# → {"ok":true,"name":"superskills-mcp","version":"0.4.0","tools":["read_x_to_markdown"]}

Exponer a ChatGPT mediante Ngrok

Ngrok proporciona un dominio estático gratuito que es ideal para conexiones persistentes al servidor MCP. Puedes obtener tu dominio estático gratuito desde tu panel de control de Ngrok.

ngrok http --domain=your-free-static-domain.ngrok-free.app 8787

Copia la URL https://your-free-static-domain.ngrok-free.app/mcp y pégala en la configuración del conector MCP de ChatGPT.

4. Conectar a Claude Desktop / Cursor (Transporte Stdio)

Para clientes MCP locales como Claude Desktop o Cursor, estos iniciarán el proceso usando stdio.

Ejemplo de configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "superskills-mcp": {
      "command": "superskills-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

5. Seguridad

• skillDir debe existir y ser un directorio (validado al inicio)

• Los scripts de ejecución deben estar dentro de serverDir (adaptador integrado) o skillDir (scripts propios de la habilidad)

• shell: false — sin inyección de shell

• Límites de tiempo de espera y tamaño de salida aplicados por habilidad

• No expongas el transporte HTTP públicamente sin un proxy inverso o una capa de autenticación