ebl-mcp-server

EBL MCP Server

This project implements a Model Context Protocol (MCP) server to manage electronic Bills of Lading (eBLs). It provides functionalities to issue, query, transfer, and surrender eBLs.

Technology Stack

• Language: TypeScript
• Package Manager: pnpm
• Runtime: Node.js
• Framework: @modelcontextprotocol/sdk

Core Features

• Issue eBL: Create and register a new electronic Bill of Lading.
• Query eBL: Retrieve details of existing eBLs.
• Transfer eBL: Change the holder/owner of an eBL.
• Surrender eBL: Mark an eBL as surrendered, typically upon cargo delivery.

Getting Started

Prerequisites

• Node.js (LTS version recommended)
• pnpm (Install via npm install -g pnpm)

Installation

1. Clone the repository:

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

2. Install dependencies:

   pnpm install
   

Running the Server

• Development Mode:

  pnpm dev
  

• Production Mode:

  pnpm build
  pnpm start
  

  (Note: Build and start scripts need to be defined in package.json)

Project Structure (Initial Idea)

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

Contributing

We welcome contributions to improve the EBL MCP Server! Please follow these guidelines to ensure a smooth collaboration:

Development Workflow

1. Fork the repository and create a feature branch from main
2. Install dependencies with pnpm install
3. Make your changes following our coding standards
4. Add tests for new functionality
5. Run tests to ensure everything works as expected
6. Submit a pull request

Coding Standards

• Write TypeScript code with proper type definitions
• Follow functional programming paradigms; avoid using classes
• Ensure all functions are pure and side-effect free when possible
• Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError)
• Structure files: exported component, subcomponents, helpers, static content
• Implement comprehensive error handling using @modelcontextprotocol/sdk's mechanisms

Pull Request Process

1. Update documentation to reflect any changes
2. Ensure code passes all tests
3. Get approval from at least one maintainer
4. Maintain clean commit history with meaningful commit messages

Reporting Issues

If you find a bug or have a feature request, please create an issue providing:

• A clear description of the problem/request
• Steps to reproduce (for bugs)
• Expected and actual behavior (for bugs)
• Any relevant logs or screenshots

License

This project is licensed under the Apache License, Version 2.0 - see the file for details.

Samples

Issue 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
    }
  }
}