Content
# Moleculer MCP Bridge
> A Model Context Protocol (MCP) server that exposes [Moleculer.js](https://github.com/moleculerjs/moleculer) actions as AI tools.
## 📋 Overview
Moleculer-MCP acts as a bridge between the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) and [Moleculer.js](https://github.com/moleculerjs/moleculer) 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
```bash
npm install -g moleculer-mcp
```
### Basic Usage
1. **Start with default settings** (connects to local NATS and exposes all actions):
```bash
moleculer-mcp start
```
2. **Use your existing Moleculer configuration**:
```bash
moleculer-mcp start -m ./moleculer.config.js
```
3. **Use a custom bridge configuration**:
```bash
moleculer-mcp start config.json
```
4. **Combine both configurations**:
```bash
moleculer-mcp start config.json -m ./moleculer.config.js
```
### Configuration
Create a `config.json` file to overwrite and customize the bridge behavior:
```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 }
}
]
}
```
**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
```bash
# 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:
```javascript
// 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:
```json
{
"name": "users_list",
"description": "List operation for the users service",
"parameters": {
"limit": { "type": "number" },
"offset": { "type": "number" }
}
}
```
## �️ Development
### Prerequisites
This project uses [mise](https://mise.jdx.dev/) for development environment management. Make sure you have mise installed:
```bash
# Install mise (macOS)
brew install mise
# Install mise (Linux/WSL)
curl https://mise.jdx.dev/install.sh | sh
```
### Setup
1. **Clone and setup the project**:
```bash
git clone https://github.com/alvaroinckot/moleculer-mcp.git
cd moleculer-mcp
mise install # Installs Node.js 22.19.0
```
2. **Install dependencies**:
```bash
mise run install
# or simply: npm install
```
3. **Build the project**:
```bash
mise run build
# or: npm run build
```
### Available mise Tasks
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
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:
```bash
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](https://github.com/alvaroinckot/moleculer-mcp).
## 📦 Publishing (Maintainers)
This project is set up for automated publishing to npm. Here's how to release new versions:
### Manual Publishing
```bash
# 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
```
### Automated Publishing
1. **Create a release on GitHub**: This triggers the automated publish workflow
2. **GitHub Actions**: Automatically builds, tests, and publishes to npm
3. **NPM Token**: Make sure `NPM_TOKEN` is set in repository secrets
### Publishing Checklist
Before releasing:
- [ ] All tests pass (`npm run test:ci`)
- [ ] Code is properly linted (`npm run lint`)
- [ ] Code is properly formatted (`npm run format:check`)
- [ ] Build succeeds (`npm run build`)
- [ ] Version number is appropriate (patch/minor/major)
- [ ] CHANGELOG is updated (if applicable)
### Package Contents
The published package includes:
- `dist/` - Compiled JavaScript (CJS + ESM) and TypeScript definitions
- `README.md` - Documentation
- `LICENSE` - License file
Development files are excluded via `.npmignore`.
## 🤝 Contributing
Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
