关键词

收银系统集成销售管理业务数据查询LLM工具API桥接

项目简介

本项目是一个基于 Model Context Protocol (MCP) 实现的服务器，旨在将 'caisse.enregistreuse.fr' (或 'free-cash-register.net') 在线收银系统的功能，封装成一系列标准化的MCP工具。通过这个服务器，大型语言模型 (LLMs) 或其他任何兼容MCP协议的客户端，可以方便地与收银系统进行交互，执行如销售创建、数据查询和用户认证等操作。服务器支持通过 HTTP (Streamable JSON-RPC) 和 STDIO (标准输入输出) 两种协议进行通信。

主要功能点

  • 认证管理: 提供 'auth_get_token' 工具，允许用户通过登录凭据获取API密钥和商店ID，从而建立一个安全且持久的MCP会话。
  • 销售操作: 包含 'sales_create' 工具，支持创建详细的销售订单，可处理目录商品、部门商品和自由输入的商品行，并支持多种支付和配送方式。
  • 业务数据查询: 提供一系列 'data_list_*' 工具，用于查询收银系统中的各类核心数据，包括商品列表、部门、客户信息、支付方式、收银机、配送区域、用户列表和订单详情等。
  • 多协议支持: 服务器可以作为独立的HTTP服务运行（通过 '/mcp' 端点提供 Streamable JSON-RPC 和 SSE 通知），也可以作为子进程通过标准输入输出（STDIO）与客户端通信。
  • 国际化: 服务器的清单文件和部分工具描述支持法语和英语，方便不同语言环境下的使用。
  • 安全机制: 实现了会话级别的认证保护，并可选支持通过Bearer Token进行HTTP请求的身份验证。

安装步骤

在开始之前，请确保您的系统已安装 Node.js (v20或更高版本) 和 pnpm (或 npm/yarn)。

  1. 克隆仓库: 
    git clone https://github.com/paracetamol951/caisse-enregistreuse-mcp-server.git
  2. 进入项目目录: 
    cd caisse-enregistreuse-mcp-server
  3. 安装依赖: 
    pnpm install  # 或者 npm install / yarn install
  4. 配置环境变量: 在项目根目录创建 '.env' 文件，并添加以下基本配置。 
    # 服务器监听的HTTP端口
PORT=8787
# 远程收银系统API的基准URL
API_BASE=https://caisse.enregistreuse.fr
# 可选：如果启用HTTP层的Bearer Token验证，请在此处列出允许的token，多个token用逗号分隔
# MCP_TOKENS=your_prod_token_1,your_prod_token_2
  5. 构建项目: 
    pnpm build
  6. 启动服务器: 
    pnpm start
    服务器启动后，您会在控制台看到类似 'MCP server running at http://localhost:8787/mcp' 的消息。
  7. （可选）生成本地化清单文件: 您可以生成特定语言版本的MCP清单文件，例如生成英文清单： 
    MCP_LANG=en npm run generate:manifest
    这将在项目根目录生成 'manifest.en.json' 文件。

服务器配置（供MCP客户端使用）

MCP客户端（如LLM工具或自定义应用）需要知道如何连接并使用此MCP服务器。以下是针对两种主要传输协议的配置信息：

1. HTTP Streamable 模式配置 (推荐用于云部署或通过代理访问)

当MCP服务器作为独立的HTTP服务运行并可被外部访问时，客户端需要以下信息：

  • 'name': 'caisse-enregistreuse-api' (服务器的标识名称)
  • 'manifest_url': MCP服务器能力清单的公开URL。
    • 示例: 'http://localhost:8787/.well-known/mcp/manifest.json'
    • 注意: 如果部署在生产环境，请将 'localhost:8787' 替换为您的实际域名和端口。
  • 'transport.protocol': 'http' (指定使用HTTP协议)
  • 'transport.url': MCP JSON-RPC 请求的端点URL。
    • 示例: 'http://localhost:8787/mcp'
    • 注意: 同样，如果部署在生产环境，请替换为您的实际域名和端口。

2. STDIO 模式配置 (推荐用于作为子进程与客户端一起运行)

当MCP客户端直接启动并管理MCP服务器作为子进程时，客户端需要以下信息：

  • 'name': 'caisse-enregistreuse-api' (服务器的标识名称)
  • 'command': 启动MCP服务器的可执行文件或解释器。
    • 示例: 'node'
  • 'args': 传递给 'command' 的参数列表。
    • 示例: '["dist/stdio.js"]' (指向编译后的STDIO服务器入口文件)
  • 'transport.protocol': 'stdio' (指定使用STDIO协议)
  • 'initial_auth': （可选）用于初始认证的Shop ID和API Key。客户端可以在连接时直接提供，避免首次调用'auth_get_token'。
    • 示例: '{"SHOPID": "您的收银店ID", "APIKEY": "您的API密钥"}'

基本使用方法

通过HTTP连接 (适用于外部集成或LLM平台)

  1. 启动MCP服务器: 确保服务器已通过 'pnpm start' 命令运行，并监听配置的端口（默认为 '8787'）。
  2. 客户端连接: 您的MCP客户端（例如，OpenAI的ChatGPT、Anthropic的Claude、n8n、Flowise 或 LangChain 等）通过 '/.well-known/mcp/manifest.json' URL获取服务器的能力清单。
  3. 初始化会话: 客户端通常会发送一个 'initialize' 请求来与服务器建立会话。
  4. 执行认证: 客户端调用 'auth_get_token' 工具，并提供 'login' (您的登录邮箱) 和 'password' (您的密码) 作为参数。成功后，服务器会存储您的API密钥和商店ID，并将其与当前会话关联。
  5. 调用业务工具: 认证成功后，客户端即可调用 'sales_create' 进行销售操作，或调用 'data_list_articles' 等工具查询数据。所有后续工具调用将自动使用会话中存储的认证信息。

通过STDIO连接 (适用于本地开发或嵌入式应用)

  1. 客户端启动服务器: MCP客户端直接执行 'node dist/stdio.js' 命令来启动MCP服务器作为子进程。
  2. 通过STDIO通信: 客户端通过标准输入 (stdin) 发送 JSON-RPC 请求，并通过标准输出 (stdout) 接收 JSON-RPC 响应。
  3. 认证: 类似HTTP模式，客户端需要调用 'auth_get_token' 进行认证，或者在客户端配置中预设 'initial_auth' 参数来传递Shop ID和API Key。

信息

分类

商业系统

访问项目