Moleculer MCP

分子MCP桥

一个模型上下文协议（MCP）服务器，它公开 Moleculer.js 作为人工智能工具的行动。

Moleculer MCP in action.

📋 概述

🚀 快速开始

安装

npm install -g moleculer-mcp

基本用法

1. 从默认设置开始 （连接到本地NATS并公开所有操作）：

   moleculer-mcp start

1. 使用现有的Moleculer配置:

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

1. 使用自定义网桥配置:

   moleculer-mcp start config.json

1. 结合这两种配置:

   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代理可以调用的MCP工具：

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

�️ 发展

先决条件

此项目使用 布置 开发环境管理。确保您已安装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

1. 安装依赖项:

   mise run install
   # or simply: npm install

1. 构建项目:

   mise run build
   # or: npm run build

可用任务

# 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上创建发布：这将触发自动发布工作流
2. GitHub操作：自动构建、测试并发布到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许可证获得许可-请参阅 许可证 文件以获取详细信息。