mcp-for-beginners / uk

# AGENTS.md

## Огляд проєкту

**MCP для початківців** — це відкритий навчальний курс для вивчення Протоколу Контексту Моделі (MCP) — стандартизованої рамки для взаємодії між AI-моделями та клієнтськими додатками. Цей репозиторій надає комплексні навчальні матеріали з практичними прикладами коду на кількох мовах програмування.

### Основні технології

- **Мови програмування**: C#, Java, JavaScript, TypeScript, Python, Rust
- **Фреймворки та SDK**: 
  - MCP SDK (`@modelcontextprotocol/sdk`)
  - Spring Boot (Java)
  - FastMCP (Python)
  - LangChain4j (Java)
- **Бази даних**: PostgreSQL з розширенням pgvector
- **Хмарні платформи**: Azure (Container Apps, OpenAI, Content Safety, Application Insights)
- **Інструменти збірки**: npm, Maven, pip, Cargo
- **Документація**: Markdown з автоматизованим багатомовним перекладом (понад 48 мов)

### Архітектура

- **11 основних модулів (00-11)**: Послідовна навчальна програма від базових до просунутих тем
- **Практичні лабораторії**: Практичні вправи з повним кодом рішень на кількох мовах
- **Прикладні проєкти**: Робочі серверні та клієнтські реалізації MCP
- **Система перекладу**: Автоматизований робочий процес GitHub Actions для багатомовної підтримки
- **Графічні ресурси**: Централізована директорія зображень із перекладеними версіями

## Команди для налаштування

Це репозиторій, орієнтований на документацію. Більшість налаштувань відбувається у кожному окремому прикладі проекту та лабораторії.

### Налаштування репозиторію

```bash
# Клонувати репозиторій
git clone https://github.com/microsoft/mcp-for-beginners.git
cd mcp-for-beginners
```

### Робота з прикладними проєктами

Прикладні проєкти знаходяться в:
- `03-GettingStarted/samples/` - Приклади для конкретних мов
- `03-GettingStarted/01-first-server/solution/` - Перші реалізації серверів
- `03-GettingStarted/02-client/solution/` - Клієнтські реалізації
- `11-MCPServerHandsOnLabs/` - Комплексні лабораторії інтеграції бази даних

Кожен приклад містить власні інструкції з налаштування:

#### Проєкти на TypeScript/JavaScript
```bash
cd <project-directory>
npm install
npm start
```

#### Проєкти на Python
```bash
cd <project-directory>
pip install -r requirements.txt
# або
pip install -e .
python main.py
```

#### Проєкти на Java
```bash
cd <project-directory>
mvn clean install
mvn spring-boot:run
```

## Робочий процес розробки

### Готовність MCP 7-28

#### Чеклист готовності репозиторію

- [x] **Чіткість для нових учасників**: цей файл визначає призначення репозиторію,
  структуру, правила внесення внесків та шляхи налаштування прикладів.
- [x] **Команди збірки/тестування/лінтингу з точними прапорами**:
  - Лінтинг документації репозиторію:
    `npx --yes markdownlint-cli2 "**/*.md" "#node_modules" "#translations" "#translated_images"`
  - Аудит шаблону посилань у документації репозиторію:
    `find . -name "*.md" -not -path "*/node_modules/*" -not -path "./translations/*" -not -path "./translated_images/*" -print0 | xargs -0 grep -En "\[.*\]\(.*\)"`
  - Валідація прикладу TypeScript:
    `cd 03-GettingStarted/samples/typescript && npm ci && npm test && npm run build`
  - Валідація прикладу Python:
    `cd 10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/lab3/code/weather_mcp && python -m pip install -e . && pytest -q`
  - Валідація прикладу Java:
    `cd 03-GettingStarted/samples/java/calculator && mvn -B -ntp test verify`
- [x] **Один реалістичний робочий процес, який може стати інструментом MCP**:
  `validate_curriculum_change`
- [x] **Вхідні/вихідні дані є явними** (див. специфікацію нижче).
- [x] **Документовано права доступу та режими збоїв** (див. специфікацію нижче).
- [x] **Явність можливості тестування CI** (детерміновані команди, явні
  коди виходу та машинночитаємі виходи).

#### Кандидат робочого процесу інструменту MCP: `validate_curriculum_change`

##### Мета

Перевірити зміни в документації курсу та репрезентативному прикладному коді на коректність перед злиттям.


##### Вхідні дані

- `changed_paths: string[]` (обов’язково) — відносні шляхи, змінені в PR.
- `run_docs_lint: boolean` (за замовчуванням `true`)
- `run_links_audit: boolean` (за замовчуванням `true`)
- `run_samples: { typescript?: boolean, python?: boolean, java?: boolean }`
  (за замовчуванням всі `false`)

##### Вихідні дані

- `status: "ok" | "failed"`
- `checks: Array<{ name: string, command: string, exit_code: number,
  summary: string }>`
- `artifacts: Array<{ type: "log" | "report", path: string }>`
- `failed_checks: string[]`

##### Права доступу

- Читати файли робочого простору та записувати артефакти, згенеровані інструментом (наприклад, звіти лінтингу,
  журнали тестів) лише; без запису в `translations/` чи
  `translated_images/`.
- Виконувати локальні shell-команди.
- Опціональний доступ до мережі лише для відновлення пакетів (`npm ci`,
  `python -m pip install`, розв’язання залежностей `mvn`).
- Без права пушу, злиття чи модифікації `translations/` чи
  `translated_images/`.

##### Режими збоїв

- `E_NO_INPUT_PATHS`: `changed_paths` порожній.
- `E_INVALID_PATH`: вхідний шлях виходить за межі кореня репозиторію.
- `E_LINT_FAILED`: лінтинг markdown виходить з кодом відмінним від нуля.
- `E_LINK_AUDIT_FAILED`: команда аудиту посилань виходить з кодом відмінним від нуля.
- `E_SAMPLE_TEST_FAILED`: тест/збірка прикладу виходить з кодом відмінним від нуля.
- `E_TIMEOUT`: команда перевищила встановлений час очікування.

##### Рекомендована угода CI

Для автоматизації валідації налаштуйте CI-завдання, яке:

- Спрацьовує при pull-запитах, які зачіпають `*.md`, приклади коду або цей файл.
- Виконує точно наведені вище команди.
- Зберігає логи як артефакти.
- Завершує завдання з помилкою при будь-якому коді виходу відмінному від нуля.

#### Якщо ви розгортаєте MCP сервер з цього репозиторію

- [ ] Прочитайте остаточний журнал змін MCP `2026-07-28`:
  <https://modelcontextprotocol.io/specification/2026-07-28/changelog>
- [ ] Перевірте, що обрана версія SDK підтримує MCP `2026-07-28`:
  <https://modelcontextprotocol.io/docs/sdk>
- [ ] Видаліть припущення про сесії та рукостискання; розглядайте кожен запит як
  самодостатній:
  <https://modelcontextprotocol.io/specification/2026-07-28/basic/lifecycle>
- [ ] Надсилайте заголовки `Mcp-Method` та `Mcp-Name` для сирих HTTP-запитів:
  <https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http>
- [ ] Перевірте жорстко закодовані коди помилок (`missing resource` переміщено з `-32002` до `-32602`).

- [ ] Міграція застарілих Roots, Sampling, Logging та Dynamic Client
  Реєстрація:
  <https://modelcontextprotocol.io/specification/2026-07-28/deprecated>
- [ ] Перехід з експериментального API `2025-11-25` Tasks:
  <https://modelcontextprotocol.io/extensions/tasks>
- [ ] Перевірка авторизації для посилення безпеки OAuth та OpenID Connect:
  <https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization>

### Структура документації

- **Modules 00-11**: Основний навчальний курс у послідовному порядку
- **translations/**: Версії мовою (автоматично створюються, не редагувати безпосередньо)
- **translated_images/**: Локалізовані версії зображень (автоматично створюються)
- **images/**: Початкові зображення та діаграми

### Внесення змін до документації

1. Редагуйте лише англомовні markdown-файли у кореневих каталогах модулів (00-11)
2. Оновлюйте зображення в каталозі `images/`, якщо потрібно
3. GitHub Action co-op-translator автоматично згенерує переклади
4. Переклади відтворюються автоматично при пуші в гілку main

### Робота з перекладами

- **Автоматичний переклад**: робочий процес GitHub Actions керує всіма перекладами
- **Не редагуйте вручну** файли у каталозі `translations/`
- Метадані перекладу вбудовані у кожен перекладений файл
- Підтримувані мови: понад 48 мов, включаючи арабську, китайську, французьку, німецьку, хінді, японську, корейську, португальську, російську, іспанську та багато інших

## Інструкції для тестування

### Перевірка документації

Оскільки це переважно репозиторій документації, тестування зосереджене на:

1. **Аудит шаблону посилань**: перелік Markdown-посилань для перевірки

   ```bash
   # Перелік Markdown посилань (перевірка патернів)
   find . -name "*.md" -not -path "*/node_modules/*" -not -path "./translations/*" -not -path "./translated_images/*" -print0 | xargs -0 grep -En "\[.*\]\(.*\)"
   ```

2. **Перевірка зразків коду**: тестування, що приклади коду компілюються/запускаються

   ```bash
   # Перейдіть до конкретного зразка та запустіть його тести
   cd 03-GettingStarted/samples/typescript
   npm install && npm test
   ```

3. **Лінтування Markdown**: перевірка консистентності форматування

   ```bash
   # Використовуйте markdownlint за потреби
   npx --yes markdownlint-cli2 "**/*.md" "#node_modules" "#translations" "#translated_images"
   ```

### Тестування прикладів проекту

Кожен мовний приклад має власний підхід до тестування:

#### TypeScript/JavaScript
```bash
npm test
npm run build
```

#### Python
```bash
pytest
python -m pytest tests/
```

#### Java
```bash
mvn test
mvn verify
```

## Рекомендації щодо стилю коду

### Стиль документації

- Використовуйте зрозумілу мову, дружню до початківців
- Включайте приклади коду кількома мовами, якщо це доречно
- Дотримуйтесь найкращих практик Markdown:
  - Використовуйте заголовки стилю ATX (`#` синтаксис)
  - Використовуйте блоки коду з визначенням мови
  - Додавайте описовий alt-текст для зображень
  - Підтримуйте помірну довжину рядків (без жорстких обмежень, але розумно)

### Стиль зразків коду

#### TypeScript/JavaScript
- Використовуйте ES модулі (`import`/`export`)
- Дотримуйтесь суворого режиму TypeScript
- Додавайте анотації типів
- Цільова версія ES2022

#### Python
- Дотримуйтесь стилю PEP 8
- Використовуйте підказки типів, де це доречно
- Включайте докстрінги для функцій та класів
- Використовуйте сучасні можливості Python (3.8+)

#### Java
- Дотримуйтесь конвенцій Spring Boot
- Використовуйте можливості Java 21
- Дотримуйтесь стандартної структури проекту Maven
- Включайте коментарі Javadoc

### Організація файлів

```
<module-number>-<ModuleName>/
├── README.md              # Main module content
├── samples/               # Code examples (if applicable)
│   ├── typescript/
│   ├── python/
│   ├── java/
│   └── ...
└── solution/              # Complete working solutions
    └── <language>/
```

## Побудова і розгортання

### Розгортання документації

Репозиторій використовує GitHub Pages або подібні сервіси для хостингу документації (якщо застосовно). Зміни у гілці main запускають:

1. Робочий процес перекладу (`.github/workflows/co-op-translator.yml`)
2. Автоматичний переклад усіх англомовних markdown-файлів
3. Локалізацію зображень за потребою

### Процес побудови не потрібен

Цей репозиторій переважно містить документацію у форматі markdown. Кроки компіляції чи побудови для основного навчального курсу не потрібні.

### Розгортання прикладу проекту

Окремі приклади проектів можуть містити інструкції для розгортання:
- Див. `03-GettingStarted/09-deployment/` для керівництва з розгортання MCP сервера
- Приклади розгортання Azure Container Apps у `11-MCPServerHandsOnLabs/`

## Правила внесення внесків

### Процес Pull Request

1. **Fork та Клонування**: Відфоркать репозиторій і клонувати власний форк локально
2. **Створення гілки**: Використовуйте описові назви гілок (наприклад, `fix/typo-module-3`, `add/python-example`)
3. **Внесення змін**: Редагуйте лише англомовні markdown-файли (не переклади)
4. **Локальне тестування**: Перевірте коректне відображення markdown
5. **Надсилання PR**: Використовуйте чіткі назви та описи PR
6. **CLA**: Підпишіть Microsoft Contributor License Agreement при запиті

### Формат назви PR

Використовуйте чіткі, описові назви:
- `[Module XX] Короткий опис` для змін, що стосуються конкретного модуля
- `[Samples] Опис` для змін у прикладах коду
- `[Docs] Опис` для загальних оновлень документації

### Що можна внести

- Виправлення помилок у документації або прикладах коду
- Нові приклади коду додатковими мовами
- Уточнення та покращення існуючого контенту
- Нові кейс-стаді або практичні приклади
- Звіти про проблеми через нечіткий або некоректний контент

### Чого НЕ потрібно робити

- Не редагуйте файли у каталозі `translations/` безпосередньо
- Не редагуйте каталог `translated_images/`
- Не додавайте великі бінарні файли без попередньої дискусії
- Не змінюйте файли робочого процесу перекладу без узгодження

## Додаткові нотатки

### Підтримка репозиторію

- **Журнал змін**: Усі значущі зміни документуються у `changelog.md`
- **Навчальний гайд**: Використовуйте `study_guide.md` для огляду навігації по курсу
- **Шаблони Issues**: Використовуйте шаблони GitHub issues для звітів про помилки та запитів функцій
- **Кодекс поведінки**: Всі учасники повинні дотримуватись Microsoft Open Source Code of Conduct

### Навчальний шлях

Слідуйте модулям у послідовному порядку (00-11) для оптимального навчання:
1. **00-02**: Основи (Вступ, Основні концепції, Безпека)
2. **03**: Початок роботи із практичним виконанням
3. **04-05**: Практична реалізація та розширені теми
4. **06-10**: Спільнота, найкращі практики та застосування у реальному світі
5. **11**: Комплексні лабораторії інтеграції баз даних (13 послідовних лабораторій)

### Ресурси підтримки

- **Документація**: https://modelcontextprotocol.io/
- **Специфікації**: https://modelcontextprotocol.io/specification/2026-07-28/
- **Спільнота**: https://github.com/orgs/modelcontextprotocol/discussions
- **Discord**: сервер Microsoft Foundry Discord
- **Пов’язані курси**: Див. README.md для інших навчальних шляхів Microsoft

### Поширені проблеми

**П: Мій PR провалює перевірку перекладу**
В: Переконайтеся, що ви редагували лише англомовні markdown-файли у кореневих каталогах модулів, а не переклади.

**П: Як додати нову мову?**
В: Підтримка мов керується робочим процесом co-op-translator. Відкрийте issue для обговорення додавання нових мов.

**П: Зразки коду не працюють**
В: Переконайтеся, що ви виконали інструкції з налаштування у README конкретного зразка. Перевірте, що у вас встановлені правильні версії залежностей.


**П: Зображення не відображаються**

A: Перевірте, що шляхи до зображень відносні і використовують прямі слеші. Зображення повинні бути в каталозі `images/` або в `translated_images/` для локалізованих версій.

### Питання продуктивності

- Переклад може зайняти кілька хвилин
- Великі зображення потрібно оптимізувати перед комітом
- Тримайте окремі markdown-файли сфокусованими та помірного розміру
- Використовуйте відносні посилання для кращої портативності

### Управління проектом

Цей проект дотримується практик відкритого коду Microsoft:
- Ліцензія MIT для коду та документації
- Кодекс поведінки Microsoft Open Source
- Для внесків потрібна CLA
- Питання безпеки: Дотримуйтесь інструкцій у SECURITY.md
- Підтримка: Дивіться SUPPORT.md для ресурсів допомоги

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**Відмова від відповідальності**:
Цей документ було перекладено за допомогою сервісу штучного інтелекту для перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->