← [Раздел](README.md) · [Главная](../README.md)

# Functions агента и MCP tools

## Цель

Различать **встроенные инструменты** агента Cursor (read, edit, terminal, grep…) и **MCP-серверы** (внешние API), понимать, как они пополняют контекст и когда подключать MCP.

## Предварительно

- [variables-i-mentions.md](variables-i-mentions.md)
- Раздел [10 — Cursor практика](../10-cursor-praktika/mcp-servery.md) (углубление)
- Базовое понимание API

## Время

~60 минут.

---

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

| Класс | Кто предоставляет | Примеры |
|-------|-------------------|---------|
| **Native / built-in** | Cursor, harness | Read file, Write, Shell, Grep, SemanticSearch |
| **MCP tools** | Внешние серверы | Context7 docs, Yandex Tracker, Kubernetes, Figma |

Агент **сам выбирает** tool по описанию задачи (если режим Agent и права позволяют).

---

## Built-in functions (типичный набор)

Точные имена зависят от версии; логические группы:

### Файлы и поиск

- чтение файла (целиком или диапазон);
- запись/патч;
- glob по имени;
- grep / ripgrep;
- семантический поиск по коду.

### Терминал

- выполнение shell-команд;
- фоновые процессы;
- чтение вывода терминала.

### Оркестрация (продвинуто)

- запуск **субагентов** (Task);
- переключение Plan/Agent mode;
- todo-листы для длинных задач.

**Контекст:** результат каждого tool call добавляется в историю сессии → расход токенов.

---

## MCP (Model Context Protocol)

**MCP** — открытый протокол: сервер объявляет **tools** и **resources**, клиент (Cursor) показывает их агенту.

### Конфигурация

Обычно в настройках Cursor: `Settings → MCP` или файл конфигурации MCP (путь зависит от ОС и версии).

Пример логической записи (без секретов):

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"],
      "env": {}
    }
  }
}
```

Реальные ключи — только в env, не в Git.

### Популярные сценарии

| MCP | Задача |
|-----|--------|
| Context7 (`user-context7`) | Актуальная документация библиотек |
| Yandex Tracker | Читать/искать задачи |
| Kubernetes | Статус подов (осторожно на проде) |
| Figma | Дизайн → код |
| Stripe | Платежи (только test keys) |

ECC skill `mcp-server-patterns` — как **писать** свои MCP-серверы.

---

## Hooks на MCP

Из раздела 08: `beforeMCPExecution` логирует вызовы. Политика:

- allowlist серверов в корпоративной среде;
- запрет prod-кластеров без явного запроса в rule.

---

## Как агент выбирает tool

```text
Промпт: «найди определение функции Foo»
  → скорее Grep/SemanticSearch, не MCP

Промпт: «как в Next.js 15 настроить middleware»
  → Context7 MCP или @Docs

Промпт: «статус пода app в namespace staging»
  → Kubernetes MCP (если настроен)
```

Уточняйте в промпте: «используй MCP Context7, не выдумывай API».

---

## Ограничения и безопасность

| Риск | Мера |
|------|------|
| MCP с prod credentials | Отдельный профиль, read-only |
| Shell `rm -rf` | beforeShellExecution hook |
| Галлюцинация API | MCP docs + verification |
| Утечка PII в Tracker | Минимальный scope tool |

---

## Functions vs @-mentions

| @mention | Tool |
|----------|------|
| Вы явно кладёте файл в контекст | Агент сам читает по необходимости |
| Статично на старте запроса | Динамично по ходу рассуждения |
| Хорошо для 1–3 файлов | Хорошо для исследования |

Можно комбинировать: `@handler.go` + «дополнительно grep по repo».

---

## ECC и MCP inventory

В ECC есть скрипты инвентаризации MCP для разных harness:

```text
ECC/.cursor/scripts/lib/mcp-inventory/
```

Команда `/ecc-guide` может направить к актуальным путям установки.

---

## Упражнение

1. Дайте агенту задачу без @: «где объявлен тип User» — посмотрите, какой tool вызван.
2. Если есть Context7 — спросите версионный API вашего фреймворка.
3. Запишите: какой MCP вы бы подключили для своей работы и почему.

---

## Самопроверка

1. Чем built-in read отличается от MCP?
2. Где настраиваются MCP-серверы в Cursor?
3. Зачем hook `beforeMCPExecution`?
4. Когда просить Context7 вместо @Web?

---

## Дальше

→ [10 — Cursor на практике](../10-cursor-praktika/README.md)  
← [@-упоминания](variables-i-mentions.md)