@realeng/maestro/README.md

Easy setup and management for local MCP servers

# Maestro MCP Manager

Easy setup and management for local MCP (Model Context Protocol) servers.

## Installation

### Install from npm

```bash
npm install -g @realeng/maestro
```

### macOS Users - Download & Click Installation

1. Download the latest `maestro-macos-vX.X.X.zip` from [Releases](https://github.com/yourusername/maestro/releases)
2. Unzip the file
3. Double-click `1-install-maestro.command` to install Maestro
4. Double-click `2-configure-servers.command` to set up your MCP servers

### macOS Users - From Source

1. Clone this repository
2. Double-click `1-install-maestro.command` to install Maestro
3. Double-click `2-configure-servers.command` to set up your MCP servers

### Manual Installation from Source

1. Clone this repository
2. Install globally:
   ```bash
   npm install -g .
   ```

Or install for development:

1. Clone this repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Build the project:
   ```bash
   npm run build
   ```
4. Make the CLI globally available:
   ```bash
   npm link
   ```

## Usage

### Initialize MCP Servers

Configure authentication for MCP servers:

```bash
maestro init
```

This interactive command will:
- List available MCP servers
- Guide you through authentication setup (URLs, API tokens, etc.)
- Save credentials securely in `~/.maestro/config.json`

### Run MCP Servers

Start all configured MCP servers:

```bash
maestro run
```

This will:
- Start all enabled MCP servers
- Display port information for each server
- Keep servers running until you press Ctrl+C
- Save logs to `~/.maestro/logs/`

### Generate Claude Configuration

Generate configuration for Claude Desktop or Claude Code:

```bash
maestro mcp-config
```

This will:
- Create a JSON configuration for all your MCP servers
- Display the configuration in the terminal
- Save it to `claude-config.json` in the current directory
- Provide instructions for adding it to Claude

### View Server Logs

View logs for a specific MCP server:

```bash
# Show available servers
maestro logs

# View last 50 lines of logs for a server
maestro logs youtrack

# View last 100 lines
maestro logs youtrack -n 100

# Follow logs in real-time (like tail -f)
maestro logs youtrack -f

# Clear all log files
maestro logs clear
```

## Supported MCP Servers

Currently supported:
- **YouTrack** - JetBrains issue tracking integration

## Adding New MCP Servers

To add support for a new MCP server:

1. Create a new file in `src/servers/` (e.g., `github.ts`)
2. Implement the `MCPServerDefinition` interface:
   ```typescript
   export const githubServer: MCPServerDefinition = {
     name: 'github',
     displayName: 'GitHub',
     description: 'GitHub integration',
     requiredAuth: [
       {
         key: 'token',
         label: 'Personal Access Token',
         description: 'Your GitHub PAT',
         type: 'password'
       }
     ],
     command: (config) => ['npx', '-y', '@modelcontextprotocol/server-github'],
     env: (config) => ({
       GITHUB_PERSONAL_ACCESS_TOKEN: config.auth.token
     })
   };
   ```
3. Register it in `src/servers/index.ts`
4. Rebuild: `npm run build`

## Configuration

Maestro stores configuration in `~/.maestro/config.json`. This includes:
- Server authentication credentials
- Server enable/disable status
- Optional server settings

## Development

```bash
npm run dev     # Run in development mode
npm run build   # Build for production
npm run lint    # Run linter
npm run typecheck # Type checking
```

## Security

- Credentials are stored locally in your home directory
- API tokens are never logged or exposed
- Each server runs in isolation with its own environment

## License

MIT