EBL MCP Server

EBL MCP サーバー

このプロジェクトは、電子船荷証券（eBL）を管理する**Model Context Protocol（MCP）**サーバーを実装します。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. リポジトリをフォークし、main から機能ブランチを作成します
2. pnpm install で依存関係をインストールします
3. コーディング規約に従って変更を加えます
4. 新しい機能のテストを追加します
5. テストを実行し、すべてが想定どおりに動作することを確認します
6. プルリクエストを提出します

コーディング規約

• 適切な型定義を用いて TypeScript コードを記述します
• 関数型プログラミングの考え方に従い、クラスの使用は避けます
• 可能な限り、すべての関数を純粋関数にし、副作用のないものにします
• 補助動詞を用いた、説明的な変数名を使用します（例：isLoading、hasError）
• ファイルは、エクスポートするコンポーネント、サブコンポーネント、ヘルパー、静的コンテンツの順に構成します
• @modelcontextprotocol/sdk の仕組みを用いて、包括的なエラー処理を実装します

プルリクエストのプロセス

1. 変更内容を反映するようドキュメントを更新します
2. コードがすべてのテストに合格することを確認します
3. 少なくとも 1 人のメンテナーから承認を得ます
4. 意味のあるコミットメッセージを使い、コミット履歴を整理された状態に保ちます

問題の報告

バグを見つけた場合、または機能をリクエストする場合は、以下の情報を記載して issue を作成してください：

• 問題／リクエストの明確な説明
• 再現手順（バグの場合）
• 期待される動作と実際の動作（バグの場合）
• 関連するログやスクリーンショット

ライセンス

このプロジェクトは 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
    }
  }
}