# bansko.be MCP — референция

Версия 1.0.0 · протокол 2025-06-18 · Streamable HTTP · JSON отговори · без ключ · само четене

## Връзка

- Endpoint: https://bansko.be/mcp
- Discovery: https://bansko.be/.well-known/mcp.json
- Документация за хора: https://bansko.be/ai
- Тази референция: https://bansko.be/ai/docs.md

Всяка заявка е самостоятелна. Няма сесии и няма нужда от initialize преди tools/call.

### Пример с curl

```bash
curl -X POST https://bansko.be/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_places","arguments":{"q":"аптека","limit":2}}}'
```

## Правила за употреба

- Всеки отговор съдържа url. Цитирай го, когато предаваш данните на човек.
- Никога не измисляй телефон, адрес или работно време. Ако полето липсва, кажи, че не е известно.
- Сървърът е само за четене. Няма лични данни, няма акаунти, няма писане.
- Няма API ключ и няма лимит на заявките за нормална употреба. Не прави повече от 10 заявки в секунда.
- Данните са на български. name_en и label_en са налични, където има превод.

## Инструменти

### search_places

Търси в публичния указател на Банско по име, категория или адрес.

Кога: Човек пита за аптека, месарница, ресторант, ветеринар, или споменава име на обект.

| Параметър | Тип | Задължителен | Описание |
|---|---|---|---|
| q | string, 2–120 знака | да | Име, категория или част от адрес. Кирилица и латиница. |
| limit | integer, 1–12 | не | Колко места да върне. По подразбиране 8. |

Заявка:

```json
{
  "name": "search_places",
  "arguments": {
    "q": "аптека",
    "limit": 2
  }
}
```

Отговор (content[0].text):

```json
{
  "query": "аптека",
  "count": 2,
  "places": [
    {
      "name": "Аптека Азарум 1",
      "name_en": "Аптека Азарум 1",
      "category": "Аптека",
      "address": "гр. Банско, ул. Луи Пастьор 4",
      "phone": "+35974982161",
      "open": true,
      "lat": 41.8354012,
      "lng": 23.4915049,
      "url": "https://bansko.be/shop/apteka-azarum-1"
    }
  ]
}
```

- Кратките думи „при“, „на“, „до“ се пренебрегват при търсене, освен ако са единствените.
- Съвпадение по име тежи повече от съвпадение по адрес или категория.
- Полетата phone, hours и website липсват, когато не са известни. Не ги измисляй.

### get_place

Пълната публична карта на обект по slug или id от адрес на bansko.be.

Кога: Имаш URL или slug от search_places и ти трябват всички публични данни.

| Параметър | Тип | Задължителен | Описание |
|---|---|---|---|
| ref | string, 1–160 знака | да | Slug или id от /shop/{ref}. Например butchery-pri-dinko. |

Заявка:

```json
{
  "name": "get_place",
  "arguments": {
    "ref": "butchery-pri-dinko"
  }
}
```

Отговор (content[0].text):

```json
{
  "name": "Месарница При Динко Банско",
  "name_en": "Pri Dinko Butchery Bansko",
  "category": "Месарница",
  "address": "кв. Новия град, ул. „Глазне“ 43, 2770 Банско",
  "phone": "+359885005733",
  "hours": "08:00-19:00",
  "open": true,
  "lat": 41.8356923,
  "lng": 23.4832742,
  "url": "https://bansko.be/shop/butchery-pri-dinko"
}
```

- Ако обектът не съществува или не е публичен, отговорът е грешка с isError: true и текст „No public place found for …“.

### list_categories

Категориите в указателя: аптеки, месарници, ресторанти, хотели и други.

Кога: Трябва ти общ преглед какво има в Банско, или slug на категория за връзка.

Без параметри.

Заявка:

```json
{
  "name": "list_categories",
  "arguments": {}
}
```

Отговор (content[0].text):

```json
{
  "categories": [
    {
      "id": "pharmacy",
      "label_bg": "Аптека",
      "label_en": "Pharmacy",
      "url": "https://bansko.be/find/pharmacy"
    }
  ]
}
```

- Полето url води към публичната страница на категорията с всички места в нея.

### list_trades

Занаятите в Банско, или публичните профили в един занаят.

Кога: Човек търси водопроводчик, електротехник, бояджия, ски инструктор.

| Параметър | Тип | Задължителен | Описание |
|---|---|---|---|
| trade | string, 1–80 знака | не | Slug на занаят, например electrician. Без него връща каталога. |

Заявка:

```json
{
  "name": "list_trades",
  "arguments": {}
}
```

Отговор (content[0].text):

```json
{
  "trades": [
    {
      "id": "plumbing",
      "label_bg": "ВиК",
      "label_en": "Plumbing",
      "count": 3,
      "url": "https://bansko.be/majstori/plumbing"
    },
    {
      "id": "electrical",
      "label_bg": "Електро",
      "label_en": "Electrical",
      "count": 2,
      "url": "https://bansko.be/majstori/electrical"
    }
  ]
}
```

- С trade отговорът е { trade, providers[] }, където всеки provider има name, trade, rating, reviewCount, verified, url.
- verified: true означава проверен от екипа на bansko.be профил.

### list_news

Последните 24 публични новини от Банско: община, събития, спорт, туризъм.

Кога: Човек пита какво се случва в града, за ремонти, събития, съобщения на общината.

Без параметри.

Заявка:

```json
{
  "name": "list_news",
  "arguments": {}
}
```

Отговор (content[0].text):

```json
{
  "articles": [
    {
      "title": "От 23 септември: ремонт на ул. „Ванюша Валчук“ и „Иван Попов Деницин“ в Добринище",
      "category": "municipality",
      "date": "2026-09-21",
      "source": "Кметство Добринище",
      "summary": "От 23 септември (сряда) започват ремонтни дейности на улиците…",
      "url": "https://bansko.be/news/from-23-september-repairs-on-vanyusha-valchuk-and-ivan-popov-denitsin-st"
    }
  ]
}
```

- summary е първите 280 знака от текста. За целия текст ползвай get_news с url или slug.
- Категориите са municipality, events, sport, tourism, culture, community.

### get_news

Целият текст на новина по slug или id.

Кога: Имаш url или slug от list_news и трябва пълният текст.

| Параметър | Тип | Задължителен | Описание |
|---|---|---|---|
| ref | string, 1–200 знака | да | Slug или id от /news/{ref}. |

Заявка:

```json
{
  "name": "get_news",
  "arguments": {
    "ref": "from-23-september-repairs-on-vanyusha-valchuk-and-ivan-popov-denitsin-st"
  }
}
```

Отговор (content[0].text):

```json
{
  "title": "От 23 септември: ремонт на ул. „Ванюша Валчук“ и „Иван Попов Деницин“ в Добринище",
  "category": "municipality",
  "date": "2026-09-21",
  "source": "Кметство Добринище",
  "sourceUrl": "https://…",
  "body": "От 23 септември (сряда) започват ремонтни дейности…",
  "url": "https://bansko.be/news/from-23-september-repairs-on-vanyusha-valchuk-and-ivan-popov-denitsin-st"
}
```

- body е до 4000 знака.
- Цитирай source и url, когато предаваш новината.

## Ресурси

- bansko://about (text/markdown): Какво е bansko.be, кои са публичните страници и как се цитира. Същото съдържание като /llms.txt.

## Грешки

| Код | Значение |
|---|---|
| -32602 | Невалидни аргументи. Текстът казва кое поле и защо, например q под 2 знака. |
| -32601 | Непознат инструмент или метод. |
| -32603 | Вътрешна грешка на сървъра. Опитай отново след секунда. |
| isError: true | Инструментът е приел аргументите, но няма резултат: обектът не съществува или не е публичен. Не е грешка на протокола. |

## Клиенти

- Claude: Settings → Connectors → Add custom connector. Постави адреса на сървъра. Без OAuth.
- ChatGPT: Settings → Apps → Advanced / Developer mode → New MCP server. Authentication: None.
- Grok и X: Добави remote MCP сървър с този URL. Транспортът е Streamable HTTP.
- Cursor: В mcp.json: { "mcpServers": { "bansko": { "url": "https://bansko.be/mcp" } } }

## Обхват на данните

- Места: публичният указател на Банско и Добринище с адреси, телефони, работно време и координати, когато са потвърдени.
- Майстори: публични профили с оценка и брой отзиви. Телефонът не се дава през MCP; връзката е през url.
- Новини: местни новини с посочен източник. bansko.be обобщава, не е първоизточник.
- Няма: лични профили, съобщения, обяви в борсата с контакти, кадастрални данни. Кадастърът е достъпен на картата на сайта.

## Лиценз и цитиране

Данните са публични и могат да се предават на потребители с посочване на bansko.be и url на записа. Масово копиране на указателя за друг продукт не е разрешено.