MCP Skills

Ein leichtgewichtiges, robustes und entkoppeltes CLI/Agent-Framework, das die progressive Offenlegung von Agent Skills über das Model Context Protocol (MCP) demonstriert.

Dieses Projekt implementiert eine vollständige lokale Agentenschleife, die über stdio-Transport mit einem Backend-MCP-Server kommuniziert. Es ermöglicht dem Agenten, Tools zu entdecken und komplexe Anweisungen (Skills) dynamisch und nur bei Bedarf abzurufen.

🗺️ Obsidian-Vault-Karte

Schnelle Navigation durch die Dokumentation in Obsidian:

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

• 📖 Laienhandbuch: [[LAYMAN_GUIDE|Ein Laienhandbuch zu MCP Skills]]

• ⚙️ Systemablauf & Walkthrough: [[FLOW|Wie es funktioniert – ein End-to-End-Walkthrough]]

• 🏴☠️ Beispiel-Skill: [[skills/pirate-speak/SKILL|Pirate Speak Skill (SKILL.md)]]

Related MCP server: Forage MCP Server

Hauptfunktionen

• Entkoppelte Architektur: Prozess A (CLI/Agent) kommuniziert mit Prozess B (MCP-Server) ausschließlich über JSON-RPC über das Model Context Protocol. Kein Import von Server-Tools oder Skill-Loader-Logik im Agenten.

• Progressive Skill-Offenlegung: Der Agent listet zuerst günstig Metadaten (Namen und Beschreibungen) verfügbarer Skills auf und zieht nur dann die tokenintensiven Anweisungen, wenn das LLM feststellt, dass der Skill relevant ist.

• AST-basierter Taschenrechner: Ein sicheres Mathematik-Auswertungstool, das die Ausführung auf grundlegende Zahlen und arithmetische Operationen beschränkt und vollständig vor Remote-Code-Ausführung geschützt ist.

• Robustes lokales Testen: Integrierter regelbasierter und skriptbasierter DummyClient ermöglicht deterministische Offline-Tests von mehrstufigen Agentenverhalten ohne LLM-API-Schlüssel.

• Echte LLM-Integration: Nahtloser Wechsel zu echten OpenAI-kompatiblen Endpunkten über Umgebungskonfiguration.

• Moderne Paketstruktur: Saubere Paketstruktur mit Click-basierter CLI und pyproject.toml-Setup.

Systemarchitektur

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"]

Projektstruktur

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] Obsidian-Navigationstipp: Sie können Schlüsseldateien direkt in Obsidian über diese Links öffnen und bearbeiten:

• [[FLOW]] — Detaillierter technischer Walkthrough der ReAct-Agentenschleife und der stdio-Kommunikation.

• [[LAYMAN_GUIDE]] — Hochrangige, entwicklerfreundliche Übersicht mit Analogien.

• [[skills/pirate-speak/SKILL]] — Die Beispiel-Skill-Anweisungsvorlage.

Installation

Installieren Sie das Paket und seine Entwicklungsabhängigkeiten im bearbeitbaren Modus:

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

Verwendung

1. Agentenschleife ausführen

Lösen Sie den Agenten aus, um Fragen zu beantworten. Er startet automatisch den stdio-MCP-Server-Subprozess, untersucht aktive Tools, denkt über Schritte nach, ruft geeignete Tools auf und gibt eine Zusammenfassung zurück.

Mathematik-Ausführung (verwendet AST-Taschenrechner-Tool):

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

Skills-Entdeckung & Lazy Loading:

mcp-skills run "what skills exist?"

2. Entdeckte Skills über die CLI erkunden

Erkunden Sie geladene Skill-Vorlagen, ohne die Agentenschleife zu starten:

mcp-skills skills list

3. Eigenständigen MCP-Server ausführen

Starten Sie einen rohen MCP-Server, der auf stdin/stdout lauscht:

mcp-skills serve

Untersuchen Sie Tools und Prompts interaktiv über den MCP Inspector:

npx @modelcontextprotocol/inspector mcp-skills serve

4. Web-UI & Hintergrundserver

Wir stellen Skripte bereit, um den MCP-Server und eine statische Web-UI im Hintergrund auszuführen:

./start.sh

Dies startet mcp-skills serve auf Port 8000 über SSE und einen Python-HTTP-Server auf Port 8080. Navigieren Sie zu http://127.0.0.1:8080, um die Chatbot-UI zu erreichen.

Um die Hintergrundprozesse zu stoppen, führen Sie aus:

./stop.sh

Ausführen mit einem echten LLM

Um vom Offline-DummyClient zu einem echten Modell zu wechseln, erstellen Sie eine .env-Datei im Projektstamm:

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

Tests ausführen

Führen Sie die Testsuite aus, um 18 Offline-Verifizierungsprüfungen durchzuführen:

pytest -v