Ново: Дай на своя AI агент българския WordPress опит

Преди няколко месеца ви обещахме чат асистент на българската WP общност, но докато се накумиме – те излязоха от мода.

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

1. Резюме

FB групите са най-богатият източник на локално техническо знание в България – и същевременно най-трудният за търсене. WPBulgaria MCP решава този проблем, като индексира съдържанието на групата и го поднася на AI агента на потребителя през Model Context Protocol (MCP).

Какво постигнахме:

👉 Хибридно търсене (пълнотекстово + семантично, слети с Reciprocal Rank Fusion), което намира дискусия дори когато потребителят не помни точните думи.

👉 Три MCP инструмента и три готови промпта, които всеки MCP‑съвместим клиент (Cursor, Claude Code, VS Code, Codex, ChatGPT, Claude.ai, Antigravity) може да ползва след едно конфигурационно поле.

👉 Отговори с директни линкове към оригиналния пост и коментарите – агентът не преразказва, а цитира и препраща.

👉 Редакторски контрол и квоти – админ панел за включване/изключване на съдържание, планове с лимити и API ключове.

👉Автоматизиран прием на данни – indexer → webhook → опашка → вграждания в Qdrant, без ръчна намеса.

2. Контекст: за WPBulgaria

WPBulgaria е общност около WordPress в България – сайт, събития и Facebook група, която е най‑голямата WordPress общност на Балканите. Всеки ден в нея се случват множество разговори: проблеми с хостинг доставчици, съвместимост на плъгини, миграции, цени на клиентски проекти, локални особености (български платежни решения, счетоводен софтуер, доставчици на домейни, GDPR практики).

Това е знание, което не съществува в англоезичния интернет. Точно затова е и толкова ценно за AI агент, който помага на български разработчик или собственик на сайт.

3. Проблемът

3.1 Търсенето в социалната мрежа е практически неизползваемо

Всеки член на голяма група познава усещането: сигурен си, че темата е била обсъждана – може би дори си коментирал в нея – но не можеш да я намериш. Причините са структурни:

• Само по ключови думи. Ако постът казва „сайтът гърми след ъпдейт“, а ти търсиш „бял екран PHP 8.3“, резултат няма да има.
• Няма езикова нормализация. Българският се пише с различни падежни форми, на кирилица и на латиница (шльокавица), със и без диакритика в имената на продуктите. Търсачката третира това като различни думи.
• Подредба по ангажираност, не по релевантност. Най-полезният отговор често е закопан в коментар с 3 реакции под пост с 50 коментара.
• Знанието е в коментарите, не в поста. Постът е въпрос; решението е четиридесетият коментар подред.
• Няма стабилни линкове и филтри. Няма как да ограничиш по период, автор или тип съдържание, а безкрайният скрол прави ръчното преглеждане невъзможно.

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

3.2 AI агентите нямат локален контекст

Паралелно с това всички започнаха да работят с AI агенти. Но когато попиташ агент „кой български хостинг е подходящ за WooCommerce с 5000 продукта“, той отговаря с общи, глобални и често остарели съвети – или направо халюцинира, защото в обучаващите му данни просто няма българския опит.

Агентът има разсъждаваща способност, но му липсва актуалната, локална, преживяна практика на общността.

3.3 Цената на проблема

4. Цели и критерии за успех

Дефинирахме проекта около четири измерими цели:

1. Намираемост. Заявка на естествен език, без точните думи от поста, да връща релевантния пост в топ резултатите.
2. Проверимост. Всеки резултат да носи URL към поста и към конкретните коментари, за да може човекът да провери първоизточника.
3. Съвместимост. Интеграция с произволен MCP клиент за под 5 минути, без инсталиране на локален софтуер.
4. Контрол. Общността да запази контрол върху това какво е индексирано, кой има достъп и колко може да ползва.

Изрично не беше цел: да построим собствен чат интерфейс. Хората вече имат любим агент – нашата работа е да го захраним с контекст.

5. Защо MCP, а не поредният чатбот

Разгледахме три подхода:

MCP превърна дистрибуцията в тривиален проблем: вместо да убеждаваме хората да ползват нов продукт, ние допълваме инструмента, който вече ползват. Един JSON блок в конфигурацията и агентът в Cursor вече „познава“ българската WordPress общност.

6. Решението – общ преглед

Целият продукт е един Laravel монолит: публичен лендинг с форма за кандидатстване, потребителско табло с API ключове и квоти, админ панел за съдържанието и MCP/REST слой за агентите.

7. AI-assisted development: как беше построено това

Проектът е разработен предимно с AI агенти (Cursor) – и самият процес беше източник на не по-малко изводи от продукта.

Какво проработи:

• Конвенционална рамка = добър агент. Laravel има предвидима структура: агентът знае къде отива middleware, къде – service, къде – миграция. Малко от контекстния прозорец се харчи за обяснения „как е подредено тук“.
• Тънки, еднозадачни услуги. QueryTransformer, PostDocumentBuilder, QdrantClient, HybridPostSearch – всяка има една отговорност и се събира в контекста наведнъж. Агент, който вижда целия файл, прави далеч по-малко грешки от агент, който гадае за половината.
• PHPDoc array shapes като договор. Описаните форми на масивите (array{original: string, primary: string, keywords: list<string>, …}) карат агента да генерира съвместим код при следващата промяна и правят рефакторите безопасни.
• Тестове около рисковите места, не навсякъде. Покрити са именно частите, където агентът най-лесно би счупил нещо тихо: MCP инструментите, поведението при трансформация на заявката, webhook‑ът, импортният job.
• Работа на вертикални срезове. „Добави инструмент X от route до тест“ дава по-добър резултат от „напиши всички модели“, защото всеки срез има наблюдаема, проверима крайна точка.

Какво изискваше човешка намеса:

• Продуктовите решения. Че се вгражда пост заедно с коментарите, че коментарите се подреждат по реакции, че RRF е правилният начин за сливане – това са решения, произтичащи от разбиране на проблема, а не от кода.
• Устойчивостта при грешка. Първите варианти бяха от типа „щастлив път“. Изричното изискване „ако Qdrant падне, търсенето трябва да продължи“ и „кеширай трансформацията“ дойде от ревю, не от генерация.
• Промптите за агента. Описанията на инструментите бяха преписвани няколко пъти, докато агентите започнат да извикват правилния инструмент в правилния момент — това е UX работа, вършена с тестване на живо.

Затварящият кръг: продуктът е инструмент за AI агенти, построен с AI агенти и тестван, като на агент се дава реална задача и се наблюдава дали ще стигне до верния пост. Ако не стигне, поправяш описанието, трансформацията или сливането – и опитваш пак.

8. Резултати

Доставено:

Ефект върху потребителското преживяване:

Преди: „Търсих в групата 20 минути, не намерих нищо, питам отново.“

Сега: потребителят пита агента си „Сайтът ми показва бял екран след ъпдейт на PHP – какво съветва общността?“ Агентът извиква search-posts, получава релевантните дискусии заедно с най-харесваните коментари и връща обобщение с директни линкове към оригиналните постове. Отговорът е локален, актуален и проверим – а човекът така и не отваря Facebook.

Какво измерваме: потребление по квоти на потребител и инструмент (plan_item_usages), последно ползване на всеки API ключ, обхват на индекса (общо срещу включени постове), heartbeat на worker‑а и – най-важното за релевантността – разпределението на ranks.fulltext спрямо ranks.vector в резултатите, което показва кой клон реално върши работата за реалните заявки.

9. Научени уроци

1. Единицата за вграждане е по-важна от модела. Преминаването от „пост“ към„пост + подредени по реакции коментари“ промени качеството повече от всяка настройка на модел или параметър.
2. Хибридно > семантично. Реалните заявки съдържат имена на плъгини, версии и съобщения за грешка. Чисто векторното търсене се проваля точно там, където потребителят е най-конкретен.
3. RRF е правилният компромис. Сливане по позиции елиминира калибрирането на несъпоставими резултати – минимален код, максимална стабилност.
4. Всяка LLM зависимост трябва да е опционална. Трансформацията на заявката и векторният клон могат да отпаднат, без продуктът да спре да работи.
5. Описанието на инструмента е потребителски интерфейс. Пишеш го за агент – и то определя дали инструментът изобщо ще бъде извикан.
6. Модерацията трябва да е един превключвател. is_included контролира и двата индекса; всичко останало би довело до разминаване между тях.
7. Дистрибуцията беше решена от протокола. Нулев нов интерфейс за научаване се оказа най-силната продуктова характеристика.

10. Какво следва

• Отделно индексиране на коментарите като самостоятелни точки с връзка към родителския пост, за по-прецизно извличане на дълги дискусии.
• Филтри по период, група и автор в search-posts.
• MCP resources за директно четене на конкретен пост по ID.
• Повече източници – други общности и групи през същия конвейер.
• OAuth като алтернатива на API ключовете за клиенти, които го поддържат.
• Публични планове след края на бетата.

Архитектурата е умишлено обща: „група в социална мрежа → MCP“ е шаблон, а не еднократно решение. Същият конвейер може да захрани всяка общност, чието знание днес е заключено във вечния скрол.

11. Технически справочник

Endpoint-и:

GET/POST  /mcp/wpbulgaria      MCP (Bearer API ключ)
GET/POST  /api/search          Хибридно търсене (REST)
GET       /api/posts/latest    Най-нови постове (REST)
GET       /up                  Health check

Примерна конфигурация в клиент (Cursor):

{
  "mcpServers": {
    "wpbulgaria": {
      "url": "https://<домейн>/mcp/wpbulgaria",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

12. За автора

Sashe Vuchkov – продуктов и софтуерен разработчик, автор на WPBulgaria MCP. Проектът е създаден за общността на WPBulgaria.com с идеята, че знанието на една общност трябва да е достъпно там, където хората работят – днес това все по-често е техният AI агент.

Искаш подобен MCP сървър за твоята общност или група? Свържи се със Sashe Vuchkov.