MCP-Smallest.ai
用于 Smallest.ai API 集成的模型上下文协议 (MCP) 服务器实现。该项目提供了与 Smallest.ai 知识库管理系统交互的标准化接口。
建筑学
系统概述
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ Client App │◄────┤ MCP Server │◄────┤ Smallest.ai │
│ │ │ │ │ API │
└─────────────────┘ └─────────────────┘ └─────────────────┘
组件详细信息
1.客户端应用层
- 实现 MCP 客户端协议
- 处理请求格式
- 管理响应解析
- 提供错误处理
2. MCP 服务器层
- 协议处理程序
- 管理 MCP 协议通信
- 处理客户端连接
- 将请求路由到适当的工具
- 工具实现
- API 集成
- Smallest.ai API 通信
- 身份验证管理
- 请求/响应处理
3. Smallest.ai API层
数据流
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 服务器，作为客户端和 Smallest.ai API 之间的中间件。它提供了一种通过模型上下文协议 (MCP) 与 Smallest.ai 知识库管理功能进行交互的标准化方式。
建筑学
[Client Application] <---> [MCP Server] <---> [Smallest.ai API]
成分
- MCP 服务器
- 处理客户端请求
- 管理 API 通信
- 提供标准化的响应
- 实现错误处理
- 知识库工具
listKnowledgeBases ：列出所有知识库createKnowledgeBase ：创建新的知识库getKnowledgeBase ：检索特定知识库详细信息
- 文档资源
- 可在
docs://smallest.ai获取 - 提供使用说明和示例
先决条件
- Node.js 18+ 或 Bun 运行时
- Smallest.ai API 密钥
- TypeScript 知识
安装
- 克隆存储库：
git clone https://github.com/yourusername/MCP-smallest.ai.git
cd MCP-smallest.ai
- 安装依赖项：
- 在根目录中创建一个
.env文件：
SMALLEST_AI_API_KEY=your_api_key_here
配置
使用 Smallest.ai API 配置创建一个config.ts文件：
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文件。
致谢