Metadata-Version: 2.4
Name: pointguard-mcp
Version: 0.3.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.

## Quick Start — Cursor

**1. Install from PyPI:**

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

**2. Find where it was installed:**

```bash
which pointguard-mcp
```

Copy the full path (e.g. `/usr/local/bin/pointguard-mcp` or `/Users/you/miniforge3/envs/myenv/bin/pointguard-mcp`).

**3. Add to Cursor:**

Go to **Cursor → Settings → Features → MCP → Add new global MCP server**, or create/edit `~/.cursor/mcp.json`:

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

**4. Restart Cursor** (or go to Settings → Features → MCP and click the ↺ refresh icon next to `pointguard`).

**5. Open a chat and try it:**

> *"Find me a condensed sans-serif for a sports brand logo"*

---

## Features

| Tool | Description |
|------|-------------|
| `search_products` | Search by style, mood, subject, or keyword with natural language |
| `get_product` | Internal Pointguard index metadata for agent reasoning — numeric shop ID, category IDs, file type IDs, visibility, staff pick flag |
| `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` | Display-ready product data from the CM API — title, URL, full image gallery, description, shop name, formatted price. Accepts up to 50 IDs |

## 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 Filson Pro Font Family (16 fonts)."* (uses `find_similar`)
- *"What's trending in the Fonts category?"*
- *"Show me everything by Loudoun Design Co."* (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 | Returns |
|------|----------|---------|
| `search_products` | `POST /creative-market/products/search` | Product IDs + relevance tokens |
| `get_product` | `GET /creative-market/product/{id}` | Internal metadata — shop ID, category IDs, file types, flags |
| `browse_category` | `POST /creative-market/products/category` | Product IDs |
| `browse_shop` | `POST /creative-market/products/shop` | Product IDs |
| `find_similar` | `POST /creative-market/product/{id}/similar` | Product IDs |
| `autocomplete` | `GET /creative-market/completions/suggest` | Suggestion strings |
| `suggested_searches` | `POST /creative-market/suggested-searches` | Related search terms |
| `browse_creative_market` | `GET https://creativemarket.com/search/{query}` | Display-ready product cards (title, price, thumbnail, shop name) |
| `get_product_details` | `GET https://creativemarket.com/api/external/newsletter/product-details/{ids}` | Display-ready detail (title, URL, images, description, shop URL) |
