Lumi MCP Server

Local MCP (Model Context Protocol) server providing AI agents with tools to automate BMAD-METHOD installation and setup

Overview

Lumi MCP is a local Model Context Protocol server that empowers AI agents (Claude Desktop, Cursor, etc.) to automatically install and configure the BMAD-METHOD on user machines. It bridges the gap between AI agents and local system operations, enabling seamless automation of complex setup tasks.

Key Features

• 🚀 Automated BMAD Installation: One-command setup of BMAD-METHOD with all dependencies
• 🔍 Smart System Detection: Automatically checks Node.js, Git, and system requirements
• 🛡️ Safe Operations: Validates directories and permissions before making changes
• 📊 Structured Responses: AI-friendly JSON responses with detailed status and error handling
• 🌍 Cross-Platform: Works on macOS, Linux, and Windows (WSL/PowerShell)
• 🔧 stdio Transport: Uses standard input/output for efficient local communication
• 📦 npm Distribution: Easy installation and updates via npm

Quick Start

Installation

Install Lumi MCP globally using npm:

npm install -g lumi-mcp

Verify installation:

lumi-mcp --version

Configuration

Add Lumi MCP to your MCP client configuration:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "lumi-mcp": {
      "command": "lumi-mcp",
      "args": []
    }
  }
}

Cursor (.cursor/config.json in your project):

{
  "mcpServers": {
    "lumi-mcp": {
      "command": "lumi-mcp",
      "args": []
    }
  }
}

Restart your MCP client to activate Lumi MCP.

Usage

In your MCP client (Claude Desktop, Cursor, etc.), simply ask:

"Please install BMAD-METHOD in my home directory"

The AI agent will use the install_bmad tool to:

1. ✅ Check system requirements (Node.js v20+, Git)
2. ✅ Clone the BMAD-METHOD repository
3. ✅ Prepare the installation directory
4. ✅ Provide clear status and next steps

Architecture

Lumi MCP uses a Local MCP architecture with stdio transport, running directly on the user's machine to enable full access to the local filesystem and system tools.

┌─────────────────────────────────────────────┐
│         AI Agent (Claude Desktop/Cursor)    │
│         MCP Client                          │
└───────────────────┬─────────────────────────┘
                    │ stdio (JSON-RPC)
                    │ stdin/stdout
                    ↓
┌─────────────────────────────────────────────┐
│         Lumi MCP Process (Local)            │
│  ┌────────────────────────────────────────┐ │
│  │  StdioServerTransport                  │ │
│  │  • JSON-RPC over stdin/stdout          │ │
│  │  • Logs to stderr                      │ │
│  └────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────┐ │
│  │  Tools                                 │ │
│  │  • install_bmad                        │ │
│  │  • (future tools...)                   │ │
│  └────────────────────────────────────────┘ │
└───────────────────┬─────────────────────────┘
                    │ Direct execution
                    ↓
┌─────────────────────────────────────────────┐
│         Local System                        │
│  • File system (full access)               │
│  • Git operations                          │
│  • npm operations                          │
│  • Node.js runtime                         │
└─────────────────────────────────────────────┘

Available Tools

install_bmad

Automatically clones and prepares BMAD-METHOD installation in a specified directory.

Parameters:

• user_directory (string, optional): Target directory for BMAD installation
  • Default: User's home directory (~)
  • For AI agents: Please provide your current working directory
  • Examples: "~", "/Users/username", "/Users/username/projects"

Example Request:

{
  "user_directory": "~",
  "agent_type": "analyzer"
}

Success Response:

{
  "status": "success",
  "message": "BMAD-METHOD prepared successfully",
  "installation_path": "/Users/username/BMAD-METHOD",
  "next_steps": [
    "cd /Users/username/BMAD-METHOD",
    "node install.js",
    "Follow the interactive prompts to complete installation"
  ]
}

Error Response:

{
  "status": "error",
  "error_code": "GIT_NOT_INSTALLED",
  "message": "Git is not installed on this system",
  "suggestions": [
    "Install Git from https://git-scm.com/downloads",
    "Verify installation with: git --version"
  ]
}

System Requirements

• Node.js: v20.0.0 or higher
• npm: v9.0.0 or higher
• Git: v2.0.0 or higher
• Operating System: macOS, Linux, or Windows (WSL/PowerShell)
• Disk Space: 500 MB for Lumi MCP and BMAD-METHOD
• Internet: Required for npm installation and Git operations

Documentation

• 📘 Installation Guide - Detailed installation instructions
• ⚙️ Configuration Guide - MCP client configuration
• 🔧 Troubleshooting Guide - Common issues and solutions

Project Structure

lumi_proto_v6/
├── src/
│   ├── index.ts              # CLI entry point (stdio transport)
│   ├── tools/
│   │   └── bmad-installer.ts # install_bmad tool implementation
│   ├── utils/
│   │   ├── system-check.ts   # System requirements validation
│   │   ├── git-operations.ts # Git clone and operations
│   │   ├── error-handler.ts  # Structured error handling
│   │   └── logger.ts         # Logging to stderr
│   └── types.ts              # TypeScript type definitions
├── docs/
│   ├── installation.md       # Installation guide
│   ├── configuration.md      # Configuration guide
│   └── troubleshooting.md    # Troubleshooting guide
├── claudedocs/               # AI agent documentation
│   ├── lumi-mcp-implementation-plan.md
│   ├── lumi-tech-practices.md
│   └── lumi-implementation-tracker.md
├── tests/                    # Test suites
│   ├── unit/
│   └── integration/
├── package.json
├── tsconfig.json
└── README.md

Development

Prerequisites

• Node.js v20+
• npm v9+
• Git

Setup

Clone the repository:

git clone https://github.com/FebruaryLi/lumi_proto.git
cd lumi_proto

Install dependencies:

npm install

Build the project:

npm run build

Run in development mode:

npm run dev

Link for local testing:

npm link
lumi-mcp --version

Testing

Run unit tests:

npm test

Run integration tests:

npm run test:integration

Project Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Run in development mode with watch
• npm test - Run unit tests
• npm run test:integration - Run integration tests
• npm run lint - Lint code with ESLint
• npm run format - Format code with Prettier

Error Handling

Lumi MCP uses structured error codes for clear diagnosis and AI-friendly responses:

| Error Code | Description | |------------|-------------| | PREREQUISITES_NOT_MET | System requirements not satisfied (Node.js v20+, Git) | | GIT_NOT_INSTALLED | Git not found in PATH | | GIT_CLONE_FAILED | Git clone operation failed | | DIRECTORY_NOT_WRITABLE | No write permission to target directory | | DIRECTORY_NOT_EMPTY | Target directory contains existing files | | BMAD_ALREADY_INSTALLED | BMAD already exists in target directory | | NPM_INSTALL_FAILED | npm install failed during BMAD setup | | INVALID_AGENT_TYPE | Unknown agent type specified |

Each error includes:

• Clear error message
• Specific error code
• Actionable suggestions for resolution

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (npm test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to your fork (git push origin feature/amazing-feature)
8. Open a Pull Request

Coding Standards

• Follow TypeScript best practices
• Use ESLint and Prettier for code formatting
• Write unit tests for new code
• Update documentation for API changes
• Follow conventional commit messages

Technical Stack

• Language: TypeScript (ES2022)
• Runtime: Node.js v20+
• MCP SDK: @modelcontextprotocol/sdk v1.20.1
• Transport: stdio (StdioServerTransport)
• Validation: Zod v3.25.76
• Build: TypeScript compiler
• Testing: Vitest
• Linting: ESLint + Prettier

Roadmap

v1.0.0 (Current)

• ✅ Basic BMAD installation automation
• ✅ System requirements validation
• ✅ Cross-platform support
• ✅ Structured error handling

v1.1.0 (Planned)

• 🔄 BMAD configuration automation
• 🔄 Agent-specific setup
• 🔄 Post-installation validation
• 🔄 Update checking

v2.0.0 (Future)

• 📅 Additional automation tools
• 📅 Advanced error recovery
• 📅 Configuration templates
• 📅 Plugin system

FAQ

Q: What is MCP (Model Context Protocol)?

A: MCP is an open standard that enables AI agents to securely access external tools and data. Lumi MCP implements this protocol to provide BMAD installation capabilities to AI agents.

Q: Why local instead of remote?

A: Local execution provides:

• Direct access to user's filesystem
• Ability to run system commands (git, npm)
• No network latency
• Better security (no remote server access)
• Simpler deployment (npm package vs. infrastructure)

Q: Is it safe to let an AI agent install software?

A: Lumi MCP includes multiple safety measures:

• System requirements validation before operations
• Directory permission checks
• Structured error responses
• User maintains full control via MCP client
• All operations visible in logs

Q: Can I use Lumi MCP with other AI agents?

A: Yes! Lumi MCP works with any MCP-compatible client that supports stdio transport, including:

• Claude Desktop
• Cursor
• Other MCP clients supporting stdio

Q: How do I update Lumi MCP?

A: Simply run:

npm update -g lumi-mcp

Support

• Documentation: GitHub Repository
• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

ISC License - see LICENSE file for details

Acknowledgments

• Anthropic for Claude and MCP specification
• BMAD-METHOD project
• Model Context Protocol community

Version History

1.0.0 (Initial Release)

• Local MCP server with stdio transport
• install_bmad tool for automated BMAD installation
• Cross-platform support (macOS, Linux, Windows)
• Comprehensive documentation
• Structured error handling
• System requirements validation

Made with ❤️ by the BMAD-METHOD team