# Purefeed MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that connects AI assistants to your [Purefeed](https://purefeed.ai) account — giving them access to your AI-curated Twitter/X feed, signals, semantic search, and post creation studio.

## Features

- **Feed** — Read your AI-ranked Twitter/X feed with signal relevance scores
- **Signals** — Create, manage, and query AI signals that auto-detect topics in your feed
- **Search** — Semantic (vector) search across all your saved tweets
- **Studio** — Generate, humanize, publish, schedule, and queue posts via Typefully
- **Folders** — Browse your bookmark folders and saved tweets

## Setup

1. Go to [purefeed.ai/profile](https://purefeed.ai/profile) and create a **Public API Key**
2. Install using the instructions for your platform below

## Installation

### OpenClaw

```bash
# Install the skill from ClawHub
clawhub install purefeed

# Configure the MCP server
openclaw config set mcpServers.purefeed.command "npx"
openclaw config set mcpServers.purefeed.args '[ "-y", "@purefeed/mcp-server" ]'
openclaw config set mcpServers.purefeed.env.PUREFEED_API_KEY "your-api-key"
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "purefeed": {
      "command": "npx",
      "args": ["-y", "@purefeed/mcp-server"],
      "env": {
        "PUREFEED_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add purefeed -- npx -y @purefeed/mcp-server \
  --env PUREFEED_API_KEY=your-api-key
```

### Cursor

Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "purefeed": {
      "command": "npx",
      "args": ["-y", "@purefeed/mcp-server"],
      "env": {
        "PUREFEED_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Tools

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_me` | Get your user profile and verify the API key | — |
| `get_feed` | Retrieve your AI-ranked tweet feed | `limit`, `search`, `signal_ids` |
| `get_signal_insights` | Get AI signal analysis for specific tweets | `tweet_ids` (comma-separated) |
| `list_folders` | List your bookmark folders | — |
| `get_folder_tweets` | Get tweets saved in a folder | `folder_id`, `limit` |
| `list_signals` | List all your AI signal configurations | — |
| `create_signal` | Create a new AI signal | `name`, `description`, `tags`, `include_keywords`, `exclude_keywords` |
| `get_signal` | Get details of a specific signal | `signal_id` |
| `update_signal` | Update signal name or description | `signal_id`, `name`, `description` |
| `delete_signal` | Permanently delete a signal | `signal_id` |
| `get_signal_matches` | Get tweets that triggered a signal | `signal_id`, `limit` |
| `list_styles` | List available writing styles | — |
| `search_tweets` | Semantic search across saved tweets | `query`, `limit` |
| `generate_post` | Generate a post using AI and reference tweets | `tweetIds`, `styleId`, `ideaPrompt` |
| `humanize_post` | Score a post for AI-likeness and rewrite if needed | `posts` |
| `publish_post` | Publish a post to X/Twitter immediately | `posts` |
| `schedule_post` | Schedule a post for a specific time | `posts`, `scheduled_at` |
| `save_draft` | Save a post as a draft in Typefully | `posts` |
| `queue_post` | Add a post to the next queue slot | `posts` |

## Resources

The server exposes these MCP resources for ambient context:

| Resource | URI | Description |
|----------|-----|-------------|
| Signals | `purefeed://signals` | Your AI signal configurations with IDs |
| Styles | `purefeed://styles` | Available writing styles with IDs |
| Profile | `purefeed://profile` | Your Purefeed user profile |
| Folders | `purefeed://folders` | Your bookmark folders with IDs |

## Prompts

| Prompt | Description |
|--------|-------------|
| `analyze_feed` | Analyze your feed for key themes, notable tweets, and signal matches |
| `draft_post` | Find interesting content and draft a post (optionally about a specific topic) |
| `signal_report` | Get a summary of what each AI signal detected recently |

## Configuration

| Environment Variable | Required | Default | Description |
|---------------------|----------|---------|-------------|
| `PUREFEED_API_KEY` | Yes | — | Your Purefeed API key from [purefeed.ai/profile](https://purefeed.ai/profile) |
| `PUREFEED_API_URL` | No | `https://purefeed.ai` | API base URL (for self-hosted or development) |

## Debugging

Test the server locally with the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector):

```bash
npx @modelcontextprotocol/inspector npx -y @purefeed/mcp-server
```

Set the `PUREFEED_API_KEY` environment variable in the Inspector UI, then test individual tools.

## License

MIT