Настройка источников — документация AIKraft Agents

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

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

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

Прежде чем делать что-либо другое, обратитесь к документации продукта по настроенному адресу CRAFT_DOCS_BASE_URL:

Наши собственные руководства по сервисам — сначала прочитайте локальный файл, это быстрее и не зависит от сети:

Сервис	Локальное руководство	Опубликованная копия
Google (Gmail, Calendar, Drive, Docs, Sheets, YouTube, Search Console)	`~/.craft-agent/docs/source-guides/google.md`	{{CRAFT_DOCS_BASE_URL}}/sources/guides/google
GitHub	`~/.craft-agent/docs/source-guides/github.md`	{{CRAFT_DOCS_BASE_URL}}/sources/guides/github
Любой сервис OAuth — чек-лист	`~/.craft-agent/docs/source-guides/oauth-checklist.md`	{{CRAFT_DOCS_BASE_URL}}/sources/guides/oauth-checklist

Для сервиса, у которого нет собственного руководства:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2. Исследование сервиса

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

WebSearch/WebFetch: Найти официальную документацию, справочник API, лучшие практики.
Инструменты встроенного браузера: Используйте, когда документация динамическая, интерактивная или находится за логином.
Уточните: Ограничения частоты запросов (rate limits), квоты, методы аутентификации.
Определите: Ключевые эндпоинты или инструменты, относящиеся к заявленным целям пользователя.
Запишите: Любые ограничения или подводные камни для документации.

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

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

3. Интеллектуальная настройка

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

Базовые поля:

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

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

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

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

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

После подключения получите список доступных инструментов сервера.
Определите инструменты только для чтения (операции list, get, search, find, query).
Создайте простые паттерны для этих операций.

terminaljson

{
  "allowedMcpPatterns": [
    { "pattern": "list", "comment": "Все операции list" },
    { "pattern": "get", "comment": "Все операции get/чтения" },
    { "pattern": "search", "comment": "Все операции search" },
    { "pattern": "find", "comment": "Все операции find" }
  ]
}

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

terminaljson

{
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*", "comment": "Все запросы GET только для чтения" },
    { "method": "POST", "path": "^/search", "comment": "Эндпоинт поиска (только для чтения, несмотря на POST)" }
  ]
}

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

terminaljson

{
  "allowedBashPatterns": [
    { "pattern": "^(ls|cat|head|tail|grep|find|tree)\\s", "comment": "Команды только для чтения" }
  ]
}

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

5. Написание подробного guide.md

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

Обобщите назначение источника в их конкретном сценарии использования.
Задокументируйте возможности, относящиеся к их рабочему процессу.
Включите ссылки на конкретные проекты/команды/области, которые они упомянули.
Добавьте примеры использования, адаптированные под их задачи.
Укажите ограничения частоты запросов, квоты или другие ограничения.

6. Тестирование и валидация (ОБЯЗАТЕЛЬНО)

ВЫ ОБЯЗАНЫ использовать инструмент source_test после создания любого источника. Это относится ко ВСЕМ типам источников — MCP, API и локальным файловым системам. Это не опционально.

terminalbash

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

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

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

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

Источники OAuth: source_oauth_trigger({ sourceSlug: "{slug}" })
Bearer/API key: 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

# Название Источника

Краткое описание того, что предоставляет этот источник и конкретный сценарий использования пользователя.

## Область применения

Какие данные/функциональность это предоставляет. Включите:
- Конкретные проекты, команды или репозитории, упомянутые пользователем
- Соответствующие фильтры или значения по умолчанию
- Любые ограничения доступа

## Руководство

- Лучшие практики использования этого источника
- Ограничения частоты запросов или квоты, о которых следует знать
- Частые паттерны, которые понадобятся пользователю
- Чего следует избегать или на что быть осторожным

## Примеры

Конкретные примеры, адаптированные под рабочий процесс пользователя:
- «Чтобы найти задачи в проекте Craft iOS: ...»
- «Чтобы найти недавние коммиты мобильной команды: ...»

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

Будьте конкретны в контексте пользователя: Ссылайтесь на проекты, команды и задачи, которые они упомянули.
Включайте конкретные примеры: Используйте их фактические названия проектов и рабочие процессы.
Документируйте предпочтения пользователя: Любые предпочтения, которые они поделили для будущих сессий.
Укажите границы области применения: Что источник может и не может делать.
Держите его практичным: Сосредоточьтесь на том, что Claude нужно знать для эффективной помощи.

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

terminalbash

Пользователь: Я хочу добавить Linear

Агент: [СНАЧАЛА: читает руководство по источникам MCP по адресу {{CRAFT_DOCS_BASE_URL}}/sources/mcp-servers/overview,
       затем проверяет текущий MCP-эндпоинт Linear и поток аутентификации через WebSearch]

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

Пользователь: Отслеживание задач для моей iOS-команды, проект называется "Craft iOS"

Агент: [Использует WebSearch для проверки текущего MCP URL Linear]
Агент: [Создает config.json с:
        - icon: (ищет иконку приложения в вебе или использует favicon)
        - tagline: "Отслеживание задач для команды Craft iOS"
        - Аутентификация OAuth]
Агент: [Пишет guide.md, упоминающий проект "Craft iOS" и контекст iOS-команды]
Агент: [Настраивает permissions.json для перечисления только для чтения в режиме Изучение]
Агент: [ОБЯЗАТЕЛЬНО: Запускает source_test для валидации]
       mcp__session__source_test({ sourceSlug: "linear" })
Агент: [Запускает source_oauth_trigger для аутентификации]
       mcp__session__source_oauth_trigger({ sourceSlug: "linear" })

Агент: Linear теперь настроен! Я настроил его для фокуса на проекте "Craft iOS".
Вы можете использовать его для:
- Поиска и просмотра задач в Craft iOS
- Отслеживания прогресса спринта для iOS-команды
- Создания и обновления задач

Хотите, я покажу, какие задачи сейчас открыты?

Обзор

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

~/.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": "Человекочитаемое имя",
  "slug": "url-safe-identifier",
  "enabled": true,
  "provider": "provider-name",
  "type": "mcp" | "api" | "local",

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

  // Для источников 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

Серверы 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 с режимом "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, form data и т. д.), используйте специальные параметры _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.

Используйте headerName (единственное число) для API, которым нужен один заголовок. Учетные данные, введенные через мульти-заголовочный промпт для источника с одним заголовком, распаковываются в «голое» значение и никогда не отправляются как JSON-блок. source_test отправляет ровно то, что отправляют инструменты api_<source>, поэтому успешный аутентифицированный тест означает, что реальные вызовы также будут аутентифицированы.

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

terminalbash

source_credential_prompt({
  sourceSlug: "datadog",
  mode: "multi-header",
  headerNames: ["DD-API-KEY", "DD-APPLICATION-KEY"],
  description: "Введите ваши учетные данные API Datadog"
})

Частые сценарии использования мульти-заголовков:

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" — эндпоинты, регистрация клиента и индикатор resource по RFC 8707 (чтобы серверы, связанные с ресурсом, принимали токен) обнаруживаются автоматически:

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 (обязательно): ID клиента вашего OAuth-приложения.
clientSecret (опционально): Секрет клиента — не требуется для публичных PKCE-клиентов.
scopes (опционально): Запрашиваемые скоупы OAuth.
audience (опционально): Параметр audience в стиле Auth0.
resource (опционально): Индикатор ресурса по RFC 8707 для серверов, выпускающих токены с ограниченной аудиторией; отправляется в запросах авторизации, токена и обновления.
extraParams (опционально): Дополнительные query-параметры для URL авторизации (например, {"access_type": "offline"}).

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

terminalbash

source_oauth_trigger({ sourceSlug: "github" })

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

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

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

terminalbash

source_credential_prompt({
  sourceSlug: "ashby",
  mode: "basic",
  passwordRequired: false,  // Поле пароля становится опциональным
  labels: { username: "API Key" },
  description: "Введите ваш API-ключ Ashby"
})

Когда passwordRequired: false:

Поле пароля показывает метку "(optional)" и плейсхолдер "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

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

Требует аутентификации (чтобы проверить, работают ли учетные данные).
Легковесный (не запрашивает много данных).
Возвращает ответ быстро (эндпоинты health/status идеальны).

Частые паттерны:

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 token
`headers`	Нет	—	Дополнительные заголовки. Используйте `{{token}}` как плейсхолдер. Слияние поверх `defaultHeaders`
`tokenField`	Нет	`"access_token"`	Имя поля JSON для нового токена в ответе
`expiresInField`	Нет	`"expires_in"`	Имя поля JSON для срока действия в секундах в ответе
`fallbackTtlSecs`	Нет	—	Запасной TTL в секундах, если в ответе нет информации о сроке действия

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

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

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

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

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

# Название Источника

Краткое описание того, что предоставляет этот источник.

## Область применения

Какие данные/функциональность этот источник предоставляет доступ.

## Руководство

- Лучшие практики использования этого источника
- Ограничения частоты запросов или квоты, о которых следует знать
- Частые паттерны и примеры

## Справочник API

Для источников API задокументируйте доступные эндпоинты:

### POST /search
Поиск контента.

**Параметры:**
- `query` (string, обязательно): Запрос поиска
- `limit` (number, опционально): Максимум результатов (по умолчанию: 10)

**Пример:**
```json
{
  "query": "machine learning",
  "limit": 5
}
```

Формат permissions.json

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

terminaljson

{
  "allowedMcpPatterns": [
    {
      "pattern": "^mcp__linear__list",
      "comment": "Разрешить перечисление ресурсов в режиме Изучение"
    }
  ],
  "allowedApiEndpoints": [
    {
      "method": "GET",
      "path": "^/search",
      "comment": "Разрешить эндпоинт поиска в режиме Изучение"
    },
    {
      "method": "POST",
      "path": "^/v1/query$",
      "comment": "POST разрешен для эндпоинтов только запросов"
    }
  ],
  "allowedBashPatterns": [
    {
      "pattern": "^ls\\s",
      "comment": "Разрешить команды ls"
    }
  ]
}

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

Поле 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.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 как клиент Web application (не "Desktop app") и добавьте https://thecraftagents.com/auth/callback как авторизованный redirect URI. Требуется клиентский секрет.

Использует 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

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

Brave Search

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

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

Memory

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

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

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

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

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

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

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

Создайте папку источника:
terminalbash
```
mkdir -p ~/.craft-agent/workspaces/{ws}/sources/my-source
```
Напишите config.json с соответствующими настройками (см. схемы выше).
Напишите guide.md, адаптированный под контекст и сценарий использования пользователя.
Создайте permissions.json для режима Изучение - Перечислите инструменты источника, определите операции только для чтения (list, get, search) и добавьте простые паттерны. Паттерны автоматически ограничиваются этим источником.
Запустите source_test для валидации конфигурации и тестирования подключения.
Если требуется аутентификация, запустите соответствующий поток:
- 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 })
Подтвердите с пользователем, что источник работает как ожидается.

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

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

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

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

Статус "needs_auth":

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

Статус "failed":

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

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

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

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

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

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

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

2. Исследование сервиса

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

3. Интеллектуальная настройка

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

5. Написание подробного guide.md

6. Тестирование и валидация (ОБЯЗАТЕЛЬНО)

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

Структура

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

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

Обзор

Схема config.json

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

Источники MCP

Источники API

Настройка testEndpoint

Настройка renewEndpoint (Опционально)

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

Формат guide.md

Формат permissions.json

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

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

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

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

Linear

GitHub

Exa (Поиск)

Brave Search

Memory

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

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

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

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

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