MCP Skills

Un framework CLI/Agente ligero, robusto y desacoplado que demuestra la divulgación progresiva de habilidades de agente sobre el Protocolo de Contexto de Modelo (MCP).

Este proyecto implementa un bucle agéntico local completo que se comunica con un servidor MCP backend mediante transporte stdio. Permite al agente descubrir herramientas y obtener instrucciones complejas (habilidades) de forma dinámica y bajo demanda solo cuando son relevantes.

🗺️ Mapa de la Bóveda de Obsidian

Navega rápidamente por la documentación dentro de Obsidian:

• 🏠 Inicio (README): [[README]]

• 📖 Guía para principiantes: [[LAYMAN_GUIDE|Una guía para principiantes sobre MCP Skills]]

• ⚙️ Flujo del sistema y recorrido: [[FLOW|Cómo funciona: un recorrido de principio a fin]]

• 🏴☠️ Habilidad de ejemplo: [[skills/pirate-speak/SKILL|Habilidad de hablar como pirata (SKILL.md)]]

Related MCP server: Forage MCP Server

Características principales

• Arquitectura desacoplada: El Proceso A (CLI/Agente) se comunica con el Proceso B (Servidor MCP) estrictamente mediante JSON-RPC sobre el Protocolo de Contexto de Modelo. No se importan herramientas del servidor ni lógica de carga de habilidades en el agente.

• Divulgación progresiva de habilidades: El agente primero lista metadatos (nombres y descripciones) de las habilidades disponibles de forma económica y solo extrae las instrucciones pesadas en tokens cuando el LLM determina que la habilidad es relevante.

• Calculadora basada en AST: Una herramienta de evaluación matemática segura que restringe la ejecución a números básicos y operaciones aritméticas, totalmente protegida contra la ejecución remota de código.

• Pruebas locales robustas: Un DummyClient integrado basado en reglas y con scripts que permite pruebas deterministas y sin conexión de comportamientos de agente de múltiples pasos sin necesidad de claves API de LLM.

• Integración real con LLM: Cambio sin problemas a endpoints reales compatibles con OpenAI mediante configuración de entorno.

• Estructura de paquete moderna: Diseño de paquete limpio con una CLI basada en Click y configuración de pyproject.toml.

Arquitectura del sistema

graph LR
    subgraph CLI_PROC["Process A — CLI / Agent"]
        CLI["cli.py<br/>run command"]
        AG["Agent<br/>ReAct Loop"]
        LLM["LLMClient<br/>(Dummy / OpenAI)"]
        MC["MCPClient<br/>(stdio client)"]
        CLI --> AG
        AG --> LLM
        AG --> MC
    end

    subgraph SRV_PROC["Process B — MCP Server"]
        SRV["FastMCP Server<br/>app.py"]
        TOOLS["Tools<br/>calculator, echo"]
        SKILLS["Skills<br/>list_skills / load_skill<br/>+ prompts"]
        SRV --> TOOLS
        SRV --> SKILLS
    end

    MC <-->|"MCP stdio<br/>(JSON-RPC on stdin/stdout)"| SRV
    LLM -.->|"OpenAI Chat API"| EXT["LLM API Endpoint"]

Estructura del proyecto

mcp-skills-new/
├── chatbot-ui/                 # Premium Chatbot Web UI
├── start.sh                    # Starts MCP server & UI in background
├── stop.sh                     # Stops background services
├── pyproject.toml              # Build backend and dependencies config
├── FLOW.md                     # Walkthrough explaining how the framework runs
├── README.md                   # This overview file
├── skills/                     # Builtin skills catalog
│   └── pirate-speak/
│       └── SKILL.md            # Pirate-speak instructions with frontmatter
├── src/
│   └── mcp_skills/
│       ├── __init__.py
│       ├── cli.py              # Click commands entry point
│       ├── config.py           # Configuration parser settings
│       ├── agent/              # CLI Agent components
│       │   ├── __init__.py
│       │   ├── agent.py        # ReAct orchestration loop
│       │   ├── mcp_client.py   # MCP stdio client wrapper
│       │   └── prompts.py      # System prompts
│       ├── llm/                # LLM connectors (Dummy & OpenAI)
│       │   ├── __init__.py
│       │   ├── base.py
│       │   ├── dummy.py
│       │   └── openai_client.py
│       └── server/             # Stdio/SSE MCP server
│           ├── __init__.py
│           ├── __main__.py
│           ├── app.py          # FastMCP server wiring
│           ├── skills/         # Skill markdown loader
│           │   ├── __init__.py
│           │   ├── loader.py
│           │   └── models.py
│           └── tools/          # Registry and builtin tools
│               ├── __init__.py
│               ├── base.py
│               ├── registry.py
│               └── builtins.py
└── tests/                      # 18 pytest unit/integration tests

[!TIP] Consejo de navegación en Obsidian: Puedes abrir y editar archivos clave directamente dentro de Obsidian usando estos enlaces:

• [[FLOW]] — Recorrido técnico detallado del bucle de agente ReAct y la comunicación stdio.

• [[LAYMAN_GUIDE]] — Resumen de alto nivel, amigable para desarrolladores, con analogías.

• [[skills/pirate-speak/SKILL]] — La plantilla de instrucciones de la habilidad de ejemplo.

Instalación

Instala el paquete y sus dependencias de desarrollo en modo editable:

python3 -m pip install -e ".[dev]"

Uso

1. Ejecutar el bucle del agente

Activa el agente para responder preguntas. Este iniciará automáticamente el subproceso del servidor MCP stdio, inspeccionará las herramientas activas, razonará a través de los pasos, llamará a las herramientas apropiadas y devolverá un resumen.

Ejecución matemática (usa la herramienta de calculadora AST):

mcp-skills run "what is 6 * 7?"

Descubrimiento de habilidades y carga diferida:

mcp-skills run "what skills exist?"

2. Explorar habilidades descubiertas mediante CLI

Explora las plantillas de habilidades cargadas sin iniciar el bucle del agente:

mcp-skills skills list

3. Ejecutar servidor MCP independiente

Inicia un servidor MCP sin procesar que escucha en stdin/stdout:

mcp-skills serve

Inspecciona herramientas y prompts de forma interactiva mediante el Inspector MCP:

npx @modelcontextprotocol/inspector mcp-skills serve

4. Interfaz web y servidor en segundo plano

Proporcionamos scripts para ejecutar el servidor MCP y una interfaz web estática en segundo plano:

./start.sh

Esto inicia mcp-skills serve en el puerto 8000 mediante SSE y un servidor HTTP de Python en el puerto 8080. Navega a http://127.0.0.1:8080 para acceder a la interfaz de chatbot.

Para detener los procesos en segundo plano, ejecuta:

./stop.sh

Ejecutar con un LLM real

Para cambiar del DummyClient sin conexión a un modelo real, crea un archivo .env en la raíz del proyecto:

MCP_SKILLS_LLM_PROVIDER=openai
MCP_SKILLS_MODEL=gpt-4o-mini
MCP_SKILLS_OPENAI_BASE_URL=https://api.openai.com/v1
MCP_SKILLS_OPENAI_API_KEY=your-api-key-here

Ejecutar pruebas

Ejecuta la suite de pruebas para realizar 18 verificaciones sin conexión:

pytest -v