Metadata-Version: 2.4
Name: hyperstore-mcp
Version: 0.1.0
Summary: MCP server for HyperStore — discover 1000+ AI apps from any LLM.
Project-URL: Homepage, https://store.hypergpt.ai
Project-URL: Repository, https://github.com/deficlow/HyperStore-MCP
Project-URL: Issues, https://github.com/deficlow/HyperStore-MCP/issues
Project-URL: MCP Endpoint, https://mcp.store.hypergpt.ai
Author-email: HyperGPT <hello@hypergpt.ai>
License: MIT
License-File: LICENSE
Keywords: ai,directory,hypergpt,hyperstore,llm,marketplace,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: anyio>=4.3.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: pydantic>=2.6.0
Provides-Extra: dev
Requires-Dist: pyright>=1.1.360; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Provides-Extra: http
Requires-Dist: starlette>=0.37.0; extra == 'http'
Requires-Dist: uvicorn>=0.30.0; extra == 'http'
Description-Content-Type: text/markdown

# HyperStore MCP

> Plug 6,500+ AI apps into any LLM via the [Model Context Protocol](https://modelcontextprotocol.io).

[![PyPI](https://img.shields.io/pypi/v/hyperstore-mcp.svg)](https://pypi.org/project/hyperstore-mcp/)
[![CI](https://github.com/deficlow/HyperStore-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/deficlow/HyperStore-MCP/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**HyperStore** is a curated directory of 6,500+ AI applications, developed by [HyperGPT](https://hypergpt.ai).
This MCP server exposes the [HyperStore](https://store.hypergpt.ai) catalog to any LLM client — Claude, ChatGPT, Cursor,
Windsurf, Cline, Zed, Gemini, and anything else that speaks MCP.

Ask your LLM:

> *"Find me a free AI tool that summarises PDFs."*
> *"Compare ChatGPT, Claude, and Gemini side-by-side."*
> *"Show me the top 5 image-generation apps with an API."*

The LLM calls HyperStore MCP behind the scenes and answers with up-to-date, curated results.

---

## What you get

**8 tools:**

| Tool | Purpose |
|---|---|
| `search_apps` | Full-text keyword search |
| `ai_search` | Embedding-based semantic search |
| `get_app` | Full app detail (features, screenshots, pricing) |
| `list_apps` | Paginated apps with filters (category, pricing) |
| `list_categories` | Browse all 30+ categories |
| `category_apps` | Apps within a category |
| `browse_apps` | A-Z directory listing |
| `get_homepage` | Trending + top categories overview |

**3 resources:**

- `hyperstore://app/{slug}` — markdown rendering of any app
- `hyperstore://category/{slug}` — top apps in a category
- `hyperstore://catalog` — full category index

**3 prompts:**

- `find_tool_for_task` — guided discovery for a task
- `compare_apps` — side-by-side app comparison
- `discover_category` — explore a topic

---

## Install

### Option A — `uvx` (zero install, recommended)

Requires [uv](https://docs.astral.sh/uv/). One command and you're done:

```bash
uvx hyperstore-mcp
```

### Option B — `pipx`

```bash
pipx install hyperstore-mcp
hyperstore-mcp
```

### Option C — Docker (for remote hosting)

```bash
docker run --rm -p 8080:8080 ghcr.io/deficlow/hyperstore-mcp
# Now MCP Streamable HTTP at http://localhost:8080/mcp
```

### Option D — Hosted endpoint (no install)

Use our managed Streamable HTTP server:

```
https://mcp.store.hypergpt.ai/mcp
```

---

## Connect from your LLM client

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "hyperstore": {
      "command": "uvx",
      "args": ["hyperstore-mcp"]
    }
  }
}
```

Restart Claude → tools appear in the 🛠 menu.

### Claude Code

```bash
claude mcp add hyperstore -- uvx hyperstore-mcp
```

### Cursor

`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "hyperstore": {
      "command": "uvx",
      "args": ["hyperstore-mcp"]
    }
  }
}
```

### Windsurf

`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "hyperstore": {
      "command": "uvx",
      "args": ["hyperstore-mcp"]
    }
  }
}
```

### Cline (VS Code)

`settings.json`:

```json
{
  "cline.mcpServers": {
    "hyperstore": {
      "command": "uvx",
      "args": ["hyperstore-mcp"]
    }
  }
}
```

### Zed

`~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "hyperstore": {
      "command": {
        "path": "uvx",
        "args": ["hyperstore-mcp"]
      }
    }
  }
}
```

### Gemini CLI

`~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "hyperstore": {
      "command": "uvx",
      "args": ["hyperstore-mcp"]
    }
  }
}
```

### ChatGPT (Pro / Team / Enterprise)

**Settings → Connectors → Add custom connector**:

- **Name**: HyperStore
- **MCP Server URL**: `https://mcp.store.hypergpt.ai/mcp`
- **Authentication**: None

### OpenAI Responses API

```python
from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "mcp",
        "server_label": "hyperstore",
        "server_url": "https://mcp.store.hypergpt.ai/mcp",
        "require_approval": "never",
    }],
    input="Find me 3 free AI tools for writing unit tests.",
)
print(response.output_text)
```

### Anthropic Messages API

```python
from anthropic import Anthropic

client = Anthropic()
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    mcp_servers=[{
        "type": "url",
        "url": "https://mcp.store.hypergpt.ai/mcp",
        "name": "hyperstore",
    }],
    messages=[{"role": "user", "content": "Top 5 AI image generators?"}],
)
```

See [`examples/`](examples/) for ready-to-paste configs for every supported client.

---

## Run as a remote server

```bash
# Streamable HTTP (modern, ChatGPT/OpenAI/Anthropic)
hyperstore-mcp --transport http --host 0.0.0.0 --port 8080

# Legacy SSE (older MCP clients)
hyperstore-mcp --transport sse --port 8080
```

The hosted endpoint at `https://mcp.store.hypergpt.ai` runs the Docker image
behind a CDN — no auth, rate-limited per IP.

---

## Configuration

All settings come from environment variables (see [`.env.example`](.env.example)):

| Variable | Default | Purpose |
|---|---|---|
| `HYPERSTORE_API_BASE` | `https://store.hypergpt.ai` | Upstream API base URL |
| `HYPERSTORE_TIMEOUT` | `20` | HTTP timeout in seconds |
| `HYPERSTORE_USER_AGENT` | `hyperstore-mcp/{version}` | UA string |
| `MCP_HOST` | `0.0.0.0` | Bind host (http/sse only) |
| `MCP_PORT` | `8080` | Bind port (http/sse only) |
| `LOG_LEVEL` | `INFO` | Logging level |

---

## Development

```bash
git clone https://github.com/deficlow/HyperStore-MCP
cd HyperStore-MCP
uv sync --all-extras
uv run pytest
uv run hyperstore-mcp        # stdio mode for local testing
```

Inspect the running server with the official **MCP Inspector**:

```bash
npx @modelcontextprotocol/inspector uvx hyperstore-mcp
```

---

## How it works

HyperStore MCP is a thin async wrapper around the [HyperStore](https://store.hypergpt.ai) public
REST API. It is **read-only** — no credentials, no writes, no PII. The same data that
powers the website powers the MCP server. Updates land in your LLM the moment they
land on the site.

```
LLM client ──MCP──▶ hyperstore-mcp ──HTTPS──▶ store.hypergpt.ai/api
```

---

## License

MIT © [HyperGPT](https://hypergpt.ai)
