# Feather MCP Server

[![npm version](https://img.shields.io/npm/v/feather-mcp-server.svg)](https://www.npmjs.com/package/feather-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blue.svg)](https://modelcontextprotocol.io)

**Connect AI agents to Facebook lead generation and CRM automation.**

An MCP (Model Context Protocol) server that exposes **Feather Connector** and **Feather Messenger CRM** tools to any AI agent. Search leads, manage contacts, send broadcasts, and track growth metrics through a universal plugin interface.

## Quick Start

Zero-install via npx:

```bash
npx feather-mcp-server
```

Or install and build locally:

```bash
npm install
npm run build
node dist/index.js
```

Test with the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

---

## Demo Mode

> **Try all 10 tools without installing the Chrome extension!**
>
> The server runs in **demo mode** by default, returning realistic mock data (leads, contacts, stats, growth metrics) so you can explore every tool immediately. Set `FEATHER_DEMO=false` when you're ready to connect to the live Feather extensions.

| Variable | Default | Description |
|---|---|---|
| `FEATHER_DEMO` | `true` | Use mock data (`true`) or connect to live extensions (`false`) |

---

## Works With

- **Claude Desktop** — add to `claude_desktop_config.json`
- **Cursor** — add as an MCP server in settings
- **VS Code** — via MCP extension
- **Windsurf** — add as an MCP server
- **OpenClaw** — add to your OpenClaw config
- **Any MCP client** — standard stdio transport

## Tools

### Feather Connector (Facebook Automation)

| Tool | Description |
|---|---|
| `search_leads` | Search for potential leads by keywords, groups, or interests |
| `send_friend_request` | Send a friend request with an optional note |
| `get_request_status` | Check status of sent friend requests (pending/accepted/declined) |
| `get_connector_stats` | Get overall statistics: sent, accepted, declined, accept rate |

### Feather Messenger CRM

| Tool | Description |
|---|---|
| `list_contacts` | List CRM contacts with optional label, tag, or search filters |
| `add_label` | Add a label to a contact |
| `add_tag` | Add a tag to a contact |
| `send_broadcast` | Send a broadcast message to all contacts with a given label |
| `get_crm_stats` | Get aggregate CRM stats: contact count, label distribution, recent activity |

### Analytics

| Tool | Description |
|---|---|
| `get_growth_metrics` | Get growth metrics (connections, messages, engagement) over 7d/30d/90d |

## Example Usage

### Search for leads

```json
{
  "tool": "search_leads",
  "arguments": {
    "query": "marketing",
    "limit": 5,
    "source": "groups"
  }
}
```

### Send a broadcast

```json
{
  "tool": "send_broadcast",
  "arguments": {
    "label": "warm",
    "message": "New webinar this Thursday! Link in bio.",
    "dryRun": true
  }
}
```

### Check growth

```json
{
  "tool": "get_growth_metrics",
  "arguments": {
    "metric": "connections",
    "period": "30d"
  }
}
```

## Integration

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "feather": {
      "command": "npx",
      "args": ["-y", "feather-mcp-server"]
    }
  }
}
```

### OpenClaw

Add to your OpenClaw config:

```yaml
mcp:
  servers:
    feather:
      command: npx
      args:
        - -y
        - feather-mcp-server
```

## Architecture

```
src/
  index.ts          Entry point (stdio transport)
  server.ts         MCP server setup + tool registration
  types.ts          TypeScript types
  utils.ts          Helpers (demo mode check, JSON results, error handling)
  tools/
    connector.ts    Feather Connector tools (4 tools)
    messenger.ts    Feather Messenger CRM tools (5 tools)
    analytics.ts    Analytics tools (1 tool)
  mock/
    data.ts         Realistic demo data (leads, contacts, stats, growth series)
```

## Tech Stack

- TypeScript + Node.js
- `@modelcontextprotocol/sdk` (official MCP SDK)
- `zod` for input validation
- stdio transport (MCP standard)

## License

MIT