README.md•6.74 kB
# 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
1. **MCP Server**
- Handles client requests
- Manages API communication
- Provides standardized responses
- Implements error handling
2. **Knowledge Base Tools**
- `listKnowledgeBases`: Lists all knowledge bases
- `createKnowledgeBase`: Creates new knowledge bases
- `getKnowledgeBase`: Retrieves specific knowledge base details
3. **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
1. Clone the repository:
```bash
git clone https://github.com/yourusername/MCP-smallest.ai.git
cd MCP-smallest.ai
```
2. Install dependencies:
```bash
bun install
```
3. Create a `.env` file in the root directory:
```env
SMALLEST_AI_API_KEY=your_api_key_here
```
## Configuration
Create a `config.ts` file with your Smallest.ai API configuration:
```typescript
export const config = {
API_KEY: process.env.SMALLEST_AI_API_KEY,
BASE_URL: 'https://atoms-api.smallest.ai/api/v1'
};
```
## Usage
### Starting the Server
```bash
bun run index.ts
```
### Testing the Server
```bash
bun run test-client.ts
```
### Available Tools
1. **List Knowledge Bases**
```typescript
await client.callTool({
name: "listKnowledgeBases",
arguments: {}
});
```
2. **Create Knowledge Base**
```typescript
await client.callTool({
name: "createKnowledgeBase",
arguments: {
name: "My Knowledge Base",
description: "Description of the knowledge base"
}
});
```
3. **Get Knowledge Base**
```typescript
await client.callTool({
name: "getKnowledgeBase",
arguments: {
id: "knowledge_base_id"
}
});
```
## Response Format
All responses follow this structure:
```typescript
{
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
```
### Adding New Tools
1. Define the tool in `index.ts`:
```typescript
server.tool(
"toolName",
{
param1: z.string(),
param2: z.number()
},
async (args) => {
// Implementation
}
);
```
2. Update documentation in the resource:
```typescript
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
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Smallest.ai API](https://smallest.ai)
- [Bun Runtime](https://bun.sh)
[](https://mseep.ai/app/vinayaktiwari1103-mcp-smallest-ai)