apifable

Читайте спецификацию. Понимайте API. Интегрируйте с уверенностью.

English | 繁體中文

Обзор

apifable — это MCP-сервер, который помогает AI более плавно интегрировать API в проекты на TypeScript. Он упрощает изучение структуры API, поиск эндпоинтов и генерацию типов TypeScript, предоставляя вашему AI-агенту контекст, необходимый для написания точного кода интеграции.

Related MCP server: openapi-mcp-proxy

✨ Возможности

• 📦 Контекст API, готовый для AI — предоставьте AI структуру, необходимую для понимания и работы с вашим API

• 📘 Поддержка OpenAPI 3.0 / 3.1 — работает со стандартными спецификациями как с надежным источником истины

• 🤖 MCP-сервер для AI-агентов — подключайтесь к Claude, Cursor и Windsurf

• 🔍 Инструменты исследования API — просматривайте эндпоинты, ищите по ключевым словам и изучайте полные детали запросов/ответов

• 🏷️ Генерация типов TypeScript — создавайте определения типов TypeScript, готовые к использованию в коде фронтенда

Начало работы

Установка

Запустите apifable init для настройки конфигурации вашего проекта:

npx apifable@latest init

Это создаст файл apifable.config.json в корне вашего проекта. Файл конфигурации следует добавить в систему контроля версий, чтобы путь к спецификации был доступен вашей команде.

После запуска команды вы сможете выбрать между Локальным файлом и Удаленным URL.

1. Локальный файл

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

init запросит путь к локальному файлу, например openapi.yaml.

Затем вам нужно будет вручную разместить спецификацию OpenAPI по этому пути. При изменении бэкенд-API вам также нужно будет обновлять этот файл вручную.

2. Удаленный URL

Используйте этот режим, если ваша спецификация OpenAPI доступна по стабильному удаленному URL, например, через эндпоинт спецификации OpenAPI, предоставляемый документацией вашего бэкенд-API.

init сначала запросит удаленный URL, например https://api.example.com/openapi.yaml, а затем запросит путь для локального сохранения, например ./openapi.yaml.

[!NOTE] В этом режиме init также автоматически добавляет путь к загруженной локальной спецификации в .gitignore, так как файл предназначен для обновления из удаленного источника.

Затем вы можете выполнить следующую команду, чтобы загрузить спецификацию OpenAPI с удаленного URL по вашему локальному пути (spec.url → spec.path). Всякий раз, когда спецификация меняется, просто запустите её снова для обновления:

npx apifable@latest fetch

Заголовки

Для неконфиденциальных заголовков, которыми можно поделиться с командой, добавьте spec.headers в apifable.config.json:

{
  "spec": {
    "path": "openapi.yaml",
    "url": "https://example.com/openapi.yaml",
    "headers": {
      "X-Api-Version": "2"
    }
  }
}

Заголовки авторизации (секретные токены)

Если для загрузки удаленной спецификации OpenAPI требуется аутентификация (приватный API), храните секретные заголовки в .apifable/auth.json. Этот файл не должен добавляться в систему контроля версий:

{
  "headers": {
    "Authorization": "Bearer YOUR_SECRET_TOKEN"
  }
}

И apifable.config.json, и .apifable/auth.json поддерживают синтаксис ${ENV_VAR} в значениях заголовков.

{
  "headers": {
    "Authorization": "Bearer ${MY_API_KEY}"
  }
}

Приоритет заголовков (от высшего к низшему)

1. Заголовки из .apifable/auth.json (переопределяют ключи с тем же именем)

2. spec.headers из apifable.config.json

Claude Code

Добавьте следующее в ваш .mcp.json:

{
  "mcpServers": {
    "apifable": {
      "command": "npx",
      "args": ["-y", "apifable@latest", "mcp"]
    }
  }
}

Для других AI-агентов, таких как Cursor и Windsurf, вы можете следовать тому же подходу для настройки apifable в качестве MCP-сервера.

Использование

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

Изучение API

List all APIs

Show me APIs related to posts

List APIs under the Post tag

Show me the API details for post comments

Show me the API details for GET /posts/{id}/comments

Show me the API details for postComments

Создание функции

Implement the post comments feature

Post page: src/pages/posts/[id].tsx

Related APIs:
- GET /posts/{id}/comments (list post comments)
- POST /posts/{id}/comments (create a post comment)

[!TIP] При написании промпта для создания функции включите соответствующий контекст: пути к страницам, расположение компонентов, связанные API, а также любые шаблоны или примеры, которым нужно следовать.

Руководство для AI-агента

Добавьте следующее в файл AGENTS.md вашего проекта, чтобы помочь AI-агентам более эффективно использовать apifable:

## API Integration (apifable)

- Always use `get_endpoint` to verify the exact path, method, and parameters before writing integration code. Never assume.
- When presenting endpoint list data from apifable tools, display exactly these columns in order: `Method` (Uppercase), `Path`, `Summary`. Keep all values verbatim, including summary prefixes like `[ 32 - 001 ]`. Do not omit, rename, paraphrase, or add extra columns.
- When saving generated types, store them under `src/types/` and name files by domain (e.g., `src/types/auth.ts`, `src/types/user.ts`), not by OpenAPI tag names.

Вышеприведенное является рекомендуемой отправной точкой. Не стесняйтесь настраивать столбцы списка эндпоинтов и путь к папке с типами в соответствии с вашим проектом.

Справочник инструментов MCP

get_spec_info

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

list_endpoints_by_tag

Входные данные:

• tag (строка): Имя тега для фильтрации

• limit (число, опционально): Максимальное количество эндпоинтов для возврата

• offset (число, опционально): Количество эндпоинтов для пропуска (по умолчанию: 0)

Возвращает все эндпоинты, принадлежащие заданному тегу. Ответ включает поля total, offset и hasMore для пагинации. Включает предупреждение, если результаты превышают 30 элементов, а limit не указан.

search_endpoints

Входные данные:

• query (строка): Ключевое слово для поиска

• tag (строка, опционально): Ограничить поиск определенным тегом

• limit (число, опционально): Максимальное количество результатов для возврата (по умолчанию: 10)

Поиск по ключевым словам в operationId, пути, сводке и описании. Результаты ранжируются по релевантности. Если точных совпадений не найдено, автоматически переключается на нечеткий поиск. Ответ включает поле matchType ("exact" или "fuzzy"); нечеткие результаты также включают поле score для каждого результата.

get_endpoint

Входные данные (выберите одно):

• method (строка) + path (строка): HTTP-метод и путь эндпоинта (например, get + /users/{id})

• operationId (строка): ID операции (например, listUsers)

Возвращает полный объект эндпоинта, включая параметры, requestBody и ответы, с разрешенными внутренними компонентами $ref.

search_schemas

Входные данные:

• query (строка): Ключевое слово для поиска

• limit (число, опционально): Максимальное количество результатов для возврата (по умолчанию: 10)

Поиск по ключевым словам в имени схемы и описании. Результаты ранжируются по релевантности. Если точных совпадений не найдено, автоматически переключается на нечеткий поиск. Ответ включает поле matchType ("exact" или "fuzzy"); нечеткие результаты также включают поле score для каждого результата. Пустые результаты могут также включать поле message с рекомендациями для следующего шага.

get_schema

Входные данные:

• name (строка): Имя схемы из components/schemas

Возвращает полную схему с разрешенными внутренними компонентами $ref.

get_types

Входные данные (выберите один режим):

• schemas (строка[]): Массив имен схем из components/schemas

• method (строка) + path (строка): HTTP-метод и путь эндпоинта

• operationId (строка): ID операции (например, listUsers)

Генерирует автономные объявления TypeScript в виде текстового кода. В режиме эндпоинта он следует за поддерживаемыми внутренними компонентами $ref перед сбором зависимостей схемы. Автоматически включает транзитивные зависимости и не включает операторы импорта.

Правила режима:

• Используйте ровно один режим для вызова: schemas, method + path или operationId

• Не смешивайте режимы в одном вызове

Ограничения

• Внешние $ref (например, ссылки на другие файлы или URL) не поддерживаются.

• OpenAPI 2.0 (Swagger) не поддерживается. Поддерживаются только спецификации OpenAPI 3.0 и 3.1.

Спонсорство

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

Авторы

• @reapi/mcp-openapi — за первоначальное вдохновение

Лицензия

MIT LICENSE

История звезд