@matcha-chai/mcp-matchai-team/README.md

Access the entire Matchai AI development team through a single MCP interface - powered by n8n, LLMs, and Graphiti temporal knowledge graph

# Matchai Team MCP Server

Access the entire Matchai AI development team through a single MCP (Model Context Protocol) interface. Powered by n8n workflows, advanced LLMs, and Graphiti temporal knowledge graph for continuous learning and improvement.

## 🚀 Overview

The Matchai Team is an AI-powered development squad that combines specialized agents to handle any aspect of your project. Instead of juggling multiple tools or agents, you interact with the team through natural language, and the Project Manager ensures the right specialists collaborate on your request.

## 🤖 Meet the Team

### Backend Engineer Agent
Your technical implementation specialist who handles:
- **Database Architecture**: Designing schemas, migrations, and relationships in Supabase/PostgreSQL
- **API Development**: Creating GraphQL queries, REST endpoints, and Edge Functions
- **Workflow Automation**: Building n8n workflows for complex business processes
- **Security Implementation**: RLS policies, authentication flows, and data protection
- **Performance Optimization**: Query tuning, caching strategies, and load optimization
- **Integration Services**: Connecting with external APIs and third-party services
- **Testing & Debugging**: Comprehensive testing strategies and issue resolution

### Business Logic Analyst Agent
Your domain expert who focuses on:
- **Requirements Analysis**: Breaking down complex business needs into actionable tasks
- **Process Documentation**: Creating clear, comprehensive documentation
- **Domain Modeling**: Designing entities, relationships, and business rules
- **Logic Optimization**: Streamlining workflows and identifying inefficiencies
- **Validation & Verification**: Ensuring implementations meet business requirements
- **Edge Case Identification**: Finding potential issues before they become problems
- **Pattern Recognition**: Recommending proven architectural solutions

### Project Manager (Coordinator)
Behind the scenes, the Project Manager:
- Analyzes your natural language requests
- Determines which specialists are needed
- Coordinates multi-agent collaboration
- Consolidates responses into actionable solutions
- Learns from past interactions via Graphiti

## 🧠 Powered by Advanced Technology

### n8n Workflows
- Orchestrates complex multi-step operations
- Manages agent coordination and communication
- Handles asynchronous processing and queuing
- Integrates with external services and APIs

### Large Language Models (LLMs)
- Natural language understanding and generation
- Context-aware problem solving
- Code generation and optimization
- Intelligent decision making

### Graphiti Temporal Knowledge Graph
- **Living Memory**: Tracks how your codebase evolves over time
- **Pattern Learning**: Remembers what worked and what didn't
- **Relationship Mapping**: Understands dependencies between components
- **Continuous Improvement**: Each interaction makes the team smarter
- **Decision History**: Records why architectural choices were made

## 📦 Installation

### Prerequisites

Before installation, you'll need:
1. **Node.js 18+** installed on your system
2. **Matchai Team API Key** (required for authentication)

To get your API key, contact the Matchai team.

### Via NPX (Recommended)

The easiest way to use the Matchai Team is through npx, which downloads and runs the latest version automatically:

```bash
# Basic usage (you'll be prompted for the API key)
npx @matcha-chai/mcp-matchai-team

# With API key provided via environment variable (recommended)
MATCHAI_TEAM_API_KEY=your-api-key-here npx @matcha-chai/mcp-matchai-team

# With both API key and custom webhook URL
MATCHAI_TEAM_URL=https://custom.webhook.url \
MATCHAI_TEAM_API_KEY=your-api-key-here \
npx @matcha-chai/mcp-matchai-team
```

**Note:** The API key is **required**. The server will not start without it.

### Global Installation

For frequent use, you can install globally:

```bash
# Install globally
npm install -g @matcha-chai/mcp-matchai-team

# Run from anywhere
MATCHAI_TEAM_API_KEY=your-api-key-here mcp-matchai-team
```

### Setting Up Environment Variables

For convenience, you can set environment variables permanently:

**Linux/Mac:**
```bash
# Add to ~/.bashrc or ~/.zshrc
export MATCHAI_TEAM_API_KEY="your-api-key-here"

# Reload your shell configuration
source ~/.bashrc  # or source ~/.zshrc
```

**Windows (PowerShell):**
```powershell
# Set for current session
$env:MATCHAI_TEAM_API_KEY = "your-api-key-here"

# Set permanently (requires admin)
[System.Environment]::SetEnvironmentVariable("MATCHAI_TEAM_API_KEY", "your-api-key-here", "User")
```

**Using .env file:**
```bash
# Create .env file in your project
echo 'MATCHAI_TEAM_API_KEY=your-api-key-here' > .env

# The server will automatically load from .env
npx @matcha-chai/mcp-matchai-team
```

## ⚙️ Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "matchai-team": {
      "command": "npx",
      "args": ["@matcha-chai/mcp-matchai-team"],
      "env": {
        "MATCHAI_TEAM_URL": "https://matchai.app.n8n.cloud/webhook/matchai-team",
        "MATCHAI_TEAM_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**Important:** Replace `your-api-key-here` with your actual Matchai Team API key.

### Configuration File Locations

**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```

**Mac:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Linux:**
```
~/.config/Claude/claude_desktop_config.json
```

## 🎯 Usage

The server exposes a single tool: `matchai-team`

### Input Parameters

- `prompt` (string, required): Your request or question in natural language
- `context` (object, optional): Additional context relevant to the request

### Example Requests

```javascript
// Technical implementation request
{
  "prompt": "Create a GraphQL query for loading project data with all related entities"
}

// Business logic analysis
{
  "prompt": "Analyze the lead conversion workflow and suggest optimizations"
}

// Complex multi-agent task
{
  "prompt": "Design and implement a real-time chat system with proper RLS policies",
  "context": {
    "requirements": "Team-based access control, message history, typing indicators"
  }
}

// Debugging with context
{
  "prompt": "Fix the RLS policy issue preventing team members from viewing projects",
  "context": {
    "error": "permission denied for table projects",
    "user_role": "team_member",
    "current_policy": "..."
  }
}
```

## 🔄 How It Works

1. **You describe what you need** in plain English
2. **Claude calls the matchai-team tool** with your request
3. **The Project Manager analyzes** your request and determines the approach
4. **Specialized agents collaborate** to solve different aspects
5. **Graphiti records the solution** for future reference and learning
6. **You receive a comprehensive solution** with code, explanations, and next steps

## 🌟 Key Benefits

- **Natural Language Interface**: No need to learn complex commands or syntax
- **Intelligent Routing**: Automatically engages the right specialists
- **Collaborative Problem Solving**: Multiple agents work together on complex tasks
- **Continuous Learning**: Every interaction improves future responses
- **Comprehensive Solutions**: Get complete implementations, not just snippets
- **Context Awareness**: Understands your project's specific needs and patterns

## 🔧 Environment Variables

- `MATCHAI_TEAM_URL`: The n8n webhook endpoint (default: `https://matchai.app.n8n.cloud/webhook/matchai-team`)
- `MATCHAI_TEAM_API_KEY`: **Required** - API key for authentication

## 🎨 Example Workflow

When you ask: *"Create a secure API endpoint for team management with proper authentication"*

1. **Project Manager** breaks down the request
2. **Business Logic Analyst** defines the requirements and constraints
3. **Backend Engineer** implements:
   - Database schema for teams
   - RLS policies for security
   - GraphQL/REST endpoint
   - Authentication middleware
   - n8n workflow for team operations
4. **Graphiti** records the pattern for future similar requests
5. **You receive** complete, production-ready code with documentation

## 🐛 Troubleshooting

### Common Issues

**"MATCHAI_TEAM_API_KEY is required"**
- The API key is missing. Set it as an environment variable or pass it when running:
  ```bash
  MATCHAI_TEAM_API_KEY=your-key npx @matcha-chai/mcp-matchai-team
  ```

**Connection errors**
- Verify your internet connection
- Check if the webhook URL is accessible
- Ensure your API key is valid

**Timeout errors**
- Complex requests may take longer. The timeout is set to 2 minutes
- Break down very complex requests into smaller parts

## 📈 Continuous Improvement

The Matchai Team gets smarter with every interaction:
- Learns your coding patterns and preferences
- Remembers previous solutions and their outcomes
- Adapts to your project's specific requirements
- Identifies and avoids past mistakes
- Suggests optimizations based on accumulated knowledge

## 📄 License

MIT

## 💬 Support

For issues, questions, or feature requests: https://github.com/matcha-chai/mcp-matchai-team/issues

---

*Built with ❤️ by the Matchai Team - Where AI meets Real Estate Development*