mcp-for-beginners / bg

# AGENTS.md

## Преглед на проекта

**MCP за начинаещи** е отворен образователен курс за изучаване на Model Context Protocol (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 workflow за поддръжка на много езици
- **Графични ресурси**: Централизирана директория с изображения с преведени версии

## Команди за настройка

Това е подредено хранилище, фокусирано върху документацията. Повечето настройки се извършват в отделни примерни проекти и лаборатории.

### Настройка на хранилището

```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` зависимост).
- Без права за push, merge или модификация на `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 requests, които засягат `*.md`, примерен код или този файл.
- Изпълнява точните команди, посочени по-горе.
- Запазва логовете като артефакти.
- Неуспешно приключва задачата при всеки код на изход различен от нула.

#### Ако пускате MCP сървър от това хранилище

- [ ] Прочетете окончателния MCP `2026-07-28` changelog:
  <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` за raw HTTP заявки:
  <https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http>
- [ ] Проверете твърдо кодирани кодове за грешки (`missing resource` преместен от `-32002` към `-32602`).
- [ ] Мигрирайте от остарелите Roots, Sampling, Logging и Dynamic Client
  Registration:
  <https://modelcontextprotocol.io/specification/2026-07-28/deprecated>
- [ ] Мигрирайте от експерименталния `2025-11-25` Tasks API:
  <https://modelcontextprotocol.io/extensions/tasks>
- [ ] Прегледайте упълномощаването за укрепване на OAuth и OpenID Connect:
  <https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization>

### Структура на документацията

- **Модули 00-11**: Основно съдържание на учебната програма в последователен ред
- **translations/**: Езиково специфични версии (автоматично генерирани, не редактирайте директно)
- **translated_images/**: Локализирани версии на изображения (автоматично генерирани)
- **images/**: Изходни изображения и диаграми

### Извършване на промени в документацията

1. Редактирайте само английските markdown файлове в основните директории на модулите (00-11)
2. Актуализирайте изображенията в директорията `images/` при необходимост
3. GitHub Action co-op-translator автоматично генерира преводите
4. Преводите се регенерират при push към главния клон

### Работа с преводите

- **Автоматизиран превод**: GitHub Actions workflow управлява всички преводи
- **НЕ редактирайте ръчно** файлове в директорията `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 стилова насока
- Използвайте type hints, където е подходящо
- Включвайте docstrings за функции и класове
- Използвайте модерни функции на 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 или подобно за хостинг на документацията (ако е приложимо). Промените по основния клон предизвикват:

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

### Без необходимост от процес за изграждане

Това хранилище съдържа главно markdown документация. Не е необходима компилация или билд стъпка за основното учебно съдържание.

### Разгръщане на примерни проекти

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

## Насоки за приноси

### Процес за Pull Request

1. **Форк и клониране**: Форкнете хранилището и го клонирайте локално
2. **Създаване на клон**: Използвайте описателни имена на клонове (напр., `fix/typo-module-3`, `add/python-example`)
3. **Направете промени**: Редактирайте само английските markdown файлове (не преводите)
4. **Тествайте локално**: Уверете се, че markdown се визуализира правилно
5. **Изпратете PR**: Използвайте ясни заглавия и описания на PR
6. **CLA**: Подпишете Microsoft Contributor License Agreement при поискване

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

Използвайте ясни, описателни заглавия:
- `[Модул XX] Кратко описание` за промени в конкретни модули
- `[Примери] Описание` за промени в примерния код
- `[Документация] Описание` за общи обновления на документацията

### Какво да допринасяте

- Поправки на грешки в документацията или примерния код
- Нови примери с код на допълнителни езици
- Уточнения и подобрения на съществуващо съдържание
- Нови казуси или практически примери
- Доклади за проблеми при неясно или неправилно съдържание

### Какво НЕ трябва да правите

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

## Допълнителни бележки

### Поддръжка на хранилището

- **Дневник на промените**: Всички значими промени са документирани в `changelog.md`
- **Учебно ръководство**: Използвайте `study_guide.md` за обзор на навигацията в учебната програма
- **Шаблони за проблеми**: Използвайте GitHub шаблони за доклади на грешки и заявки за функции
- **Кодекс на поведение**: Всички сътрудници трябва да спазват 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 файлове в основните директории на модулите, а не преведените версии.

**В: Как да добавя нов език?**
О: Поддръжката на езици се управлява чрез workflow co-op-translator. Отворете issue за обсъждане на добавяне на нови езици.

**В: Примерите с код не работят**
О: Уверете се, че сте следвали инструкциите за настройка в README на конкретния пример. Проверете дали имате правилните версии на зависимостите.

**В: Изображенията не се показват**

A: Уверете се, че пътищата към изображенията са относителни и използват наклонени напред черти. Изображенията трябва да са в директорията `images/` или `translated_images/` за локализирани версии.

### Съображения относно производителността

- Работният процес по превода може да отнеме няколко минути
- Големите изображения трябва да бъдат оптимизирани преди комитване
- Поддържайте отделните markdown файлове фокусирани и с разумен размер
- Използвайте относителни връзки за по-добра преносимост

### Управление на проекта

Този проект следва практиките на Microsoft за отворен код:
- Лиценз MIT за код и документация
- Кодекс на поведение на Microsoft за отворен код
- Изисква се CLA за приноси
- Проблеми със сигурността: Следвайте указанията в SECURITY.md
- Поддръжка: Вижте SUPPORT.md за ресурси за помощ

---

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