MCP-Smallest.ai

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]

组件

1. MCP 服务

   • 处理客户端请求
   • 管理 API 通信
   • 提供标准化响应
   • 实现错误处理

2. 知识库工具

   • listKnowledgeBases：列出所有知识库
   • createKnowledgeBase：创建新的知识库
   • getKnowledgeBase：获取特定知识库的详细信息

3. 文档资源

   • 位于 docs://smallest.ai
   • 提供使用说明和示例

先决条件

• Node.js 18+ 或 Bun 运行时
• Smallest.ai API 密钥
• TypeScript 知识

安装

1. 克隆仓库：

git clone https://github.com/yourusername/MCP-smallest.ai.git
cd MCP-smallest.ai

2. 安装依赖项：

bun install

3. 在根目录中创建 .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

可用工具

1. 列出知识库

await client.callTool({
  name: "listKnowledgeBases",
  arguments: {}
});

2. 创建知识库

await client.callTool({
  name: "createKnowledgeBase",
  arguments: {
    name: "My Knowledge Base",
    description: "Description of the knowledge base"
  }
});

3. 获取知识库

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

添加新工具

1. 在 index.ts 中定义工具：

server.tool(
  "toolName",
  {
    param1: z.string(),
    param2: z.number()
  },
  async (args) => {
    // Implementation
  }
);

2. 更新资源中的文档：

server.resource(
  "documentation",
  "docs://smallest.ai",
  async (uri) => ({
    contents: [{
      uri: uri.href,
      text: `Updated documentation...`
    }]
  })
);

安全

• API 密钥存储在环境变量中
• 所有请求均经过身份验证
• 已实现参数验证
• 错误消息经过清理

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 模型上下文协议
• Smallest.ai API
• Bun 运行时