EBL MCP Server

EBL MCP 服务

本项目实现了一个 Model Context Protocol (MCP) 服务，用于管理电子提单（eBL）。它提供签发、查询、转让和交回 eBL 的功能。

技术栈

• 语言： TypeScript
• 包管理器： pnpm
• 运行时： Node.js
• 框架： @modelcontextprotocol/sdk

核心功能

• 签发 eBL： 创建并登记新的电子提单。
• 查询 eBL： 获取现有 eBL 的详细信息。
• 转让 eBL： 更改 eBL 的持有人／所有者。
• 交回 eBL： 将 eBL 标记为已交回，通常在货物交付时进行。

入门指南

前提条件

• Node.js（建议使用 LTS 版本）
• pnpm（通过 npm install -g pnpm 安装）

安装

1. 克隆仓库：

   git clone <your-repo-url>
   cd ebl-mcp-server
   

2. 安装依赖：

   pnpm install
   

运行服务

• 开发模式：

  pnpm dev
  

• 生产模式：

  pnpm build
  pnpm start
  

  (注意：需要在 package.json 中定义构建和启动脚本)

项目结构（初步设想）

ebl-mcp-server/
├── src/
│   ├── index.ts         # Main application entry point
│   ├── routes/          # API route definitions
│   ├── controllers/     # Request handlers
│   ├── services/        # Business logic
│   ├── models/          # Data models/interfaces (e.g., eBL structure)
│   ├── middleware/      # Custom middleware (auth, logging, etc.)
│   └── config/          # Configuration files
├── test/                # Unit and integration tests
├── .env.example         # Environment variable template
├── .gitignore
├── package.json
├── pnpm-lock.yaml
├── tsconfig.json
├── README.md            # This file
└── PLAN.md              # Development plan

贡献

欢迎为改进 EBL MCP 服务作出贡献！请遵循以下指南，以确保协作顺畅：

开发工作流

1. Fork 仓库，并从 main 创建功能分支
2. 使用 pnpm install 安装依赖
3. 按照我们的编码规范进行修改
4. 为新功能添加测试
5. 运行测试，确保一切正常
6. 提交拉取请求

编码规范

• 编写 TypeScript 代码，并提供适当的类型定义
• 遵循函数式编程范式；避免使用类
• 尽可能确保所有函数都是纯函数且无副作用
• 使用描述性变量名，并采用辅助动词（例如，isLoading、hasError）
• 文件结构：导出的组件、子组件、辅助函数、静态内容
• 使用 @modelcontextprotocol/sdk 的机制实现全面的错误处理

拉取请求流程

1. 更新文档以反映任何更改
2. 确保代码通过所有测试
3. 至少获得一位维护者的批准
4. 保持提交历史整洁，并使用有意义的提交消息

报告问题

如果发现错误或有功能请求，请创建问题并提供：

• 对问题／请求的清晰描述
• 复现步骤（针对错误）
• 预期行为和实际行为（针对错误）
• 任何相关日志或屏幕截图

许可证

本项目采用 Apache License, Version 2.0 许可，详情请参阅 LICENSE 文件。

示例

签发 eBL

{
  "method": "tools/call",
  "params": {
    "name": "issue_ebl",
    "arguments": {
      "requester_bu_id": "did:openebl:3993ace7-eb6c-4a1f-bed8-121643a278c9",
      "file_content": {
        "url": "https://flash-store.kevin-a65.workers.dev/file/pStQB1tvsV89Ms6AhImTQQ"
      },
      "bl_number": "BL-20250417-12999",
      "bl_doc_type": "HouseBillOfLading",
      "pol": {
        "locationName": "YanTian",
        "UNLocationCode": "CNYTN"
      },
      "pod": {
        "locationName": "LA",
        "UNLocationCode": "USLAX"
      },
      "shipper": "did:openebl:d2856f4e-e636-4cf0-9110-fbb45304e614",
      "consignee": "did:openebl:0158341d-5c6b-4121-bfe4-535c7606bbd5",
      "release_agent": "did:openebl:66c71465-3d0b-43d8-9e1b-c88c7a7634ca",
      "draft": false,
      "to_order": false,
      "eta": "2025-05-01",
      "endorsee": "",
      "notify_parties": [],
      "note": "Test from MCP",
      "encrypt_content": false
    },
    "_meta": {
      "progressToken": 11
    }
  }
}