NotariumҚұжаттама
Құжаттама нұсқасы: latest
KZ

Агентті қосу

Notarium-ның ең негізгі ерекшелігі — сол бір білім қорының адамға да, ЖИ-агентке де бірдей ашық болуы. Сіз веб-редактор арқылы жұмыс істейсіз, агент — кіріктірілген MCP-эндпоинт арқылы, әрі оның өзгертулері дәл сіздікі сияқты нұсқаланады, рұқсаттармен шектеледі және шығу тегімен қолтаңбаланады. Бұл үшін бөлек сервис көтерудің қажеті жоқ: MCP шлюзі веб-интерфейспен бір процесте әрі бір портта тұрады.

Бұл бет — жылдам жол: токен шығару, эндпоинтті көрсету және агенттің білім қорын көретініне көз жеткізу. Толық контракт (құралдар, шақыру конвенциялары, жад, аудит, қауіпсіздік) — Агенттер және MCP бөлімінде.

1-қадам. Токен шығару

Агент жеке қатынау токенімен (PAT) аутентификацияланады. Оны өз аккаунтыңыздың параметрлерінде (токендер бөлімінде) шығарыңыз — сол жерде мыналар да белгіленеді:

  • ауқым — read немесе write (токеннің рұқсат шегі);
  • міндетті емес кеңістіктер бойынша тарылту — қай кеңістіктер қолжетімді;
  • міндетті емес қолданылу мерзімі.

Токен ntp_<id>_<secret> түрінде болады және тек бір рет көрсетіледі — оны бірден көшіріп алыңыз. Ағып кеткен PAT құқықтарын кеңейте алмайды: басқарушы әрекеттер (токен шығару, мүшелік, кеңістік құру) тек адам сессиясында ғана қолжетімді, токен арқылы емес.

Токеннің құқықтары — агенттің шегі

Read-only токен жазатын құралдарды физикалық түрде көрмейді: олар оның құралдар жиынтығында тіпті пайда болмайды. Бөтен кеңістік мүлдем қолжетімсіз. Агентке дәл тапсырмаға қажет құқықтарды ғана беріңіз.

2-қадам. Эндпоинтті көрсету

Агентті (немесе MCP-клиентті) эндпоинтке бағыттаңыз:

POST http://localhost:3000/mcp
Authorization: Bearer ntp_<id>_<secret>

Транспорт — ресми MCP-SDK-тан streamable-HTTP, stateless, әр сұранысқа бір JSON-жауап (GET/DELETE 405 қайтарады). Эндпоинт Claude API-дің MCP-коннекторымен және кез келген HTTP-MCP-клиентпен үйлесімді.

claude.ai және chatgpt.com веб-коннекторлары

Веб-интерфейстердің custom-коннекторларына PAT-ты кірістіру мүмкін емес — олар тек OAuth арқылы жұмыс істейді. Notarium жұқа OAuth-фасадты қамтиды: коннектор сіздің сессияңызбен кіріп, сол субъектке сәйкестендірілетін токен алады. Толығырақ — Агентті қосу бөлімінде.

3-қадам. Алғашқы шақыру — start_session

Жаңа сессияда агент алдымен start_session шақырады. Бір сұраныспен ол профильді, қолжетімді жобалар тізімін және өткен визиттен бергі өзгерістердің дельтасын алады, ал project параметрін берсеңіз — сол жобаның ықшам индексін де. Жұмысты осы контекстен бастаған жөн.

Одан әрі — таныс тәртіп: құрылымды шолу (list_notes, recent_activity), жазар алдында іздеу (search — дедуп), содан кейін жазу (create_note, edit_note, жад remember_about_user / remember_about_project). Агент әмбебап оқу/жазу операциялары арқылы емес, нақты тапсырмаларға арналған тар құралдар жиынтығы арқылы жұмыс істейді — әр құрал қауіпсіз әрекетті өзі міндеттейді (жазбаның класы, көрінуі, шығу тегі, сақтау кезінде нұсқаны тексеру, бөтен өзгерістерді басып қалмау үшін).

none-дананы желіге шығармаңыз

AUTH_MODE=none режимінде /mcp эндпоинті токенсіз ашық (жалғыз all-access субъект). Бұл жұмыс үстелі мен сенімді орта үшін ыңғайлы, бірақ мұндай дананы жария желіге шығаруға болмайды.

4-қадам. Мұны агент ережелеріне бекіту

Қай құралды шақыруды модель өзі шешеді, сондықтан «алдымен start_session шақыру» ережесін агенттің тұрақты нұсқауына (CLAUDE.md, AGENTS.md, Cursor ережелері, жүйелік промпт) жобаңыздың хэндлімен қоса бір рет жазып қойған жөн:

- Жаңа сессияның басында `notarium` MCP-серверінде
  `start_session(project: "acme/website")` шақыр.
- Кез келген жазудан бұрын алдымен `search(...)` — қосарлануларды көбейтпе.

Онсыз агентке білім қоры туралы әр жолы қолмен еске салуға тура келеді. Толығырақ, канон картасымен әрі глобалдық және жобалық ережелердің бөлінісімен, — Агент ережелері бетінде.

Әрі қарай