---
title: "Ниет құралдары"
description: "MCP шлюзіндегі 21 ниет құралының толық жиынтығы, мақсаты бойынша топталған: bootstrap, навигация, оқу, жазу, қайта ұйымдастыру және ауқымды операциялар."
---

# Ниет құралдары

MCP шлюзі агентке жалпы CRUD емес, **ниетке бағытталған 21 құрал** ұсынады — олардың әрқайсысы кестедегі операцияны емес, ниетті білдіреді («жазба құру», «контекстті еске түсіру», «жобаның атын өзгерту»). Мұндай жиынтық шектеулерді өз құрылымымен қояды: агент кеңістікті де, жазбаның класын да таңдамайды — оларды құралдың өзі белгілейді, ал токен рұқсаттары қандай құралдар жалпы көрінетінін шешеді.

Агент `tools/list` ішінде көретін атаулар мен сипаттамалар статикалық — оларға жазбалардың мазмұны ешқашан араласпайды (tool-poisoning-тен қорғаныс).

## Токен рұқсаттары — көріну шегі

`read`-токен тек оқу құралдарын көреді; жазу құралдары `tools/list` ішінде мүлдем пайда болмайды. Оның үстіне әр шақыру нақты кеңістікке қол жеткізуді бөлек тексереді. Сондықтан төмендегі кестелер — мүмкін болатын ең толық жиынтық; шын мәнінде не көретініңіз токеніңізге байланысты.

## Bootstrap

Сессия басындағы құралдар: мен кіммін, маған не қолжетімді, не өзгерді.

| Құрал | Мақсаты |
|---|---|
| `start_session` | Жаңа сессияда **бірінші** шақырылады. Бір сұрауда: пайдаланушы профилі (әрқашан жүктеледі), қолжетімді жобалар, ал `project` көрсетілсе — жобаның ықшам индексі (жазба саны + жоғарғы деңгейдегі қалталар), өткен визиттен бергі өзгерістердің дельтасы және `knownValues` (қолданыстағы категориялар мен тегтердің сөздігі). Идемпотентті; шақыру міндетті емес — тек контекст азырақ болады. |
| `whoami` | Мен кіммін (principal-id), шегім қандай (`read`/`write`), қай жобаларда мүшемін және қозғалтқыштың `capabilities` жиынтығы (`vector`/`trash`/`revisions`) — соқыр күйде байқап көрмеу үшін. |
| `get_my_projects` | Дайын хэндлдері бар қолжетімді жобалардың жалпақ тізімі — `project` аргументіне арналған. Хэндл әдетте `space/slug` түрінде болады, бірақ кеңістіктің түбірлік жобасында бір ғана сегментке жиырылады, сондықтан оны ережемен шығармай, жауаптан сол қалпында алады. Жеке домен тізімге кірмейді (ол токеннен айқын). |

> [!tip] Шақыру реті
> `start_session` → (жоба керек пе?) `get_my_projects` → құрылымды шолу: `list_notes`/`recent_activity` → жазар **алдында** `search`/`recall` → `create_note`/`remember_*`/`edit_note`/`link`.

Бұл рет — ұсыныс қана, механизм емес: қай құралды шақыруды модель шешеді. Ол өздігінен сақталуы үшін ретті агенттің тұрақты нұсқауына бекітіңіз — [Агент ережелері](/docs/agents/agent-files/).

## Discover — навигация

| Құрал | Мақсаты |
|---|---|
| `list_notes` | Білім қорының `ls`-і: қалтаның тікелей жазбалары мен ішкі қалталары (детерминистік, беттеуге келеді). `project` кеңістікті таңдайды, `path` — қалта (жауаптан сол қалпында алынады), `tag` сүзеді. Агенттің жадын емес, көрінетін жазбаларды тізеді. |
| `recent_activity` | Ең соңғы өзгертілген жазбалар («жақында нені қозғады, ревью керек»). Әр жазба бойынша: кім (адам/агент), қалай, қайда, қашан. Бұл `start_session`-дегі дельта емес. |

## Read — оқу және recall

| Құрал | Мақсаты |
|---|---|
| `search` | Гибридті іздеу (семантика + лексика, RRF арқылы); вектор қолжетімсіз болғанда іздеу толық мәтін (FTS) бойынша жұмысын жалғастырады — қатесіз. **Агенттің өз жадын да** қамтиды: «жазар алдында іздеу» ондағы қосарлануларды да жояды. Толық жазбаларды емес, `score` мен `path` қоса берілген, рейтингі бойынша реттелген сниппеттерді қайтарады. |
| `get_note` | Ref бойынша (note-id немесе wiki-ref) толық жазба: мазмұны, frontmatter, `path`, `class`, `versionToken` (қауіпсіз жазу үшін) және шығу тегі. `detailed` режимінде — қосымша `outline` (тақырыптар) мен `links` (граф қырлары). |
| `recall` | Тақырып төңірегіндегі контекст-бандлды токен-бюджет шегінде жинау: релевантты жазбалар **және** олардың граф-көршілері. `search`-тен бай: білімнен де, жеке жадтан да тартады. `budgetTokens` көлемін шектейді. |

`search` пен `recall` айырмашылығы туралы толығырақ — [Агент жады](/docs/agents/memory/).

## Write — жазу және ниет

| Құрал | Мақсаты |
|---|---|
| `create_note` | Жобада жаңа ортақ (KB) жазба құру, класы — `user-doc`. Жазбаның тақырыбын `body` (Markdown) ішіндегі бастапқы `# H1` белгілейді; `path?` — баратын қалта; `type?`/`tags?` — міндетті емес оверрайд-параметрлер; `links?` типтелген қырларды бірден қосады. Класты да, кеңістікті де агент таңдамайды. |
| `remember_about_user` | Пайдаланушы туралы ұзақ өмір сүретін фактіні (қалаулары, контексті) оның жеке жадына жазу. `category` астына `observation` үстеп жазылады. |
| `remember_about_project` | Жоба туралы фактіні агенттің жеке жадына жазу (класы `agent-memory`, `remember_about_user`-ге симметриялы). Ортақ білім емес — ол үшін `create_note` бар. |
| `edit_note` | Жазбаны позиция бойынша емес, сөз бойынша инкрементті түзету: `append`/`prepend`, `replace` (дене түгелдей), `replaceSection` (тақырып бойынша), `findReplace` (бірегей сниппет; бос `content` = жою). `versionToken` талап етеді (CAS). |
| `delete_note` | Жазбаны **себетке** жылжыту — агенттің жалғыз деструктивті әрекеті әрі құрылымы бойынша қайтарымды. Қалпына келтіруді де, себетті тазартуды да тек адам жасайды. |
| `link` | `from`→нысана түріндегі типтелген байланыс. Нысана — `to` (note-id) немесе `toTitle` (әлі құрылмаған жазбаның тақырыбы бойынша forward-ref). Екі жазба да бір кеңістікте болуға тиіс. |

> [!important] Жазу CAS қорғауымен
> `edit_note` жаңа ғана алынған `get_note`-тың `versionToken`-ін талап етеді. Қатарлас түзету `versionConflict` қатесін қайтарады — құрал бөгде өзгерістерді үнсіз баспайды, агент қайта оқып, әрекетті қайталайды.

## Reorganize — қайта ұйымдастыру

Қайта ұйымдастыру құралдарының грамматикасы — `verb_entity`. Жазба id-і арқылы, қалта `path`-ы арқылы, жоба хэндлі арқылы адрестеледі.

| Құрал | Мақсаты |
|---|---|
| `move_note` | Жазбаны атын сақтай отырып басқа қалтаға жылжыту. id мен URL тұрақты қалады, кіріс сілтемелер үзілмейді. |
| `rename_note` | Жазбаның тақырыбын өзгерту. Link-safe: ескі тақырып alias-тарихқа өтеді, кіріс `[[сілтемелер]]` резолвтеле береді. |
| `move_folder` | Қалтаны ішіндегісімен түгел басқа аталық қалтаға жылжыту. Ішіндегі барлық жазбалардың id-і тұрақты. |
| `rename_folder` | Қалтаның атын орнында өзгерту. Егер қалта — жоба болса, оның хэндлі өзгермейді (хэндл үшін — `rename_project`). |
| `rename_project` | Жобаның хэндлін және/немесе адам оқитын атауын өзгерту. Link-safe: ескі хэндл alias-қа өтеді. |

## Scale — миграция ауқымы

| Құрал | Мақсаты |
|---|---|
| `create_notes` | Бір жобада бір шақырумен бірнеше KB-жазба құру. Best-effort, транзакциялық емес: `results[]` әрқайсысын `ok`/`error` деп белгілейді — тек сәтсіз болғандарын қайталау керек. |
| `link_many` | Бір шақырумен бірнеше типтелген байланыс құру. Best-effort, идемпотентті. |

## Әрі қарай

- [Агент жады](/docs/agents/memory/) — remember мен recall егжей-тегжейлі.
- [Контекст жиынтықтары мен бекітулер](/docs/agents/context-pins/) — `start_session`-ге не түседі.
- [Қауіпсіздік және көріну](/docs/agents/security/) — бұл жиынтық «lethal trifecta»-ны қалай үзеді.