Ad Pos MCP Server

Aamar Dokan POS MCP服务器

Aamar Dokan POS系统的模型上下文协议（MCP）服务器，提供与MongoDB的安全中间件连接，具有分析功能、订单管理和人工智能辅助提示生成。

目录

• 特性
• 安装说明

- 先决条件 - 安装 - 环境配置

• 建筑

- 项目结构 - MCP协议

• API文档

- 资源方法 - 工具方法 - 快速能力

• 开发指南

- 可用脚本 - 添加新方法 - 测试 - 编码标准

• 故障排除
• 更新日志
• 许可证

特性

• 🔒 安全的MongoDB连接
• 📊 具有安全验证的只读聚合管道
• 📦 订单生命周期管理
• 🤖 人工智能辅助销售运营的提示生成
• 📈 业务分析能力
• 🔍 集合探索和模式发现
• 📱 与Aamar Dokan POS系统集成
• 🛡️ 使用TypeScript实现类型安全

安装说明

先决条件

• Node.js v18+
• npm v9+
• MongoDB v6+
• TypeScript v5+
• MCP SDK v1.9.0

安装

# Clone repository
git clone https://github.com/manishankarvakta/ad-pos-mcp-server.git
cd ad-pos-mcp-server

# Install dependencies
npm install

# Create environment file
cp .env.example .env

环境配置

在中配置环境变量 .env 文件：

MONGO_URI=mongodb://username:password@hostname:port/database?authSource=admin

建筑

项目结构

ad-pos-mcp-server/
├── src/
│   ├── config/
│   │   ├── env.ts             # Environment variables
│   │   └── constants.ts       # Application constants
│   ├── handlers/
│   │   ├── resource.handler.ts # Collection and resource handlers
│   │   ├── tool.handler.ts     # Tool method implementations
│   │   └── prompt.handler.ts   # AI prompt generation
│   ├── services/
│   │   └── database.services.ts # MongoDB connection
│   ├── types/
│   │   └── index.ts           # TypeScript interfaces
│   ├── global.d.ts            # Global type declarations
│   └── index.ts               # Entry point
├── .env                       # Environment variables
├── tsconfig.json              # TypeScript configuration
├── package.json               # Dependencies and scripts
└── README.md                  # Documentation

MCP协议

MCP（模型上下文协议）服务器为AI模型实现了一个标准化的接口，以便与您的应用程序数据进行交互。它提供：

1. 资源：数据来源和收集
2. 工具：数据操作的类似功能
3. 鼓励：上下文感知模板生成

API文档

资源方法

listCollections

返回连接的MongoDB数据库中所有集合的列表。

• 参数：无
• 退货：集合信息对象数组
• 示例:

  const collections = await listCollections();
  // Returns: [{ name: "orders", ... }, { name: "products", ... }]

getCollectionSchema

从集合中返回一个示例文档，以帮助识别其架构。

• 参数:

- collectionName （string）：集合的名称

• 退货：收藏中的示例文档
• 示例:

  const schema = await getCollectionSchema("orders");
  // Returns: { _id: "...", customerId: "...", products: [...], ... }

工具方法

createOrder

在数据库中创建新订单。

• 参数:

- orderData （OrderData）：订单信息包括： - customerId （string）：客户标识符 - products （array）：包含以下内容的产品数组： - productId （string）：产品标识符 - quantity （编号）：订购数量 - price （数字，可选）：产品价格 - total （数量，可选）：订单总数

• 退货：使用生成的orderId和时间戳创建订单对象
• 示例:

  const order = await createOrder({
    customerId: "CUST-001",
    products: [
      { productId: "PROD-001", quantity: 2, price: 10.99 }
    ]
  });
  // Returns: { orderId: "ORD-1619364578245", customerId: "CUST-001", ... }

runAggregation

对具有安全验证的集合执行MongoDB聚合管道。

• 参数:

- collection （string）：要查询的集合的名称 - pipeline （数组）：MongoDB聚合管道阶段

• 退货：聚合操作的结果
• 安全：阻止危险操作，如 $out, $merge，以及 $geoNear
• 示例:

  const results = await runAggregation("orders", [
    { $match: { customerId: "CUST-001" } },
    { $group: { _id: "$customerId", total: { $sum: "$total" } } }
  ]);
  // Returns: [{ _id: "CUST-001", total: 245.87 }]

快速能力

create_sales_order

生成创建销售订单的提示。

• 参数:

- customerId （string）：客户标识符 - products （array）：订单中要包含的产品数组

• 退货：提示消息结构
• 示例:

  const prompt = await create_sales_order({
    customerId: "CUST-001",
    products: [{ productId: "PROD-001", quantity: 2 }]
  });

开发指南

可用脚本

• npm run build -将TypeScript编译为JavaScript
• npm run start -启动生产服务器
• npm run dev -使用热重新加载启动开发服务器
• npm run test -运行测试套件

添加新方法

要向MCP服务器添加新方法，请执行以下操作：

1. 定义类型：在中添加必要的接口 src/types/index.ts
2. 实施该方法：在适当的处理程序文件中创建实现
3. 注册方法：将其添加到服务器中 src/index.ts

添加新工具方法的示例：

// 1. Define the type
interface ProductData {
  name: string;
  price: number;
  category: string;
}

// 2. Implement the method
const createProduct = async (productData: ProductData) => {
  const db = await getDatabase();
  const result = await db.collection('products').insertOne({
    ...productData,
    createdAt: new Date()
  });
  return { ...productData, _id: result.insertedId };
};

// 3. Register in index.ts
mcpServer.method('createProduct', createProduct);

测试

使用运行测试 npm test.在中添加新测试 test/ 目录。

示例测试：

describe('createOrder', () => {
  it('should create an order with valid data', async () => {
    const order = await createOrder({
      customerId: 'test',
      products: [{ productId: 'p1', quantity: 1 }]
    });
    expect(order).toHaveProperty('orderId');
    expect(order.customerId).toBe('test');
  });
});

编码标准

• 遵循TypeScript的最佳实践，进行严格的类型检查
• 对所有数据库操作使用async/await
• 为所有公共方法添加JSDoc注释
• 遵循现有项目结构
• 在执行数据库操作之前验证所有输入

故障排除

常见问题

• MongoDB连接失败：验证您的MongoDB URI和网络设置
• 类型错误：确保所有接口都得到正确定义和使用
• MCP SDK版本冲突：此项目使用MCP SDK v1.9.0

调试模式

集 DEBUG=true 在你的 .env 用于附加日志记录的文件。

更新日志

v1.0.0（2024-04-22）

• 具有核心MCP服务器功能的初始版本
• 用于数据库操作的MongoDB集成
• 用于收集操作的基本资源处理程序
• 用于创建订单和运行聚合的工具处理程序
• 快速生成销售订单

许可证

ISC许可证

版权所有（c）2024 Aamar Dokan

特此授予出于任何目的使用、复制、修改和/或分发本软件的许可，无论是否收费，前提是上述版权声明和本许可声明出现在所有副本中。