MCP-Smallest.ai
Implementación de un servidor del Protocolo de Contexto de Modelo (MCP) para la integración de la API de Smallest.ai. Este proyecto proporciona una interfaz estandarizada para interactuar con el sistema de gestión de la base de conocimientos de Smallest.ai.
Arquitectura
Descripción general del sistema
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ Client App │◄────┤ MCP Server │◄────┤ Smallest.ai │
│ │ │ │ │ API │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Detalles del componente
1. Capa de aplicación del cliente
- Implementa el protocolo de cliente MCP
- Maneja el formato de la solicitud
- Gestiona el análisis de respuestas
- Proporciona manejo de errores
2. Capa de servidor MCP
- Manejador de protocolo
- Gestiona la comunicación del protocolo MCP
- Maneja las conexiones del cliente
- Envía solicitudes a las herramientas adecuadas
- Implementación de herramientas
- Herramientas de gestión de bases de conocimientos
- Validación de parámetros
- Formato de respuesta
- Manejo de errores
- Integración de API
- Comunicación API de Smallest.ai
- Gestión de autenticación
- Manejo de solicitudes/respuestas
3. Capa de API de Smallest.ai
- Gestión de la base de conocimientos
- Almacenamiento y recuperación de datos
- Autenticación y autorización
Flujo de datos
1. Client Request
└─► MCP Protocol Validation
└─► Tool Parameter Validation
└─► API Request Formation
└─► Smallest.ai API Call
└─► Response Processing
└─► Client Response
Arquitectura de seguridad
┌─────────────────┐
│ Client Auth │
└────────┬────────┘
│
┌────────▼────────┐
│ MCP Validation │
└────────┬────────┘
│
┌────────▼────────┐
│ API Auth │
└────────┬────────┘
│
┌────────▼────────┐
│ Smallest.ai │
└─────────────────┘
Descripción general
Este proyecto implementa un servidor MCP que actúa como middleware entre los clientes y la API de Smallest.ai. Proporciona una forma estandarizada de interactuar con las funciones de gestión de la base de conocimiento de Smallest.ai mediante el Protocolo de Contexto de Modelo.
Arquitectura
[Client Application] <---> [MCP Server] <---> [Smallest.ai API]
Componentes
- Servidor MCP
- Maneja las solicitudes de los clientes
- Gestiona la comunicación API
- Proporciona respuestas estandarizadas
- Implementa el manejo de errores
- Herramientas de la base de conocimientos
listKnowledgeBases : enumera todas las bases de conocimientocreateKnowledgeBase : Crea nuevas bases de conocimientogetKnowledgeBase : recupera detalles específicos de la base de conocimientos
- Recurso de documentación
- Disponible en
docs://smallest.ai - Proporciona instrucciones de uso y ejemplos.
Prerrequisitos
- Node.js 18+ o entorno de ejecución de Bun
- Clave API de Smallest.ai
- Conocimiento de TypeScript
Instalación
- Clonar el repositorio:
git clone https://github.com/yourusername/MCP-smallest.ai.git
cd MCP-smallest.ai
- Instalar dependencias:
- Cree un archivo
.env en el directorio raíz:
SMALLEST_AI_API_KEY=your_api_key_here
Configuración
Cree un archivo config.ts con la configuración de su API de Smallest.ai:
export const config = {
API_KEY: process.env.SMALLEST_AI_API_KEY,
BASE_URL: 'https://atoms-api.smallest.ai/api/v1'
};
Uso
Iniciando el servidor
Probando el servidor
Herramientas disponibles
- Lista de bases de conocimiento
await client.callTool({
name: "listKnowledgeBases",
arguments: {}
});
- Crear una base de conocimientos
await client.callTool({
name: "createKnowledgeBase",
arguments: {
name: "My Knowledge Base",
description: "Description of the knowledge base"
}
});
- Obtener base de conocimientos
await client.callTool({
name: "getKnowledgeBase",
arguments: {
id: "knowledge_base_id"
}
});
Todas las respuestas siguen esta estructura:
{
content: [{
type: "text",
text: JSON.stringify(data, null, 2)
}]
}
Manejo de errores
El servidor implementa un manejo integral de errores:
- Errores HTTP
- Errores de API
- Errores de validación de parámetros
- Respuestas de error de tipo seguro
Desarrollo
Estructura del proyecto
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
Agregar nuevas herramientas
- Define la herramienta en
index.ts :
server.tool(
"toolName",
{
param1: z.string(),
param2: z.number()
},
async (args) => {
// Implementation
}
);
- Actualizar la documentación en el recurso:
server.resource(
"documentation",
"docs://smallest.ai",
async (uri) => ({
contents: [{
uri: uri.href,
text: `Updated documentation...`
}]
})
);
Seguridad
- Las claves API se almacenan en variables de entorno
- Todas las solicitudes están autenticadas
- Se implementa la validación de parámetros
- Los mensajes de error se desinfectan
Contribuyendo
- Bifurcar el repositorio
- Crea tu rama de funciones (
git checkout -b feature/amazing-feature ) - Confirme sus cambios (
git commit -m 'Add some amazing feature' ) - Empujar a la rama (
git push origin feature/amazing-feature ) - Abrir una solicitud de extracción
Licencia
Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.
Expresiones de gratitud