使用说明
零售MCP服务器
A. 模型上下文协议(MCP) Clojure中的服务器实现,用于将AI助手与零售API集成。该服务器提供工具、资源和提示,使AI助手能够与电子商务平台交互,以管理集合、订单和库存。
⚠️ 重要免责声明
此存储库仅用于信息和教育目的。
- 这个项目是 不参与任何商业活动
- 所有实施都是基于 仅基于公开来源 在互联网上发布
- 这个项目 不侵犯任何版权或许可
- 该代码用于学习和演示
- 用户有责任确保在使用本软件时遵守所有适用的服务条款和许可要求
- 这是一个独立的实施,与任何商业实体没有正式联系或认可
特性
- 本地编译:编译为GraalVM本机映像,以实现快速启动(<100ms)和低内存使用率
- API全面覆盖:所有主要零售API端点(集合、订单、库存、管理)-14个MCP工具
- 符合MCP标准:全面实施MCP 2024-11-05规范(工具、资源、提示)
- 生产就绪:正确的日志记录、错误处理、超时管理(5秒)和配置
- 类型安全:用于结构化数据验证的Clojure规范
- 测试良好:88个测试,1027个断言,包括基于属性的测试
- REPL驱动开发:全面支持交互式开发和测试
目录
入门指南
先决条件
- GraalVM 23.1.0+版本 (或更新版本):用于使用JDK 21+支持进行本机映像编译
- Clojure命令行界面1.11+:用于依赖关系管理和运行应用程序
- 零售API密钥:必填-通过设置
RETAIL_API_KEY环境变量 - clj kondo (可选):用于开发过程中的代码过滤
安装
1.安装GraalVM
# Download from https://www.graalvm.org/downloads/
export GRAALVM_HOME=/path/to/graalvm
export PATH=$GRAALVM_HOME/bin:$PATH
# Install native-image component
gu install native-image
2.安装Clojure命令行界面
跟随 Clojure官方安装指南.
3.克隆和设置
git clone <repository-url>
cd clj-retail-mcp
# Install dependencies
clojure -P
配置
环境变量
创建一个 .env 文件或设置环境变量:
export RETAIL_API_KEY="your-api-key-here"
export RETAIL_BASE_URL="https://api-test.kingpin.global" # Optional, defaults to test environment
export LOG_LEVEL="INFO" # Optional, defaults to INFO
配置文件
配置通过以下方式管理 resources/config.edn 具有环境变量支持:
{:retail-api {:base-url #or [#env "RETAIL_BASE_URL" "https://api-test.kingpin.global"]
:api-key #env "RETAIL_API_KEY"}
:mcp-server {:name "retail-mcp-server"
:version "1.0.0"
:description "MCP Server for Retail API Integration"}
:logging {:level #env ["LOG_LEVEL" :info]
:pattern "%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"}
:graal {:initialize-at-build-time ["clojure" "retail"]
:reflection-config ["reflect-config.json"]}}
用法
运行服务器(开发)
MCP服务器使用 stdio传输 (非基于HTTP/端口):
# Start REPL with development profile
clojure -M:dev
# In REPL - development utilities (not actual MCP server):
(test-api-connection) # Test Retail API connectivity
(list-tools) # List available MCP tools
# Test individual client functions
(client/list-collections :limit 5)
# Test MCP tools directly
(let [tool (tools/tool-by-name "collections_get")]
((:handler tool) {:page 0 :limit 5}))
备注:实际的MCP服务器通过stdio传输运行,旨在由MCP客户端(如Claude Desktop)调用,而不是通过端口独立运行。
运行服务器(生产)
服务器使用 stdio传输 并且应由MCP客户端调用:
# Run directly with Clojure
clojure -M -m retail.mcp-server.core
# Or use the run script
./scripts/run-server.sh
# Or use the native binary (recommended)
./target/retail-mcp-server
重要:这是一个基于stdio的MCP服务器。它从stdin读取JSON-RPC请求,并将响应写入stdout。它被设计为由MCP客户端(如Claude Desktop)调用,而不是作为独立的HTTP服务器运行。
构建本土形象
# Build JAR
clojure -T:build uberjar
# Build optimized native image (recommended for production)
clojure -T:build native-image
# Build quick native image (faster, for development)
clojure -T:build quick-native
# Run native binary
./target/retail-mcp-server
本机映像功能:
- 快速启动(<100ms)
- 低内存占用(约87MB二进制)
- 串行GC(对单线程工作负载高效)
- CPU优化
-march=native - 启用HTTP/HTTPS协议支持
- 完全支持MCP协议(工具、资源、提示)
MCP集成
可用工具
服务器为零售API操作提供了14个MCP工具:
| 工具 | 说明 | 必需参数 | 可选参数 |
|---|---|---|---|
collections_get |
列出所有收藏 | - | page, limit |
collections_get_by_id |
按ID获取收藏 | collection_id |
- |
collections_create |
创建新收藏 | collection_data |
- |
collections_update |
更新收藏 | collection_id, collection_data |
- |
collections_products |
收集产品 | collection_id |
page, limit |
collections_add_products |
将产品添加到收藏 | collection_id, products |
- |
collections_remove_products |
从收藏中删除产品 | collection_id, product_ids |
- |
collections_modify_product |
修改集合中的产品 | product_id, product_data |
- |
collections_remove_all_products |
删除所有产品 | collection_id |
- |
orders_list |
列出所有订单 | - | page, limit |
orders_get |
按ID获取订单 | order_id |
- |
orders_create |
创建新订单 | collection_id, products, currency |
requested_delivery_date |
inventory_update |
更新库存数量 | products |
- |
admin_generate_api_key |
生成API密钥(管理员) | entity_id |
- |
资源
retail://api-status:当前API连接状态和运行状况检查
提示
retail-order-assistant:用于创建订单并提供验证和指导的交互式助手
客户端集成
Claude桌面设置
步骤1:构建本机二进制文件(如果尚未完成)
clojure -T:build native-image
# Produces: target/retail-mcp-server (87MB)
步骤2:查找Claude Desktop配置文件
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json
步骤3:添加MCP服务器配置
{
"mcpServers": {
"retail-mcp": {
"command": "/absolute/path/to/clj-retail-mcp/target/retail-mcp-server",
"env": {
"RETAIL_API_KEY": "your-api-key-here",
"RETAIL_BASE_URL": "https://api-test.kingpin.global",
"LOG_LEVEL": "INFO"
}
}
}
}
⚠️ 重要:使用 绝对路径 二进制!相对路径将不起作用。
步骤4:重新启动克劳德桌面
退出并重新启动Claude Desktop应用程序以使更改生效。
步骤5:验证集成
如果工具未出现,请检查Claude Desktop日志:
- macOS:
~/Library/Logs/Claude/mcp*.log - 查找连接或启动错误
与其他MCP客户端一起使用
对于支持stdio传输的其他MCP客户端:
{
"mcpServers": {
"retail-mcp": {
"command": "/absolute/path/to/retail-mcp-server",
"args": [],
"env": {
"RETAIL_API_KEY": "your-api-key-here",
"LOG_LEVEL": "INFO"
}
}
}
}
备注:此服务器仅使用stdio传输(通过stdin/stdout的JSON-RPC),不使用HTTP。
协议遵从
实施完整 MCP 2024-11-05规范:
- 工具:作为MCP工具暴露的所有零售API运营
- 资源:API状态监视和运行状况检查
- 提示:交互式订单创建辅助
- 运输:JSON-RPC通过stdio实现最大兼容性
- 错误处理:正确的JSON-RPC错误代码和结构化响应
Claude使用示例
一旦与Claude Desktop集成,请尝试以下查询:
"Use the retail-mcp tools to list the first 5 collections"
"Show me the API status using the retail resource"
"Help me create an order using the retail-order-assistant prompt"
"Get collection details for ID 689b4145140f9871a93441bc"
"List all orders with a limit of 10"
Claude将自动使用适当的MCP工具来满足这些请求。
发展
项目结构
clj-retail-mcp/
├── deps.edn # Clojure dependencies
├── build.clj # Build scripts for JAR and native image
├── README.md # This file
├── LICENSE # Apache License 2.0
├── .gitignore # Git ignore rules
├── scripts/
│ └── run-server.sh # Server startup script
├── resources/
│ ├── config.edn # Configuration with env var support
│ ├── logback.xml # Logging configuration
│ └── META-INF/native-image/
│ └── reflect-config.json # GraalVM reflection config
├── src/retail/mcp_server/
│ ├── core.clj # Main MCP server & JSON-RPC protocol handlers
│ ├── retail_client.clj # HTTP client for Retail API
│ └── tools.clj # MCP tools implementation (14 tools)
├── test/retail/mcp_server/ # Comprehensive test suite (88 tests)
│ ├── protocol_test.clj # MCP protocol compliance tests
│ ├── tools_test.clj # Tool functionality tests
│ ├── tools_comprehensive_test.clj # Comprehensive tool tests
│ ├── retail_client_test.clj # API client tests
│ ├── integration_test.clj # Integration tests
│ ├── reliability_test.clj # Reliability and error tests
│ ├── performance_test.clj # Performance tests
│ ├── validation_test.clj # Validation tests
│ └── functional_test.clj # Functional tests
└── dev/
└── user.clj # REPL development utilities
REPL工作流程
;; Start development
(require 'user)
(in-ns 'user)
;; Test API connection
(test-api-connection)
;; List available tools
(list-tools)
;; Test individual client functions
(client/list-collections :limit 5)
(client/get-collection "collection-id")
;; Test MCP tools directly
(let [tool (tools/tool-by-name "collections_get")]
((:handler tool) {:page 0 :limit 5}))
;; Reload code after changes
(refresh)
备注:对于实际的MCP服务器测试,请使用测试套件或运行带有MCP客户端集成的二进制文件。
API客户参考
这 retail.mcp-server.retail-client 命名空间为所有零售API操作提供函数:
;; Collections
(list-collections :page 0 :limit 10)
(get-collection "collection-id")
(create-collection {:name "New Collection" :type "inStock" :description "..."})
(update-collection "collection-id" {:name "Updated"})
(delete-collection "collection-id")
(list-collection-products "collection-id" :page 0 :limit 10)
(add-products-to-collection "collection-id" {:products [...]})
(remove-products-from-collection "collection-id" ["product-id-1" "product-id-2"])
(modify-product-in-collection "product-id" {:price 99.99})
(remove-all-products-from-collection "collection-id")
;; Orders
(list-orders :page 0 :limit 10)
(get-order "order-id")
(create-order {:collection_id "..." :products [...] :currency "USD"})
;; Inventory
(update-inventory {:products [{:id "..." :quantity 100}]})
;; Admin
(generate-api-key {:entity_id "entity-id"})
;; Health Check
(check-api-connectivity)
建筑
# Clean build artifacts
clojure -T:build clean
# Build JAR only
clojure -T:build uberjar
# Build optimized native image (production)
clojure -T:build native-image
# Build quick native image (development, faster compilation)
clojure -T:build quick-native
建筑
设计决策
为什么选择自定义HTTP客户端而不是生成代码?
此项目使用自定义HTTP客户端(retail.mcp-server.retail-client)而不是从OpenAPI规范生成代码,原因有几个:
OpenAPI规范问题:
目标API的OpenAPI规范具有不完整的架构定义:
#/components/schemas/Product缺失#/components/schemas/UpdateProductDto缺失
这些缺失的模式将导致OpenAPI生成器创建对不存在的类的引用,从而导致编译失败。
我们方法的优点:
- 可靠性:与实际API一起使用,而不考虑规范的完整性
- 类型安全:使用Clojure规范进行验证和正确的数据结构
- 错误处理:根据MCP服务器需求定制错误处理
- 演出:没有不必要的Java互操作开销
- 可维护性:比生成的代码更容易调试和扩展
- GraalVM 兼容性:反射问题比生成的Java代码少
实施堆栈
- 语言:Clojure 1.12.0
- HTTP客户端:
http-kitv2.8.0(高性能,GraalVM友好,出色的超时处理) - JSON处理:
jsonistav0.3.8与kebab案例密钥转换 - 验证:用于参数验证的Clojure规范(Clojure.spec.alpha)
- 错误处理:具有正确HTTP状态代码的结构化错误响应
- 配置:
aerov1.1.6用于支持环境变量的外部配置 - 日志记录:
logbackv1.4.14,带有SLF4J,针对stdio传输进行了优化(日志到stderr) - 生成工具:Clojure CLI工具
tools.buildv0.10.4
GraalVM本机映像配置
优化级别
生产构建 (native-image):
-O3优化(最大性能)--gc=serialGC(高效,适用于所有平台-G1仅在Linux上可用)-march=native(CPU特定优化)--enable-http和--enable-https(协议支持)--initialize-at-build-time=clojure(启动速度更快)- 构建时间:~4-5分钟,生成~87MB二进制文件
开发建设 (quick-native):
-O1优化(更快的编译)-Ob快速构建模式(编译速度显著加快)--gc=serialGC(开销最小,构建速度更快)--enable-http和--enable-https(协议支持)
反射结构
这 reflect-config.json 包括:
- 代理生成:使用捕获
java -agentlib:native-image-agent - Clojure特定:基本Clojure运行时模式(RT、Var、命名空间)
- 特定应用:所有MCP处理程序功能和零售API客户方法
- I/O操作:用于stdio传输的BufferedReader、InputStreamReader
- 日志记录:SLF4J和Logback反射模式
这确保了最小的反射开销,同时保持了完整的功能。
MCP协议实现
运输:基于stdio的JSON-RPC(标准MCP传输)
兼容性:
- Claude桌面版
- VS代码MCP扩展
- 其他支持stdio传输的MCP兼容客户端
- 纯stdio传输(不需要HTTP服务器)
响应结构:
;; Success response
{:result {:content [{:type "text" :text "..."}]
:isError false
:structuredContent {:data ...}}}
;; Error response
{:result {:content [{:type "text" :text "Error: ..."}]
:isError true
:structuredContent {:error "..." :message "..." :status 500}}}
测试
测试套件概述
全面测试 88次测试 和 1027条断言 涵盖:
- MCP协议合规性
- 所有API端点
- 错误处理场景
- 基于属性的测试
- 集成测试
- 性能测试
- 可靠性测试
测试框架
- 克隆试验 -标准Clojure测试框架
- test.check -基于属性的全面覆盖测试
- clojure.test.check.clojure-test -test.check与clojure.test的集成
测试类别
1.MCP协议测试(protocol_test.clj)
- 初始化请求处理
- 工具发现和列表
- 资源管理
- 快速配置
- 未知方法的错误处理
- JSON-RPC协议合规性
2.工具测试(tools_test.clj, tools_comprehensive_test.clj)
- 所有14个MCP工具均已验证
- 参数验证(必需与可选)
- 刀具查找功能
- 响应结构验证
3.API客户测试(retail_client_test.clj)
- HTTP请求处理
- 响应解析
- 错误处理(401404429500)
- 超时管理
- 连接失败场景
4.集成测试(integration_test.clj)
- 配置加载
- 端到端MCP协议流程
- API与所有端点的集成
5.可靠性测试(reliability_test.clj)
- 错误恢复
- 超时处理
- 优雅降级
- API错误场景
6.性能测试(performance_test.clj)
- 负载测试
- 并发请求处理
- 响应时间验证
7.验证测试(validation_test.clj)
- 参数验证
- 数据结构验证
- MongoDB对象ID格式验证
8.功能测试(functional_test.clj)
- 实际使用场景
- 完整的工作流程
- 边缘案例
运行测试
# Run all tests
clojure -M:test
# Run specific test namespace
clojure -M:test -n retail.mcp-server.protocol-test
# Run with coverage
clojure -M:coverage
# Check linting
clj-kondo --lint src/ test/ dev/
测试数据
样本ID(来自Postman收藏):
- 测试集合ID:
689b4145140f9871a93441bc - 测试订单ID:
688cb1a4ec09249e669b42fe - 测试产品ID:
689b4d309af98b9bbc0791e0 - 测试实体ID:
68918a94d577736caa45c89b
基于属性的测试生成器:
- 页码:0-100
- 限制:1-100
- 有效货币:美元、欧元、英镑、加元、澳元
- 带SKU、数量、价格的产品项目
- 带有collection_id、产品、货币的订单数据
测试覆盖率
API终点:
- 集合API:
/v1/integrations/collections/(获取、发布、放置、删除) - 订单API:
/v1/integrations/orders/(获取、发布) - 库存API:
/v1/integrations/inventory(PUT) - 管理员API:
/admin/integrations/api-key(职位)
MCP协议:
- 工具发现和执行
- 资源管理
- 及时管理
- 错误处理
- JSON-RPC合规性
边缘案例:
- 工具名称无效
- 缺少必要参数
- 速率限制场景
- 网络错误
- 响应结构验证
黑匣子测试方法
测试遵循黑盒测试原理:
- 无内部依赖关系:仅测试公共API和MCP接口
- 现实世界场景:基于Postman的实际收藏示例
- 全面覆盖:快乐路径、边缘情况和错误条件
- 基于属性的测试:发电机在输入范围内进行测试
- 响应验证:验证响应结构是否符合API规范
故障排除
常见问题
1.API连接失败
问题:工具返回“连接失败”或“超时”错误
解决方案:
- 验证
RETAIL_API_KEY设置正确 - 检查
RETAIL_BASE_URL指向正确的环境 - 验证与零售API的网络连接
- 审查API密钥权限和有效性
调试:
# Start REPL and test API connectivity
clojure -M:dev
# In REPL:
(test-api-connection)
# Check configuration
(client/load-config)
2.缺少API密钥错误
问题:“未设置RETAIL_API_KEY环境变量”
解决方案:
- 设置环境变量:
export RETAIL_API_KEY="your-key" - 验证密钥未设置为占位符“not_set”
- 检查
.env文件已正确加载
3.本机映像构建失败
问题:生成失败,出现反射或缺少类错误
解决方案:
- 确保
GRAALVM_HOME或JAVA_HOME设置正确 - 使用GraalVM 23.1.0+支持JDK 21+
- 审查
resources/META-INF/native-image/reflect-config.json - 首先尝试快速本地构建以隔离问题
调试:
# Verify GraalVM
echo $GRAALVM_HOME
$GRAALVM_HOME/bin/native-image --version
# Build with verbose output
clojure -T:build native-image
4.MCP客户端集成问题
问题:Claude Desktop或MCP客户端找不到或无法连接到服务器
解决方案:
- 使用绝对路径 配置为二进制(不是相对路径)
- 验证二进制文件是否具有执行权限:
chmod +x target/retail-mcp-server - 检查Claude Desktop日志中的启动错误:
- macOS:
~/Library/Logs/Claude/mcp*.log - Linux:
~/.config/Claude/logs/ - 视窗:
%APPDATA%\Claude\logs\
- macOS:
- 确保环境变量在客户端配置中(而不是在shell中)
- 配置更改后重新启动Claude Desktop
调试:
# Test server manually with stdio
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./target/retail-mcp-server
# Expected output (JSON on stdout, logs on stderr):
# {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",...}}
# Get absolute path for configuration
pwd
# Use: /absolute/path/shown/target/retail-mcp-server
5.费率限制
问题:来自API的429个错误
解决方案:
- 在客户端代码中实现指数回退
- 查看速率限制标题:
x-ratelimit-limit,x-ratelimit-remaining,x-ratelimit-reset - 减少并发请求量
调试
启用调试日志记录
# Development mode
LOG_LEVEL=DEBUG clojure -M -m retail.mcp-server.core
# Production binary
LOG_LEVEL=DEBUG ./target/retail-mcp-server
检查日志
日志被写入 标准错误 以避免干扰stdout上的MCP JSON-RPC通信。
日志级别:
ERROR:需要注意的关键错误WARN:警告(缺少API密钥、请求失败等)INFO:一般操作信息DEBUG:详细的请求/响应信息
健康检查
测试服务器初始化:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | ./target/retail-mcp-server
预期响应:
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"resources":{},"tools":{},"prompts":{}},"serverInfo":{"name":"retail-mcp-server","version":"1.0.0",...}}}
性能调整
运行时性能:
- 启动时间:<100ms(本机二进制)
- 内存占用:低(约87MB二进制文件,运行时开销最小)
- 请求延迟:<50ms用于工具执行(不包括外部API调用)
- API超时:对零售API的每个HTTP请求5秒
超时配置:
- 默认HTTP超时:5000毫秒(5秒)
- 配置于
retail-client.clj通过:timeout选项 - 保持活动:30000毫秒(30秒)用于连接重用
- 如果API需要更长的响应时间,请调整代码中的超时
原生图像优化:
- 生产建设使用
-O3优化与串行GC(--gc=serial) - 开发构建使用
-O1优化与串行GC(--gc=serial)与-Ob快速生成 - 串行GC用于跨平台兼容性(G1 GC仅在Linux AMD64/AArch64上可用)
- 构建时间:生产二进制文件约4-5分钟
- 调整中的优化标志
build.clj根据需要
支持
资源
- MCP规范: 模型上下文协议
- GraalVM 文档: GraalVM本机映像
- Clojure文档: Clojure指南
- http工具包客户端: HTTP客户端文档
贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 进行更改
- 运行测试:
clojure -M:test - 运行linting:
clj-kondo --lint src/ - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
代码质量标准
所有变更必须:
- 通过所有测试(88项测试,1027项断言)
- 没有clj kondo警告/错误
- 保持本机映像编译兼容性
- 包括对新功能的适当测试
- 遵循现有的代码风格和约定
许可证
此项目根据Apache许可证2.0获得许可-请参阅 许可证 文件以获取详细信息。
版权所有2025
根据Apache许可证2.0版(“许可证”)许可; 除非遵守许可证,否则您不得使用此文件。 您可以在以下网址获得许可证副本
http://www.apache.org/licenses/LICENSE-2.0
除非适用法律要求或书面同意,否则软件 根据许可证分发的内容按“原样”分发, 无任何明示或暗示的保证或条件。 请参阅许可证,了解管理权限和 许可证下的限制
附录
环境变量参考
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
RETAIL_API_KEY |
是 | - | neneneba API身份验证密钥 |
RETAIL_BASE_URL |
没有 | https://api-test.kingpin.global |
API基本URL |
LOG_LEVEL |
没有 | INFO |
日志记录级别(调试、信息、警告、错误) |
构建产物
| 工件 | 路径 | 目的 |
|---|---|---|
| 罐子 | target/mcp-server-0.1.0.jar |
独立JAR |
| 原生二进制 | target/retail-mcp-server |
GraalVM本机可执行文件 |
| 课程 | target/classes/ |
编译的Clojure类 |
已处理HTTP状态代码
| 代码 | 错误类型 | 描述 |
|---|---|---|
| 200-299 | 成功 | 请求已成功完成 |
| 401 | unauthorized |
API密钥无效 |
| 404 | not-found |
未找到资源 |
| 429 | rate-limit-exceeded |
请求太多 |
| 500+ | api-error |
服务器错误 |
| 超时 | timeout |
请求超时超过5秒 |
| 网络 | connection-failed |
无法访问API |
验证规则
集合ID:24个字符的MongoDB对象ID(十六进制) 订单ID:24个字符的MongoDB对象ID(十六进制) 产品ID:24个字符的MongoDB对象ID(十六进制) 货币:美元、欧元、英镑、加元、澳元 分页:页面≥0,限制1-100
最后更新时间:2025-10-29
