AIKraft/AI/Поиск…⌘KВойти
Главная/Документация/Справочник агента/Настройка источников
Справочник агента

Настройка источников

Руководство по настройке источников в AIKraft Agents: MCP-серверы, API и локальные файловые системы. Описаны процесс создания, структура config.json, права для режима Изучение и тестирование.

Это руководство объясняет, как настроить источники (MCP-серверы, API, локальные файловые системы) в AIKraft Agents.

Рабочий процесс с приоритетом CLI (рекомендуется): используйте команды craft-agent source ... вместо прямого редактирования файлов конфигурации источников.

  • craft-agent source --help
  • Канонический справочник команд: craft-cli.md

Процесс настройки источника

Когда пользователь хочет добавить новый источник, следуйте этому диалоговому процессу настройки, чтобы создать индивидуальную и хорошо документированную интеграцию.

0. Проверьте наличие специализированного руководства по источнику (ОБЯЗАТЕЛЬНЫЙ ПЕРВЫЙ ШАГ)

Прежде чем что-либо делать, ознакомьтесь с документацией продукта по адресу /docs:

Примечание: руководства по настройке отдельных сервисов (GitHub, Linear, Slack, Gmail, Outlook, …) не публикуются на нашем сайте документации. Исходный проект удалил встроенные руководства из кода и предоставляет их только с сайта вендора, которым мы не пользуемся. Поэтому для конкретного сервиса:

  1. Следуйте общим руководствам выше для типа источника (MCP / API / файловая система)
  2. Проверьте актуальные эндпоинты и поток аутентификации через WebSearch и/или встроенный браузер — URL и документация API часто меняются, и теперь это основной источник достоверности
  3. Проверьте, есть ли в workspace уже похожий настроенный источник, и повторите структуру его config.json
  4. Обращайте внимание на специфичные для сервиса предварительные требования (например, GitHub лучше всего работает, если CLI gh уже аутентифицирован — проверьте перед ручной настройкой API-источника)

Почему это важно: у некоторых сервисов есть важные предварительные требования или подводные камни, которые нужно проверить перед созданием источника. Пропуск этого шага может привести к неудачной настройке или избыточным конфигурациям.

0.5. Выберите путь: источник или браузер (РЕКОМЕНДУЕМАЯ ПРЕДВАРИТЕЛЬНАЯ ПРОВЕРКА)

Источники по-прежнему остаются основным вариантом для переиспользуемых интеграций. Перед созданием нового источника спросите: это повторяемая интеграционная работа или разовая/управляемая через интерфейс задача?

Предпочитайте создание/использование источника, если:

  • рабочий процесс повторяемый и, вероятно, будет переиспользован
  • нужны структурированные запросы/отчёты
  • важны согласованность команды и автоматизация
  • аутентификация API/MCP достаточно стабильна для поддержки

Сначала предпочитайте встроенный браузер (или как запасной вариант), если:

  • аутентификация/настройка известна как хрупкая (часто встречается в некоторых сценариях Gmail/Microsoft)
  • пользователю нужно быстро выполнить разовую задачу
  • API ограничен, нестабилен или не имеет необходимых операций
  • рабочий процесс ориентирован на интерфейс, и полная интеграция не оправдана

Если вы выбрали путь через браузер, всё равно предложите позже опциональную настройку источника, когда пользователю понадобится повторяемость.

1. Поймите намерение пользователя

Перед созданием любой конфигурации задайте вопросы, чтобы понять:

  • Основная цель: чего они хотят достичь с этим источником?
  • Область: конкретные проекты, команды, репозитории или данные, на которых нужно сфокусироваться?
  • Типичные задачи: какие операции они будут выполнять чаще всего?
  • Уровень доступа: только чтение/изучение или полный доступ?

Примеры вопросов:

«С удовольствием помогу настроить Linear! Несколько вопросов: 1. Для чего вы в основном будете использовать Linear? (отслеживание задач, планирование спринтов и т. д.) 2. Есть ли конкретные команды или проекты, на которых вы хотите сфокусироваться? 3. Настроить ли его для чтения/изучения или с полным доступом?»

2. Изучите сервис

Используйте доступные инструменты, чтобы узнать о сервисе:

  • WebSearch/WebFetch: найдите официальную документацию, справочники API, лучшие практики
  • Инструменты встроенного браузера: используйте, когда документация динамическая, интерактивная или доступна только после входа
  • Уточните: лимиты запросов, квоты, способы аутентификации
  • Определите: ключевые эндпоинты или инструменты, связанные с целями пользователя
  • Отметьте: любые ограничения или подводные камни, которые нужно задокументировать

Источник и браузер: практические примеры

  • Настройка Gmail/Microsoft постоянно падает при аутентификации: попробуйте настроить источник, но подтвердите запасной путь через браузер для немедленного выполнения задачи.
  • Нужен разовый экспорт из административного интерфейса: используйте браузер напрямую; пропустите полную настройку источника, если задача не повторяется.
  • В API отсутствует нужный эндпоинт, но интерфейс его поддерживает: используйте браузер как основной путь и задокументируйте ограничение.

3. Настройте разумно

На основе исследования и намерения пользователя создайте config.json со всеми обязательными полями:

Основные поля:

  • id — ОБЯЗАТЕЛЬНО: строка-идентификатор. Формат: {slug}_{random} (например, linear_a1b2c3d4). Случайную часть можно сгенерировать любым способом (например, 8 шестнадцатеричных символов).
  • name, slug, provider, type — базовая идентификация
  • icon — РЕКОМЕНДУЕТСЯ: URL на favicon, логотип или иконку приложения сервиса. Иконка автоматически скачивается и кэшируется локально. В качестве запасного варианта используйте эмодзи.
  • tagline — РЕКОМЕНДУЕТСЯ: краткое описание для контекста агента (например, «Отслеживание задач, планирование спринтов и управление проектами»)
  • Конфигурация, специфичная для типа (mcp, api или local)
  • Способ аутентификации, подходящий для сервиса

4. Настройте права для режима Изучение (ОБЯЗАТЕЛЬНО)

Источники по умолчанию должны работать в режиме Изучение. Создайте permissions.json, чтобы разрешить операции только для чтения.

Как это работает: шаблоны в permissions.json источника автоматически ограничиваются этим источником. Записывайте простые шаблоны, например list — система внутренне преобразует их в mcp__<sourceSlug>__.*list. Это предотвращает утечку между источниками.

Для MCP-источников:

  1. После подключения получите список доступных инструментов сервера
  2. Определите инструменты только для чтения (операции list, get, search, find, query)
  3. Создайте простые шаблоны для этих операций
terminaljson
{
  "allowedMcpPatterns": [
    { "pattern": "list", "comment": "All list operations" },
    { "pattern": "get", "comment": "All get/read operations" },
    { "pattern": "search", "comment": "All search operations" },
    { "pattern": "find", "comment": "All find operations" }
  ]
}

Для API-источников:

terminaljson
{
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*", "comment": "All GET requests are read-only" },
    { "method": "POST", "path": "^/search", "comment": "Search endpoint (read-only despite POST)" }
  ]
}

Для локальных источников:

terminaljson
{
  "allowedBashPatterns": [
    { "pattern": "^(ls|cat|head|tail|grep|find|tree)\\s", "comment": "Read-only commands" }
  ]
}

Цель: источники должны быть полностью функциональны в режиме Изучение. По умолчанию разрешайте все операции чтения. Блокируйте только фактические изменения (create, update, delete).

5. Напишите подробный guide.md

Создайте guide.md, адаптированный под контекст пользователя:

  • кратко опишите назначение источника в их конкретном сценарии использования
  • задокументируйте возможности, важные для их рабочего процесса
  • включите конкретные ссылки на проекты/команды/область, которые они упомянули
  • добавьте примеры использования, адаптированные под их задачи
  • отметьте лимиты запросов, квоты или ограничения

6. Протестируйте и проверьте (ОБЯЗАТЕЛЬНО)

Вы обязаны использовать инструмент source_test после создания любого источника. Это относится ко всем типам источников — MCP, API и локальные файловые системы. Это не опционально.

terminalbash
mcp__session__source_test({ sourceSlug: "{slug}" })

Инструмент source_test:

  1. Проверяет config.json по схеме
  2. Скачивает и кэширует иконку, если был указан URL
  3. Тестирует подключение, чтобы убедиться, что источник доступен
  4. Сообщает о недостающих полях (icon, tagline), которые нужно добавить
  5. Автоматически включает источник (по умолчанию): при успешном запуске при необходимости устанавливает enabled: true в config и активирует источник в текущей сессии, чтобы его инструменты стали доступны без перезапуска. Передайте autoEnable: false, чтобы сохранить поведение чистой проверки.

После успешной проверки запустите соответствующий поток аутентификации:

  • OAuth-источники: source_oauth_trigger({ sourceSlug: "{slug}" })
  • Bearer/API-ключ: source_credential_prompt({ sourceSlug: "{slug}", mode: "bearer" })
  • Сервисы Google: source_google_oauth_trigger({ sourceSlug: "{slug}" })
  • Сервисы Microsoft: source_microsoft_oauth_trigger({ sourceSlug: "{slug}" })
  • Slack: source_slack_oauth_trigger({ sourceSlug: "{slug}" })

Не пропускайте проверку — она выявляет ошибки конфигурации до того, как они приведут к сбоям во время выполнения.

Лучшие практики для guide.md

Файл guide.md критически важен — он помогает Claude понимать, как эффективно использовать источник в будущих сессиях.

Структура

terminalbash
# Source Name

Brief description of what this source provides and the user's specific use case.

## Scope

What data/functionality this provides. Include:
- Specific projects, teams, or repos the user mentioned
- Relevant filters or defaults
- Any limitations on access

## Guidelines

- Best practices for using this source
- Rate limits or quotas to be aware of
- Common patterns the user will need
- Things to avoid or be careful about

## Examples

Concrete examples tailored to the user's workflow:
- "To find issues in the Craft iOS project: ..."
- "To search for recent commits by the mobile team: ..."

Ключевые принципы

  1. Будьте конкретны в контексте пользователя: ссылайтесь на упомянутые проекты, команды и задачи
  2. Включайте конкретные примеры: используйте их реальные имена проектов и рабочие процессы
  3. Документируйте предпочтения пользователя: любые предпочтения, которые они поделили для будущих сессий
  4. Отмечайте границы области: что источник может и не может делать
  5. Делайте практичным: сосредоточьтесь на том, что Claude нужно знать, чтобы эффективно помогать

Пример диалогового потока

terminalyaml
User: I want to add Linear

Agent: [FIRST: reads the MCP source guide at /docs/sources/mcp-servers/overview,
       then checks Linear's current MCP endpoint and auth flow via WebSearch]

Agent: I've got the setup path for Linear. A few questions:
1. What will you primarily use Linear for? (issue tracking, sprint planning, reporting?)
2. Are there specific teams or projects you want to focus on?
3. Should I set it up for read-only exploration or full access?

User: Issue tracking for my iOS team, project called "Craft iOS"

Agent: [Uses WebSearch to verify current Linear MCP URL]
Agent: [Creates config.json with:
        - icon: (searches web for app icon or uses favicon)
        - tagline: "Issue tracking for the Craft iOS team"
        - OAuth authentication]
Agent: [Writes guide.md mentioning "Craft iOS" project and iOS team context]
Agent: [Sets up permissions.json for read-only listing in Explore mode]
Agent: [MANDATORY: Runs source_test to validate]
       mcp__session__source_test({ sourceSlug: "linear" })
Agent: [Triggers source_oauth_trigger for authentication]
       mcp__session__source_oauth_trigger({ sourceSlug: "linear" })

Agent: Linear is now set up! I've configured it to focus on the "Craft iOS" project.
You can use it to:
- Search and view issues in Craft iOS
- Track sprint progress for the iOS team
- Create and update issues

Would you like me to show you what issues are currently open?

Обзор

Источники хранятся в виде папок по пути:

  • ~/.craft-agent/workspaces/{workspaceId}/sources/{sourceSlug}/

Каждая папка источника содержит:

  • config.json — конфигурация источника (обязательно)
  • guide.md — документация по использованию для Claude (опционально)
  • permissions.json — пользовательские правила прав для режима Изучение (опционально)
  • icon.svg, icon.png, icon.jpg или icon.jpeg — иконка источника (опционально)

Схема config.json

terminaljson
{
  "id": "linear_a1b2c3d4",        // Уникальный идентификатор: {slug}_{random}
  "name": "Human-readable name",
  "slug": "url-safe-identifier",
  "enabled": true,
  "provider": "provider-name",
  "type": "mcp" | "api" | "local",

  // РЕКОМЕНДУЕТСЯ: иконка и tagline для лучшего интерфейса и контекста агента
  "icon": "https://example.com/favicon.ico",  // URL (автоскачивание) или эмодзи
  "tagline": "Brief description for agent context",

  // Для MCP-источников:
  "mcp": {
    "url": "https://mcp.example.com",
    "authType": "oauth" | "bearer" | "none"
  },

  // Для API-источников:
  "api": {
    "baseUrl": "https://api.example.com/",  // Обязательно с завершающим слэшем
    "authType": "bearer" | "header" | "query" | "basic" | "oauth" | "none",
    "headerName": "X-API-Key",      // Для аутентификации одним заголовком
    "headerNames": ["X-API-KEY", "X-APP-KEY"],  // Для аутентификации несколькими заголовками (2 и более)
    "queryParam": "api_key",         // Для аутентификации через query
    "authScheme": "Bearer"           // Для bearer-аутентификации (по умолчанию: "Bearer")
  },

  // Для локальных источников:
  "local": {
    "path": "/path/to/folder"
  },

  // Статус (обновляется source_test):
  "isAuthenticated": true,
  "connectionStatus": "connected" | "needs_auth" | "failed" | "untested",
  "lastTestedAt": 1704067200000,

  // Иконка: эмодзи или URL (автоскачивается в локальный файл icon.*)
  // Локальные файлы иконок обнаруживаются автоматически, конфигурация не нужна
  "icon": "🔧",                      // Эмодзи-иконка (опционально)

  // Метки времени:
  "createdAt": 1704067200000,
  "updatedAt": 1704067200000
}

Типы источников

MCP-источники

MCP-серверы (Model Context Protocol) предоставляют инструменты через HTTP/SSE.

Аутентификация OAuth (рекомендуется):

terminaljson
{
  "id": "linear_a1b2c3d4",
  "type": "mcp",
  "provider": "linear",
  "mcp": {
    "url": "https://mcp.linear.app",
    "authType": "oauth"
  }
}

После создания используйте source_oauth_trigger для аутентификации.

Аутентификация bearer-токеном:

terminaljson
{
  "type": "mcp",
  "provider": "custom-mcp",
  "mcp": {
    "url": "https://my-mcp-server.com",
    "authType": "bearer"
  }
}

После создания используйте source_credential_prompt с mode "bearer".

Публичный (без аутентификации):

terminaljson
{
  "type": "mcp",
  "provider": "public-mcp",
  "mcp": {
    "url": "https://public-mcp.example.com",
    "authType": "none"
  }
}

Stdio-транспорт (локальная команда):

Для MCP-серверов, которые запускаются локально через командную строку (npx, node, python), используйте stdio-транспорт.

Пользователи часто предоставляют конфигурации в формате Claude Desktop / Claude Code:

terminaljson
{
  "mcpServers": {
    "airbnb": {
      "command": "npx",
      "args": ["-y", "@openbnb/mcp-server-airbnb"]
    }
  }
}

Преобразуйте в нативный формат:

terminaljson
{
  "type": "mcp",
  "name": "Airbnb",
  "provider": "airbnb",
  "mcp": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@openbnb/mcp-server-airbnb"],
    "authType": "none"
  }
}

С переменными окружения:

terminaljson
{
  "type": "mcp",
  "name": "Brave Search",
  "provider": "brave",
  "mcp": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "BRAVE_API_KEY": "your-api-key"
    },
    "authType": "none"
  }
}

API-источники

REST API становятся гибкими инструментами, которые может вызывать Claude.

Тела запросов: по умолчанию params сериализуется в JSON для запросов POST/PUT/PATCH. Для эндпоинтов, ожидающих тела не в JSON (обычный текст, XML, данные формы и т. д.), используйте специальные параметры _rawBody и _contentType:

terminaljson
{
  "params": {
    "_rawBody": "raw string content to send as-is",
    "_contentType": "text/plain"
  }
}
  • _rawBody (string) — отправляется как тело запроса без JSON-кодирования
  • _contentType (string, опционально) — устанавливает заголовок Content-Type (по умолчанию text/plain)

ВАЖНО: для аутентифицированных API-источников требуется testEndpoint, чтобы проверить учётные данные во время source_test. Без него мы не можем убедиться, что ваши учётные данные работают.

Аутентификация заголовком (стиль X-API-Key):

terminaljson
{
  "type": "api",
  "provider": "exa",
  "api": {
    "baseUrl": "https://api.exa.ai/",
    "authType": "header",
    "headerName": "x-api-key",
    "testEndpoint": {
      "method": "POST",
      "path": "search",
      "body": { "query": "test", "numResults": 1 }
    }
  }
}

Bearer-токен (заголовок Authorization):

terminaljson
{
  "type": "api",
  "provider": "openai",
  "api": {
    "baseUrl": "https://api.openai.com/v1/",
    "authType": "bearer",
    "testEndpoint": {
      "method": "GET",
      "path": "models"
    }
  }
}

Параметр query:

terminaljson
{
  "type": "api",
  "provider": "weather",
  "api": {
    "baseUrl": "https://api.weather.com/",
    "authType": "query",
    "queryParam": "apikey",
    "testEndpoint": {
      "method": "GET",
      "path": "v1/current"
    }
  }
}

Базовая аутентификация:

terminaljson
{
  "type": "api",
  "provider": "jira",
  "api": {
    "baseUrl": "https://your-domain.atlassian.net/rest/api/3/",
    "authType": "basic",
    "testEndpoint": {
      "method": "GET",
      "path": "myself"
    }
  }
}

Аутентификация несколькими заголовками:

Некоторые API требуют несколько заголовков аутентификации одновременно. Например, Datadog требует и DD-API-KEY, и DD-APPLICATION-KEY. Используйте массив headerNames, чтобы указать все необходимые заголовки:

terminaljson
{
  "type": "api",
  "provider": "datadog",
  "api": {
    "baseUrl": "https://api.datadoghq.com/api/",
    "authType": "header",
    "headerNames": ["DD-API-KEY", "DD-APPLICATION-KEY"],
    "testEndpoint": {
      "method": "GET",
      "path": "v1/validate"
    }
  }
}

Когда указан headerNames:

  • Для каждого имени заголовка создаётся своё поле ввода при аутентификации
  • Все значения заголовков хранятся вместе как JSON-объект
  • Каждый заголовок добавляется в каждый API-запрос

Чтобы запросить учётные данные для нескольких заголовков:

terminalbash
source_credential_prompt({
  sourceSlug: "datadog",
  mode: "multi-header",
  headerNames: ["DD-API-KEY", "DD-APPLICATION-KEY"],
  description: "Enter your Datadog API credentials"
})

Типичные сценарии для нескольких заголовков:

  • Datadog: DD-API-KEY + DD-APPLICATION-KEY
  • API с ключом идентификации и ключом подписи: отдельный API-ключ и секрет
  • Сервисы с учётными данными приложения и пользователя: ключ приложения плюс токен пользователя

Универсальный OAuth (authType: 'oauth'):

Для API-источников, которые используют OAuth 2.0, но не являются Google, Slack или Microsoft. Два режима:

Автоматическое обнаружение (рекомендуется): если API поддерживает RFC 9728 (OAuth Protected Resource Metadata), просто установите authType: "oauth" — эндпоинты и регистрация клиента обнаруживаются автоматически:

terminaljson
{
  "name": "Craft Connect",
  "type": "api",
  "provider": "craft",
  "api": {
    "baseUrl": "https://connect.craft.do/my/api/v1/",
    "authType": "oauth"
  }
}

Явная конфигурация: для API без стандартных метаданных OAuth (GitHub, Linear и т. д.) укажите эндпоинты вручную:

terminaljson
{
  "name": "GitHub",
  "type": "api",
  "provider": "github",
  "api": {
    "baseUrl": "https://api.github.com/",
    "authType": "oauth",
    "oauth": {
      "authorizationUrl": "https://github.com/login/oauth/authorize",
      "tokenUrl": "https://github.com/login/oauth/access_token",
      "clientId": "Iv1.your_client_id",
      "clientSecret": "your_client_secret",
      "scopes": ["repo", "read:user"]
    }
  }
}

Поля блока oauth (нужны только для явной конфигурации):

  • authorizationUrl (обязательно): эндпоинт авторизации OAuth
  • tokenUrl (обязательно): эндпоинт обмена токеном OAuth
  • clientId (обязательно): идентификатор клиента вашего OAuth-приложения
  • clientSecret (опционально): секрет клиента — не требуется для публичных PKCE-клиентов
  • scopes (опционально): запрашиваемые OAuth-области
  • audience (опционально): параметр audience в стиле Auth0
  • extraParams (опционально): дополнительные query-параметры для URL авторизации (например, {"access_type": "offline"})

Чтобы запустить аутентификацию OAuth, используйте source_oauth_trigger (тот же инструмент, что и для MCP OAuth):

terminalbash
source_oauth_trigger({ sourceSlug: "github" })

Токены отправляются как Authorization: Bearer {token} в каждом запросе. Обновление токена выполняется автоматически, если доступен refresh-токен.

Базовая аутентификация с необязательным паролем:

Некоторые API используют HTTP Basic Auth, но требуют только поле имени пользователя (API-ключ), оставляя пароль пустым. Для таких API при запросе учётных данных используйте passwordRequired: false:

terminalbash
source_credential_prompt({
  sourceSlug: "ashby",
  mode: "basic",
  passwordRequired: false,  // Поле пароля становится необязательным
  labels: { username: "API Key" },
  description: "Enter your Ashby API key"
})

Когда passwordRequired: false:

  • Поле пароля получает лейбл «(optional)» и placeholder «Optional - leave blank»
  • Кнопка Save становится активной только с именем пользователя
  • Для пароля отправляется пустая строка (согласно спецификации HTTP Basic Auth: base64(username:))

Примечание: passwordRequired применяется только к mode: "basic". По умолчанию установлено true для обратной совместимости с сервисами вроде Jira или Amplitude, где требуются и имя пользователя, и пароль.

Конфигурация testEndpoint

testEndpoint указывает, какой эндпоинт вызывать при проверке учётных данных:

terminaljson
{
  "testEndpoint": {
    "method": "GET",           // "GET" или "POST"
    "path": "v1/me",           // Путь относительно baseUrl (БЕЗ начального слэша)
    "body": { ... }            // Опционально: тело запроса для POST
  }
}

ВАЖНО: форматирование URL:

  • baseUrl обязательно должен заканчиваться слэшем: https://api.example.com/v1/
  • В testEndpoint.path не должно быть начального слэша: users/me

Выберите эндпоинт, который:

  • требует аутентификации (чтобы проверить, что учётные данные работают)
  • лёгкий (не запрашивает много данных)
  • возвращает ответ быстро (эндпоинты состояния/статуса — идеальны)

Типичные паттерны:

  • me, user, profile — эндпоинты информации о пользователе
  • v1/status, health — эндпоинты статуса, требующие аутентификации
  • models, projects — эндпоинты списков с минимальными данными

Публичные API (authType: 'none') не требуют testEndpoint — мы тестируем, обращаясь к базовому URL.

Конфигурация renewEndpoint (опционально)

Опциональный renewEndpoint обеспечивает автоматическое обновление токенов для API с bearer-токенами без OAuth. Когда токен истекает, система вызывает этот эндпоинт, чтобы получить новый токен — ручная повторная аутентификация не нужна.

terminaljson
{
  "api": {
    "baseUrl": "https://api.example.com/",
    "authType": "bearer",
    "renewEndpoint": {
      "path": "auth/refresh",
      "method": "POST",
      "tokenField": "access_token",
      "expiresInField": "expires_in"
    }
  }
}

Поля:

Поле Обязательно По умолчанию Описание
path Да — URL обновления — относительный путь (решается относительно baseUrl) или абсолютный URL
method Нет "POST" HTTP-метод: "GET" или "POST"
body Нет — Тело запроса (JSON). Используйте {{token}} как плейсхолдер для текущего access-токена
headers Нет — Дополнительные заголовки. Используйте {{token}} как плейсхолдер. Складываются поверх defaultHeaders
tokenField Нет "access_token" Имя JSON-поля для нового токена в ответе
expiresInField Нет "expires_in" Имя JSON-поля для срока действия в секундах в ответе
fallbackTtlSecs Нет — Запасной TTL в секундах, если в ответе нет информации о сроке действия

Как это работает:

  1. Перед каждым API-запросом система проверяет, не истёк ли токен и не истекает ли он скоро (в пределах 5 минут)
  2. Если да, она вызывает renewEndpoint с текущим токеном в заголовке Authorization
  3. Новый токен и срок действия извлекаются из ответа и сохраняются
  4. Обновлённый токен используется для API-запроса

Подстановка токена: используйте {{token}} в body или headers, чтобы вставить текущий access-токен. Поддерживаются вложенные объекты — все строковые значения сканируются рекурсивно.

Пример с токеном в теле запроса:

terminaljson
{
  "renewEndpoint": {
    "path": "auth/refresh",
    "body": { "current_token": "{{token}}" },
    "tokenField": "new_token",
    "expiresInField": "ttl"
  }
}

Когда body опущен, текущий токен отправляется через стандартный заголовок Authorization (с использованием authScheme источника).

Примечание: это для API с собственным механизмом обновления токенов, а не для OAuth. Для API на основе OAuth используйте authType: "oauth".

Локальные источники

Доступ к файловой системе для локальных папок.

terminaljson
{
  "type": "local",
  "provider": "obsidian",
  "local": {
    "path": "/Users/me/Documents/ObsidianVault"
  }
}

После создания запустите source_test, чтобы проверить, что путь существует и доступен.

Формат guide.md

Файл guide.md помогает Claude понимать, как эффективно использовать источник.

terminalbash
# Source Name

Brief description of what this source provides.

## Scope

What data/functionality this source provides access to.

## Guidelines

- Best practices for using this source
- Rate limits or quotas to be aware of
- Common patterns and examples

## API Reference

For API sources, document the available endpoints:

### POST /search
Search for content.

**Parameters:**
- `query` (string, required): Search query
- `limit` (number, optional): Max results (default: 10)

**Example:**
```json
{
  "query": "machine learning",
  "limit": 5
}
```

Формат permissions.json

Пользовательские правила для расширения прав режима Изучение для этого источника.

terminaljson
{
  "allowedMcpPatterns": [
    {
      "pattern": "^mcp__linear__list",
      "comment": "Allow listing resources in Explore mode"
    }
  ],
  "allowedApiEndpoints": [
    {
      "method": "GET",
      "path": "^/search",
      "comment": "Allow search endpoint in Explore mode"
    },
    {
      "method": "POST",
      "path": "^/v1/query$",
      "comment": "POST allowed for query-only endpoints"
    }
  ],
  "allowedBashPatterns": [
    {
      "pattern": "^ls\\s",
      "comment": "Allow ls commands"
    }
  ]
}

Обработка иконок

Поле config.icon управляет иконкой источника. Разрешение следует этому приоритету:

Значение config.icon Поведение
Эмодзи (например, "🔧") Отображается как текст эмодзи
Локальный путь "./icon.svg" Загружается из sources/{slug}/icon.svg
URL "https://..." Автоматически скачивается в локальный файл icon.* инструментом source_test
Undefined/null Автоматически обнаруживает sources/{slug}/icon.{svg,png}, запасной вариант — favicon

Примеры:

terminalbash
// Эмодзи-иконка
{ "icon": "📝" }

// Явный локальный путь (редко нужен — автообнаружение это обрабатывает)
{ "icon": "./icon.svg" }

// URL (автоскачивается source_test)
{ "icon": "https://linear.app/static/favicon.svg" }

// Нет поля icon — автообнаруживает icon.svg/icon.png или разрешает favicon
{}

Лучшая практика: при создании источника установите icon в URL. Запустите source_test, чтобы скачать и кэшировать его локально. Затем приложение использует локальный файл для быстрого отображения, работающего офлайн.

Кэш доменов провайдеров

Для разрешения favicon кэш сопоставляет имена провайдеров с их каноническими доменами по пути: ~/.craft-agent/provider-domains.json

Формат:

terminaljson
{
  "version": 1,
  "domains": {
    "linear": "linear.app",
    "notion": "notion.so",
    "brave": "brave.com"
  },
  "updatedAt": 1704067200000
}

Когда обновлять: если favicon источника выглядит неверно (общий глобус, неправильная иконка), добавьте сопоставление провайдер→домен в этот файл. Приложение загружает этот кэш при запуске.

Пример: если у источника «acme-mcp» отображается неправильная иконка, добавьте:

terminalbash
"acme": "acme.com"

Частые провайдеры

Gmail (и другие сервисы Google)

Провайдер: google, тип: api

Требует учётные данные OAuth, предоставленные пользователем, в конфигурации источника:

  • googleOAuthClientId: ваш Google OAuth Client ID
  • googleOAuthClientSecret: ваш Google OAuth Client Secret

Создайте учётные данные в Google Cloud Console (тип приложения «Desktop app»). Используется OAuth через source_google_oauth_trigger.

Linear

Провайдер: linear, тип: mcp

URL: https://mcp.linear.app, аутентификация OAuth.

GitHub

Провайдер: github, тип: mcp

URL: https://api.githubcopilot.com/mcp/, bearer-аутентификация (требуется PAT — OAuth не сработает).

Exa (поиск)

Провайдер: exa, тип: api

Базовый URL: https://api.exa.ai, аутентификация заголовком с x-api-key.

Провайдер: brave, тип: mcp

Транспорт: stdio, команда: npx -y @modelcontextprotocol/server-brave-search, требуется переменная окружения BRAVE_API_KEY.

Memory

Провайдер: memory, тип: mcp

Транспорт: stdio, команда: npx -y @modelcontextprotocol/server-memory, без аутентификации.

Рабочий процесс

Создание источника

Всегда следуйте диалоговому процессу настройки (см. выше). Ключевые шаги:

  1. Спросите перед созданием: поймите намерение, область и типичные задачи пользователя
  2. Выберите правильный путь: подтвердите, должен ли это быть источник или разовый рабочий процесс с приоритетом браузера
  3. Изучите сервис перед настройкой: используйте WebSearch/WebFetch и браузерные инструменты по мере необходимости
  4. Адаптируйте guide.md под контекст: включите конкретные проекты/команды, которые упомянул пользователь
  5. Протестируйте перед тем, как объявить готовность: проверьте конфигурацию, запустите аутентификацию, убедитесь в подключении

Технические шаги:

  1. Создайте папку источника:

    terminalbash
    mkdir -p ~/.craft-agent/workspaces/{ws}/sources/my-source

  2. Напишите config.json с соответствующими настройками (см. схемы выше)

  3. Напишите guide.md, адаптированный под контекст и сценарий использования пользователя

  4. Создайте permissions.json для режима Изучение — получите список инструментов источника, определите операции только для чтения (list, get, search) и добавьте простые шаблоны. Шаблоны автоматически ограничиваются этим источником.

  5. Запустите source_test, чтобы проверить конфигурацию и подключение

  6. Если требуется аутентификация, запустите соответствующий поток:

    • source_oauth_trigger для MCP OAuth
    • source_google_oauth_trigger для сервисов Google (Gmail, Calendar, Drive, Docs, Sheets, YouTube, Search Console)
    • source_microsoft_oauth_trigger для сервисов Microsoft
    • source_slack_oauth_trigger для Slack
    • source_credential_prompt для API-ключей/токенов
    • Для базовой аутентификации с необязательным паролем: source_credential_prompt({ mode: "basic", passwordRequired: false })

  7. Подтвердите пользователю, что источник работает как ожидается

Тестирование источника

Используйте source_test со slug источника:

  • Проверяет схему config.json
  • Тестирует подключение
  • Скачивает иконку при необходимости
  • Обновляет connectionStatus

Устранение неполадок

Статус «needs_auth»:

  • Источнику требуется аутентификация
  • Используйте соответствующий инструмент запуска аутентификации

Статус «failed»:

  • Проверьте connectionError в config.json
  • Убедитесь, что URL корректен
  • Проверьте сетевое подключение

Иконка не отображается:

  • Убедитесь, что iconUrl корректен
  • Запустите source_test, чтобы скачать повторно
  • Проверьте, что файл существует в папке источника

Нужен такой агент в вашей компании?

Устанавливаем под ключ: настройка на компьютерах сотрудников, единый аккаунт, интеграция с 1С и внутренними системами, обучение команды. Подробнее о внедрении →