originselect-mcp-server

# OriginSelect MCP Server

[![npm version](https://img.shields.io/npm/v/originselect-mcp-server)](https://www.npmjs.com/package/originselect-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Model Context Protocol server for [OriginSelect](https://originselect.com) — search ethical, origin-verified products and brands via AI agents.

Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

See the [OriginSelect developer page](https://www.originselect.com/global/developers) for API docs and other integration options.

## Quick Start

### Option 1: npx (recommended)

No install needed — just add to your Claude Desktop config:

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

### Option 2: Global install

```bash
npm install -g originselect-mcp-server
```

Then add to Claude Desktop config:

```json
{
  "mcpServers": {
    "originselect": {
      "command": "originselect-mcp-server"
    }
  }
}
```

### Option 3: From source

```bash
git clone https://github.com/chhavimishra/originselect-mcp-server.git
cd originselect-mcp-server
npm install
```

```json
{
  "mcpServers": {
    "originselect": {
      "command": "node",
      "args": ["/absolute/path/to/originselect-mcp-server/src/index.js"],
      "env": {
        "API_BASE_URL": "https://api.originselect.com"
      }
    }
  }
}
```

### Cursor / Windsurf

Add to your MCP settings:

```json
{
  "originselect": {
    "command": "npx",
    "args": ["originselect-mcp-server"]
  }
}
```

## Example Queries

Once connected, ask your AI assistant:

- *"Find organic baby products from Canada under $25"*
- *"Show me women-owned coffee brands in the US"*
- *"What B Corp certified skincare brands do you have?"*
- *"Find vegan, cruelty-free pet products"*

## Tools

### `search_products`

Search the curated product catalog by values, country, category, brand, or keywords.

```
"Find organic baby products from Canada under $25"
→ { country: "Canada", category: "Baby", values: ["organic"], priceMax: 25 }
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | string | Optional NL query for context |
| `country` | string | Country of origin (Canada, USA) |
| `category` | string | Product category (Beauty, Baby, Pet Care, etc.) |
| `values` | string[] | Ethical values (women-owned, organic, b-corp, etc.) |
| `brand` | string | Brand name |
| `keywords` | string[] | Product keywords (shampoo, coffee, etc.) |
| `priceMax` | number | Maximum price in dollars |
| `market` | string | `canada`, `global`, or `all` (default: all) |
| `limit` | number | Max products (1-50, default: 12) |

### `search_brands`

Discover brands by ethical values, country, or category.

| Parameter | Type | Description |
|-----------|------|-------------|
| `country` | string | Country of origin |
| `values` | string[] | Ethical values |
| `category` | string | Product category |
| `brand` | string | Brand name to look up |
| `market` | string | Market scope |
| `limit` | number | Max brands (1-20, default: 10) |

### `refine_search`

Refine a previous search by adding/removing filters. Takes the `intent` object from a prior `search_products` response and applies modifications — no need to re-query from scratch.

```json
{
  "intent": { "...from previous response..." },
  "modifications": [
    { "action": "add", "field": "values", "value": "organic" },
    { "action": "remove", "field": "values", "value": "vegan" },
    { "action": "modify", "field": "priceMax", "value": 30 }
  ]
}
```

### `get_values`

List all 21 supported ethical/ownership values (women-owned, b-corp, organic, etc.).

### `get_categories`

List all 17 supported product categories.

### `get_countries`

List all supported countries of origin (currently Canada and USA).

### First-party intelligence tools

Proprietary OriginSelect traffic/revenue evidence — requires `INTELLIGENCE_API_KEY`
(see Environment Variables). Every response is bounded, includes date-window and
freshness context, and labels attribution as `deterministic`/`aggregate`/`inferred`
so you know how much to trust each number. These tools answer "what's going on
with our own site," not public-web research (SERPs, competitors) — do that
separately with your own search/browse tools.

| Tool | Purpose |
|---|---|
| `get_daily_priorities` | Top ranked opportunities with evidence and reason codes |
| `get_page_performance` | Cross-channel performance for one URL |
| `get_query_performance` | One query's performance across engines and pages |
| `get_page_queries` | Queries driving traffic to one page |
| `get_query_pages` | Pages ranking for one query |
| `get_ranking_changes` | Gains/losses in a page's queries over time |
| `get_ctr_opportunities` | Low-CTR-for-position pages/queries |
| `get_cannibalization` | Queries with overlapping page visibility |
| `get_channel_performance` | Google/Bing/Pinterest/AI breakdown for one page |
| `get_affiliate_performance` | Affiliate clicks/revenue/commission by program+market |
| `get_ai_referral_performance` | AI-engine referral behavior for one page |
| `get_change_history` | Logged build/content changes for one page |
| `get_data_freshness` | Connector status for every intelligence source |

## Architecture

```
AI Agent (Claude, GPT, Cursor)
    │
    │  MCP (stdio)
    ▼
┌─────────────────────────┐
│  MCP Server (this pkg)  │
│  19 tools               │
└───────────┬─────────────┘
            │  HTTPS
            ▼
┌─────────────────────────┐
│  OriginSelect API       │
│  api.originselect.com   │
└─────────────────────────┘
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `API_BASE_URL` | `https://api.originselect.com` | Discovery API base URL |
| `INTELLIGENCE_API_KEY` | _(none)_ | Required only for the intelligence tools listed above; product search works without it |

## Supported Values

```
women-owned · black-owned · indigenous-owned · veteran-owned
family-owned · lgbtq-owned · aapi-owned · latino-owned · minority-owned
b-corp · organic · sustainable · vegan · non-gmo · fair-trade
non-toxic · cruelty-free · fragrance-free · plastic-free
social-impact · gluten-free
```

## Security & Trust

This MCP server is **open source** and fully auditable:

- **Read-only** — only makes outbound HTTPS requests to `api.originselect.com`
- **No filesystem access** — does not read or write any local files
- **No telemetry** — does not send user data or analytics anywhere
- **Minimal dependencies** — single runtime dependency (`@modelcontextprotocol/sdk`)
- **Source code** — [github.com/chhavimishra/originselect-mcp-server](https://github.com/chhavimishra/originselect-mcp-server)

See [SECURITY.md](SECURITY.md) for vulnerability reporting.

## License

MIT


## Private ChatGPT transport (prepared, not published or deployed)

The existing `src/index.js` stdio entry point and its 19-tool inventory remain
unchanged. The private Codex connection can continue using its current launcher
and server-side `INTELLIGENCE_API_KEY` setup.

`originselect-mcp-server/intelligence` exports `createIntelligenceServer`, a
separate factory reusing the 13 existing intelligence descriptors. It requires
an authenticated read dispatcher; it contains no catalog/mutation dispatch and
adds strict schemas, OAuth metadata and read-only annotations. Remote-only
options expose a pinned page-only baseline and dated country/device diagnostics.
These options do not alter the legacy stdio schemas.

The existing OriginSelect backend mounts this factory at the proposed
`https://mcp.originselect.com/mcp` endpoint using stateless Streamable HTTP.
Cognito handles user sign-in/PKCE/refresh through the official MCP SDK OAuth
proxy. Backend controllers execute the reads directly: no intelligence API key
is given to ChatGPT, put into a URL, or forwarded in OAuth tokens.

The backend installs a local `vendor/originselect-mcp-server-1.0.12.tgz` produced
by its `scripts/vendor-private-mcp.mjs`; no npm publication is needed. After
changing this factory or its descriptors, rebuild that artifact and update the
backend lockfile. The vendored manifest records the archive checksum.

Deployment, owner allowlisting, ChatGPT connection instructions and rollback
are documented in the backend's `intelligence/mcp/README.md`. A local SDK test
is not ChatGPT acceptance: the deployment remains unaccepted until an actual
authenticated ChatGPT call matches the saved Aug 8–Sep 4, 2026 page-only evidence.