MCP-Smallest.ai
Реализация сервера Model Context Protocol (MCP) для интеграции API Smallest.ai. Этот проект предоставляет стандартизированный интерфейс для взаимодействия с системой управления базой знаний Smallest.ai.
Архитектура
Обзор системы
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ Client App │◄────┤ MCP Server │◄────┤ Smallest.ai │
│ │ │ │ │ API │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Детали компонента
1. Уровень клиентского приложения
- Реализует клиентский протокол MCP
- Обрабатывает форматирование запроса
- Управляет анализом ответов
- Обеспечивает обработку ошибок
2. Уровень сервера MCP
- Обработчик протоколов
- Управляет коммуникацией по протоколу MCP
- Обрабатывает клиентские соединения
- Направляет запросы соответствующим инструментам
- Реализация инструмента
- Инструменты управления базой знаний
- Проверка параметров
- Форматирование ответа
- Обработка ошибок
- API-интеграция
- API-коммуникация Smallest.ai
- Управление аутентификацией
- Обработка запросов/ответов
3. Уровень API Smallest.ai
- Управление базой знаний
- Хранение и извлечение данных
- Аутентификация и авторизация
Поток данных
1. Client Request
└─► MCP Protocol Validation
└─► Tool Parameter Validation
└─► API Request Formation
└─► Smallest.ai API Call
└─► Response Processing
└─► Client Response
Архитектура безопасности
┌─────────────────┐
│ Client Auth │
└────────┬────────┘
│
┌────────▼────────┐
│ MCP Validation │
└────────┬────────┘
│
┌────────▼────────┐
│ API Auth │
└────────┬────────┘
│
┌────────▼────────┐
│ Smallest.ai │
└─────────────────┘
Обзор
Этот проект реализует сервер MCP, который действует как промежуточное ПО между клиентами и API Smallest.ai. Он предоставляет стандартизированный способ взаимодействия с функциями управления базой знаний Smallest.ai через протокол контекста модели.
Архитектура
[Client Application] <---> [MCP Server] <---> [Smallest.ai API]
Компоненты
- MCP-сервер
- Обрабатывает запросы клиентов
- Управляет коммуникацией API
- Предоставляет стандартизированные ответы
- Реализует обработку ошибок
- Инструменты базы знаний
listKnowledgeBases : список всех баз знанийcreateKnowledgeBase : создает новые базы знанийgetKnowledgeBase : извлекает конкретные сведения из базы знаний
- Ресурс документации
- Доступно на
docs://smallest.ai - Предоставляет инструкции по использованию и примеры
Предпосылки
- Node.js 18+ или среда выполнения Bun
- API-ключ Smallest.ai
- Знание TypeScript
Установка
- Клонируйте репозиторий:
git clone https://github.com/yourusername/MCP-smallest.ai.git
cd MCP-smallest.ai
- Установите зависимости:
- Создайте файл
.env в корневом каталоге:
SMALLEST_AI_API_KEY=your_api_key_here
Конфигурация
Создайте файл config.ts с конфигурацией API Smallest.ai:
export const config = {
API_KEY: process.env.SMALLEST_AI_API_KEY,
BASE_URL: 'https://atoms-api.smallest.ai/api/v1'
};
Использование
Запуск сервера
Тестирование сервера
Доступные инструменты
- Список баз знаний
await client.callTool({
name: "listKnowledgeBases",
arguments: {}
});
- Создать базу знаний
await client.callTool({
name: "createKnowledgeBase",
arguments: {
name: "My Knowledge Base",
description: "Description of the knowledge base"
}
});
- Получить базу знаний
await client.callTool({
name: "getKnowledgeBase",
arguments: {
id: "knowledge_base_id"
}
});
Формат ответа
Все ответы имеют следующую структуру:
{
content: [{
type: "text",
text: JSON.stringify(data, null, 2)
}]
}
Обработка ошибок
На сервере реализована комплексная обработка ошибок:
- HTTP-ошибки
- Ошибки API
- Ошибки проверки параметров
- Типобезопасные ответы на ошибки
Разработка
Структура проекта
MCP-smallest.ai/
├── index.ts # MCP server implementation
├── test-client.ts # Test client implementation
├── config.ts # Configuration file
├── package.json # Project dependencies
├── tsconfig.json # TypeScript configuration
└── README.md # This file
Добавление новых инструментов
- Определите инструмент в
index.ts :
server.tool(
"toolName",
{
param1: z.string(),
param2: z.number()
},
async (args) => {
// Implementation
}
);
- Обновление документации в ресурсе:
server.resource(
"documentation",
"docs://smallest.ai",
async (uri) => ({
contents: [{
uri: uri.href,
text: `Updated documentation...`
}]
})
);
Безопасность
- Ключи API хранятся в переменных среды.
- Все запросы аутентифицированы.
- Реализована проверка параметров
- Сообщения об ошибках очищаются
Внося вклад
- Форк репозитория
- Создайте ветку функций (
git checkout -b feature/amazing-feature ) - Зафиксируйте свои изменения (
git commit -m 'Add some amazing feature' ) - Отправить в ветку (
git push origin feature/amazing-feature ) - Открыть запрос на извлечение
Лицензия
Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE .
Благодарности