# Раздел 03 - Интеграция на Протокола за Контекст на Модела (MCP)

## Въведение в MCP (Протокол за Контекст на Модела)

Протоколът за Контекст на Модела (MCP) е стандарт с отворен код за свързване на AI приложения с външни системи. С MCP, AI приложения като Claude или ChatGPT могат да се свързват с източници на данни (например локални файлове, бази данни), инструменти (например търсачки, калкулатори) и работни процеси (например специализирани подканвания), което им позволява да получават ключова информация и да изпълняват задачи.

Представете си MCP като **USB-C порт за AI приложения**. Точно както USB-C предоставя стандартизиран начин за свързване на електронни устройства, MCP предоставя стандартизиран начин за свързване на AI приложения с външни системи.

### Какво може да осигури MCP?

MCP отключва мощни възможности за AI приложения:

- **Персонализирани AI асистенти**: Агентите могат да получат достъп до вашия Google Calendar и Notion, действайки като по-персонализиран AI асистент
- **Разширено генериране на код**: Claude Code може да създаде цял уеб приложение, използвайки дизайн от Figma
- **Интеграция на корпоративни данни**: Корпоративни чатботове могат да се свързват с множество бази данни в организацията, позволявайки на потребителите да анализират данни чрез чат
- **Креативни работни процеси**: AI модели могат да създават 3D дизайни в Blender и да ги отпечатват с 3D принтер
- **Достъп до информация в реално време**: Свързване с външни източници на данни за актуална информация
- **Сложни многоетапни операции**: Изпълнение на сложни работни процеси, комбиниращи множество инструменти и системи

### Защо MCP е важен?

MCP предоставя ползи за цялата екосистема:

**За разработчиците**: MCP намалява времето за разработка и сложността при създаване или интеграция с AI приложение или агент.

**За AI приложенията**: MCP осигурява достъп до екосистема от източници на данни, инструменти и приложения, които подобряват възможностите и подобряват потребителското изживяване.

**За крайните потребители**: MCP води до по-способни AI приложения или агенти, които могат да получат достъп до вашите данни и да предприемат действия от ваше име, когато е необходимо.

## Малки езикови модели (SLMs) в MCP

Малките езикови модели представляват ефективен подход към внедряването на AI, предлагайки няколко предимства:

### Предимства на SLMs
- **Ефективност на ресурсите**: По-ниски изисквания за изчислителна мощност
- **По-бързи времена за отговор**: Намалена латентност за приложения в реално време  
- **Икономичност**: Минимални нужди от инфраструктура
- **Поверителност**: Могат да работят локално без предаване на данни
- **Персонализация**: По-лесно адаптиране за специфични области

### Защо SLMs работят добре с MCP

SLMs, съчетани с MCP, създават мощна комбинация, при която способностите за разсъждение на модела се допълват от външни инструменти, компенсирайки по-малкия брой параметри чрез разширена функционалност.

## Преглед на Python MCP SDK

Python MCP SDK предоставя основата за създаване на приложения, поддържащи MCP. SDK включва:

- **Клиентски библиотеки**: За свързване с MCP сървъри
- **Сървърна рамка**: За създаване на персонализирани MCP сървъри
- **Протоколни обработчици**: За управление на комуникацията
- **Интеграция на инструменти**: За изпълнение на външни функции

## Практическа реализация: Phi-4 MCP клиент

Нека разгледаме реална реализация, използваща мини модела Phi-4 на Microsoft, интегриран с MCP възможности.

### Преглед на архитектурата на MCP

MCP следва **клиент-сървър архитектура**, при която MCP хост (AI приложение като Claude Code или Claude Desktop) установява връзки с един или повече MCP сървъри. MCP хостът постига това, като създава един MCP клиент за всеки MCP сървър.

#### Основни участници

- **MCP хост**: AI приложението, което координира и управлява един или няколко MCP клиенти
- **MCP клиент**: Компонент, който поддържа връзка с MCP сървър и получава контекст от MCP сървър за използване от MCP хоста
- **MCP сървър**: Програма, която предоставя контекст на MCP клиенти

#### Двуслойна архитектура

MCP се състои от два отделни слоя:

**Слой данни**: Определя JSON-RPC базирания протокол за клиент-сървър комуникация, включително:
- Управление на жизнения цикъл (инициализация на връзката, договаряне на възможности)
- Основни примитиви (инструменти, ресурси, подканвания)
- Клиентски функции (семплиране, събиране на информация, логване)
- Утилитарни функции (известия, проследяване на напредъка)

**Транспортен слой**: Определя механизмите и каналите за комуникация:
- **STDIO транспорт**: Използва стандартни входно-изходни потоци за локални процеси (оптимална производителност, без мрежови натоварвания)
- **Streamable HTTP транспорт**: Използва HTTP POST с опционални Server-Sent Events за отдалечени сървъри (поддържа стандартна HTTP автентикация)

```
┌─────────────────────────────────────┐
│           MCP Host                  │
│     (AI Application)                │
└─────────────────┬───────────────────┘
                  │
┌─────────────────┴───────────────────┐
│         MCP Client 1                │
│  ┌─────────────────────────────────┐ │
│  │        Data Layer               │ │
│  │  ├── Lifecycle Management       │ │
│  │  ├── Primitives (Tools/Resources)│ │
│  │  └── Notifications              │ │
│  └─────────────────────────────────┘ │
│  ┌─────────────────────────────────┐ │
│  │      Transport Layer           │ │
│  │  ├── STDIO Transport           │ │
│  │  └── HTTP Transport            │ │
│  └─────────────────────────────────┘ │
└─────────────────┬───────────────────┘
                  │
┌─────────────────┴───────────────────┐
│         MCP Server 1                │
│    (Local/Remote Context Provider)  │
└─────────────────────────────────────┘
```

### Основни примитиви на MCP

MCP определя примитиви, които специфицират типовете контекстуална информация, която може да се споделя с AI приложения, и обхвата на действията, които могат да се изпълняват.

#### Сървърни примитиви

MCP определя три основни примитива, които сървърите могат да предоставят:

**Инструменти**: Изпълними функции, които AI приложенията могат да извикват за изпълнение на действия
- Примери: файлови операции, API извиквания, заявки към бази данни
- Методи: `tools/list`, `tools/call`
- Поддържат динамично откриване и изпълнение

**Ресурси**: Източници на данни, които предоставят контекстуална информация на AI приложенията
- Примери: съдържание на файлове, записи в бази данни, отговори от API
- Методи: `resources/list`, `resources/read`
- Позволяват достъп до структурирани данни

**Подканвания**: Повторно използваеми шаблони, които помагат за структуриране на взаимодействията с езикови модели
- Примери: системни подканвания, примери с малко данни
- Методи: `prompts/list`, `prompts/get`
- Стандартизират моделите на взаимодействие с AI

#### Клиентски примитиви

MCP също определя примитиви, които клиентите могат да предоставят за по-богати взаимодействия:

**Семплиране**: Позволява на сървърите да заявяват завършвания от езиковия модел на клиента
- Метод: `sampling/complete`
- Позволява разработка на сървъри, независими от модела
- Осигурява достъп до езиковия модел на хоста

**Събиране на информация**: Позволява на сървърите да заявяват допълнителна информация от потребителите
- Метод: `elicitation/request`
- Позволява взаимодействие с потребителя и потвърждение
- Поддържа динамично събиране на информация

**Логване**: Позволява на сървърите да изпращат лог съобщения към клиентите
- Използва се за целите на дебъгинг и мониторинг
- Осигурява видимост в операциите на сървъра

### Жизнен цикъл на MCP протокола

#### Инициализация и договаряне на възможности

MCP е протокол със състояние, който изисква управление на жизнения цикъл. Процесът на инициализация изпълнява няколко критични цели:

1. **Договаряне на версията на протокола**: Осигурява съвместимост между клиента и сървъра (например "2025-06-18")
2. **Откриване на възможности**: Всяка страна декларира поддържаните функции и примитиви
3. **Обмен на идентичност**: Осигурява информация за идентификация и версия

```python
# Example initialization request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "elicitation": {},  # Client supports user interaction
      "sampling": {}      # Client can provide LLM completions
    },
    "clientInfo": {
      "name": "edge-ai-client",
      "version": "1.0.0"
    }
  }
}
```

#### Откриване и изпълнение на инструменти

След инициализацията клиентите могат да откриват и изпълняват инструменти:

```python
# Discover available tools
tools_response = await session.list_tools()

# Execute a tool
result = await session.call_tool(
    "weather_current",
    {
        "location": "San Francisco",
        "units": "imperial"
    }
)
```

#### Известия в реално време

MCP поддържа известия в реално време за динамични актуализации:

```python
# Server sends notification when tools change
{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

# Client responds by refreshing tool list
await session.list_tools()  # Get updated tools
```

## Първи стъпки: Ръководство стъпка по стъпка

### Стъпка 1: Настройка на средата

Инсталирайте необходимите зависимости:
```bash
pip install fastmcp mcp-python-client openai requests pyautogui Pillow
```

### Стъпка 2: Основна конфигурация

Настройте вашите променливи на средата:
```python
# System Configuration
SYSTEM_PROMPT = "You are an AI assistant with some tools."

# Ollama Configuration (Local)
OLLAMA_URL = "http://localhost:11434/api/chat"
OLLAMA_MODEL_ID = "phi4-mini:3.8b-fp16"

# vLLM Configuration (Server)
VLLM_URL = "http://localhost:8000/v1"
VLLM_MODEL_ID = "microsoft/Phi-4-mini-instruct"
```

### Стъпка 3: Стартиране на първия MCP клиент

**Основна настройка на Ollama:**
```bash
python ghmodel_mcp_demo.py
```

**Използване на vLLM бекенд:**
```bash
python ghmodel_mcp_demo.py --env vllm
```

**Връзка със Server-Sent Events:**
```bash
python ghmodel_mcp_demo.py --run sse
```

**Персонализиран MCP сървър:**
```bash
python ghmodel_mcp_demo.py --server /path/to/server.py
```

### Стъпка 4: Програмно използване

```python
import asyncio
from ghmodel_mcp_demo import OllamaClient, Phi4MiniMCPClient

async def automated_interaction():
    # Configure MCP server parameters
    server_params = StdioServerParameters(
        command="npx",
        args=["@playwright/mcp@latest"],
        env=None,
    )
    
    # Create MCP client and process tools
    async with Phi4MiniMCPClient(server_params) as mcp_client:
        tools = await process_mcp_tools(mcp_client)
        llm_client = OllamaClient()
        
        # Generate response with tool capabilities
        response, messages = await llm_client.generate_response(
            "Help me automate a web task",
            tools
        )
        return response

# Execute the automation
result = asyncio.run(automated_interaction())
print(result)
```

## Разширени функции

### Поддръжка на множество бекенди

Реализацията поддържа както Ollama, така и vLLM бекенди, позволявайки ви да изберете според вашите изисквания:

- **Ollama**: По-добър за локална разработка и тестване
- **vLLM**: Оптимизиран за продукция и сценарии с висока пропускателна способност

### Гъвкави протоколи за връзка

Поддържат се два режима на връзка:

**STDIO режим**: Директна комуникация между процеси
- По-ниска латентност
- Подходящ за локални инструменти
- Лесна настройка

**SSE режим**: Поточно предаване чрез HTTP
- Подходящ за мрежови системи
- По-добър за разпределени системи
- Актуализации в реално време

### Възможности за интеграция на инструменти

Системата може да се интегрира с различни инструменти:
- Уеб автоматизация (Playwright)
- Файлови операции
- API взаимодействия
- Системни команди
- Персонализирани функции

## Управление на грешки и добри практики

### Цялостно управление на грешки

Реализацията включва надеждно управление на грешки за:

**Грешки при връзка:**
- Неуспехи на MCP сървъра
- Мрежови таймаути
- Проблеми с връзката

**Грешки при изпълнение на инструменти:**
- Липсващи инструменти
- Валидация на параметри
- Неуспехи при изпълнение

**Грешки при обработка на отговори:**
- Проблеми с JSON парсинг
- Несъответствия във формата
- Аномалии в отговорите на LLM

### Добри практики

1. **Управление на ресурси**: Използвайте асинхронни контекстни мениджъри
2. **Управление на грешки**: Внедрете цялостни try-catch блокове
3. **Логване**: Активирайте подходящи нива на логване
4. **Сигурност**: Валидирайте входните данни и почиствайте изходните
5. **Производителност**: Използвайте пулове за връзки и кеширане

## Приложения в реалния свят

### Уеб автоматизация
```python
# Example: Automated web testing
async def web_automation_example():
    tools = await setup_playwright_tools()
    response = await llm_client.generate_response(
        "Navigate to example.com and take a screenshot",
        tools
    )
```

### Обработка на данни
```python
# Example: File analysis
async def data_processing_example():
    tools = await setup_file_tools()
    response = await llm_client.generate_response(
        "Analyze the CSV file and generate a summary report",
        tools
    )
```

### API интеграция
```python
# Example: API interactions
async def api_integration_example():
    tools = await setup_api_tools()
    response = await llm_client.generate_response(
        "Fetch weather data and create a forecast summary",
        tools
    )
```

## Оптимизация на производителността

### Управление на паметта
- Ефективно управление на историята на съобщенията
- Правилно почистване на ресурси
- Пулове за връзки

### Мрежова оптимизация
- Асинхронни HTTP операции
- Конфигурируеми таймаути
- Гъвкаво възстановяване при грешки

### Конкурентна обработка
- Неблокиращ I/O
- Паралелно изпълнение на инструменти
- Ефективни асинхронни модели

## Съображения за сигурност

### Защита на данните
- Сигурно управление на API ключове
- Валидиране на входните данни
- Почистване на изходните данни

### Мрежова сигурност
- Поддръжка на HTTPS
- Локални крайни точки по подразбиране
- Сигурно управление на токени

### Безопасност при изпълнение
- Филтриране на инструменти
- Среда с ограничен достъп
- Логване за одит

## Екосистема и разработка на MCP

### Обхват на проекта MCP

Екосистемата на Протокола за Контекст на Модела включва няколко ключови компонента:

- **[Спецификация на MCP](https://modelcontextprotocol.io/specification/latest)**: Официална спецификация, описваща изискванията за внедряване на клиенти и сървъри
- **[MCP SDKs](https://modelcontextprotocol.io/docs/sdk)**: SDKs за различни програмни езици, които внедряват MCP
- **Инструменти за разработка на MCP**: Инструменти за разработка на MCP сървъри и клиенти, включително [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
- **[Референтни реализации на MCP сървъри](https://github.com/modelcontextprotocol/servers)**: Референтни реализации на MCP сървъри

### Първи стъпки с разработката на MCP

За да започнете да изграждате с MCP:

**Създаване на сървъри**: [Създайте MCP сървъри](https://modelcontextprotocol.io/docs/develop/build-server), за да предоставите вашите данни и инструменти

**Създаване на клиенти**: [Разработете приложения](https://modelcontextprotocol.io/docs/develop/build-client), които се свързват с MCP сървъри

**Научете концепции**: [Разберете основните концепции](https://modelcontextprotocol.io/docs/learn/architecture) и архитектурата на MCP

## Заключение

SLMs, интегрирани с MCP, представляват промяна в парадигмата на разработката на AI приложения. Чрез комбиниране на ефективността на малките модели с мощта на външни инструменти, разработчиците могат да създават интелигентни системи, които са едновременно ресурсно ефективни и високо способни.

Протоколът за Контекст на Модела предоставя стандартизиран начин за свързване на AI приложения с външни системи, подобно на това как USB-C предоставя универсален стандарт за свързване на електронни устройства. Тази стандартизация позволява:

- **Безпроблемна интеграция**: Свързване на AI модели с разнообразни източници на данни и инструменти
- **Растеж на екосистемата**: Създаване веднъж, използване в множество AI приложения
- **Разширени възможности**: Допълване на SLMs с външна функционалност
- **Актуализации в реално време**: Поддръжка на динамични, отзивчиви AI приложения

Основни изводи:
- MCP е отворен стандарт, който свързва AI приложения и външни системи
- **[Ollama Документация](https://ollama.ai/docs)** - Платформа за локално разгръщане на LLM
- **[vLLM Документация](https://docs.vllm.ai/)** - Високопроизводително обслужване на LLM

### Технически стандарти и протоколи

- **[JSON-RPC 2.0 Спецификация](https://www.jsonrpc.org/)** - Основен RPC протокол, използван от MCP
- **[JSON Schema](https://json-schema.org/)** - Стандарт за дефиниране на схеми за MCP инструменти
- **[OpenAPI Спецификация](https://swagger.io/specification/)** - Стандарт за документация на API
- **[Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)** - Уеб стандарт за актуализации в реално време

### Разработка на AI агенти

- **[Microsoft Agent Framework](https://github.com/microsoft/agent-framework)** - Готова за производство рамка за разработка на агенти
- **[LangChain Документация](https://docs.langchain.com/)** - Рамка за интеграция на агенти и инструменти
- **[Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/)** - SDK за оркестрация на AI от Microsoft

### Отраслови доклади и изследвания

- **[Съобщение за протокола Model Context на Anthropic](https://www.anthropic.com/news/model-context-protocol)** - Оригинално представяне на MCP
- **[Проучване на малки езикови модели](https://arxiv.org/abs/2410.20011)** - Академично проучване на изследванията за SLM
- **[Анализ на пазара на Edge AI](https://www.marketsandmarkets.com/Market-Reports/edge-ai-software-market-74385617.html)** - Тенденции и прогнози в индустрията
- **[Най-добри практики за разработка на AI агенти](https://arxiv.org/abs/2309.02427)** - Изследване на архитектури на агенти

Този раздел предоставя основата за изграждане на собствени MCP приложения, захранвани от SLM, отваряйки възможности за автоматизация, обработка на данни и интеграция на интелигентни системи.

## ➡️ Какво следва

- [Модул 7. Примери за Edge AI](../Module07/README.md)

---

**Отказ от отговорност**:  
Този документ е преведен с помощта на AI услуга за превод [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи може да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Не носим отговорност за недоразумения или погрешни интерпретации, произтичащи от използването на този превод.