Moleculer MCP Bridge

Moleculer MCP Bridge

Moleculer.js のアクションを AI ツールとして公開する、Model Context Protocol（MCP）サーバーです。

📋 概要

Moleculer-MCP は、Model Context Protocol（MCP） と Moleculer.js マイクロサービスをつなぐブリッジとして機能します。Moleculer サービスのすべてのアクションを MCP ツールとして自動的に公開し、AI エージェントが Moleculer サービスをシームレスに利用できるようにします。

🚀 クイックスタート

インストール

npm install -g moleculer-mcp

基本的な使い方

1. デフォルト設定で起動します（ローカルの NATS に接続し、すべてのアクションを公開します）：

   moleculer-mcp start
   

2. 既存の Moleculer 設定を使用します：

   moleculer-mcp start -m ./moleculer.config.js
   

3. カスタムブリッジ設定を使用します：

   moleculer-mcp start config.json
   

4. 両方の設定を組み合わせます：

   moleculer-mcp start config.json -m ./moleculer.config.js
   

設定

ブリッジの動作を上書きおよびカスタマイズするには、config.json ファイルを作成します：

{
  "allow": ["users.*", "posts.*", "$node.health"],
  "server": {
    "port": 3000
  },
  "tools": [
    {
      "name": "get_user_list",
      "action": "users.list",
      "description": "Get paginated list of users",
      "params": { "limit": 50 }
    }
  ]
}

設定オプション：

• allow：公開するアクションパターンの配列です（"users.*" のようなワイルドカードをサポートします）
• server.port：MCP サーバーのポートです（デフォルト：3000）
• broker.configFile：Moleculer 設定ファイルへのパスです
• tools：パラメーターの上書きを含むカスタムツール定義です

CLI コマンド

# Start the bridge
moleculer-mcp start [config.json] [-m moleculer.config.js]

# List available actions
moleculer-mcp list-actions [-c config.json] [-m moleculer.config.js]

# Validate configuration
moleculer-mcp validate-config config.json

AI クライアントとの統合

起動すると、Moleculer のアクションは次の場所で利用できます：

• http://localhost:3000/（MCP エンドポイント）
• http://localhost:3000/v1/mcp（代替エンドポイント）

このエンドポイントを MCP サーバーとして使用するように、AI クライアント（Claude Desktop など）を設定します。

📚 例

次のような Moleculer サービスがある場合：

// user.service.js
module.exports = {
  name: "users",
  actions: {
    list: {
      params: { limit: "number", offset: "number" },
      handler(ctx) {
        return this.getUsers(ctx.params);
      }
    }
  }
};

ブリッジはこれを、AI エージェントが呼び出せる MCP ツールとして自動的に公開します：

{
  "name": "users_list",
  "description": "List operation for the users service",
  "parameters": {
    "limit": { "type": "number" },
    "offset": { "type": "number" }
  }
}

�️ 開発

前提条件

このプロジェクトでは、開発環境の管理に mise を使用します。mise がインストールされていることを確認してください：

# Install mise (macOS)
brew install mise

# Install mise (Linux/WSL)
curl https://mise.jdx.dev/install.sh | sh

セットアップ

1. プロジェクトをクローンしてセットアップします：

   git clone https://github.com/alvaroinckot/moleculer-mcp.git
   cd moleculer-mcp
   mise install  # Installs Node.js 22.19.0
   

2. 依存関係をインストールします：

   mise run install
   # or simply: npm install
   

3. プロジェクトをビルドします：

   mise run build
   # or: npm run build
   

利用可能な mise タスク

# Development tasks
mise run dev          # Start development server
mise run test         # Run tests
mise run lint         # Run linter
mise run format       # Format code

# Build tasks
mise run build        # Build all targets
mise run clean        # Clean build artifacts

# Example tasks
mise run example      # Run with example configuration
mise run cli          # Run CLI commands

# Publishing tasks (maintainers)
mise run release-patch    # Release patch version
mise run release-minor    # Release minor version
mise run release-major    # Release major version
mise run release-dry      # Test publish without publishing
mise run publish-check    # Verify package is ready for publishing

環境

このプロジェクトは次のように設定されています：

• Node.js：22.19.0（.tool-versions 経由）
• 環境：デフォルトで開発モード
• TypeScript：厳格な設定を適用した ES2020 ターゲット

�🔧 高度な使い方

Docker での使用

このプロジェクトには、最新の Node.js LTS バージョン、設定可能なポート、カスタム設定ファイルのサポートを備えた、本番環境向けの Dockerfile が含まれています。

Docker を使ったクイックスタート

# Build the image
docker build -t moleculer-mcp .

# Run with default settings (port 3000)
docker run -p 3000:3000 moleculer-mcp

# Run with custom port
docker run -p 8080:8080 -e PORT=8080 moleculer-mcp

# Run with custom settings file
docker run -p 3000:3000 \
  -v $(pwd)/my-settings.json:/app/my-settings.json \
  -e SETTINGS_FILE=/app/my-settings.json \
  moleculer-mcp

Docker Compose の使用

# Copy the example environment file
cp .env.example .env

# Start with default configuration
docker-compose up

# Start with custom port (edit .env or use environment variables)
HOST_PORT=8080 CONTAINER_PORT=8080 docker-compose up

# Start with custom settings file
SETTINGS_FILE=/app/my-settings.json docker-compose up

Docker 環境変数

• PORT：コンテナー内のポートです（デフォルト：3000）
• SETTINGS_FILE：コンテナー内のカスタム設定ファイルへのパスです（任意）

ボリュームマウント

設定ファイルをマウントできます：

docker run -p 3000:3000 \
  -v $(pwd)/moleculer.config.js:/app/moleculer.config.js:ro \
  -v $(pwd)/settings.json:/app/settings.json:ro \
  moleculer-mcp

環境変数

環境変数で設定を指定します：

export MCP_BRIDGE_SETTINGS='{"allow":["*"],"server":{"port":3000}}'
moleculer-mcp start

📖 ドキュメント

詳細なドキュメント、API リファレンス、高度な設定オプションについては、ドキュメントサイトをご覧ください。

📦 公開（メンテナー向け）

このプロジェクトでは、npm への自動公開が設定されています。新しいバージョンをリリースする手順は次のとおりです：

手動での公開

# Test the package before publishing
mise run publish-check     # Runs tests, linting, formatting, and build
mise run release-dry        # Dry run to see what would be published

# Release new versions
mise run release-patch      # 1.0.0 -> 1.0.1
mise run release-minor      # 1.0.0 -> 1.1.0  
mise run release-major      # 1.0.0 -> 2.0.0

自動公開

1. GitHub でリリースを作成します：自動公開ワークフローが起動します
2. GitHub Actions：ビルド、テスト、npm への公開を自動的に実行します
3. NPM トークン：リポジトリのシークレットに NPM_TOKEN が設定されていることを確認してください

公開前チェックリスト

リリース前に、次の項目を確認してください：

• すべてのテストが成功する（npm run test:ci）
• コードのリントが適切に行われている（npm run lint）
• コードのフォーマットが適切である（npm run format:check）
• ビルドが成功する（npm run build）
• バージョン番号が適切である（パッチ／マイナー／メジャー）
• CHANGELOG が更新されている（該当する場合）

パッケージの内容

公開されるパッケージには、以下が含まれます。

• dist/ - コンパイル済みの JavaScript（CJS + ESM）および TypeScript の型定義
• README.md - ドキュメント
• LICENSE - ライセンスファイル

開発用ファイルは .npmignore によって除外されます。

🤝 貢献

貢献を歓迎します。詳しくは、貢献ガイドをご覧ください。

📄 ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳しくは LICENSE ファイルをご覧ください。