Как написать свой коннектор

Коннектор EDL OS — это TypeScript-модуль, который описывает источник данных (REST API, базу, файл) и набор tools, которые AI-агент может вызвать. Минимальный коннектор пишется за 30 минут.

Анатомия коннектора

Каждый коннектор живёт в отдельной папке connectors/<name>/ и содержит:

connectors/my-api/
├── manifest.ts      // метаданные + список tools
├── auth.ts          // OAuth / API-key handshake
├── tools/
│   ├── list_users.ts
│   └── get_order.ts
└── README.md

Шаг 1 · Создайте манифест

Манифест объявляет имя, версию и список tools:

// connectors/my-api/manifest.ts
import { defineConnector } from '@edl-os/sdk';
import { listUsers } from './tools/list_users';
import { getOrder } from './tools/get_order';

export default defineConnector({
  name: 'my-api',
  version: '0.1.0',
  displayName: 'My API',
  auth: { type: 'oauth2', authUrl: 'https://my-api.com/oauth' },
  tools: [listUsers, getOrder],
});

Шаг 2 · Опишите tool

Tool — это функция с JSON-схемой входа/выхода. SDK сам зарегистрирует её в tools/list и передаст MCP-клиенту.

// connectors/my-api/tools/list_users.ts
import { defineTool } from '@edl-os/sdk';
import { z } from 'zod';

export const listUsers = defineTool({
  name: 'list_users',
  description: 'Список пользователей за период',
  input: z.object({
    since: z.string().describe('ISO date, например 2026-01-01'),
    limit: z.number().min(1).max(200).default(50),
  }),
  handler: async ({ input, ctx }) => {
    const res = await ctx.http.get('/users', {
      params: { since: input.since, limit: input.limit },
    });
    return res.data;
  },
});

Шаг 3 · Безопасность данных

Что отдавать модели: агрегаты, метрики, ID. Что не отдавать: PII, полные строки, токены. Если возвращаете список — отрезайте чувствительные поля:

return res.data.map((u) => ({
  id: u.id,
  name: u.name,
  created: u.created_at,
  // НЕ возвращаем: email, phone, address, payment_token
}));

Шаг 4 · Регистрация и тест

Подключите коннектор в корневой config.yaml:

connectors:
  - my-api

Перезапустите сервер и проверьте, что tool появился:

curl -X POST http://localhost:8080/mcp/v1/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Ожидаем в ответе list_users с описанием.

Шаг 5 · Опубликовать

• Откройте PR в edl-connectors — community-репо.
• Добавьте README с примером использования и таблицей возвращаемых полей.
• После мерджа коннектор появится в managed-облаке + в каталоге.

Шаблоны для старта

Готовые скелеты на GitHub:

• templates/rest — REST API + OAuth
• templates/db — PostgreSQL / MySQL
• templates/file — CSV / Excel / JSON