MCP 服务器

OpenL MCP Server

Enables AI assistants to interact with OpenL Studio's business rules management system, allowing repository, project, rule, and deployment management via natural language.

README

OpenL MCP Server

Model Context Protocol server for OpenL Studio Business Rules Management System.

Built with MCP SDK v1.26+ featuring type-safe validation (Zod) and comprehensive OpenL Studio integration.

Quick Links

🚀 Quick Start - Get up and running in 5 minutes
⚙️ MCP Connection Guide - Configure Claude Desktop, Cursor, or Docker
📖 Usage Examples - Learn how to use MCP tools
🔐 Authentication - Authentication setup
🐛 Troubleshooting - Common issues and solutions
👨‍💻 Contributing - Development guide

npm Distribution

The MCP server is published as an npm package: openl-mcp-server — stdio transport via npx for Claude Desktop / Cursor / VS Code.

For details see README.npm.md.

Quick Start

Run OpenL Studio + MCP with Docker

You only need a local copy of compose.studio.yaml.

docker compose -f compose.studio.yaml up -d

This starts:

OpenL Studio image from GHCR: ghcr.io/openl-tablets/webstudio:x
MCP image from GHCR: ghcr.io/openl-tablets/openl-mcp:latest
OpenL Studio at http://localhost:8080
MCP server at http://localhost:3000

For a fast setup, use Method 1 (Docker Compose, recommended) in the Quick Start guide.

Documentation Structure

Getting Started

Quick Start - Get up and running quickly

Setup Guides

MCP Connection Guide - Complete guide for connecting Cursor and Claude Desktop to MCP server (Remote and Docker)
Docker Setup - Running MCP server in Docker (technical details)

Guides

Usage Examples - Practical examples of using MCP tools
Authentication Guide - All authentication methods (Basic Auth, Personal Access Token)
Troubleshooting Guide - Common issues, debugging, and solutions

Development

Contributing Guide - How to contribute to the project
Architecture - System architecture and design
Testing Guide - Testing strategy and how to run tests
Code Standards - Best practices and coding standards
Tool Review - Technical review of MCP tools vs OpenL API

Reference

Enable Disabled Tools - How to enable temporarily disabled tools

OpenL Studio Concepts

OpenL Studio uses dual versioning: Git-based commits (temporal) and dimension properties (business context). Supports multiple table types: Decision Tables (Rules, SimpleRules, SmartRules, Lookups), Spreadsheet Tables, and others (Method, Datatype, Test, etc.).

See prompts/create_rule.md for detailed table type guidance.

Tools

The MCP server provides 25 active tools for managing OpenL Studio repositories, projects, rules, and deployments. All tools are prefixed with openl_ and versioned (v1.0.0+).

Categories:

Repository Management (4 tools) - List repositories, branches, features
Project Management (12 active + 2 disabled = 14 total) - List, open, save, branch projects, test execution
Rules & Tables (5 active + 1 disabled = 6 total) - List, get, update, append, create tables
Deployment (4 tools) - List, deploy, redeploy projects

Note: 6 additional tools are temporarily disabled pending implementation fixes.

See Usage Examples for detailed tool usage and Enable Disabled Tools for tool reference.

Prompts

15 expert guidance templates for complex OpenL Studio workflows. Prompts provide contextual assistance, best practices, and step-by-step instructions directly in Claude Desktop or MCP Inspector.

Available prompts: local_projects, create_rule, create_rule_decision_tables, create_rule_spreadsheet, create_test, update_test, run_test, execute_rule, append_table, datatype_vocabulary, dimension_properties, deploy_project, get_project_errors, file_history, project_history.

Usage: Request prompts in Claude Desktop (e.g., "Use the create_rule prompt") or access via MCP Inspector. See prompts/create_rule.md for detailed content.

Configuration

Environment Variables

# Required
OPENL_BASE_URL=<your-base-url>

# Auth Method 1: Basic Auth
OPENL_USERNAME=<your-username>
OPENL_PASSWORD=<your-password>

# Auth Method 2: Personal Access Token
OPENL_PERSONAL_ACCESS_TOKEN=<your-token>

# Optional
OPENL_TIMEOUT=60000

See Authentication Guide for detailed auth setup.

Claude Desktop / Cursor Configuration

See MCP Connection Guide for client-specific configuration instructions.

Key Features

Type-Safe: Zod schemas with strict validation and TypeScript inference
Multiple Auth Methods: Basic Auth and Personal Access Token (PAT)
4 Response Formats: json, markdown, markdown_concise, markdown_detailed
Pagination Support: Metadata for all list operations
AI Prompts: 15 expert guidance templates
Comprehensive Tests: Full test suite covering core functionality

Development

npm run build          # Build TypeScript
npm test               # Run all tests
npm run lint           # Check code quality
npm run watch          # Dev mode with auto-rebuild

See Contributing Guide for development guidelines and Testing Guide for test suites.

Project Structure

openl-mcp/
├── src/                    # Source code (TypeScript)
├── tests/                  # Jest test suites
├── prompts/                # AI assistant guidance (OpenL-specific)
├── dist/                   # Compiled output
├── docs/                   # Documentation
│   ├── getting-started/    # Quick start and installation
│   ├── setup/              # Client setup guides
│   ├── guides/             # Usage guides and examples
│   ├── development/        # Developer documentation
│   └── reference/          # Reference materials
└── README.md               # This file