Metadata-Version: 2.4
Name: pointguard-mcp
Version: 0.2.0
Summary: MCP server for Creative Market's Pointguard search platform — discover fonts, graphics, and creative assets through natural conversation.
Project-URL: Homepage, https://github.com/creativemarket/pointguard-mcp
Project-URL: Repository, https://github.com/creativemarket/pointguard-mcp
Author: Creative Market
License: MIT
Keywords: ai,creative-market,fonts,mcp,search
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# Pointguard MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes Creative Market's Pointguard search platform to AI assistants. Discover fonts, graphics, templates, and creative assets through natural conversation.

## Features

| Tool | Description |
|------|-------------|
| `search_products` | Search by style, mood, subject, or keyword with natural language |
| `get_product` | Get full product details from the Pointguard index — pricing, category, file types, availability |
| `browse_category` | Explore products by classification using the full CM category taxonomy |
| `browse_shop` | Browse a designer or studio's full catalog by shop ID |
| `find_similar` | Find visually/stylistically similar products using embeddings |
| `autocomplete` | Get search suggestions from partial input |
| `suggested_searches` | Discover related searches and trending terms |
| `browse_creative_market` | Search CM directly for rich display data — titles, prices, preview images, designer info |
| `get_product_details` | Fetch full metadata for up to 50 product IDs — full image gallery, description, licenses |

## Example Queries

Once connected to an MCP-compatible client (Claude, Cursor, etc.), you can ask:

- *"Find me a condensed sans-serif for a sports brand logo."*
- *"Show me retro display fonts for a vinyl record label."*
- *"I need textures and grunge graphics for a concert poster."*
- *"Find script fonts under $30 that work for wedding stationery."*
- *"Show me font alternatives to Futura."* (uses `find_similar`)
- *"What's trending in the Fonts category?"*
- *"Show me everything by Set Sail Studios."* (uses `browse_shop`)
- *"Browse sans-serif fonts."* (uses `browse_category` with ID 81)

## Installation

```bash
pip install pointguard-mcp
```

Or in development mode:

```bash
cd pointguard-mcp
pip install -e .
```

## Configuration

Set environment variables before running:

| Variable | Default | Description |
|----------|---------|-------------|
| `POINTGUARD_BASE_URL` | `http://localhost:5000` | Pointguard API base URL |
| `POINTGUARD_TIMEOUT` | `30` | Request timeout in seconds |
| `CM_API_USER` | _(required)_ | Creative Market API basic auth username |
| `CM_API_PASS` | _(required)_ | Creative Market API basic auth password |

## Usage

### Standalone (stdio)

```bash
pointguard-mcp
```

### With Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pointguard": {
      "command": "pointguard-mcp",
      "env": {
        "POINTGUARD_BASE_URL": "https://your-api-host.com",
        "CM_API_USER": "your-cm-api-user",
        "CM_API_PASS": "your-cm-api-pass"
      }
    }
  }
}
```

### With Cursor

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

```json
{
  "mcpServers": {
    "pointguard": {
      "command": "pointguard-mcp",
      "env": {
        "POINTGUARD_BASE_URL": "https://your-api-host.com",
        "CM_API_USER": "your-cm-api-user",
        "CM_API_PASS": "your-cm-api-pass"
      }
    }
  }
}
```

## Category Reference

### Top-level Categories

| ID | Category |
|----|----------|
| 1 | Graphics |
| 2 | Templates |
| 3 | Fonts |
| 4 | Add-ons (Brushes & More) |
| 6 | Photos |
| 7 | 3D |
| 8 | Stock Video / Footage |
| 23 | Illustrations |
| 26 | Icons |
| 1800 | Mockups |

### Font Subcategories

| ID | Subcategory |
|----|-------------|
| 80 | Serif |
| 81 | Sans Serif |
| 82 | Script |
| 84 | Symbols |
| 85 | Blackletter |
| 86 | Slab Serif |
| 88 | Handwritten |

### Template Subcategories

| ID | Subcategory |
|----|-------------|
| 50 | Logos |
| 19 | Posters |
| 42 | Flyers |
| 46 | Invitations |
| 45 | Business Cards |
| 49 | Presentations |
| 52 | Social Media |
| 44 | Stationery |
| 41 | Brochures |
| 43 | Resumes |

### Other Notable Subcategories

| ID | Subcategory |
|----|-------------|
| 27 | Textures (Graphics) |
| 28 | Patterns (Graphics) |
| 24 | Objects (Graphics) |
| 131 | Nature (Photos) |
| 132 | People (Photos) |
| 127 | Food & Drink (Photos) |
| 21 | Product Mockups |
| 1801 | Device Mockups |
| 1805 | Apparel Mockups |
| 2601 | Solid Icons |
| 2602 | Outline Icons |
| 2603 | Duotone Icons |

See `CATEGORY_MAP` in `server.py` for the full list of 170+ category and subcategory mappings.

## Development

```bash
# Install in development mode
pip install -e .

# Run directly
python -m pointguard_mcp.server

# Test with MCP inspector (browser UI)
npx @modelcontextprotocol/inspector pointguard-mcp
```

## Architecture

```
┌─────────────────┐     stdio      ┌──────────────────┐     HTTP/JSON     ┌──────────────────────┐
│  AI Assistant   │◄──────────────►│  pointguard-mcp  │◄────────────────►│  Pointguard API      │
│  (Claude, etc.) │                │  (MCP Server)    │                   │  (Flask + ES)        │
└─────────────────┘                └──────────────────┘                   └──────────────────────┘
                                           │
                                           │ HTTPS
                                           ▼
                                   ┌──────────────────┐
                                   │  creativemarket  │
                                   │  .com (search +  │
                                   │  product detail) │
                                   └──────────────────┘
```

The MCP server has two data sources:

1. **Pointguard API** (`POINTGUARD_BASE_URL`) — powers `search_products`, `get_product`, `browse_category`, `browse_shop`, `find_similar`, `autocomplete`, `suggested_searches`
2. **creativemarket.com** — powers `browse_creative_market` (search with preview images) and `get_product_details` (full image gallery, descriptions, licenses via authenticated API)

## Endpoints Used

| Tool | Endpoint |
|------|----------|
| `search_products` | `POST /creative-market/products/search` |
| `get_product` | `GET /creative-market/product/{id}` |
| `browse_category` | `POST /creative-market/products/category` |
| `browse_shop` | `POST /creative-market/products/shop` |
| `find_similar` | `POST /creative-market/product/{id}/similar` |
| `autocomplete` | `GET /creative-market/completions/suggest` |
| `suggested_searches` | `POST /creative-market/suggested-searches` |
| `browse_creative_market` | `GET https://creativemarket.com/search/{query}` |
| `get_product_details` | `GET https://creativemarket.com/api/external/newsletter/product-details/{ids}` |
