npm package: @merabylabs/meraby-ai-mcp
Description: MCP server for Meraby AI - AI-powered autonomous coding agent with workspace-aware tools.
Latest version: 1.1.0

# @merabylabs/meraby-ai-mcp

[![npm version](https://img.shields.io/npm/v/@merabylabs/meraby-ai-mcp.svg)](https://www.npmjs.com/package/@merabylabs/meraby-ai-mcp)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
[![Version](https://img.shields.io/badge/version-1.1.0-purple)](https://www.npmjs.com/package/@merabylabs/meraby-ai-mcp)

> **Meraby AI MCP Server** — Your tireless background guardian for AI-powered development

A Model Context Protocol (MCP) server that provides autonomous coding capabilities powered by Vertex AI with Gemini. Part of the **Meraby Daemon** ecosystem — Watch, Plan, Execute.

**Works with:** Claude Desktop • VS Code (Copilot) • Cursor • Windsurf • Zed • JetBrains IDEs • Continue.dev • Cline

---

## 🔗 Part of the Meraby Daemon Ecosystem

| Product | Description |
|---------|-------------|
| **Meraby AI MCP** | This package — MCP server for IDE integration |
| **[VS Code Extension](https://marketplace.visualstudio.com/items?itemName=merabylabs.meraby-daemon)** | Full Daemon panel with autonomous agent capabilities |
| **[Web App](https://merabylabs.com/daemon)** | Full-featured web application |

---

## ✨ Why Meraby AI MCP?

### 🎯 Workspace-Aware Intelligence

Unlike generic AI tools, Meraby AI understands **your project context**. When executing tasks, it considers:

- **Your tech stack** — React, Node, Python, or whatever you're building with
- **Project structure** — File organization, naming conventions, architecture patterns  
- **Dependencies** — Libraries and frameworks from your package.json/requirements.txt
- **Your original request** — Ensures actions stay aligned with your actual goal

This means AI assistance tailored to **your specific codebase**, not generic boilerplate.

### 🚀 Key Benefits

- **No API key required** — Powered by Vertex AI with Gemini
- **Works in your IDE** — Integrates with your existing workflow via MCP
- **Context-aware** — Actions that understand your project conventions
- **Autonomous execution** — Plan and execute multi-step tasks

## Features

### 🛠️ Tools

| Tool | Description |
|------|-------------|
| `prompt` | Generate, refine, analyze prompts, or run workflows |
| `read_file` | Read file contents from the workspace |
| `write_file` | Create or update files |
| `list_files` | List directory contents (glob filters, respects .gitignore) |
| `search` | Text or semantic search across files (auto-index for semantic) |
| `search_and_replace` | Make targeted edits across files |
| `get_workspace_context` | Get project structure and tech stack |
| `symbols` | Symbol overview, lookup, references, edits, and AST structure |
| `execute_command` | Run shell commands |
| `run_in_terminal` | **NEW** Execute commands in VS Code integrated terminal |
| `quick_command` | **NEW** Run quick commands with automatic tool selection |
| `run_npm_script` | Execute npm scripts |
| `git_command` | Git operations |
| `install_dependencies` | Install packages |
| `custom_workflow` | Custom automation workflows |

### 📦 Resources

- **Template Library**: Reference templates for coding, writing, research, and analysis tasks
- **Category Collections**: Browse templates by category for inspiration

## Installation

```bash
npm install @merabylabs/meraby-ai-mcp
```

Or install globally:

```bash
npm install -g @merabylabs/meraby-ai-mcp
```

## Usage

Meraby AI MCP server works with any IDE or application that supports the [Model Context Protocol](https://modelcontextprotocol.io). Below are configuration examples for popular editors.

> **No API key required!** The MCP server uses Vertex AI, so you don't need your own Gemini API key.

---

### Claude Desktop

Add to your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "meraby-ai": {
      "command": "npx",
      "args": ["@merabylabs/meraby-ai-mcp"]
    }
  }
}
```

---

### VS Code (GitHub Copilot)

Add to your VS Code `settings.json` (Cmd/Ctrl+Shift+P → "Preferences: Open Settings (JSON)"):

```json
{
  "github.copilot.chat.mcp.servers": {
    "meraby-ai": {
      "command": "npx",
      "args": ["@merabylabs/meraby-ai-mcp"]
    }
  }
}
```

---

### Cursor

Add to your Cursor MCP settings:
- **macOS/Linux**: `~/.cursor/mcp.json`
- **Windows**: `%USERPROFILE%\.cursor\mcp.json`
- Or via: Settings → MCP

```json
{
  "mcpServers": {
    "meraby-ai": {
      "command": "npx",
      "args": ["@merabylabs/meraby-ai-mcp"]
    }
  }
}
```

📖 [Cursor MCP Documentation](https://docs.cursor.com/advanced/model-context-protocol)

---

### Windsurf (Codeium)

Add to your Windsurf MCP configuration:
- **macOS/Linux**: `~/.codeium/windsurf/mcp_config.json`
- **Windows**: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`

```json
{
  "mcpServers": {
    "meraby-ai": {
      "command": "npx",
      "args": ["@merabylabs/meraby-ai-mcp"]
    }
  }
}
```

📖 [Windsurf MCP Documentation](https://docs.codeium.com/windsurf/mcp)

---

### Zed

Add to your Zed settings:
- **macOS**: `~/.config/zed/settings.json`
- **Linux**: `~/.config/zed/settings.json`

```json
{
  "context_servers": {
    "meraby-ai": {
      "command": {
        "path": "npx",
        "args": ["@merabylabs/meraby-ai-mcp"]
      },
      "settings": {}
    }
  }
}
```

📖 [Zed MCP Documentation](https://zed.dev/docs/assistant/model-context-protocol)

---

### JetBrains IDEs

Works with **IntelliJ IDEA, PyCharm, WebStorm, PhpStorm, GoLand, RubyMine, CLion, DataGrip, Rider, Android Studio**.

1. Install the **MCP Client** plugin from JetBrains Marketplace
2. Go to Settings → Tools → MCP Servers
3. Add a new server with this configuration:

```json
{
  "mcpServers": {
    "meraby-ai": {
      "command": "npx",
      "args": ["@merabylabs/meraby-ai-mcp"]
    }
  }
}
```

Or add to `.idea/mcp.json` in your project.

📖 [JetBrains MCP Plugin](https://plugins.jetbrains.com/plugin/mcp-client)

---

### Continue.dev

Add to your Continue configuration:
- **Global**: `~/.continue/config.json`
- **Project**: `.continue/config.json`

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["@merabylabs/meraby-ai-mcp"]
        }
      }
    ]
  }
}
```

📖 [Continue MCP Documentation](https://docs.continue.dev/features/model-context-protocol)

---

### Cline

Add to your Cline MCP settings in VS Code:

```json
{
  "cline.mcp.servers": {
    "meraby-ai": {
      "command": "npx",
      "args": ["@merabylabs/meraby-ai-mcp"]
    }
  }
}
```

📖 [Cline MCP Documentation](https://github.com/cline/cline/blob/main/docs/mcp.md)

---

## 🔧 Configuration

### Environment Variables

```bash
# For local development with API key fallback
GEMINI_API_KEY=your-key-here

# For Vertex AI (production) - auto-detected in Google Cloud
GCLOUD_PROJECT=your-project-id
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```

### Programmatic Usage

```typescript
import { createServer } from '@merabylabs/meraby-ai-mcp';

const server = createServer();
// ... connect to your transport
```

---

## 📊 How It Works

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Your IDE      │────▶│  MCP Protocol   │────▶│   Meraby AI     │
│  (Claude, etc)  │◀────│   (stdio/SSE)   │◀────│   MCP Server    │
└─────────────────┘     └─────────────────┘     └────────┬────────┘
                                                         │
                                                         ▼
                                              ┌─────────────────┐
                                              │   Vertex AI     │
                                              │     Gemini      │
                                              └─────────────────┘
```

The MCP server:
1. Receives tool calls from your IDE
2. Executes workspace operations (read/write/search)
3. Calls Vertex AI for intelligent processing
4. Returns results via MCP protocol

---

## 🔒 Security

- **No data storage**: Your code never leaves your machine (except for AI processing)
- **Vertex AI**: Enterprise-grade security with IAM authentication
- **Local execution**: All file operations happen locally
- **Audit logging**: Full visibility in Google Cloud Console

---

## 📝 License

MIT License - see [LICENSE](LICENSE) for details.

---

## 🔗 Links

- [Meraby Labs](https://merabylabs.com)
- [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=merabylabs.meraby-daemon)
- [GitHub](https://github.com/merabylabs/meraby-daemon)
- [Model Context Protocol](https://modelcontextprotocol.io)

---

**Built with 🔮 by [Meraby Labs](https://merabylabs.com)**