Moleculer MCP Bridge

Moleculer MCP Bridge

一个模型上下文协议（MCP）服务，可将 Moleculer.js 操作作为 AI 工具开放。

📋 概述

Moleculer-MCP 是 模型上下文协议（MCP） 与 Moleculer.js 微服务之间的桥接层。它会自动将所有 Moleculer 服务操作开放为 MCP 工具，让 AI Agent 能够与您的 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（备用端点）

配置您的 AI 客户端（Claude Desktop 等），将此端点用作 MCP 服务。

📚 示例

如果您有如下 Moleculer 服务：

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

桥接层会自动将其开放为 AI Agent 可调用的 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 搭配使用

此项目包含一个适用于生产环境的 Dockerfile，使用最新的 Node.js LTS 版本，支持配置端口和使用自定义配置文件。

使用 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 上创建一个 release：这会触发自动发布工作流
2. GitHub Actions：自动构建、测试并发布到 npm
3. NPM Token：确保已在仓库密钥中设置 NPM_TOKEN

发布检查清单

发布前：

• 所有测试均通过（npm run test:ci）
• 代码已正确 lint（npm run lint）
• 代码格式正确（npm run format:check）
• 构建成功（npm run build）
• 版本号合适（patch/minor/major）
• 已更新 CHANGELOG（如适用）

软件包内容

已发布的软件包包括：

• dist/ - 编译后的 JavaScript（CJS + ESM）和 TypeScript 类型定义
• README.md - 文档
• LICENSE - 许可证文件

开发文件通过 .npmignore 排除。

🤝 贡献

欢迎贡献！详情请参阅贡献指南。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。