使用说明
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之间的中间件。它提供了一种通过模型上下文协议与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
- 安装依赖项：
bun install
- 创建一个
.env根目录中的文件：
SMALLEST_AI_API_KEY=your_api_key_here
配置
创建一个 config.ts 使用Smallest.ai API配置的文件：
export const config = {
API_KEY: process.env.SMALLEST_AI_API_KEY,
BASE_URL: 'https://atoms-api.smallest.ai/api/v1'
};
用法
启动服务器
bun run index.ts
测试服务器
bun run test-client.ts
可用工具
- 列出知识库
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许可证获得许可-请参阅 许可证 文件以获取详细信息。
