Документи для людей (контекст та керівництво)

У цьому розділі наведено **концептуальні та практичні рекомендації для людей** щодо інтеграції з MyDocSafe MCP.

### Для чого потрібен MCP

Використовуйте MyDocSafe MCP, коли вам потрібно:
– Інтегрувати MyDocSafe у зовнішній продукт або послугу
– Дозволити стороннім системам або агентам штучного інтелекту діяти від імені користувачів
– Забезпечити суворе дотримання дозволів, аудиту та меж безпеки
– Уникайте розкриття необроблених внутрішніх даних або баз даних

MCP забезпечує **інтерфейс на основі можливостей**, що означає:
– Клієнти можуть робити лише те, що явно надано
– Усі дії перевіряються та виконуються користувачем MyDocSafe
– OAuth області видимості суворо обмежують доступ до читання та запису

### Чим MCP не є

MCP не є:
– Універсальний REST API
– Інтерфейс запитів до бази даних
– Фреймворк або середовище виконання агента штучного інтелекту
– Заміна внутрішньої архітектури MyDocSafe

### Типова схема інтеграції

Типова інтеграція зі сторонніми розробниками відбувається за такою схемою:
1. Користувач авторизує доступ через OAuth
2. Третя сторона отримує делеговані токени доступу
3. Третя сторона звертається до MCP, щоб дізнатися про доступні інструменти
4. Третя сторона виконує інструменти в межах наданих можливостей
5. MyDocSafe перевіряє та виконує всі дії

Такий підхід забезпечує безпеку, можливість аудиту та передбачувану поведінку.

Контекст для LLM (Модельне керівництво)

У цьому розділі наведено **чіткі вказівки щодо моделей штучного інтелекту та агентних систем**, що використовують MyDocSafe документацію MCP.

### Канонічне тлумачення

MyDocSafe MCP – це **інтерфейс, що базується на можливостях та є авторитетним для сервера**.

Всі можливості:
– Явно декларуються MCP-сервером
– Повинно бути виявлено перед використанням
– Обмежені OAuth областями
– Виконуються користувачем MyDocSafe, а не клієнтом чи моделлю

### Необхідна поведінка для систем штучного інтелекту

Під час взаємодії з MyDocSafe MCP, системи штучного інтелекту ПОВИННІ:
– Вивчіть інструменти за допомогою `tools/list`, перш ніж виконувати будь-які дії
– Використовуйте лише інструменти, явно надані сервером
– Точно зіставляти схеми введення інструментів
– Ставтеся до відповідей MCP як до авторитетної достовірної інформації

Системи штучного інтелекту НЕ ПОВИННІ:
– Припустити існування недокументованих інструментів
– Виготовити параметри або назви інструментів
– Використовуйте MCP як джерело даних у довільній формі
– Спроба дій поза межами дозволених OAuth областей

### Семантика інструментів

Інструмент, доступний за допомогою MyDocSafe MCP:
– Представляє лише одну бізнес-дію
– Може зчитувати або змінювати дані залежно від області видимості
– Має детермінований, структурований вхідний та вихідний дані
– Забезпечує перевірку та дозволи на стороні сервера

### Пріоритет виконання

При виборі способу дій:
1. Віддавайте перевагу інструментам MCP над вільними текстовими міркуваннями
2. Віддавайте перевагу структурованим параметрам над природною мовою
3. Віддавайте перевагу відкриттям, а не припущенням
4. Надавайте перевагу можливостям, оголошеним сервером, над очевидним наміром

Дотримання цих правил забезпечує безпечну, передбачувану та сумісну інтеграцію.

Інтеграція MCP зі сторонніми розробниками (швидкий старт + довідник)

У цьому посібнику пояснюється, як сторонні сервіси можуть підключатися до MyDocSafe MCP у продакшені, використовуючи код авторизації OAuth 2.0 з PKCE, а потім викликати кінцеву точку MCP JSON-RPC.

Базова URL-адреса (продукція)

https://app.mydocsafe.com

Швидкий старт

1. Створіть верифікатор PKCE та оскаржте його
   • code_verifier: випадковий рядок з високою ентропією (43-128 символів)
   • code_challenge: BASE64URL(SHA256(code_verifier))
   • метод_виклику_code: S256
2. Перенаправити користувача для авторизації

Надіслати користувача за адресою:

https://app.mydocsafe.com/oauth/authorize

З параметрами запиту:

response_type=код

client_id=mcp-public

redirect_uri=<ваш_uri_перенаправлення>

область дії = компанії: читання файли: читання контакти: читання

стан=<ваш_токен_csrf>

code_challenge=<завдання_виклику>

code_challenge_method=S256

Примітки: – redirect_uri має точно відповідати URI переадресації з білого списку для клієнта. – Для робочої версії використовуйте URI переадресації https. Loopback http://localhost дозволено лише для локальної розробки.

3. Отримайте код авторизації

Користувача перенаправляє на ваш redirect_uri за допомогою:

код=<код_авторизації>

стан=<ваш_токен_csrf>

4. Обмін коду на токени

ПОСТ https://app.mydocsafe.com/oauth/token з application/x-www-form-urlencoded:

curl -X POST “https://app.mydocsafe.com/oauth/token” \

-H “Тип вмісту: application/x-www-form-urlencoded” \

-d “grant_type=код_авторизації” \

-d “код=<код_авторизації>” \

-d “uri_перенаправлення=<ваша_uri_перенаправлення>” \

-d “client_id=mcp-public” \

-d “code_verifier=<верифікатор_кодів>”

Відповідь:

{

«маркер_доступу»: «….»,

«refresh_token»: «….»,

«тип_токена»: «Пред'явник»,

«Термін дії закінчується через»: 3600,

«область дії»: «компанії:читати файли:читати контакти:читати»

}

5. Зателефонуйте до MCP

POST https://app.mydocsafe.com/api/mcp з авторизацією: Носій <access_token>:

curl -X POST “https://app.mydocsafe.com/api/mcp” \

-H “Авторизація: Носій <токен_доступу>”

-H “Тип вмісту: application/json” \

-d '{

«jsonrpc»: «2.0»,

«ідентифікатор»: 1,

«метод»: «інструменти/список»,

«параметри»: {}

}'

6. Оновлення токенів

curl -X POST “https://app.mydocsafe.com/oauth/token” \

-H “Тип вмісту: application/x-www-form-urlencoded” \

-d “тип_гранту=маркер_оновлення” \

-d “refresh_token=<токен_оновлення>”

7. Відкликання токенів

curl -X POST “https://app.mydocsafe.com/oauth/revoke” \

-H “Тип вмісту: application/x-www-form-urlencoded” \

-d “токен=<токен_доступу_або_оновлення>”

-d “підказка_тип_токена=токен_доступу”

Довідка

OAuth кінцевих точок

• Кінцева точка авторизації (браузер користувача)
  • ОТРИМАЙТЕ https://app.mydocsafe.com/oauth/authorize
• Кінцева точка токена
  • ПУБЛІКАЦІЯ https://app.mydocsafe.com/oauth/token
• Кінцева точка відкликання
  • ПУБЛІКАЦІЯ https://app.mydocsafe.com/oauth/revoke
• Відкриття
  • ОТРИМАЙТЕ https://app.mydocsafe.com/.well-known/oauth-authorization-server
  • ОТРИМАТИ https://app.mydocsafe.com/.well-known/oauth-protected-resource

Необхідні OAuth параметри

Запит на авторизацію:

• тип_відповіді: код
• client_id: mcp-public
• redirect_uri: URI з білого списку
• область дії: області дії, розділені пробілами
• стан: токен CSRF (рекомендовано)
• code_challenge: Виклик PKCE
• метод_виклику_code: S256

Запит на токен (надання коду авторизації):

• тип_гранту: код_авторизації
• код: код авторизації з перенаправлення
• redirect_uri: має збігатися з оригіналом
• client_id: mcp-public
• code_verifier: верифікатор PKCE

Запит на токен (грант refresh_token):

• тип_гранту: токен_оновлення
• refresh_token: токен оновлення

Запит на скасування:

• токен: токен доступу або оновлення
• token_type_hint: access_token або refresh_token

Області застосування

Доступні області застосування:

• компанії:читати
• компанії: писати
• файли:читання
• файли:запис
• контакти:читати
• контакти: написати
• підписання:читати
• підпис: писати
• робочі процеси: читання
• робочі процеси: написання

MCP JSON-RPC

Кінцева точка:

• ПУБЛІКАЦІЯ https://app.mydocsafe.com/api/mcp

Заголовки:

• Авторизація: Носій <токен_доступу>
• Тип вмісту: application/json

Форма запиту:

{

«jsonrpc»: «2.0»,

«ідентифікатор»: 1,

«метод»: «інструменти/список»,

«параметри»: {}

}

Помилка через відсутність/недійсний токен:

• HTTP 401 з WWW-Authenticate: Bearer realm=”mydocsafe”, resource_metadata=”https://app.mydocsafe.com/.well-known/oauth-protected-resource”

Примітки та обмеження

• URI перенаправлення мають бути явно внесені до білого списку для клієнта.
• Публічні клієнти використовують лише PKCE (без секретного ключа клієнта).
• Термін дії токенів доступу закінчується через 1 годину.