# Unofficial Horoshop MCP Server

An unofficial MCP server for stores built on [Horoshop](https://horoshop.ua/).

This project connects AI agents, internal assistants, and MCP-compatible clients to the Horoshop API through a practical Model Context Protocol server. It is designed for teams that run e-commerce operations on Horoshop and want language models to interact with store data in a controlled, tool-based way.

This project is not affiliated with, endorsed by, or maintained by Horoshop. It is a community-built integration for the Horoshop ecosystem.

## Why This Exists

Horoshop gives merchants a hosted e-commerce platform at [horoshop.ua](https://horoshop.ua/), but AI tools still need a reliable way to access store operations such as orders, catalog data, and order status updates. MCP is a good fit for that layer because it lets LLMs call clearly defined tools instead of improvising against raw APIs.

This server turns the Horoshop API into MCP tools that can be used from clients like Claude Desktop, Cursor, and other agent frameworks that support MCP over stdio.

## Real Use Cases

This server is useful when you want AI to do real operational work around a Horoshop store, for example:

- customer support assistants that look up an order, confirm its current status, and hand back structured answers to an operator
- back-office agents that review new orders and move them into the next processing state
- catalog helpers that inspect product data before content updates or merchandising tasks
- internal dashboards where AI can answer questions like "show me the latest orders from today" or "find the product by ID and summarize its current state"
- automation flows that need a safe bridge between natural-language prompts and Horoshop API methods
- store operations copilots that combine Horoshop data with CRM, ERP, shipping, or analytics tooling

## What The Server Does

The current implementation provides a compact but useful starting point:

- authenticates against the Horoshop API using either a token or login/password credentials
- exposes MCP tools for listing and fetching orders
- exposes MCP tools for listing and fetching products
- supports updating order status from an MCP client
- includes a generic passthrough tool for calling arbitrary Horoshop API functions

This gives you enough to start with real workflows while keeping the codebase small enough to extend quickly.

## Example Agent Workflows

With this MCP server, an agent can support workflows such as:

- "Find order `12345` and tell me whether it has already moved to the shipped status."
- "List the newest orders and summarize which ones need manual attention."
- "Fetch product `9876` and prepare a short product brief for a support manager."
- "Update order `12345` to status `7` after warehouse confirmation."
- "Call a custom Horoshop API function that is not wrapped yet, then return the raw payload for inspection."

## Environment

Copy `.env.example` to `.env` and configure:

- `HOROSHOP_BASE_URL`: your Horoshop store domain, for example `https://your-store.example.com`
- `HOROSHOP_LOGIN`: API login created in the Horoshop admin panel
- `HOROSHOP_PASSWORD`: API password created in the Horoshop admin panel
- `HOROSHOP_TOKEN`: optional token if you already use token-based access

You need either:

- `HOROSHOP_TOKEN`

or:

- `HOROSHOP_LOGIN`
- `HOROSHOP_PASSWORD`

## Install

```bash
npm install
```

## Run

```bash
npm run build
npm start
```

For development:

```bash
npm run dev
```

## MCP Configuration Example

```json
{
  "mcpServers": {
    "horoshop": {
      "command": "node",
      "args": [
        "D:/usr/www/mcp-dev/horoshop/dist/index.js"
      ],
      "env": {
        "HOROSHOP_BASE_URL": "https://your-store.example.com",
        "HOROSHOP_LOGIN": "api-login",
        "HOROSHOP_PASSWORD": "api-password"
      }
    }
  }
}
```

## Available Tools

- `horoshop_auth`: verify authentication and confirm token access
- `horoshop_list_orders`: list orders using Horoshop order export functions
- `horoshop_get_order`: fetch one order by ID
- `horoshop_list_products`: list products using Horoshop catalog export functions
- `horoshop_get_product`: fetch one product by ID
- `horoshop_update_order_status`: change the status of an order
- `horoshop_call_api`: call any Horoshop API function with arbitrary JSON parameters

## Who This Is For

This project is a strong fit for:

- Horoshop merchants who want AI assistants to work with store operations
- agencies building AI-enabled tooling for Horoshop clients
- developers integrating Horoshop into MCP-based automation stacks
- teams that want a base server they can customize for their own business rules

## Current Scope

This repository focuses on the operational core first: authentication, orders, products, status updates, and a raw API escape hatch.

That means it is intentionally useful on day one, but not yet a complete wrapper for the full Horoshop API surface. The generic `horoshop_call_api` tool is included specifically so you can validate store-specific behavior and extend the server safely as new requirements appear.

## Notes

The server assumes the Horoshop API endpoint pattern:

`https://<domain>/api/<function>/`

If your store exposes different function names or request shapes than the defaults currently wrapped in this repository, use `horoshop_call_api` first and then extend [src/index.ts](./src/index.ts).

## Source

Horoshop website: [https://horoshop.ua/](https://horoshop.ua/)