MCP Skills

Легковесная, надёжная и развязанная CLI/Agent-платформа, демонстрирующая прогрессивное раскрытие навыков агента через Model Context Protocol (MCP).

Этот проект реализует полный локальный агентный цикл, который общается с бэкенд-сервером MCP через транспорт stdio. Он позволяет агенту обнаруживать инструменты и загружать сложные инструкции (навыки) динамически и по требованию, только когда это актуально.

🗺️ Карта хранилища Obsidian

Быстрая навигация по документации внутри Obsidian:

• 🏠 Главная (README): [[README]]

• 📖 Руководство для новичков: [[LAYMAN_GUIDE|Руководство для новичков по MCP Skills]]

• ⚙️ Системный поток и прохождение: [[FLOW|Как это работает — сквозное прохождение]]

• 🏴☠️ Пример навыка: [[skills/pirate-speak/SKILL|Навык «Пиратская речь» (SKILL.md)]]

Related MCP server: Forage MCP Server

Ключевые особенности

• Развязанная архитектура: Процесс A (CLI/Agent) общается с процессом B (MCP Server) строго через JSON-RPC по Model Context Protocol. Никакого импорта серверных инструментов или логики загрузчика навыков в агенте.

• Прогрессивное раскрытие навыков: Агент сначала дёшево получает список метаданных (имена и описания) доступных навыков и только тянет тяжёлые по токенам инструкции, когда LLM определяет, что навык релевантен.

• Калькулятор на основе AST: Безопасный инструмент оценки математических выражений, ограничивающий выполнение базовыми числами и арифметическими операциями, полностью защищённый от удалённого выполнения кода.

• Надёжное локальное тестирование: Встроенный DummyClient на основе правил и сценариев, позволяющий детерминированно и офлайн тестировать многошаговое поведение агента без необходимости в API-ключах LLM.

• Интеграция с реальной LLM: Бесшовное переключение на реальные OpenAI-совместимые конечные точки с помощью конфигурации окружения.

• Современная структура пакета: Чистая структура пакета с использованием Click-based CLI и настройкой pyproject.toml.

Архитектура системы

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

Структура проекта

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: Вы можете открывать и редактировать ключевые файлы прямо в Obsidian, используя эти ссылки:

• [[FLOW]] — Подробное техническое прохождение цикла агента ReAct и stdio-общения.

• [[LAYMAN_GUIDE]] — Обзор высокого уровня, удобный для разработчиков, с аналогиями.

• [[skills/pirate-speak/SKILL]] — Шаблон инструкции примера навыка.

Установка

Установите пакет и его зависимости для разработки в режиме editable:

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

Использование

1. Запуск цикла агента

Запустите агента для ответа на вопросы. Он автоматически запустит подпроцесс stdio MCP-сервера, проверит активные инструменты, обдумает шаги, вызовет подходящие инструменты и вернёт сводку.

Выполнение математических операций (использует инструмент AST-калькулятора):

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

Обнаружение навыков и ленивая загрузка:

mcp-skills run "what skills exist?"

2. Изучение обнаруженных навыков через CLI

Изучите загруженные шаблоны навыков без запуска цикла агента:

mcp-skills skills list

3. Запуск автономного MCP-сервера

Запустите сырой MCP-сервер, слушающий stdin/stdout:

mcp-skills serve

Интерактивно просматривайте инструменты и подсказки через MCP Inspector:

npx @modelcontextprotocol/inspector mcp-skills serve

4. Веб-интерфейс и фоновый сервер

Мы предоставляем скрипты для запуска MCP-сервера и статического веб-интерфейса в фоновом режиме:

./start.sh

Это запускает mcp-skills serve на порту 8000 через SSE и Python HTTP-сервер на порту 8080. Перейдите на http://127.0.0.1:8080, чтобы получить доступ к интерфейсу чат-бота.

Чтобы остановить фоновые процессы, выполните:

./stop.sh

Работа с реальной LLM

Чтобы переключиться с офлайн DummyClient на реальную модель, создайте файл .env в корне проекта:

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

Запуск тестов

Выполните набор тестов для запуска 18 офлайн-проверок:

pytest -v