MCP 服务器

Moleculer MCP Bridge

MCP server that exposes Moleculer.js microservice actions as AI tools, enabling AI agents to interact with Moleculer services.

README

Moleculer MCP Bridge

A Model Context Protocol (MCP) server that exposes Moleculer.js actions as AI tools.

Moleculer MCP in action.

📋 Overview

Moleculer-MCP acts as a bridge between the Model Context Protocol (MCP) and Moleculer.js microservices. It automatically exposes all your Moleculer service actions as MCP tools, enabling AI agents to seamlessly interact with your Moleculer services.

🚀 Quick Start

Installation

npm install -g moleculer-mcp

Basic Usage

Start with default settings (connects to local NATS and exposes all actions):
```
moleculer-mcp start
```

Use your existing Moleculer configuration:

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

Use a custom bridge configuration:
```
moleculer-mcp start config.json
```

Combine both configurations:

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

Configuration

Create a config.json file to overwrite and customize the bridge behavior:

{
  "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 }
    }
  ]
}

Configuration Options:

allow: Array of action patterns to expose (supports wildcards like "users.*")
server.port: Port for the MCP server (default: 3000)
broker.configFile: Path to your Moleculer config file
tools: Custom tool definitions with parameter overrides

CLI Commands

# 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

Integration with AI Clients

Once running, your Moleculer actions are available at:

http://localhost:3000/ (MCP endpoint)
http://localhost:3000/v1/mcp (Alternative endpoint)

Configure your AI client (Claude Desktop, etc.) to use this endpoint as an MCP server.

📚 Example

If you have a Moleculer service like this:

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

The bridge automatically exposes it as an MCP tool that AI agents can call:

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

�️ Development

Prerequisites

This project uses mise for development environment management. Make sure you have mise installed:

# Install mise (macOS)
brew install mise

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

Setup

Clone and setup the project:

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

Install dependencies:

mise run install
# or simply: npm install

Build the project:
```
mise run build
# or: npm run build
```

Available mise Tasks

# 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

Environment

The project is configured to use:

Node.js: 22.19.0 (via .tool-versions)
Environment: Development mode by default
TypeScript: ES2020 target with strict settings

�🔧 Advanced Usage

Using with Docker

The project includes a production-ready Dockerfile with the latest Node.js LTS version, configurable ports, and support for custom configuration files.

Quick Start with 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

Using 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 Environment Variables

PORT: Port inside the container (default: 3000)
SETTINGS_FILE: Path to custom settings file inside container (optional)

Volume Mounts

You can mount your configuration files:

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

Environment Variables

Set configuration via environment variable:

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

📖 Documentation

For detailed documentation, API reference, and advanced configuration options, visit our documentation site.

📦 Publishing (Maintainers)

This project is set up for automated publishing to npm. Here's how to release new versions:

Manual Publishing

# 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