# TimeLib MCP — AI agent for your Medusa store

An [MCP](https://modelcontextprotocol.io) server that lets an AI agent (Claude
Desktop, Claude Code, or any MCP client) **add and manage products** — plus
inventory, collections/categories, orders and customers — in your TimeLib
Medusa v2 store via the Admin API.

You just chat, e.g.:

> "Add a product called *Chrono Field Watch*, a draft, with S/M/L bands at $180,
> 20 in stock each, in the Watches collection."

and the agent creates it.

---

## What the agent can do

| Area | Tools |
|------|-------|
| Orientation | `get_store_context` (regions, currencies, sales channels, locations) |
| Products | `list_products`, `get_product`, `create_product`, `update_product`, `delete_product` |
| Variants | `create_variant`, `update_variant`, `delete_variant` |
| Inventory | `list_inventory_items`, `set_inventory_level` |
| Catalog | `list_collections`, `create_collection`, `list_categories`, `create_category`, `list_product_tags`, `list_product_types` |
| Orders / Customers | `list_orders`, `get_order`, `list_customers` |
| Anything else | `medusa_admin_request` (raw Admin API escape hatch) |

### Frontend content (Sanity) — optional

When `SANITY_PROJECT_ID` + `SANITY_API_TOKEN` are set, the agent also gains tools
to edit the storefront content managed in Sanity:

| Area | Tools |
|------|-------|
| Site content | `get_site_content`, `update_site_settings` |
| Hero carousel | `set_hero_carousel`, `add_hero_slide`, `update_hero_slide`, `remove_hero_slide` |
| Blog | `list_blog_posts`, `get_blog_post`, `create_blog_post`, `update_blog_post`, `delete_blog_post` |
| Images | `sanity_upload_image` |

> The token **must have Editor (write) permission** in Sanity. A read-only token
> lets the agent read content but every edit fails with `permission "create" required`.
> Create one at manage.sanity.io → your project → API → Tokens → Editor.

---

## Setup (one time)

### 1. Install

```bash
cd timelib-mcp
npm install
```

### 2. Configure credentials

```bash
cp .env.example .env
```

Open `.env`. `MEDUSA_BACKEND_URL` is already filled in. You need admin
credentials. **Two options:**

**Option A — Secret API key (recommended: non-expiring, revocable, no password stored).**
Temporarily put your Medusa admin email + password in `.env`, then:

```bash
npm run create-key
```

Copy the printed token into `MEDUSA_ADMIN_API_KEY` in `.env`, then delete the
email/password lines.

**Option B — Email + password.** Just set `MEDUSA_ADMIN_EMAIL` and
`MEDUSA_ADMIN_PASSWORD` in `.env` and leave `MEDUSA_ADMIN_API_KEY` empty. The
server logs in and refreshes the token automatically.

### 3. Test the connection

```bash
npm run smoke
```

You should see `✅ Auth OK` and a few product titles.

---

## Connect it to Claude

### Claude Code (CLI)

```bash
claude mcp add timelib -- node "C:\Users\dashi\Desktop\Projects\TimeLib\timelib-mcp\src\index.mjs"
```

(Credentials are read from `timelib-mcp/.env`, so you don't need to pass them on
the command line. To pass them explicitly instead, add `-e MEDUSA_BACKEND_URL=... -e MEDUSA_ADMIN_API_KEY=...` before the `--`.)

Verify with `claude mcp list`, then in a session ask: *"What tools does timelib expose?"*

### Claude Desktop

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "timelib": {
      "command": "node",
      "args": ["C:\\Users\\dashi\\Desktop\\Projects\\TimeLib\\timelib-mcp\\src\\index.mjs"]
    }
  }
}
```

Restart Claude Desktop. The 🔌 icon should show the `timelib` tools.

---

## Hosting the server (remote / always-on)

The server has two entrypoints that share the same tools:

| Entrypoint | Command | Use |
|------------|---------|-----|
| Local (stdio) | `node src/index.mjs` | Claude launches it on your machine |
| Hosted (HTTP) | `node src/http-server.mjs` | Runs as a web service; clients connect over HTTPS |

The hosted server exposes MCP at `POST /mcp` and is protected by a static bearer
token (`MCP_AUTH_TOKEN`). It refuses to start without one.

### Deploy to Railway (new service in the TimeLib project)

1. Push `timelib-mcp/` to a Git repo (GitHub).
2. In your existing **TimeLib** Railway project → **New → GitHub Repo** → pick this repo
   (set the root directory to `timelib-mcp` if it lives in a monorepo).
3. Railway reads `railway.json` and runs `node src/http-server.mjs`.
4. Add these **Variables** in the service:
   - `MEDUSA_BACKEND_URL` = `https://timelib-production.up.railway.app`
   - `MEDUSA_ADMIN_API_KEY` **or** `MEDUSA_ADMIN_EMAIL` + `MEDUSA_ADMIN_PASSWORD`
   - `MCP_AUTH_TOKEN` = a long random secret (see below)
   - (`PORT` is injected by Railway automatically.)
5. Under **Settings → Networking**, generate a public domain. You'll get a URL like
   `https://timelib-mcp-production.up.railway.app`. Your MCP endpoint is that URL + `/mcp`.

Generate a token:

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

Sanity-check the deploy:

```bash
curl https://YOUR-MCP-DOMAIN.up.railway.app/         # -> {"name":"timelib-mcp","status":"ok",...}
```

### Connect clients to the hosted server

**Claude Code (CLI)** — native HTTP transport with a header:

```bash
claude mcp add --transport http timelib-remote https://YOUR-MCP-DOMAIN.up.railway.app/mcp \
  --header "Authorization: Bearer YOUR_MCP_AUTH_TOKEN"
```

**Claude Desktop** — use the `mcp-remote` bridge (no native header field in the UI):

```json
{
  "mcpServers": {
    "timelib-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://YOUR-MCP-DOMAIN.up.railway.app/mcp",
        "--header", "Authorization: Bearer YOUR_MCP_AUTH_TOKEN"
      ]
    }
  }
}
```

**Claude.ai web / mobile** — uses OAuth (see next section). No token to paste;
you approve access with your owner password in the browser.

---

## OAuth for claude.ai web / mobile

claude.ai custom connectors authenticate via OAuth, not a static token. The
hosted server implements a full OAuth 2.1 flow (metadata discovery, dynamic
client registration, authorize + token endpoints, PKCE, refresh tokens). It's
**stateless** — client registrations and tokens are signed JWTs, so it survives
Railway redeploys with no database. Access is gated by a single owner password.

### Enable it

Add two more variables to the Railway service and redeploy:

```
OWNER_PASSWORD   = <a password you'll type to approve access>
OAUTH_JWT_SECRET = <64+ random hex chars: node -e "console.log(require('crypto').randomBytes(48).toString('hex'))">
```

`PUBLIC_URL` is auto-detected from Railway's `RAILWAY_PUBLIC_DOMAIN`. The static
`MCP_AUTH_TOKEN` keeps working for Claude Code/Desktop at the same time.

### Connect claude.ai

1. claude.ai → **Settings → Connectors → Add custom connector**.
2. URL: `https://YOUR-MCP-DOMAIN.up.railway.app/mcp`
3. Claude discovers the OAuth endpoints and opens a login page → enter your
   `OWNER_PASSWORD` → **Authorize**.
4. The `timelib` tools appear in claude.ai (web and mobile).

Health check shows which modes are active:

```bash
curl https://YOUR-MCP-DOMAIN.up.railway.app/    # -> "auth":{"static_token":true,"oauth":true}
```

---

## Notes & safety

- **Prices are in major currency units** in Medusa v2 (e.g. `25` = $25.00, not cents).
- **New products default to `draft`.** Ask the agent to set `status: "published"` (or use `update_product`) to make them live.
- **Destructive actions** (`delete_product`, deletes via `medusa_admin_request`) are permanent — the agent is instructed to confirm with you first, but review before approving.
- The secret API key has full admin access. Keep `.env` out of version control (already in `.gitignore`) and revoke the key in the Medusa admin if it leaks.
- Product **images** are passed as public URLs. To upload local files first, use the Medusa admin UI or extend the server with the `/admin/uploads` endpoint via `medusa_admin_request`.
- **Hosted server = full admin access behind one token.** Anyone with the `MCP_AUTH_TOKEN` and the URL can manage your store. Use a long random token, store it only in Railway variables + your client config, and rotate it (change the variable, redeploy) if it leaks.
- **OAuth secrets:** `OWNER_PASSWORD` is your login to approve claude.ai access — make it strong. Changing `OAUTH_JWT_SECRET` (or a redeploy that loses it) invalidates all issued tokens and registered connectors, so clients must reconnect. Keep it stable in Railway variables.