MCP-Smallest.ai
A Model Context Protocol (MCP) server implementation for Smallest.ai API integration. This project provides a standardized interface for interacting with Smallest.ai's knowledge base management system.
Architecture
System Overview
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ Client App │◄────┤ MCP Server │◄────┤ Smallest.ai │
│ │ │ │ │ API │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Component Details
1. Client Application Layer
- Implements MCP client protocol
- Handles request formatting
- Manages response parsing
- Provides error handling
2. MCP Server Layer
- Protocol Handler
- Manages MCP protocol communication
- Handles client connections
- Routes requests to appropriate tools
- Tool Implementation
- Knowledge base management tools
- Parameter validation
- Response formatting
- Error handling
- API Integration
- Smallest.ai API communication
- Authentication management
- Request/response handling
3. Smallest.ai API Layer
- Knowledge base management
- Data storage and retrieval
- Authentication and authorization
Data Flow
1. Client Request
└─► MCP Protocol Validation
└─► Tool Parameter Validation
└─► API Request Formation
└─► Smallest.ai API Call
└─► Response Processing
└─► Client Response
Security Architecture
┌─────────────────┐
│ Client Auth │
└────────┬────────┘
│
┌────────▼────────┐
│ MCP Validation │
└────────┬────────┘
│
┌────────▼────────┐
│ API Auth │
└────────┬────────┘
│
┌────────▼────────┐
│ Smallest.ai │
└─────────────────┘
Overview
This project implements an MCP server that acts as a middleware between clients and the Smallest.ai API. It provides a standardized way to interact with Smallest.ai's knowledge base management features through the Model Context Protocol.
Architecture
[Client Application] <---> [MCP Server] <---> [Smallest.ai API]
Components
- MCP Server
- Handles client requests
- Manages API communication
- Provides standardized responses
- Implements error handling
- Knowledge Base Tools
listKnowledgeBases: Lists all knowledge basescreateKnowledgeBase: Creates new knowledge basesgetKnowledgeBase: Retrieves specific knowledge base details
- Documentation Resource
- Available at
docs://smallest.ai - Provides usage instructions and examples
Prerequisites
- Node.js 18+ or Bun runtime
- Smallest.ai API key
- TypeScript knowledge
Installation
- Clone the repository:
git clone https://github.com/yourusername/MCP-smallest.ai.git
cd MCP-smallest.ai
- Install dependencies:
- Create a
.env file in the root directory:
SMALLEST_AI_API_KEY=your_api_key_here
Configuration
Create a config.ts file with your Smallest.ai API configuration:
export const config = {
API_KEY: process.env.SMALLEST_AI_API_KEY,
BASE_URL: 'https://atoms-api.smallest.ai/api/v1'
};
Usage
Starting the Server
Testing the Server
- List Knowledge Bases
await client.callTool({
name: "listKnowledgeBases",
arguments: {}
});
- Create Knowledge Base
await client.callTool({
name: "createKnowledgeBase",
arguments: {
name: "My Knowledge Base",
description: "Description of the knowledge base"
}
});
- Get Knowledge Base
await client.callTool({
name: "getKnowledgeBase",
arguments: {
id: "knowledge_base_id"
}
});
All responses follow this structure:
{
content: [{
type: "text",
text: JSON.stringify(data, null, 2)
}]
}
Error Handling
The server implements comprehensive error handling:
- HTTP errors
- API errors
- Parameter validation errors
- Type-safe error responses
Development
Project Structure
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
- Define the tool in
index.ts:
server.tool(
"toolName",
{
param1: z.string(),
param2: z.number()
},
async (args) => {
// Implementation
}
);
- Update documentation in the resource:
server.resource(
"documentation",
"docs://smallest.ai",
async (uri) => ({
contents: [{
uri: uri.href,
text: `Updated documentation...`
}]
})
);
Security
- API keys are stored in environment variables
- All requests are authenticated
- Parameter validation is implemented
- Error messages are sanitized
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments