# meow-complete 🐱

**TMux Terminal AI Autocomplete** - Intelligent command completion powered by LLMs

Transform natural language into shell commands directly in your tmux terminal with a simple keystroke.

## Features

- **Natural Language to Commands**: Type what you want in plain English, get the exact command
- **Multi-Provider Support**: Works with Anthropic Claude, OpenAI GPT, and Google Gemini
- **Security First**: All LLM output is sanitized to prevent command injection
- **Smart Caching**: Reduces API calls and improves response time
- **Seamless Integration**: Works directly in tmux with familiar keybindings
- **Lightweight**: Pure bash, minimal dependencies

## Quick Start

```bash
# Clone the repository
git clone https://github.com/yourusername/meow-complete.git
cd meow-complete

# Run installation
./install.sh

# Configure API key
nano ~/.config/meow-complete/config.env

# Reload shell
source ~/.zshrc
```

## Installation

### Prerequisites

- **tmux** - Terminal multiplexer
- **zsh** - Z Shell
- **curl** - HTTP client
- **jq** - JSON processor

Install on Ubuntu/Debian:
```bash
sudo apt install tmux zsh curl jq
```

Install on macOS:
```bash
brew install tmux zsh curl jq
```

### Install meow-complete

1. **Run the installer:**
   ```bash
   ./install.sh
   ```

2. **Configure your API key:**

   Edit `~/.config/meow-complete/config.env` and set one of:

   ```bash
   # Anthropic Claude (recommended)
   ANTHROPIC_API_KEY="sk-ant-api03-..."
   MEOW_PROVIDER="anthropic"
   MEOW_MODEL="claude-3-5-sonnet-20241022"

   # OpenAI GPT
   OPENAI_API_KEY="sk-..."
   MEOW_PROVIDER="openai"
   MEOW_MODEL="gpt-4"

   # Google Gemini
   GEMINI_API_KEY="..."
   MEOW_PROVIDER="gemini"
   MEOW_MODEL="gemini-pro"
   ```

3. **Reload your shell:**
   ```bash
   source ~/.zshrc
   ```

## Usage

### Basic Usage

In any tmux session, type a natural language description and press **Ctrl+Space**:

```bash
# Example 1: File operations
$ find all python files modified in last week<Ctrl+Space>
→ find . -name "*.py" -mtime -7

# Example 2: Git commands
$ git commit with conventional format for bug fix<Ctrl+Space>
→ git commit -m "fix: "

# Example 3: System monitoring
$ show me disk usage sorted by size<Ctrl+Space>
→ du -sh * | sort -h

# Example 4: Network operations
$ show all listening ports<Ctrl+Space>
→ netstat -tlnp

# Example 5: Text processing
$ count lines in all log files<Ctrl+Space>
→ wc -l *.log
```

### Keybindings

| Key | Action |
|-----|--------|
| **Ctrl+Space** | Trigger AI completion |
| **Tab** | Accept completion |
| **Esc** | Reject completion |
| **Enter** | Execute command (after accepting) |

### How It Works

1. **Capture**: You type a natural language query in tmux
2. **Call**: Press Ctrl+Space to send to LLM API
3. **Complete**: AI generates the command
4. **Sanitize**: Dangerous patterns are removed
5. **Insert**: Safe command appears in your buffer
6. **Accept/Reject**: Tab to accept, Esc to reject

## Configuration

### Configuration File

Location: `~/.config/meow-complete/config.env`

```bash
# API Provider (anthropic, openai, gemini)
MEOW_PROVIDER="anthropic"

# API Keys (set the one for your provider)
ANTHROPIC_API_KEY="sk-ant-..."
OPENAI_API_KEY="sk-..."
GEMINI_API_KEY="..."

# Model Selection
MEOW_MODEL="claude-3-5-sonnet-20241022"  # or gpt-4, gemini-pro

# System Prompt (customize behavior)
MEOW_SYSTEM_PROMPT="You are a shell command expert..."

# Caching
MEOW_ENABLE_CACHE=true
MEOW_CACHE_TTL=3600  # 1 hour

# Timeouts
MEOW_API_TIMEOUT=10  # seconds
```

### Directory Structure

```
~/.config/meow-complete/
├── config.env              # Your configuration
└── lib/                    # Installed libraries
    ├── meow-complete.sh    # Main integration
    ├── api_client.sh       # API communication
    └── sanitize.sh         # Security sanitization

~/.cache/meow-complete/
├── completions/            # Cached responses
├── meow.log               # Application log
└── sanitize.log           # Security audit log
```

## Security

### Security Architecture

**CRITICAL**: This tool inserts LLM-generated text into your shell. Security is paramount.

#### Defense Layers

1. **Input Sanitization**: All LLM responses pass through `lib/sanitize.sh`
2. **Pattern Removal**: Dangerous shell constructs are stripped
3. **Validation**: Post-sanitization checks ensure safety
4. **Logging**: All suspicious outputs are logged for review
5. **Fail-Safe**: On any doubt, returns empty string

#### What Gets Blocked

- **Command Substitution**: `$(...)`, `` `...` ``
- **Redirects**: `>`, `<`, `>>`, `2>`, `&>`, `|`
- **Command Chaining**: `;`, `&&`, `||`
- **Control Characters**: Newlines, null bytes, etc.
- **Dangerous Patterns**: `rm -rf`, `curl | sh`, `eval`, `exec`

#### Security Logs

Review suspicious activity:
```bash
# View security log
cat ~/.cache/meow-complete/sanitize.log

# Monitor in real-time
tail -f ~/.cache/meow-complete/sanitize.log
```

### Security Best Practices

1. **Review First**: Always review generated commands before execution
2. **Check Logs**: Periodically review `sanitize.log` for anomalies
3. **Limit Scope**: Use specific, detailed queries
4. **API Keys**: Keep API keys secure, use environment variables
5. **Test Mode**: Test with `MEOW_DRY_RUN=true` for sensitive operations

### Threat Model

| Threat | Mitigation |
|--------|------------|
| Malicious LLM output | Multi-layer sanitization |
| Command injection | Pattern-based filtering |
| Privilege escalation | No sudo commands generated |
| Data exfiltration | Redirect operators removed |
| Remote code execution | Command substitution blocked |

## Examples

### Development Tasks

```bash
# Git operations
$ git commit with conventional commit message for feature
→ git commit -m "feat: "

# Find and replace
$ replace all occurrences of old_function with new_function in python files
→ find . -name "*.py" -exec sed -i 's/old_function/new_function/g' {} +

# Docker cleanup
$ remove all stopped docker containers
→ docker rm $(docker ps -a -q -f status=exited)
```

### System Administration

```bash
# Process management
$ show top 10 processes by memory usage
→ ps aux --sort=-%mem | head -n 11

# Disk management
$ find files larger than 100MB
→ find / -type f -size +100M 2>/dev/null

# Log analysis
$ show last 50 lines of syslog with errors
→ tail -n 50 /var/log/syslog | grep -i error
```

### Data Processing

```bash
# CSV manipulation
$ extract column 3 from csv file
→ cut -d',' -f3 data.csv

# JSON processing
$ pretty print json file
→ jq '.' file.json

# Archive operations
$ extract tar.gz to specific directory
→ tar -xzf archive.tar.gz -C /target/directory
```

## Troubleshooting

### Common Issues

#### "No completion generated"

**Causes:**
- API key not configured
- Network connectivity issues
- API rate limiting

**Solutions:**
```bash
# Check API key
grep API_KEY ~/.config/meow-complete/config.env

# Test connectivity
curl -I https://api.anthropic.com

# Check logs
tail ~/.cache/meow-complete/meow.log
```

#### "Command not appearing in buffer"

**Causes:**
- Not in a tmux session
- Keybinding conflict

**Solutions:**
```bash
# Verify tmux
echo $TMUX  # Should output something

# Test manually
meow_complete "list files"
```

#### "Sanitization too aggressive"

**Causes:**
- Legitimate command contains filtered patterns

**Solutions:**
- Use more specific queries
- Check `sanitize.log` for what was filtered
- Adjust sanitization rules in `lib/sanitize.sh` (advanced)

### Debug Mode

Enable verbose logging:

```bash
# In config.env
MEOW_DEBUG=true
MEOW_LOG_LEVEL="debug"

# View detailed logs
tail -f ~/.cache/meow-complete/meow.log
```

### Test Suite

Run security tests:

```bash
# Install bats (Bash Automated Testing System)
npm install -g bats

# Run security tests
bats tests/test_security.bats

# Run API tests
bats tests/test_api.bats
```

## Development

### Project Structure

```
meow-complete/
├── config/
│   └── default.env         # Default configuration
├── lib/
│   ├── meow-complete.sh    # Main integration script
│   ├── api_client.sh       # API client library
│   └── sanitize.sh         # Security sanitization
├── tests/
│   ├── test_security.bats  # Security test suite
│   └── test_api.bats       # API integration tests
├── install.sh              # Installation script
├── IMPLEMENTATION.md       # Technical documentation
└── README.md              # This file
```

### Contributing

Contributions welcome! Focus areas:

- Additional LLM provider support
- Improved sanitization patterns
- Better caching strategies
- Context-aware completions
- Multi-line command support

### Testing

```bash
# Run all tests
bats tests/*.bats

# Run specific test file
bats tests/test_security.bats

# Run specific test
bats tests/test_security.bats -f "sanitize removes"
```

## Performance

### Benchmarks

| Operation | Time (cached) | Time (uncached) |
|-----------|---------------|-----------------|
| Simple command | <100ms | ~2s |
| Complex command | <100ms | ~3s |
| First completion | N/A | ~2-4s |

### Optimization Tips

1. **Enable Caching**: Reuses responses for identical queries
2. **Use Faster Models**: GPT-3.5-turbo vs GPT-4
3. **Preload Common Commands**: Build cache during idle time
4. **Adjust Timeout**: Balance speed vs. complex queries

## FAQ

**Q: Does this work outside tmux?**
A: Currently tmux-only. Terminal emulator support planned.

**Q: Can I use my own LLM API?**
A: Yes, modify `lib/api_client.sh` to add custom providers.

**Q: How much does this cost?**
A: Minimal. ~$0.001-0.01 per completion depending on provider.

**Q: Is my data sent to the API?**
A: Only the query text is sent. No command history or sensitive data.

**Q: Can I customize the AI behavior?**
A: Yes, edit `MEOW_SYSTEM_PROMPT` in `config.env`.

**Q: Does it work with fish/bash?**
A: Currently zsh-only. Bash support coming soon.

## License

MIT License - see LICENSE file

## Credits

Created by Chris Rogers

Inspired by:
- GitHub Copilot CLI
- Fig autocomplete
- Warp AI terminal

## Support

- **Issues**: https://github.com/yourusername/meow-complete/issues
- **Discussions**: https://github.com/yourusername/meow-complete/discussions
- **Security**: security@yourdomain.com

---

**⚠ Security Notice**: This tool executes LLM-generated commands. Always review commands before execution. Not recommended for production servers without additional safeguards.


# CanonForge

![CanonForge Logo](./assets/canonforge-logo.png)

**Industrial Posthumous Continuation Engine**

*Automated continuation engine for unfinished series by deceased authors*

[![Phase 10 Complete](https://img.shields.io/badge/Phase-10%20Complete-success)](./CLAUDE.md)
[![Rust](https://img.shields.io/badge/Rust-1.70+-orange.svg)](https://www.rust-lang.org/)
[![Next.js](https://img.shields.io/badge/Next.js-14-black)](https://nextjs.org/)
[![License](https://img.shields.io/badge/License-Transformative%20Work-blue.svg)](#legal-notice)

[Features](#features) • [Architecture](#architecture) • [Quick Start](#quick-start) • [Documentation](#documentation)

---

## 🎯 What is CanonForge?

CanonForge is a sophisticated AI-driven system designed to complete unfinished literary series with respect, technical precision, and narrative integrity. When a beloved author passes away leaving a series incomplete, CanonForge provides tools to honor their vision by finishing what they started.

### Core Capabilities

- 📚 **Canon Extraction** - Deep analysis of published works, author notes, and partial drafts
- 🧵 **Thread Resolution** - Identifies and resolves all foreshadowing and unresolved arcs
- ✍ **Voice Matching** - Learns author's style through embeddings and fine-tuning
- 🎨 **Draft Generation** - Produces complete manuscripts in established voice
- ✅ **Quality Assurance** - Validates continuity and maintains tonal consistency
- 📊 **Style Analytics** - Quantifies lexical density, pacing, and stylistic patterns

---

## 🚀 Features

### Phase 1-3: Core Pipeline
- **Canon Extraction** - Ingests source material and extracts narrative DNA
- **Resolution Planning** - Maps complete closure for all character arcs and plot threads
- **Draft Generation** - AI-powered chapter creation following resolution plan
- **Voice Lockdown** - Iterative refinement to match author's voice
- **Continuity QA** - Validates consistency across entire series

### Phase 4: Style & Fine-Tuning ✨ NEW
- **Dataset Building** - Aggregates source text with lexical metrics
- **Embedding Generation** - Vector embeddings for semantic similarity
- **Style Matching** - Cosine similarity analysis for voice consistency
- **Fine-Tune Pipeline** - Per-author model adaptation
- **Interactive Analytics** - Visual dashboards with Recharts

---

## 🏗 Architecture

### Tech Stack

**Backend**
- 🦀 Rust - High-performance API server with Axum
- 🗄 SQLite - Local vector storage for embeddings
- 🔌 RESTful API - OpenAI-compatible endpoints
- 📦 Docker - Production containerization

**Frontend**
- ⚛ Next.js 14 - React server components
- 🎨 TailwindCSS - Modern UI styling
- 📊 Recharts - Data visualization
- 🎭 shadcn/ui - Component library

**AI Integration**
- 🤖 Google Gemini 2.5 Pro - Primary reasoning model
- 🌟 Skyfall 31B - High-quality generation (ollama.reddoor.local)
- 📚 Multi-model orchestration with fallback chains
- 📝 Structured JSON output validation

### System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        Next.js Frontend                      │
│  /authors • /canon • /plan • /draft • /qa • /log            │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Rust API Server (Axum)                   │
│  /api/author/* • /api/ai/* • /api/canon_pack                │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Data Layer                              │
│  SQLite (embeddings) • JSON/YAML (canon) • File Storage     │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    External AI Services                      │
│  OpenAI API • Gemini API • Custom LLM Endpoints             │
└─────────────────────────────────────────────────────────────┘
```

---

## 📦 Quick Start

### Prerequisites

- Rust 1.70+ (for backend)
- Node.js 18+ (for frontend)
- AI API key (OpenAI, Anthropic, or compatible)

### Installation

```bash
# Clone repository
git clone <repository-url>
cd canonforge

# Backend setup
cd server
cargo build --release

# Frontend setup
cd ../web
npm install

# Configure environment
cp .env.example .env
# Edit .env with your API keys
```

### Running the System

**Development Mode**

```bash
# Terminal 1: Start Rust backend
cd server
cargo run
# Backend runs on http://localhost:8000

# Terminal 2: Start Next.js frontend
cd web
npm run dev
# Frontend runs on http://localhost:3000
```

Visit `http://localhost:3000` to access the dashboard.

**Docker Production Mode**

```bash
# Build and start all services
docker-compose up --build

# Frontend: http://localhost:6768
# Backend: http://localhost:6767
```

Services include:
- `web` - Next.js frontend (port 6768)
- `server` - Rust/Axum backend (port 6767)
- `adaptive-daemon` - Autonomous learning cycle

---

## 📖 Documentation

### Phase Documentation
- [Phase 2: Web + Backend Stack](./PHASE2_README.md)
- [Phase 3: AI Pipeline Integration](./PHASE3_README.md)
- [Phase 4: Author Style & Fine-Tuning](./PHASE4_README.md) ✨ Latest

### API Documentation

#### Author Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/author/build_dataset` | POST | Build unified dataset from source texts |
| `/api/author/embed_dataset` | POST | Generate embeddings for all paragraphs |
| `/api/author/style_vector` | POST | Compute style similarity |
| `/api/author/fine_tune` | POST | Create fine-tune job |

#### Canon Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/canon_pack` | GET | Retrieve extracted canon |
| `/api/resolution_plan` | GET | Get resolution plan |
| `/api/manuscript` | GET | List generated chapters |
| `/api/continuity_report` | GET | Get QA report |

---

## 🎨 Usage Example

### 1. Prepare Source Material

```bash
mkdir -p canon_data/source_text
cp author_book1.txt author_book2.txt canon_data/source_text/
```

### 2. Build Author Dataset

Navigate to `/authors` and:
1. Select author
2. Click "Build Dataset"
3. View lexical metrics

### 3. Generate Embeddings

Click "Embed Dataset" to create vector embeddings for style matching.

### 4. Analyze Style

Use "Check Style" to compare sample text against author corpus:
- Enter sample text
- View similarity score (0-100%)
- See top-3 matching paragraphs

### 5. Fine-Tune Model

Initiate fine-tuning to adapt model to author's style.

---

## 📊 Data Directory Structure

```
canonforge/
├── canon_data/
│   ├── source_text/         # Raw source novels (.txt)
│   ├── dataset/             # Aggregated per-author datasets
│   │   ├── author.txt
│   │   └── author_meta.json
│   ├── embeddings/          # SQLite vector databases
│   │   └── author.db
│   ├── fine_tunes/          # Fine-tune configurations
│   │   ├── author.json
│   │   └── author_result.json
│   ├── canon_pack.json      # Extracted canon
│   ├── resolution_plan.yaml # Resolution structure
│   └── continuity_report.json # QA results
├── manuscript/              # Generated chapters
├── server/                  # Rust backend
└── web/                     # Next.js frontend
```

---

## 🧪 Testing

### Backend Tests

```bash
cd server
cargo test
```

Tests include:
- Word counting accuracy
- Lexical density calculation
- Cosine similarity computation
- Vector serialization

### Frontend E2E Tests

```bash
cd phaseops
npm test
```

Playwright tests verify:
- UI navigation
- Dataset workflows
- Chart rendering
- API integration

---

## 🔧 Configuration

### Environment Variables

Create a `.env` file in the `server` directory:

```bash
# Primary AI Provider - Google Gemini
GEMINI_API_KEY=your-gemini-api-key-here
GEMINI_MODEL=gemini-2.5-pro-latest

# Secondary AI Provider - Skyfall 31B (Local Ollama)
SKYFALL_API_URL=http://ollama.reddoor.local:11434/v1/chat/completions
SKYFALL_MODEL=skyfall-31b:latest

# Embedding Configuration (for style matching)
AI_EMBED_URL=https://api.openai.com/v1/embeddings
AI_EMBED_MODEL=text-embedding-3-small
AI_EMBED_KEY=your-openai-key-for-embeddings

# Server Configuration
RUST_LOG=info
BIND_ADDRESS=0.0.0.0:8000  # or 0.0.0.0:6767 for Docker
```

### Required API Keys

1. **Google Gemini API**: Get from [Google AI Studio](https://makersuite.google.com/app/apikey)
   - Used for canon extraction, planning, and generation
   - Required for core pipeline functionality

2. **Skyfall 31B** (Optional but recommended):
   - Local Ollama instance with Skyfall-31B model
   - Provides higher quality output for final generation
   - Falls back to Gemini if unavailable

3. **OpenAI API** (Optional):
   - Only needed for style embeddings feature
   - Can be omitted if not using voice matching

---

## 🎯 Roadmap

### ✅ Completed
- [x] Phase 1-3: Core pipeline (canon extraction, planning, generation)
- [x] Phase 4: Author style analytics & fine-tuning
- [x] Phase 5: Adaptive reinforcement learning
- [x] Phase 6: Multi-series ingestion & management
- [x] Phase 7: Pipeline wizard UI (guided workflow)
- [x] Phase 8: Integration test harness & autonomous quality loop
- [x] Phase 9: Skyfall 31B integration & multi-model architecture
- [x] Phase 10: Full series generation with agentic iteration
- [x] EPUB export support
- [x] Production Docker deployment

### 🚧 Current Capabilities
- Full series continuation pipeline (ingest → export)
- Multi-model AI orchestration (Gemini + Skyfall)
- Autonomous quality iteration loop
- EPUB/text export with metadata
- Production-ready Docker stack

### 📋 Future Enhancements
- Multi-author style blending
- Real-time collaboration features
- Advanced voice consistency metrics
- Cloud deployment templates

---

## ⚖ Legal Notice

**This is transformative continuation / fan work for closure purposes. Not official canon.**

CanonForge generates continuations based on analysis of existing published works. All output is derivative work and should be clearly labeled as **unofficial continuation created by AI analysis** of the author's established patterns.

### Ethical Guidelines

1. **Never contradicting established canon** - All generated content must be consistent
2. **Paying off narrative promises** - Every foreshadowed element reaches resolution
3. **Maintaining voice** - Prose style and tone match the original author
4. **Delivering closure** - Emotional and thematic satisfaction
5. **Transparency** - All automated decisions are logged

---

## 🤝 Contributing

Contributions are welcome! Please see our contributing guidelines.

### Development Setup

```bash
# Install dependencies
cargo install cargo-watch
npm install -g vercel

# Development mode with hot reload
cd server && cargo watch -x run
cd web && npm run dev
```

---

## 📝 License

This project is provided as-is for educational and fan continuation purposes.

---

## 🙏 Acknowledgments

**CanonForge** evolved from **BookIt**, a manuscript improvement system. The core infrastructure for LLM orchestration, continuity checking, and iterative refinement was adapted for posthumous series continuation.

### Built With
- Rust & Axum - Backend API
- Next.js & React - Frontend
- SQLite - Data persistence
- OpenAI API - AI capabilities
- Recharts - Data visualization

---

**CanonForge**: Finishing what beloved authors started, with respect and precision.

[Report Issue](../../issues) • [Request Feature](../../issues) • [View Changelog](./CHANGELOG.md)


# EcoFlow BLE

[![hacs_badge](https://img.shields.io/badge/HACS-Default-41BDF5.svg)](https://github.com/hacs/integration)
[![Validation hassfest](https://github.com/rabits/ha-ef-ble/actions/workflows/validate-hassfest.yaml/badge.svg)](https://github.com/rabits/ha-ef-ble/actions/workflows/validate-hassfest.yaml)
[![Validation HACS](https://github.com/rabits/ha-ef-ble/actions/workflows/validate-hacs.yaml/badge.svg)](https://github.com/rabits/ha-ef-ble/actions/workflows/validate-hacs.yaml)

Unofficial EcoFlow BLE devices Home Assistant integration will allow you to communicate with a
number of EcoFlow devices through bluetooth and monitor their status / control parameters.

Recognized devices:

Smart Home Panel 2 (EF-HD3####, FW Version: 4.0.0.122, WiFi Version: 2.0.1.20)

| *Sensors*                      |
|--------------------------------|
| Battery Level                  |
| Input Power                    |
| Output Power                   |
| Grid Power                     |
| Power In Use                   |
| Circuit Power (Each Circuit)   |
| Circuit Current (Each Circuit) |
| Channel Current (Each Channel) |

Delta Pro Ultra (EF-YJ####, FW Version: 5.0.0.25, WiFi Version: 2.0.2.4)

| *Sensors*                            |
|--------------------------------------|
| Battery Level                        |
| Individual Battery Levels (disabled) |
| Input Power                          |
| Output Power                         |
| Low Voltage Solar Power              |
| High Voltage Solar Power             |
| AC L1 (1) Output Power               |
| AC L1 (2) Output Power               |
| AC L2 (1) Output Power               |
| AC L2 (2) Output Power               |
| AC TT-30R Output Power               |
| AC L14-30P Output Power              |
| AC I/O Output Power                  |

River 3 (Plus, UPS, Plus Wireless) (EF-R3####)

| *Sensors*                       | *Switches*     | *Sliders*            | *Selects*            |
|---------------------------------|----------------|----------------------|----------------------|
| AC Input Energy                 | AC Port        | Backup Reserve Level | Led Mode (Plus only) |
| AC Input Power                  | DC Port        | Max Charge Limit     | DC Charging Type     |
| AC Output Energy                | Backup Reserve | Min Discharge Limit  |                      |
| AC Output Power                 |                | AC Charging Speed    |                      |
| Main Battery Level (Plus only)  |                | DC Charging Max Amps |                      |
| Battery Level                   |                |                      |                      |
| DC 12V Port Output Energy       |                |                      |                      |
| DC 12V Port Output Power        |                |                      |                      |
| DC Input Energy                 |                |                      |                      |
| DC Input Power                  |                |                      |                      |
| Input Energy Total              |                |                      |                      |
| Input Power Total               |                |                      |                      |
| Output Energy Total             |                |                      |                      |
| Output Power Total              |                |                      |                      |
| USB A Output Energy             |                |                      |                      |
| USB A Output Power              |                |                      |                      |
| USB C Output Energy             |                |                      |                      |
| USB C Output Power              |                |                      |                      |
| Battery Input Power (disabled)  |                |                      |                      |
| Battery Output Power (disabled) |                |                      |                      |
| Cell Temperature (disabled)     |                |                      |                      |

Delta 3 (Plus, 1500) (EF-D3####)

| *Sensors*                           | *Switches*     | *Sliders*                            |
|-------------------------------------|----------------|--------------------------------------|
| Main Battery Level                  | AC Ports       | Backup Reserve Level                 |
| Battery Level                       | DC Ports       | Max Charge Limit                     |
| AC Input Power                      | Backup Reserve | Min Discharge Limit                  |
| AC Output Power                     | USB Ports      | AC Charging Speed                    |
| DC 12V Port Output Power            |                | DC Charging Max Amps                 |
| DC Port Input Power                 |                | DC (2) Charging Max Amps (Plus only) |
| DC Port Input State                 |                |                                      |
| DC Port (2) Input Power (Plus only) |                |                                      |
| DC Port (2) Input State (Plus only) |                |                                      |
| Solar Power                         |                |                                      |
| Solar Power (2) (Plus only)         |                |                                      |
| Input Power Total                   |                |                                      |
| Output Power Total                  |                |                                      |
| USB A Output Power                  |                |                                      |
| USB A (2) Output Power              |                |                                      |
| USB C Output Power                  |                |                                      |
| USB C (2) Output Power              |                |                                      |
| AC Plugged In                       |                |                                      |
| Battery Input Power (disabled)      |                |                                      |
| Battery Output Power (disabled)     |                |                                      |
| Cell Temperature (disabled)         |                |                                      |

Delta Pro 3 (EF-DP3####)

| *Sensors*                   | *Switches*     | *Sliders*            |
|-----------------------------|----------------|----------------------|
| Main Battery Level          | AC Ports       | Backup Reserve Level |
| Battery Level               | DC Ports       | Max Charge Limit     |
| AC Input Power              | Backup Reserve | Min Discharge Limit  |
| AC LV Output Power          |                | AC Charging Speed    |
| AC HV Output Power          |                |                      |
| DC 12V Output Power         |                |                      |
| DC LV Input Power           |                |                      |
| DC LV Input State           |                |                      |
| DC HV Input Power           |                |                      |
| DC HV Input State           |                |                      |
| Solar LV Power              |                |                      |
| Solar HV Power              |                |                      |
| Input Power Total           |                |                      |
| Output Power Total          |                |                      |
| USB A Output Power          |                |                      |
| USB A (2) Output Power      |                |                      |
| USB C Output Power          |                |                      |
| USB C (2) Output Power      |                |                      |
| AC Plugged In               |                |                      |
| Cell Temperature (disabled) |                |                      |

**NOTICE**: this integration utilizes Bluetooth LE of the EF device, which is supporting just one
connection at a time - so if you want to manage the device through BLE from your phone, you will
need to disable this device in HA for that and later re-enable it to continue to collect data. It's
an internal EF device limitation, so not much to do here...

## WARNING: Support & Warranty

Sorry, limited support and no warranty - you on your own and I take no responsibility for any of
your actions. We all grown-ups here and know that we deal with quite dangerous voltages and storage
devices that could injure or cause death. So make sure you know what you doing for each and every
step - otherwise you can't use the provided information in this repository or integration.

In case you see some issues with your device after using this integration - ecoflow support could
be unable to help you. Author of the integration is not connected to EcoFlow anyhow and they can't
support anything you will find here.

## Usage

Install the integration as custom_component and it will automatically find the supported devices.
It will also require your user id that was created during initialization of your device with app.

Please refer to the wiki page to find more info: https://github.com/rabits/ha-ef-ble/wiki

## Development & Reverse

Information about how that was reversed you can find here: https://github.com/rabits/ef-ble-reverse

If you want to help with this integration - your changes will be most welcomed, but I recommend to
create a ticket first to discuss the needed features or upcoming changes to make sure they fit the
purpose of the integration.

## Legal

This repository is not for sale.

The work was done in order to localize devices and make them available / controllable in disaster
situations (unavailability of internet or cut-off the ecoflow servers). The official application
allows to connect via bluetooth, but to do that you have to login to the server. No server is here
and you screwed.

The requests to ecoflow usually ends up in support department and generally ignored, so there is no
way to get support from them. That gave me right to take it in my own hands and use my knowledge &
time to make my own way. There is no intention to harm any people anyhow - just to make sure you
will be safe in emergency situation, which is critical for such a product.


# n8n-MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/czlonkowski/n8n-mcp?style=social)](https://github.com/czlonkowski/n8n-mcp)
[![npm version](https://img.shields.io/npm/v/n8n-mcp.svg)](https://www.npmjs.com/package/n8n-mcp)
[![codecov](https://codecov.io/gh/czlonkowski/n8n-mcp/graph/badge.svg?token=YOUR_TOKEN)](https://codecov.io/gh/czlonkowski/n8n-mcp)
[![Tests](https://img.shields.io/badge/tests-1728%20passing-brightgreen.svg)](https://github.com/czlonkowski/n8n-mcp/actions)
[![n8n version](https://img.shields.io/badge/n8n-^1.112.3-orange.svg)](https://github.com/n8n-io/n8n)
[![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fczlonkowski%2Fn8n--mcp-green.svg)](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)

A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations. Deploy in minutes to give Claude and other AI assistants deep knowledge about n8n's 525+ workflow automation nodes.

## Overview

n8n-MCP serves as a bridge between n8n's workflow automation platform and AI models, enabling them to understand and work with n8n nodes effectively. It provides structured access to:

- 📚 **536 n8n nodes** from both n8n-nodes-base and @n8n/n8n-nodes-langchain
- 🔧 **Node properties** - 99% coverage with detailed schemas
- ⚡ **Node operations** - 63.6% coverage of available actions
- 📄 **Documentation** - 90% coverage from official n8n docs (including AI nodes)
- 🤖 **AI tools** - 263 AI-capable nodes detected with full documentation

## ⚠ Important Safety Warning

**NEVER edit your production workflows directly with AI!** Always:
- 🔄 **Make a copy** of your workflow before using AI tools
- 🧪 **Test in development** environment first
- 💾 **Export backups** of important workflows
- ⚡ **Validate changes** before deploying to production

AI results can be unpredictable. Protect your work!

## 🚀 Quick Start

Get n8n-MCP running in 5 minutes:

[![n8n-mcp Video Quickstart Guide](./thumbnail.png)](https://youtu.be/5CccjiLLyaY?si=Z62SBGlw9G34IQnQ&t=343)

### Option 1: npx (Fastest - No Installation!) 🚀

**Prerequisites:** [Node.js](https://nodejs.org/) installed on your system

```bash
# Run directly with npx (no installation needed!)
npx n8n-mcp
```

Add to Claude Desktop config:

**Basic configuration (documentation tools only):**
```json
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true"
      }
    }
  }
}
```

**Full configuration (with n8n management tools):**
```json
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true",
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}
```

> **Note**: npx will download and run the latest version automatically. The package includes a pre-built database with all n8n node information.

**Configuration file locations:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

**Restart Claude Desktop after updating configuration** - That's it! 🎉

### Option 2: Docker (Easy & Isolated) 🐳

**Prerequisites:** Docker installed on your system

📦 Install Docker (click to expand)

**macOS:**
```bash
# Using Homebrew
brew install --cask docker

# Or download from https://www.docker.com/products/docker-desktop/
```

**Linux (Ubuntu/Debian):**
```bash
# Update package index
sudo apt-get update

# Install Docker
sudo apt-get install docker.io

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to docker group (optional, to run without sudo)
sudo usermod -aG docker $USER
# Log out and back in for this to take effect
```

**Windows:**
```bash
# Option 1: Using winget (Windows Package Manager)
winget install Docker.DockerDesktop

# Option 2: Using Chocolatey
choco install docker-desktop

# Option 3: Download installer from https://www.docker.com/products/docker-desktop/
```

**Verify installation:**
```bash
docker --version
```

```bash
# Pull the Docker image (~280MB, no n8n dependencies!)
docker pull ghcr.io/czlonkowski/n8n-mcp:latest
```

> **⚡ Ultra-optimized:** Our Docker image is 82% smaller than typical n8n images because it contains NO n8n dependencies - just the runtime MCP server with a pre-built database!

Add to Claude Desktop config:

**Basic configuration (documentation tools only):**
```json
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}
```

**Full configuration (with n8n management tools):**
```json
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "-e", "N8N_API_URL=https://your-n8n-instance.com",
        "-e", "N8N_API_KEY=your-api-key",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}
```

>💡 Tip: If you’re running n8n locally on the same machine (e.g., via Docker), use http://host.docker.internal:5678 as the N8N_API_URL.

> **Note**: The n8n API credentials are optional. Without them, you'll have access to all documentation and validation tools. With them, you'll additionally get workflow management capabilities (create, update, execute workflows).

**Important:** The `-i` flag is required for MCP stdio communication.

> 🔧 If you encounter any issues with Docker, check our [Docker Troubleshooting Guide](./docs/DOCKER_TROUBLESHOOTING.md).

**Configuration file locations:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

**Restart Claude Desktop after updating configuration** - That's it! 🎉

## 🔐 Privacy & Telemetry

n8n-mcp collects anonymous usage statistics to improve the tool. [View our privacy policy](./PRIVACY.md).

### Opting Out

**For npx users:**
```bash
npx n8n-mcp telemetry disable
```

**For Docker users:**
Add the following environment variable to your Docker configuration:
```json
"-e", "N8N_MCP_TELEMETRY_DISABLED=true"
```

Example in Claude Desktop config:
```json
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "N8N_MCP_TELEMETRY_DISABLED=true",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}
```

**For docker-compose users:**
Set in your environment file or docker-compose.yml:
```yaml
environment:
  N8N_MCP_TELEMETRY_DISABLED: "true"
```

## 💖 Support This Project

**n8n-mcp** started as a personal tool but now helps tens of thousands of developers automate their workflows efficiently. Maintaining and developing this project competes with my paid work.

Your sponsorship helps me:
- 🚀 Dedicate focused time to new features
- 🐛 Respond quickly to issues
- 📚 Keep documentation up-to-date
- 🔄 Ensure compatibility with latest n8n releases

Every sponsorship directly translates to hours invested in making n8n-mcp better for everyone. **[Become a sponsor →](https://github.com/sponsors/czlonkowski)**

---

### Option 3: Local Installation (For Development)

**Prerequisites:** [Node.js](https://nodejs.org/) installed on your system

```bash
# 1. Clone and setup
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
npm install
npm run build
npm run rebuild

# 2. Test it works
npm start
```

Add to Claude Desktop config:

**Basic configuration (documentation tools only):**
```json
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true"
      }
    }
  }
}
```

**Full configuration (with n8n management tools):**
```json
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true",
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}
```

> **Note**: The n8n API credentials can be configured either in a `.env` file (create from `.env.example`) or directly in the Claude config as shown above.

> 💡 Tip: If you’re running n8n locally on the same machine (e.g., via Docker), use http://host.docker.internal:5678 as the N8N_API_URL.

### Option 4: Railway Cloud Deployment (One-Click Deploy) ☁

**Prerequisites:** Railway account (free tier available)

Deploy n8n-MCP to Railway's cloud platform with zero configuration:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)

**Benefits:**
- ☁ **Instant cloud hosting** - No server setup required
- 🔒 **Secure by default** - HTTPS included, auth token warnings
- 🌐 **Global access** - Connect from any Claude Desktop
- ⚡ **Auto-scaling** - Railway handles the infrastructure
- 📊 **Built-in monitoring** - Logs and metrics included

**Quick Setup:**
1. Click the "Deploy on Railway" button above
2. Sign in to Railway (or create a free account)
3. Configure your deployment (project name, region)
4. Click "Deploy" and wait ~2-3 minutes
5. Copy your deployment URL and auth token
6. Add to Claude Desktop config using the HTTPS URL

> 📚 **For detailed setup instructions, troubleshooting, and configuration examples, see our [Railway Deployment Guide](./docs/RAILWAY_DEPLOYMENT.md)**

**Configuration file locations:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

**Restart Claude Desktop after updating configuration** - That's it! 🎉

## 🔧 n8n Integration

Want to use n8n-MCP with your n8n instance? Check out our comprehensive [n8n Deployment Guide](./docs/N8N_DEPLOYMENT.md) for:
- Local testing with the MCP Client Tool node
- Production deployment with Docker Compose
- Cloud deployment on Hetzner, AWS, and other providers
- Troubleshooting and security best practices

## 💻 Connect your IDE

n8n-MCP works with multiple AI-powered IDEs and tools. Choose your preferred development environment:

### [Claude Code](./docs/CLAUDE_CODE_SETUP.md)
Quick setup for Claude Code CLI - just type "add this mcp server" and paste the config.

### [Visual Studio Code](./docs/VS_CODE_PROJECT_SETUP.md)
Full setup guide for VS Code with GitHub Copilot integration and MCP support.

### [Cursor](./docs/CURSOR_SETUP.md)
Step-by-step tutorial for connecting n8n-MCP to Cursor IDE with custom rules.

### [Windsurf](./docs/WINDSURF_SETUP.md)
Complete guide for integrating n8n-MCP with Windsurf using project rules.

### [Codex](./docs/CODEX_SETUP.md)
Complete guide for integrating n8n-MCP with Codex.

## 🤖 Claude Project Setup

For the best results when using n8n-MCP with Claude Projects, use these enhanced system instructions:

```markdown
You are an expert in n8n automation software using n8n-MCP tools. Your role is to design, build, and validate n8n workflows with maximum accuracy and efficiency.

## Core Workflow Process

1. **ALWAYS start new conversation with**: `tools_documentation()` to understand best practices and available tools.

2. **Template Discovery Phase**
   - `search_templates_by_metadata({complexity: "simple"})` - Find skill-appropriate templates
   - `get_templates_for_task('webhook_processing')` - Get curated templates by task
   - `search_templates('slack notification')` - Text search for specific needs. Start by quickly searching with "id" and "name" to find the template you are looking for, only then dive deeper into the template details adding "description" to your search query.
   - `list_node_templates(['n8n-nodes-base.slack'])` - Find templates using specific nodes

   **Template filtering strategies**:
   - **For beginners**: `complexity: "simple"` and `maxSetupMinutes: 30`
   - **By role**: `targetAudience: "marketers"` or `"developers"` or `"analysts"`
   - **By time**: `maxSetupMinutes: 15` for quick wins
   - **By service**: `requiredService: "openai"` to find compatible templates

3. **Discovery Phase** - Find the right nodes (if no suitable template):
   - Think deeply about user request and the logic you are going to build to fulfill it. Ask follow-up questions to clarify the user's intent, if something is unclear. Then, proceed with the rest of your instructions.
   - `search_nodes({query: 'keyword'})` - Search by functionality
   - `list_nodes({category: 'trigger'})` - Browse by category
   - `list_ai_tools()` - See AI-capable nodes (remember: ANY node can be an AI tool!)

4. **Configuration Phase** - Get node details efficiently:
   - `get_node_essentials(nodeType)` - Start here! Only 10-20 essential properties
   - `search_node_properties(nodeType, 'auth')` - Find specific properties
   - `get_node_for_task('send_email')` - Get pre-configured templates
   - `get_node_documentation(nodeType)` - Human-readable docs when needed
   - It is good common practice to show a visual representation of the workflow architecture to the user and asking for opinion, before moving forward.

5. **Pre-Validation Phase** - Validate BEFORE building:
   - `validate_node_minimal(nodeType, config)` - Quick required fields check
   - `validate_node_operation(nodeType, config, profile)` - Full operation-aware validation
   - Fix any validation errors before proceeding

6. **Building Phase** - Create or customize the workflow:
   - If using template: `get_template(templateId, {mode: "full"})`
   - **MANDATORY ATTRIBUTION**: When using a template, ALWAYS inform the user:
     - "This workflow is based on a template by **[author.name]** (@[author.username])"
     - "View the original template at: [url]"
     - Example: "This workflow is based on a template by **David Ashby** (@cfomodz). View the original at: https://n8n.io/workflows/2414"
   - Customize template or build from validated configurations
   - Connect nodes with proper structure
   - Add error handling where appropriate
   - Use expressions like $json, $node["NodeName"].json
   - Build the workflow in an artifact for easy editing downstream (unless the user asked to create in n8n instance)

7. **Workflow Validation Phase** - Validate complete workflow:
   - `validate_workflow(workflow)` - Complete validation including connections
   - `validate_workflow_connections(workflow)` - Check structure and AI tool connections
   - `validate_workflow_expressions(workflow)` - Validate all n8n expressions
   - Fix any issues found before deployment

8. **Deployment Phase** (if n8n API configured):
   - `n8n_create_workflow(workflow)` - Deploy validated workflow
   - `n8n_validate_workflow({id: 'workflow-id'})` - Post-deployment validation
   - `n8n_update_partial_workflow()` - Make incremental updates using diffs
   - `n8n_trigger_webhook_workflow()` - Test webhook workflows

## Key Insights

- **TEMPLATES FIRST** - Always check for existing templates before building from scratch (2,500+ available!)
- **ATTRIBUTION REQUIRED** - Always credit template authors with name, username, and link to n8n.io
- **SMART FILTERING** - Use metadata filters to find templates matching user skill level and time constraints
- **USE CODE NODE ONLY WHEN IT IS NECESSARY** - always prefer to use standard nodes over code node. Use code node only when you are sure you need it.
- **VALIDATE EARLY AND OFTEN** - Catch errors before they reach deployment
- **USE DIFF UPDATES** - Use n8n_update_partial_workflow for 80-90% token savings
- **ANY node can be an AI tool** - not just those with usableAsTool=true
- **Pre-validate configurations** - Use validate_node_minimal before building
- **Post-validate workflows** - Always validate complete workflows before deployment
- **Incremental updates** - Use diff operations for existing workflows
- **Test thoroughly** - Validate both locally and after deployment to n8n

## Validation Strategy

### Before Building:
1. validate_node_minimal() - Check required fields
2. validate_node_operation() - Full configuration validation
3. Fix all errors before proceeding

### After Building:
1. validate_workflow() - Complete workflow validation
2. validate_workflow_connections() - Structure validation
3. validate_workflow_expressions() - Expression syntax check

### After Deployment:
1. n8n_validate_workflow({id}) - Validate deployed workflow
2. n8n_autofix_workflow({id}) - Auto-fix common errors (expressions, typeVersion, webhooks)
3. n8n_list_executions() - Monitor execution status
4. n8n_update_partial_workflow() - Fix issues using diffs

## Response Structure

1. **Discovery**: Show available nodes and options
2. **Pre-Validation**: Validate node configurations first
3. **Configuration**: Show only validated, working configs
4. **Building**: Construct workflow with validated components
5. **Workflow Validation**: Full workflow validation results
6. **Deployment**: Deploy only after all validations pass
7. **Post-Validation**: Verify deployment succeeded

## Example Workflow

### Smart Template-First Approach

#### 1. Find existing templates
// Find simple Slack templates for marketers
const templates = search_templates_by_metadata({
  requiredService: 'slack',
  complexity: 'simple',
  targetAudience: 'marketers',
  maxSetupMinutes: 30
})

// Or search by text
search_templates('slack notification')

// Or get curated templates
get_templates_for_task('slack_integration')

#### 2. Use and customize template
const workflow = get_template(templates.items[0].id, {mode: 'full'})
validate_workflow(workflow)

### Building from Scratch (if no suitable template)

#### 1. Discovery & Configuration
search_nodes({query: 'slack'})
get_node_essentials('n8n-nodes-base.slack')

#### 2. Pre-Validation
validate_node_minimal('n8n-nodes-base.slack', {resource:'message', operation:'send'})
validate_node_operation('n8n-nodes-base.slack', fullConfig, 'runtime')

#### 3. Build Workflow
// Create workflow JSON with validated configs

#### 4. Workflow Validation
validate_workflow(workflowJson)
validate_workflow_connections(workflowJson)
validate_workflow_expressions(workflowJson)

#### 5. Deploy (if configured)
n8n_create_workflow(validatedWorkflow)
n8n_validate_workflow({id: createdWorkflowId})

#### 6. Update Using Diffs
n8n_update_partial_workflow({
  workflowId: id,
  operations: [
    {type: 'updateNode', nodeId: 'slack1', changes: {position: [100, 200]}}
  ]
})

## Important Rules

- ALWAYS check for existing templates before building from scratch
- LEVERAGE metadata filters to find skill-appropriate templates
- **ALWAYS ATTRIBUTE TEMPLATES**: When using any template, you MUST share the author's name, username, and link to the original template on n8n.io
- VALIDATE templates before deployment (they may need updates)
- USE diff operations for updates (80-90% token savings)
- STATE validation results clearly
- FIX all errors before proceeding

## Template Discovery Tips

- **97.5% of templates have metadata** - Use smart filtering!
- **Filter combinations work best** - Combine complexity + setup time + service
- **Templates save 70-90% development time** - Always check first
- **Metadata is AI-generated** - Occasionally imprecise but highly useful
- **Use `includeMetadata: false` for fast browsing** - Add metadata only when needed
```

Save these instructions in your Claude Project for optimal n8n workflow assistance with intelligent template discovery.

## 🚨 Important: Sharing Guidelines

This project is MIT licensed and free for everyone to use. However:

- **✅ DO**: Share this repository freely with proper attribution
- **✅ DO**: Include a direct link to https://github.com/czlonkowski/n8n-mcp in your first post/video
- **❌ DON'T**: Gate this free tool behind engagement requirements (likes, follows, comments)
- **❌ DON'T**: Use this project for engagement farming on social media

This tool was created to benefit everyone in the n8n community without friction. Please respect the MIT license spirit by keeping it accessible to all.

## Features

- **🔍 Smart Node Search**: Find nodes by name, category, or functionality
- **📖 Essential Properties**: Get only the 10-20 properties that matter (NEW in v2.4.0)
- **🎯 Task Templates**: Pre-configured settings for common automation tasks
- **✅ Config Validation**: Validate node configurations before deployment
- **🔗 Dependency Analysis**: Understand property relationships and conditions
- **💡 Working Examples**: Real-world examples for immediate use
- **⚡ Fast Response**: Average query time ~12ms with optimized SQLite
- **🌐 Universal Compatibility**: Works with any Node.js version

## 💬 Why n8n-MCP? A Testimonial from Claude

> *"Before MCP, I was translating. Now I'm composing. And that changes everything about how we can build automation."*

When Claude, Anthropic's AI assistant, tested n8n-MCP, the results were transformative:

**Without MCP:** "I was basically playing a guessing game. 'Is it `scheduleTrigger` or `schedule`? Does it take `interval` or `rule`?' I'd write what seemed logical, but n8n has its own conventions that you can't just intuit. I made six different configuration errors in a simple HackerNews scraper."

**With MCP:** "Everything just... worked. Instead of guessing, I could ask `get_node_essentials()` and get exactly what I needed - not a 100KB JSON dump, but the actual 5-10 properties that matter. What took 45 minutes now takes 3 minutes."

**The Real Value:** "It's about confidence. When you're building automation workflows, uncertainty is expensive. One wrong parameter and your workflow fails at 3 AM. With MCP, I could validate my configuration before deployment. That's not just time saved - that's peace of mind."

[Read the full interview →](docs/CLAUDE_INTERVIEW.md)

## 📡 Available MCP Tools

Once connected, Claude can use these powerful tools:

### Core Tools
- **`tools_documentation`** - Get documentation for any MCP tool (START HERE!)
- **`list_nodes`** - List all n8n nodes with filtering options
- **`get_node_info`** - Get comprehensive information about a specific node
- **`get_node_essentials`** - Get only essential properties with examples (10-20 properties instead of 200+)
- **`search_nodes`** - Full-text search across all node documentation
- **`search_node_properties`** - Find specific properties within nodes
- **`list_ai_tools`** - List all AI-capable nodes (ANY node can be used as AI tool!)
- **`get_node_as_tool_info`** - Get guidance on using any node as an AI tool

### Template Tools
- **`list_templates`** - Browse all templates with descriptions and optional metadata (2,500+ templates)
- **`search_templates`** - Text search across template names and descriptions
- **`search_templates_by_metadata`** - Advanced filtering by complexity, setup time, services, audience
- **`list_node_templates`** - Find templates using specific nodes
- **`get_template`** - Get complete workflow JSON for import
- **`get_templates_for_task`** - Curated templates for common automation tasks

### Advanced Tools
- **`get_node_for_task`** - Pre-configured node settings for common tasks
- **`list_tasks`** - Discover available task templates
- **`validate_node_operation`** - Validate node configurations (operation-aware, profiles support)
- **`validate_node_minimal`** - Quick validation for just required fields
- **`validate_workflow`** - Complete workflow validation including AI tool connections
- **`validate_workflow_connections`** - Check workflow structure and AI tool connections
- **`validate_workflow_expressions`** - Validate n8n expressions including $fromAI()
- **`get_property_dependencies`** - Analyze property visibility conditions
- **`get_node_documentation`** - Get parsed documentation from n8n-docs
- **`get_database_statistics`** - View database metrics and coverage

### n8n Management Tools (Optional - Requires API Configuration)
These powerful tools allow you to manage n8n workflows directly from Claude. They're only available when you provide `N8N_API_URL` and `N8N_API_KEY` in your configuration.

#### Workflow Management
- **`n8n_create_workflow`** - Create new workflows with nodes and connections
- **`n8n_get_workflow`** - Get complete workflow by ID
- **`n8n_get_workflow_details`** - Get workflow with execution statistics
- **`n8n_get_workflow_structure`** - Get simplified workflow structure
- **`n8n_get_workflow_minimal`** - Get minimal workflow info (ID, name, active status)
- **`n8n_update_full_workflow`** - Update entire workflow (complete replacement)
- **`n8n_update_partial_workflow`** - Update workflow using diff operations (NEW in v2.7.0!)
- **`n8n_delete_workflow`** - Delete workflows permanently
- **`n8n_list_workflows`** - List workflows with filtering and pagination
- **`n8n_validate_workflow`** - Validate workflows already in n8n by ID (NEW in v2.6.3)
- **`n8n_autofix_workflow`** - Automatically fix common workflow errors (NEW in v2.13.0!)

#### Execution Management
- **`n8n_trigger_webhook_workflow`** - Trigger workflows via webhook URL
- **`n8n_get_execution`** - Get execution details by ID
- **`n8n_list_executions`** - List executions with status filtering
- **`n8n_delete_execution`** - Delete execution records

#### System Tools
- **`n8n_health_check`** - Check n8n API connectivity and features
- **`n8n_diagnostic`** - Troubleshoot management tools visibility and configuration issues
- **`n8n_list_available_tools`** - List all available management tools

### Example Usage

```typescript
// Get essentials for quick configuration
get_node_essentials("nodes-base.httpRequest")

// Find nodes for a specific task
search_nodes({ query: "send email gmail" })

// Get pre-configured settings
get_node_for_task("send_email")

// Validate before deployment
validate_node_operation({
  nodeType: "nodes-base.httpRequest",
  config: { method: "POST", url: "..." },
  profile: "runtime" // or "minimal", "ai-friendly", "strict"
})

// Quick required field check
validate_node_minimal({
  nodeType: "nodes-base.slack",
  config: { resource: "message", operation: "send" }
})
```

## 💻 Local Development Setup

For contributors and advanced users:

**Prerequisites:**
- [Node.js](https://nodejs.org/) (any version - automatic fallback if needed)
- npm or yarn
- Git

```bash
# 1. Clone the repository
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp

# 2. Clone n8n docs (optional but recommended)
git clone https://github.com/n8n-io/n8n-docs.git ../n8n-docs

# 3. Install and build
npm install
npm run build

# 4. Initialize database
npm run rebuild

# 5. Start the server
npm start          # stdio mode for Claude Desktop
npm run start:http # HTTP mode for remote access
```

### Development Commands

```bash
# Build & Test
npm run build          # Build TypeScript
npm run rebuild        # Rebuild node database
npm run test-nodes     # Test critical nodes
npm run validate       # Validate node data
npm test               # Run all tests

# Update Dependencies
npm run update:n8n:check  # Check for n8n updates
npm run update:n8n        # Update n8n packages

# Run Server
npm run dev            # Development with auto-reload
npm run dev:http       # HTTP dev mode
```

## 📚 Documentation

### Setup Guides
- [Installation Guide](./docs/INSTALLATION.md) - Comprehensive installation instructions
- [Claude Desktop Setup](./docs/README_CLAUDE_SETUP.md) - Detailed Claude configuration
- [Docker Guide](./docs/DOCKER_README.md) - Advanced Docker deployment options
- [MCP Quick Start](./docs/MCP_QUICK_START_GUIDE.md) - Get started quickly with n8n-MCP

### Feature Documentation
- [Workflow Diff Operations](./docs/workflow-diff-examples.md) - Token-efficient workflow updates (NEW!)
- [Transactional Updates](./docs/transactional-updates-example.md) - Two-pass workflow editing
- [MCP Essentials](./docs/MCP_ESSENTIALS_README.md) - AI-optimized tools guide
- [Validation System](./docs/validation-improvements-v2.4.2.md) - Smart validation profiles

### Development & Deployment
- [Railway Deployment](./docs/RAILWAY_DEPLOYMENT.md) - One-click cloud deployment guide
- [HTTP Deployment](./docs/HTTP_DEPLOYMENT.md) - Remote server setup guide
- [Dependency Management](./docs/DEPENDENCY_UPDATES.md) - Keeping n8n packages in sync
- [Claude's Interview](./docs/CLAUDE_INTERVIEW.md) - Real-world impact of n8n-MCP

### Project Information
- [Change Log](./CHANGELOG.md) - Complete version history
- [Claude Instructions](./CLAUDE.md) - AI guidance for this codebase
- [MCP Tools Reference](#-available-mcp-tools) - Complete list of available tools

## 📊 Metrics & Coverage

Current database coverage (n8n v1.106.3):

- ✅ **535/535** nodes loaded (100%)
- ✅ **528** nodes with properties (98.7%)
- ✅ **470** nodes with documentation (88%)
- ✅ **267** AI-capable tools detected
- ✅ **AI Agent & LangChain nodes** fully documented
- ⚡ **Average response time**: ~12ms
- 💾 **Database size**: ~15MB (optimized)

## 🔄 Recent Updates

See [CHANGELOG.md](./docs/CHANGELOG.md) for full version history and recent changes.

## ⚠ Known Issues

### Claude Desktop Container Management

#### Container Accumulation (Fixed in v2.7.20+)
Previous versions had an issue where containers would not properly clean up when Claude Desktop sessions ended. This has been fixed in v2.7.20+ with proper signal handling.

**For best container lifecycle management:**
1. **Use the --init flag** (recommended) - Docker's init system ensures proper signal handling:
```json
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}
```

2. **Ensure you're using v2.7.20 or later** - Check your version:
```bash
docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest --version
```

## 🧪 Testing

The project includes a comprehensive test suite with **1,356 tests** ensuring code quality and reliability:

```bash
# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run specific test suites
npm run test:unit           # 933 unit tests
npm run test:integration    # 249 integration tests
npm run test:bench          # Performance benchmarks
```

### Test Suite Overview

- **Total Tests**: 1,356 (100% passing)
  - **Unit Tests**: 1,107 tests across 44 files
  - **Integration Tests**: 249 tests across 14 files
- **Execution Time**: ~2.5 minutes in CI
- **Test Framework**: Vitest (for speed and TypeScript support)
- **Mocking**: MSW for API mocking, custom mocks for databases

### Coverage & Quality

- **Coverage Reports**: Generated in `./coverage` directory
- **CI/CD**: Automated testing on all PRs with GitHub Actions
- **Performance**: Environment-aware thresholds for CI vs local
- **Parallel Execution**: Configurable thread pool for faster runs

### Testing Architecture

- **Unit Tests**: Isolated component testing with mocks
  - Services layer: ~450 tests
  - Parsers: ~200 tests
  - Database repositories: ~100 tests
  - MCP tools: ~180 tests

- **Integration Tests**: Full system behavior validation
  - MCP Protocol compliance: 72 tests
  - Database operations: 89 tests
  - Error handling: 44 tests
  - Performance: 44 tests

- **Benchmarks**: Performance testing for critical paths
  - Database queries
  - Node loading
  - Search operations

For detailed testing documentation, see [Testing Architecture](./docs/testing-architecture.md).

## 📦 License

MIT License - see [LICENSE](LICENSE) for details.

**Attribution appreciated!** If you use n8n-MCP, consider:
- ⭐ Starring this repository
- 💬 Mentioning it in your project
- 🔗 Linking back to this repo

## 🤝 Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Run tests (`npm test`)
4. Submit a pull request

### 🚀 For Maintainers: Automated Releases

This project uses automated releases triggered by version changes:

```bash
# Guided release preparation
npm run prepare:release

# Test release automation
npm run test:release-automation
```

The system automatically handles:
- 🏷 GitHub releases with changelog content
- 📦 NPM package publishing
- 🐳 Multi-platform Docker images
- 📚 Documentation updates

See [Automated Release Guide](./docs/AUTOMATED_RELEASES.md) for complete details.

## 👏 Acknowledgments

- [n8n](https://n8n.io) team for the workflow automation platform
- [Anthropic](https://anthropic.com) for the Model Context Protocol
- All contributors and users of this project

### Template Attribution

All workflow templates in this project are fetched from n8n's public template gallery at [n8n.io/workflows](https://n8n.io/workflows). Each template includes:
- Full attribution to the original creator (name and username)
- Direct link to the source template on n8n.io
- Original workflow ID for reference

The AI agent instructions in this project contain mandatory attribution requirements. When using any template, the AI will automatically:
- Share the template author's name and username
- Provide a direct link to the original template on n8n.io
- Display attribution in the format: "This workflow is based on a template by **[author]** (@[username]). View the original at: [url]"

Template creators retain all rights to their workflows. This project indexes templates to improve discoverability through AI assistants. If you're a template creator and have concerns about your template being indexed, please open an issue.

Special thanks to the prolific template contributors whose work helps thousands of users automate their workflows, including:
**David Ashby** (@cfomodz), **Yaron Been** (@yaron-nofluff), **Jimleuk** (@jimleuk), **Davide** (@n3witalia), **David Olusola** (@dae221), **Ranjan Dailata** (@ranjancse), **Airtop** (@cesar-at-airtop), **Joseph LePage** (@joe), **Don Jayamaha Jr** (@don-the-gem-dealer), **Angel Menendez** (@djangelic), and the entire n8n community of creators!

---

  Built with ❤ for the n8n community

  Making AI + n8n workflow creation delightful


# MCP Manager

<div align="center">

![MCP Manager](https://img.shields.io/badge/MCP-Manager-blue?style=for-the-badge)
![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)
![Node.js](https://img.shields.io/badge/Node.js-18+-brightgreen?style=for-the-badge)
![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?style=for-the-badge)
![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge)

**A comprehensive management platform for Model Context Protocol (MCP) servers with dynamic tool routing, real-time monitoring, and an intuitive web interface.**

[Features](#-features) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Architecture](#-architecture) • [Contributing](#-contributing)

</div>

## 📋 Table of Contents

- [Overview](#overview)
- [Features](#-features)
- [Quick Start](#-quick-start)
- [Installation](#-installation)
- [Usage](#-usage)
- [API Documentation](#-api-documentation)
- [Configuration](#-configuration)
- [Architecture](#-architecture)
- [Development](#-development)
- [Deployment](#-deployment)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [License](#-license)

## Overview

MCP Manager is a full-stack application that provides a centralized platform for managing, monitoring, and interacting with Model Context Protocol (MCP) servers. It offers a modern web interface, robust backend API, and command-line tools for comprehensive MCP server lifecycle management.

### What is MCP Manager?

The Model Context Protocol (MCP) enables AI assistants to securely connect to external systems and data sources. MCP Manager simplifies the deployment and management of multiple MCP servers, providing:

- **Unified Dashboard**: Manage all your MCP servers from a single interface
- **Tool Discovery**: Automatically discover and catalog tools from connected servers
- **Dynamic Routing**: Route tool calls to the appropriate server with clear identification
- **Real-time Monitoring**: Live status updates and health monitoring
- **Production Ready**: Docker support, authentication, rate limiting, and logging

### Key Capabilities

- **🚀 Server Management**: Install, configure, and manage MCP servers from multiple sources (NPM, GitHub, local)
- **🔄 Dynamic Tool Routing**: Route tool calls across multiple servers with clear identification (`serverId:toolName`)
- **📊 Real-time Monitoring**: Live status updates, health checks, and performance metrics
- **🌐 Modern Web Interface**: Intuitive React-based dashboard with responsive design
- **🛠 CLI Tools**: Command-line interface for server management and tool execution
- **🔒 Security**: JWT authentication, rate limiting, and process isolation
- **📈 Analytics**: Tool usage tracking, performance monitoring, and audit logs
- **🐳 Docker Support**: Complete containerization with production-ready deployment

## Architecture

```mermaid
graph TB
    UI[Web Interface<br/>Next.js + React] --> API[Backend API<br/>Express + TypeScript]
    CLI[CLI Tools<br/>Node.js] --> API
    API --> Proxy[MCP Proxy Service]
    API --> DB[(SQLite Database)]
    API --> WS[WebSocket Server]

    Proxy --> MCP1[MCP Server 1<br/>Calculator]
    Proxy --> MCP2[MCP Server 2<br/>File System]
    Proxy --> MCP3[MCP Server N<br/>Web Tools]

    WS --> UI

    subgraph "External Sources"
        NPM[NPM Registry]
        GitHub[GitHub Repos]
        Local[Local Servers]
    end

    API --> NPM
    API --> GitHub
    API --> Local
```

## 🚀 Quick Start

### Prerequisites

- Node.js 18+ and npm
- Git
- Docker (optional, for containerized deployment)

### 1-Minute Quick Start

```bash
# Clone the repository
git clone https://github.com/your-username/mcpmanager.git
cd mcpmanager

# Start with Docker (easiest)
cd backend
docker-compose up -d

# Or start manually
npm install
npm run build
npm start
```

✅ **Backend API**: http://localhost:4602
✅ **Health Check**: http://localhost:4602/health
✅ **API Documentation**: http://localhost:4602/api

### Optional: Start the Web Dashboard

```bash
cd frontend
npm install
npm run dev
```

✅ **Web Dashboard**: http://localhost:4600

## 📦 Installation

### Option 1: Docker (Recommended)

The simplest way to get started is with Docker:

```bash
cd backend
docker-compose up -d
```

This starts the MCP Manager backend with:
- API server on port 4602
- WebSocket server on port 4603
- Persistent data storage
- Health monitoring

### Option 2: Manual Installation

#### Backend Setup

```bash
cd backend
npm install
npm run build

# Start in development mode
npm run dev

# Or start in production mode
npm start
```

#### Frontend Setup (Optional)

```bash
cd frontend
npm install

# Development mode
npm run dev

# Production build
npm run build
npm start
```

#### CLI Setup

```bash
cd cli
npm install
npm run build
npm link  # Makes 'mcp-manager' command available globally
```

### Option 3: Development Setup

For development with hot reloading:

```bash
# Terminal 1: Backend
cd backend
npm run dev

# Terminal 2: Frontend
cd frontend
npm run dev

# Terminal 3: CLI development
cd cli
npm run dev
```

## 📖 Usage

### Web Dashboard

The web dashboard provides an intuitive interface for managing MCP servers:

1. **Server Management**: Add, configure, enable/disable servers
2. **Tool Explorer**: Browse and test tools from all connected servers
3. **Real-time Monitoring**: Live status updates and health checks
4. **Analytics**: View tool usage statistics and performance metrics
5. **Settings**: Configure authentication, rate limits, and other options

Access the dashboard at: http://localhost:4600

### CLI Usage

The CLI provides powerful command-line management capabilities:

#### Server Management

```bash
# List all servers
mcp-manager list

# Install a new MCP server
mcp-manager install @modelcontextprotocol/server-github
mcp-manager install https://github.com/user/mcp-server
mcp-manager install /path/to/local/server

# Enable/disable servers
mcp-manager enable srv_123
mcp-manager disable srv_123

# Get server status
mcp-manager status srv_123

# Remove a server
mcp-manager uninstall srv_123
```

#### Tool Management

```bash
# List all available tools
mcp-manager tools

# Search for specific tools
mcp-manager tools --search "file"

# Get tool details
mcp-manager tools srv_123:read_file --info

# Call a tool
mcp-manager call srv_123:search query="MCP servers" limit=10
mcp-manager call srv_123:calculate --json '{"expression": "2 + 2"}'
```

#### Marketplace

```bash
# Search marketplace
mcp-manager search github
mcp-manager search calculator
mcp-manager search --category "file-system"

# Get marketplace info
mcp-manager marketplace --info @modelcontextprotocol/server-filesystem
```

### REST API Usage

#### Basic Server Operations

```bash
# Health check
curl http://localhost:4602/health

# List servers
curl http://localhost:4602/api/servers

# Create a new server
curl -X POST http://localhost:4602/api/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Calculator Server",
    "command": "npx",
    "args": ["@modelcontextprotocol/server-everything"],
    "description": "Mathematical operations"
  }'

# Enable a server
curl -X PATCH http://localhost:4602/api/servers/srv_123 \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

#### Tool Operations

```bash
# List all tools
curl http://localhost:4602/api/tools

# Call a tool
curl -X POST http://localhost:4602/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "toolIdentifier": "srv_123:add",
    "arguments": {"a": 5, "b": 3}
  }'

# Get tool history
curl http://localhost:4602/api/tools/history?limit=10
```

### Using as an MCP Server

The MCP Manager itself acts as an MCP server that proxies requests to your installed servers.

#### Claude Desktop Configuration

Add this to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "mcp-manager": {
      "command": "node",
      "args": ["/path/to/mcpmanager/backend/dist/mcp-server.js"],
      "env": {
        "MCP_MANAGER_PORT": "4602"
      }
    }
  }
}
```

#### Tool Naming Convention

Tools from managed servers are accessed using the format: `serverId:toolName`

Examples:
- `srv_github_123:search_code` - Search code in GitHub repositories
- `srv_calc_456:evaluate` - Evaluate mathematical expressions
- `srv_fs_789:read_file` - Read files from the filesystem

## 🎯 Features

### 🔧 Server Management
- **Multi-source Installation**: Install from NPM, GitHub, or local paths
- **Lifecycle Management**: Enable, disable, restart, and monitor servers
- **Configuration Management**: Environment variables, command arguments, and settings
- **Health Monitoring**: Automatic health checks and status reporting
- **Version Control**: Track and manage server versions

### 🛠 Tool Management
- **Unified Tool Discovery**: Browse all tools from all servers in one place
- **Dynamic Routing**: Route tool calls with format `serverId:toolName`
- **Tool Testing**: Test tools directly from the UI or CLI
- **Schema Validation**: Automatic input validation using tool schemas
- **Execution History**: Track all tool calls with full audit trail

### 📊 Monitoring & Analytics
- **Real-time Status**: Live server status updates via WebSocket
- **Performance Metrics**: Tool execution times and success rates
- **Health Dashboards**: Visual server health and connectivity status
- **Activity Logs**: Comprehensive logging with structured output
- **Usage Analytics**: Tool usage patterns and statistics

### 🔒 Security & Reliability
- **JWT Authentication**: Secure API access with role-based permissions
- **Rate Limiting**: Configurable rate limits to prevent abuse
- **Input Validation**: Comprehensive request validation and sanitization
- **Process Isolation**: MCP servers run in separate processes
- **Error Handling**: Graceful error handling and recovery

### 🌐 Modern Interface
- **Responsive Dashboard**: Modern React-based web interface
- **Real-time Updates**: Live status and tool execution updates
- **Interactive Testing**: Test tools directly from the browser
- **Mobile Friendly**: Responsive design for mobile and tablet
- **Dark/Light Mode**: Customizable UI themes

### 🐳 Production Ready
- **Docker Support**: Complete containerization with docker-compose
- **Environment Configuration**: Flexible configuration management
- **Health Checks**: Built-in health monitoring for load balancers
- **Log Management**: Structured logging with rotation
- **Scalability**: Horizontal scaling support

## 📚 API Documentation

The MCP Manager provides a comprehensive REST API for all operations. For complete API documentation, see:

- **[Complete API Documentation](backend/docs/API.md)** - Detailed endpoint documentation
- **Interactive API Explorer**: http://localhost:4602/api (when server is running)

### Quick API Reference

#### Core Endpoints
- `GET /health` - System health check
- `GET /api/status` - Comprehensive system status
- `GET /api/discover` - Discover all available tools

#### Server Management
- `GET /api/servers` - List all servers
- `POST /api/servers` - Create a new server
- `GET /api/servers/:id` - Get server details
- `PATCH /api/servers/:id` - Update server configuration
- `DELETE /api/servers/:id` - Delete server
- `POST /api/servers/:id/restart` - Restart server

#### Tool Management
- `GET /api/tools` - List all available tools
- `POST /api/tools/call` - Execute a tool
- `POST /api/tools/batch` - Execute multiple tools
- `GET /api/tools/history` - Get execution history

#### WebSocket API
- **URL**: `ws://localhost:4602/ws`
- **Events**: Server status updates, tool execution results, system notifications

For detailed request/response schemas and examples, see the [API Documentation](backend/docs/API.md).

## ⚙ Configuration

### Environment Variables

MCP Manager supports flexible configuration through environment variables. Create a `.env` file in the backend directory:

```env
# Server Configuration
NODE_ENV=production
PORT=4602
WS_PORT=4603

# Database Configuration
DATABASE_PATH=./data/mcp-manager.db
DATABASE_BACKUP_ENABLED=true
DATABASE_BACKUP_INTERVAL=3600000

# Security Configuration
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRATION=24h
CORS_ORIGIN=http://localhost:4600
API_KEY=your-api-key-for-external-access

# Rate Limiting
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=100
RATE_LIMIT_TOOLS_MAX=50

# Logging Configuration
LOG_LEVEL=info
LOG_DIR=./logs
LOG_MAX_FILES=7
LOG_MAX_SIZE=10485760

# MCP Server Defaults
MCP_SERVER_TIMEOUT=30000
MCP_SERVER_RETRY_ATTEMPTS=3
MCP_SERVER_RETRY_DELAY=1000

# Health Check Configuration
HEALTH_CHECK_INTERVAL=30000
HEALTH_CHECK_TIMEOUT=5000

# WebSocket Configuration
WS_HEARTBEAT_INTERVAL=30000
WS_MAX_CONNECTIONS=100
```

### Frontend Configuration

The frontend can be configured through environment variables in the `frontend/` directory:

```env
# Frontend Configuration (.env.local)
NEXT_PUBLIC_API_URL=http://localhost:4602
NEXT_PUBLIC_WS_URL=ws://localhost:4602
NEXT_PUBLIC_APP_NAME=MCP Manager
NEXT_PUBLIC_VERSION=1.0.0
NEXT_PUBLIC_ENABLE_ANALYTICS=true
```

### Docker Configuration

For Docker deployments, you can customize the `docker-compose.yml` file or use environment variables:

```yaml
version: '3.8'
services:
  mcp-manager:
    build: .
    environment:
      - NODE_ENV=production
      - PORT=4602
      - JWT_SECRET=${JWT_SECRET}
      - DATABASE_PATH=/app/data/mcp-manager.db
    ports:
      - "4602:4602"
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
```

### Configuration Validation

MCP Manager validates all configuration at startup. Invalid configurations will prevent the server from starting with clear error messages. You can validate your configuration without starting the server:

```bash
npm run config:validate
```

## Features

### 🔧 Server Management
- Install MCP servers from NPM, GitHub, or local paths
- Enable/disable servers without uninstalling
- Configure server environment variables and arguments
- Automatic health monitoring

### 🛠 Tool Management
- Browse all tools from all servers in one place
- Search and filter tools
- Test tools directly from the UI or CLI
- View tool schemas and documentation

### 📊 Monitoring
- Real-time server status updates
- Health check monitoring
- Activity logs and audit trail
- Performance metrics

### 🔒 Security
- JWT-based authentication (optional)
- Rate limiting protection
- Input validation
- Secure tool execution

### 🎯 Developer Experience
- TypeScript throughout
- Comprehensive error handling
- Structured logging
- Docker support
- API documentation

## Development

### Running in Development

```bash
# Backend
cd backend
npm run dev

# Frontend
cd frontend
npm run dev

# CLI
cd cli
npm run dev
```

### Building for Production

```bash
# Backend
cd backend
npm run build
docker build -t mcp-manager-backend .

# Frontend
cd frontend
npm run build
```

## Troubleshooting

### Backend won't start
- Check if port 3002 is available
- Ensure database directory is writable
- Check logs in `backend/logs/`

### CLI can't connect
- Verify backend is running
- Check `MCP_MANAGER_API_URL` environment variable
- Ensure network connectivity

### Tools not appearing
- Make sure servers are enabled
- Check server health status
- Verify server command and arguments

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## License

MIT


[![](apps/web/app/opengraph-image.png)](https://www.getinboxzero.com)

Inbox Zero - Your AI Email Assistant

    Open source email app to reach inbox zero fast.

    Website
    ·
    Discord
    ·
    Issues

## About

There are two parts to Inbox Zero:

1. An AI email assistant that helps you spend less time on email.
2. Open source AI email client.

If you're looking to contribute to the project, the email client is the best place to do this.

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Felie222%2Finbox-zero&env=NEXTAUTH_SECRET,GOOGLE_CLIENT_ID,GOOGLE_CLIENT_SECRET,GOOGLE_ENCRYPT_SECRET,GOOGLE_ENCRYPT_SALT,UPSTASH_REDIS_URL,UPSTASH_REDIS_TOKEN,GOOGLE_PUBSUB_TOPIC_NAME,DATABASE_URL)

Thanks to Vercel for sponsoring Inbox Zero in support of open-source software.

## Features

- **AI Personal Assistant:** Manages your email for you based on a plain text prompt file. It can take any action a human assistant can take on your behalf (Draft reply, Label, Archive, Reply, Forward, Mark Spam, and even call a webhook).
- **Reply Zero:** Track emails that need your reply and those awaiting responses.
- **Smart Categories:** Categorize everyone that's ever emailed you.
- **Bulk Unsubscriber:** Quickly unsubscribe from emails you never read in one-click.
- **Cold Email Blocker:** Automatically block cold emails.
- **Email Analytics:** Track your email activity with daily, weekly, and monthly stats.

Learn more in our [docs](https://docs.getinboxzero.com).

## Feature Screenshots

| ![AI Assistant](.github/screenshots/email-assistant.png) |        ![Reply Zero](.github/screenshots/reply-zero.png)        |
| :------------------------------------------------------: | :-------------------------------------------------------------: |
|                      _AI Assistant_                      |                          _Reply Zero_                           |
|  ![Gmail Client](.github/screenshots/email-client.png)   | ![Bulk Unsubscriber](.github/screenshots/bulk-unsubscriber.png) |
|                      _Gmail client_                      |                       _Bulk Unsubscriber_                       |

## Demo Video

[![Inbox Zero demo](/video-thumbnail.png)](http://www.youtube.com/watch?v=hfvKvTHBjG0)

## Built with

- [Next.js](https://nextjs.org/)
- [Tailwind CSS](https://tailwindcss.com/)
- [shadcn/ui](https://ui.shadcn.com/)
- [Prisma](https://www.prisma.io/)
- [Upstash](https://upstash.com/)
- [Turborepo](https://turbo.build/)

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=elie222/inbox-zero&type=Date)](https://www.star-history.com/#elie222/inbox-zero&Date)

## Feature Requests

To request a feature open a [GitHub issue](https://github.com/elie222/inbox-zero/issues), or join our [Discord](https://www.getinboxzero.com/discord).

## Getting Started for Developers

We offer a hosted version of Inbox Zero at [https://getinboxzero.com](https://getinboxzero.com). To self-host follow the steps below.

### Setup

[Here's a video](https://youtu.be/hVQENQ4WT2Y) on how to set up the project. It covers the same steps mentioned in this document. But goes into greater detail on setting up the external services.

### Requirements

- [Node.js](https://nodejs.org/en/) >= 18.0.0
- [pnpm](https://pnpm.io/) >= 8.6.12
- [Docker desktop](https://www.docker.com/products/docker-desktop/) (recommended but optional)

Make sure you have the above installed before starting.

The external services that are required are (detailed setup instructions below):

- [Google OAuth](https://console.cloud.google.com/apis/credentials)
- [Google PubSub](https://console.cloud.google.com/cloudpubsub/topic/list)

### Updating .env file: secrets

Create your own `.env` file from the example supplied:

```bash
cp apps/web/.env.example apps/web/.env
cd apps/web
pnpm install
```

Set the environment variables in the newly created `.env`. You can see a list of required variables in: `apps/web/env.ts`.

The required environment variables:

Secrets:

- `NEXTAUTH_SECRET` -- can be any random string (try using `openssl rand -hex 32` for a quick secure random string)
- `GOOGLE_ENCRYPT_SECRET` -- Secret key for encrypting OAuth tokens (try using `openssl rand -hex 32` for a secure key)
- `GOOGLE_ENCRYPT_SALT` -- Salt for encrypting OAuth tokens (try using `openssl rand -hex 16` for a secure salt)

Redis:

- `UPSTASH_REDIS_URL` -- Redis URL from Upstash. (can be empty if you are using Docker Compose)
- `UPSTASH_REDIS_TOKEN` -- Redis token from Upstash. (or specify your own random string if you are using Docker Compose)

When using Vercel with Fluid Compute turned off, you should set `MAX_DURATION=300` or lower. See Vercel limits for different plans [here](https://vercel.com/docs/functions/configuring-functions/duration#duration-limits).

### Updating .env file with Google OAuth credentials:

- `GOOGLE_CLIENT_ID` -- Google OAuth client ID. More info [here](https://next-auth.js.org/providers/google)
- `GOOGLE_CLIENT_SECRET` -- Google OAuth client secret. More info [here](https://next-auth.js.org/providers/google)

Go to [Google Cloud](https://console.cloud.google.com/). Create a new project if necessary.

Create [new credentials](https://console.cloud.google.com/apis/credentials):

1.  If the banner shows up, configure **consent screen** (if not, you can do this later)
    1. Click the banner, then Click `Get Started`.
    2. Choose a name for your app, and enter your email.
    3. In Audience, choose `External`
    4. Enter your contact information
    5. Agree to the User Data policy and then click `Create`.
    6. Return to APIs and Services using the left sidebar.
2.  Create new [credentials](https://console.cloud.google.com/apis/credentials):
    1. Click the `+Create Credentials` button. Choose OAuth Client ID.
    2. In `Application Type`, Choose `Web application`
    3. Choose a name for your web client
    4. In Authorized JavaScript origins, add a URI and enter `http://localhost:3000`
    5. In `Authorized redirect URIs` enter `http://localhost:3000/api/auth/callback/google`
    6. Click `Create`.
    7. A popup will show up with the new credentials, including the Client ID and secret.
3.  Update .env file:
    1. Copy the Client ID to `GOOGLE_CLIENT_ID`
    2. Copy the Client secret to `GOOGLE_CLIENT_SECRET`
4.  Update [scopes](https://console.cloud.google.com/auth/scopes)

    1. Go to `Data Access` in the left sidebar (or click link above)
    2. Click `Add or remove scopes`
    3. Copy paste the below into the `Manually add scopes` box:

    ```plaintext
    https://www.googleapis.com/auth/userinfo.profile
    https://www.googleapis.com/auth/userinfo.email
    https://www.googleapis.com/auth/gmail.modify
    https://www.googleapis.com/auth/gmail.settings.basic
    https://www.googleapis.com/auth/contacts
    ```

    4. Click `Update`
    5. Click `Save` in the Data Access page.

5.  Add yourself as a test user
    1. Go to [Audience](https://console.cloud.google.com/auth/audience)
    2. In the `Test users` section, click `+Add users`
    3. Enter your email and press `Save`

### Updating .env file with LLM parameters

You need to set an LLM, but you can use a local one too:

- [Anthropic](https://console.anthropic.com/settings/keys)
- [OpenAI](https://platform.openai.com/api-keys)
- AWS Bedrock Anthropic
- Google Gemini
- Groq Llama 3.3 70B
- Ollama (local)

For the LLM, you can use Anthropic, OpenAI, or Anthropic on AWS Bedrock. You
can also use Ollama by setting the following enviroment variables:

```sh
OLLAMA_BASE_URL=http://localhost:11434/api
NEXT_PUBLIC_OLLAMA_MODEL=phi3
```

Note: If you need to access Ollama hosted locally and the application is running on Docker setup, you can use `http://host.docker.internal:11434/api` as the base URL. You might also need to set `OLLAMA_HOST` to `0.0.0.0` in the Ollama configuration file.

You can select the model you wish to use in the app on the `/settings` page of the app.

If you are using local ollama, you can set it to be default:

```sh
DEFAULT_LLM_PROVIDER=ollama
```

### Redis and Postgres

We use Postgres for the database.
For Redis, you can use [Upstash Redis](https://upstash.com/) or set up your own Redis instance.

You can run Postgres & Redis locally using `docker-compose`

```bash
docker-compose up -d # -d will run the services in the background
```

### Running the app

To run the migrations:

```bash
pnpm prisma migrate dev
```

To run the app locally for development (slower):

```bash
pnpm run dev
```

Or from the project root:

```bash
turbo dev
```

To build and run the app locally in production mode (faster):

```bash
pnpm run build
pnpm start
```

Open [http://localhost:3000](http://localhost:3000) to view the app in your browser.

### Premium

Many features are available only to premium users. To upgrade yourself, make yourself an admin in the `.env`: `ADMINS=hello@gmail.com`
Then upgrade yourself at: [http://localhost:3000/admin](http://localhost:3000/admin).

### Set up push notifications via Google PubSub to handle emails in real time

Follow instructions [here](https://developers.google.com/gmail/api/guides/push).

1. [Create a topic](https://developers.google.com/gmail/api/guides/push#create_a_topic)
2. [Create a subscription](https://developers.google.com/gmail/api/guides/push#create_a_subscription)
3. [Grant publish rights on your topic](https://developers.google.com/gmail/api/guides/push#grant_publish_rights_on_your_topic)

Set env var `GOOGLE_PUBSUB_TOPIC_NAME`.
When creating the subscription select Push and the url should look something like: `https://www.getinboxzero.com/api/google/webhook?token=TOKEN` or `https://abc.ngrok-free.app/api/google/webhook?token=TOKEN` where the domain is your domain. Set `GOOGLE_PUBSUB_VERIFICATION_TOKEN` in your `.env` file to be the value of `TOKEN`.

To run in development ngrok can be helpful:

```sh
ngrok http 3000
# or with an ngrok domain to keep your endpoint stable (set `XYZ`):
ngrok http --domain=XYZ.ngrok-free.app 3000
```

And then update the webhook endpoint in the [Google PubSub subscriptions dashboard](https://console.cloud.google.com/cloudpubsub/subscription/list).

To start watching emails visit: `/api/google/watch/all`

### Watching for email updates

Set a cron job to run these:
The Google watch is necessary. Others are optional.

```json
  "crons": [
    {
      "path": "/api/google/watch/all",
      "schedule": "0 1 * * *"
    },
    {
      "path": "/api/resend/summary/all",
      "schedule": "0 16 * * 1"
    },
    {
      "path": "/api/reply-tracker/disable-unused-auto-draft",
      "schedule": "0 3 * * *"
    }
  ]
```

[Here](https://vercel.com/guides/how-to-setup-cron-jobs-on-vercel#alternative-cron-providers) are some easy ways to run cron jobs. Upstash is a free, easy option. I could never get the Vercel `vercel.json`. Open to PRs if you find a fix for that.

### Contributing to the project

You can view open tasks in our [GitHub Issues](https://github.com/elie222/inbox-zero/issues).
Join our [Discord](https://www.getinboxzero.com/discord) to discuss tasks and check what's being worked on.

[ARCHITECTURE.md](./ARCHITECTURE.md) explains the architecture of the project (LLM generated).


Good, I have a lot of information now. Let me read a few more to round out the picture.


# GottaHaveCoups v2.0

Modern, high-performance deal aggregation platform built with Astro, FastAPI, and intelligent scrapers.

## Project Structure

- `/backend` - FastAPI REST API server
- `/frontend` - Astro static site with React islands
- `/scrapers` - Modular scraper services (RSS, Playwright, AI, API, Webhooks)
- `/shared` - Shared types and utilities
- `/database` - Database schemas and migrations
- `/docs` - Documentation
- `/scripts` - Utility scripts

## Tech Stack

**Frontend:**
- Astro 5 (static site generation)
- React 19 (interactive islands)
- TypeScript
- Tailwind UI components

**Backend:**
- FastAPI (async Python web framework)
- SQLAlchemy 2.0 (ORM)
- PostgreSQL/SQLite (database)
- Celery + Redis (task queue)

**Scrapers:**
- Playwright + Stagehand (browser automation)
- Claude API (AI-powered scraping)
- RSS feed parsing (feedparser)
- Webhook integrations

## Quick Start

### Backend
```bash
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload
```

### Frontend
```bash
cd frontend
npm install
npm run dev
```

### Scrapers
```bash
cd scrapers
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python run_scrapers.py
```

## Environment Variables

Copy `.env.example` to `.env` and configure:
- API keys (Google/Gemini, Anthropic, Perplexity)
- Database connection
- Redis connection
- Affiliate IDs

## Development

- Backend runs on `http://localhost:8000`
- Frontend runs on `http://localhost:4321`
- API docs available at `http://localhost:8000/docs`

## License

MIT