FluentCart MCP 服务器端实现

使用说明

• 项目简介

  • 该仓库实现了一个完整的 MCP 服务器，用于向 LLM 客户端提供 FluentCart 商业系统的背景上下文，包括店铺资源、可调用工具、提示模板等。服务器通过 MCP 协议与客户端进行标准化的 JSON-RPC 通信，支持将 FluentCart 的 API 能力以统一、可扩展的后端服务形式暴露给 LLM 客户端使用。

• 主要功能点

  • MCP 核心能力：实现对 MCP 请求的处理、返回标准的 JSON-RPC 响应，支持会话管理与能力声明。
  • 资源托管与管理：注册并暴露 store 配置、国家信息、支付方法、过滤选项等资源，资源内容来自 FluentCart REST API。
  • 工具注册与执行：提供大量面向 FluentCart 的“工具”（Tools），包括商品、订单、客户、促销等操作，支持静态和动态两种工具集合方式。
  • Prompt 模板定义与渲染：注册多种提示模板，帮助 LLM 组装对话上下文与工具调用序列。
  • 会话管理与能力声明：服务器在启动时加载客户端连接、工具集和服务器版本信息，向客户端声明可用能力。
  • 多传输协议支持：默认标准传输（stdio）及 HTTP 转发等方式，确保与不同环境的客户端的集成。
  • 安全与日志：包含日志系统、基于服务端的认证/鉴权机制示例，以及错误处理与诊断工具。
  • 易于扩展：通过分离的模块（resources, prompts, tools、dynamic tool 注册等）实现插件化与扩展。

• 安装与运行（简明步骤）

  • 克隆代码库并进入 fluentcart-mcp 相关目录。
  • 安装依赖：在项目根目录执行依赖安装，确保 TypeScript/Node 环境就绪。
  • 运行方式（最简单开发模式）：直接使用 Node/TS 工具运行入口，或结合脚本工具以无需编译地启动。
  • 运行后，服务器将输出启动日志，显示注册的工具数量、服务器版本和运行模式。

• 服务器配置（供 MCP 客户端建立连接使用的配置） 重要说明：MCP 客户端需要一个配置来连接并启动服务端。配置仅用于客户端建立连接与握手，不参与具体的业务逻辑实现。以下描述以字段名和用途为导向，避免直接给出具体代码实现。

  • serverName（必填，字符串）
    • 服务器名称，建议设为 fluentcart-mcp，标识在客户端的连接目标。
  • command（必填，字符串）
    • 启动服务器所需命令的主程序名，例如用于运行服务器的命令（如 npx、node 等）。
  • args（必填，字符串数组）
    • 启动参数列表，包含运行入口与传输模式等，例如 ["tsx", "src/index.ts", "--transport=stdio"]，表示以标准输入输出模式启动 MCP 服务器。
  • 注释说明
    • 服务器名称用于在客户端注册与识别，确保与实际启动脚本相匹配。
    • command/args 组合应在目标执行环境中能够正确启动服务器进程，并打开 MCP 支持的传输通道（如 stdio）。
    • 客户端只需用到上述字段来建立连接，不需要关心内部实现细节。

• 基本使用方法（对开发与运维友好）

  • 启动方式：按照提供的服务器配置在目标运行环境中启动 MCP 服务器（默认以 stdio 传输）。
  • 客户端连接：LLM 客户端通过 MCP 客户端 API 连接到该服务器，加载服务器提供的工具、资源与 Prompts。
  • 使用流转：通过 JSON-RPC 请求触发资源读取、工具调用和 Prompt 渲染等能力，获得标准化的 JSON 响应。
  • 维护与扩展：如需新增资源、工具或 Prompts，按模块化结构（resources.ts、tools/、prompts.ts）进行扩展，服务器会在启动阶段自动注册相应组件。